https://github.com/jonaspoeller/synchronized4kplaybackrpi4
Synchronized 4K HEVC Video Playback for Raspberry Pi
https://github.com/jonaspoeller/synchronized4kplaybackrpi4
4k digital-signage h265 hevc multi-screen-video python raspberry-pi rpi4 seamless-looping synchronized-playback udp-broadcast video-synchronization video-wall vlc
Last synced: 2 months ago
JSON representation
Synchronized 4K HEVC Video Playback for Raspberry Pi
- Host: GitHub
- URL: https://github.com/jonaspoeller/synchronized4kplaybackrpi4
- Owner: jonaspoeller
- License: mit
- Created: 2025-08-13T09:08:56.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-09-10T13:06:26.000Z (10 months ago)
- Last Synced: 2025-09-10T17:20:06.791Z (10 months ago)
- Topics: 4k, digital-signage, h265, hevc, multi-screen-video, python, raspberry-pi, rpi4, seamless-looping, synchronized-playback, udp-broadcast, video-synchronization, video-wall, vlc
- Language: Shell
- Homepage:
- Size: 45.9 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Synchronized Video Playback for Raspberry Pi
A solution for synchronized, looping video playback across multiple Raspberry Pi 4 devices. This system is designed for continuous 24/7 operation in settings like video walls or art installations.
## Key Features
* **Playback Synchronization:** Coordinates video playback across multiple devices using a master-slave architecture.
* **Master Failure Recovery:** A watchdog on each slave reverts to a black screen if the master's signal is lost.
* **Automatic Slave Integration:** Slave nodes that are started late are automatically included in the next playback loop.
* **Hardware-Accelerated Playback:** Supports 4K/60fps 8-bit HEVC video decoding.
* **Professional Appliance Mode:** The screen remains completely black from power-on until video playback begins. No boot text, logos, or console prompts are ever displayed.
* **Multi-Group Support:** Allows multiple, independent player groups to operate on the same network.
* **Automated Setup:** An interactive script handles system configuration and dependency installation.
---
## How It Works
The system uses a Master-Slave model where a single Master node controls multiple Slave nodes via unidirectional UDP broadcast packets. Synchronization is enforced by the Master broadcasting a strict command sequence (`stop` -> `load` -> `prepare` -> `play`) at the beginning of each loop. This state-based approach, combined with a watchdog on each slave, ensures reliability and allows for the automatic integration of newly started devices.
---
## Prerequisites
* 2 or more Raspberry Pi 4 devices.
* A fresh installation of **Raspberry Pi OS (64-bit) Bookworm** on each SD card.
* A stable, wired (Ethernet) network connection.
* Each Pi must have a unique, fixed IP address.
* The video file, named `video.mp4`, must be located in `/home/pi/` on every device.
---
## Installation
The installation is a step-by-step process. The following must be performed on **every** Pi (both Master and Slaves). The setup will do a full apt upgrade and reboot afterwards. This is to avoid problems caused by outdated drivers.
#### Step 1: Prepare the System
Before running the installer, each device must be properly configured.
1. **Set a Static IP Address:** A static IP is essential for system stability. This can be done via the command line using `nmcli`.
* First, find your connection name (usually `"Wired connection 1"`):
```bash
nmcli connection show
```
* Use the following command to set the static IP, gateway, and DNS. **Replace the example values with your network's settings.**
```bash
sudo nmcli c mod "Wired connection 1" ipv4.method manual \
ipv4.addresses 10.0.0.220/24 \
ipv4.gateway 10.0.0.1 \
ipv4.dns "8.8.8.8,1.1.1.1"
```
* Apply the changes by restarting the connection:
```bash
sudo nmcli c down "Wired connection 1"; sudo nmcli c up "Wired connection 1"
```
A reboot will also apply the settings. Verify the new IP with `ip a`.
2. **Place the Video File:** Copy your video file to the home directory of each Pi. The system expects the file at this exact location:
`/home/pi/video.mp4`
#### Step 2: Run the Automated Installer
Once the static IP is set and the video file is in place, run the automated setup script.
1. **Download the Installer Script**
```bash
wget https://github.com/jonaspoeller/synchronized4kplaybackrpi4/releases/latest/download/setup_video_sync.sh
```
2. **Execute the Installer Script**
```bash
sudo bash setup_video_sync.sh
```
#### Step 3: Follow the Interactive Prompts
The script will guide you through the final configuration by asking for:
* The static IP address of the current device.
* The network port for this sync group (e.g., `5555`).
* The role of the device (Master or Slave).
* The IP address of the Master (if configuring a Slave).
The device will reboot automatically upon completion. After the reboot, the system is fully configured and will start playback automatically.
---
## Configuration
### Master Configuration
Path: `/opt/video-sync/sync_config.ini` on the Master
```ini
[network]
master_ip = 192.168.1.10
broadcast_ip = 192.168.1.255
sync_port = 5555
[video]
file_path = /home/pi/video.mp4
loop_delay = 0.5
```
- **loop_delay:** Pause in seconds between the end of one video loop and the start of the next.
---
### Slave Configuration
Path: `/opt/video-sync/sync_config.ini` on a Slave
```ini
[network]
master_ip = 192.168.1.10
sync_port = 5555
```
---
## Usage & Management
```bash
video-sync-start # Start the service
video-sync-stop # Stop the service
video-sync-status # Check the service status
video-sync-logs # View live logs
```
---
## Uninstallation
```bash
wget -O - https://github.com/jonaspoeller/synchronized4kplaybackrpi4/releases/latest/download/uninstall_video_sync.sh | sudo bash
```
The script will clean up all files and services and reboot the Pi back into the standard graphical desktop environment.
---
## Project Links
* **[Source Code and All Files](https://github.com/jonaspoeller/synchronized4kplaybackrpi4)**
* **[Releases (Downloads)](https://github.com/jonaspoeller/synchronized4kplaybackrpi4/releases)**
* **[Report an Issue (Issues)](https://github.com/jonaspoeller/synchronized4kplaybackrpi4/issues)**
---
## License
This project is licensed under the MIT License. See the LICENSE file for details.
© 2025 Jonas Pöller