A new home
for your next scene.

Download. Install. Press play.

1. Download the Windows installer.

   Get the .exe installer from the Windows download card and run it.

2. Choose the installation folder.

   The default is C:\ergs\player. We recommend a folder outside Program Files so you can easily edit scenes, configuration and media.

3. Follow the installer instructions.

   Complete the setup wizard. You can choose to create a desktop shortcut and launch the Player when installation finishes.

4. Connect it to your room.

   Edit config.json in the installation folder. Set your MQTT broker address and a unique device ID and client ID. The installer sets base_path to the folder you chose.

Where are my files?

With the default installation folder:

If you choose another folder, these files are installed there instead. The installer includes the runtime libraries and VLC plugins.

Start the Player

Open ERGS Player from the Start menu, use the desktop shortcut if you created one, or run ergsplayer.exe from the installation folder. The default configuration is config.json beside the executable.

To launch with a specific configuration, use PowerShell:

& "C:\ergs\player\ergsplayer.exe" "C:\ergs\player\config.json"

A native player for your installation.

Use the amd64 package for a compatible 64-bit Debian-based PC. The desktop build runs in a graphical session. For a Raspberry Pi without a desktop, use the dedicated Pi package.

1. Install the package

Download the Linux package. Open a terminal in the folder containing the downloaded file and run:

sudo apt install ./ergs-player-linux-amd64.deb

Follow the package manager's prompts to install the Player and its dependencies.

2. Find and configure your project

Edit /etc/ergsplayer/config.json with administrator privileges. Set mqtt_broker_uri, a unique device_id and mqtt_client_id. For the installed media, use "base_path": "/usr/share/ergsplayer/".

3. Launch in your graphical session

ergsplayer /etc/ergsplayer/config.json

An explicit configuration path makes it clear which project the Player will use. If your package provides ergs-player instead, use that executable name in the launch command.

A console is all you need.

The Raspberry Pi package renders directly through DRM/KMS. It does not need a desktop environment. Start with a compatible 64-bit Debian-based console distribution; the documented Pi build targets Debian 13.

1. Check the operating system architecture

dpkg --print-architecture

The arm64 package requires an arm64 operating system. An armhf system is 32-bit and cannot install this package.

2. Install the Raspberry Pi package

Download the Raspberry Pi package and run this from the folder containing the file:

sudo apt install ./ergs-player-raspberry-pi-arm64.deb

3. Configure the Player

Edit the configuration with administrator privileges. Set your broker address, unique device and client IDs, and "base_path": "/usr/share/ergsplayer/". You can also use a writable project folder in your home directory and pass its configuration explicitly.

4. Launch from a local console

Connect your display and launch the Player from the Pi's local console. Ensure DRM/KMS is enabled and your runtime user can access the required display, input, audio and GPIO devices.

ergs-player /etc/ergsplayer/config.json

If your release provides ergsplayer instead, use that command name. Verify display output, audio and input before setting up automatic startup. Start with a simple scene, then add video and shaders to suit your board's performance.

Make it part of the room.

First verify that the Player works when launched manually. For kiosk scenes, use fullscreen: true, cursor_visible: false and exit_by_keyboard: false. Keep a way to manage and stop the process outside the on-screen interface.

Debian desktop / X11

The desktop package includes ergsplayer@.service. Its template runs /usr/bin/ergsplayer, uses DISPLAY=:0 and reads /home/<user>/.Xauthority. It expects a working X11 session. Replace pi below with your runtime account.

sudo systemctl daemon-reload
sudo systemctl enable --now ergsplayer@pi

journalctl -u ergsplayer@pi -f
sudo systemctl restart ergsplayer@pi
sudo systemctl stop ergsplayer@pi

Stop log following with Ctrl+C. The next two commands restart or stop the running service.

Raspberry Pi / direct rendering

Configure console startup for your chosen distribution after testing manual playback. It must provide the same DRM/KMS device permissions and console access as your working local session. The desktop service above assumes X11 and is not a ready-to-use DRM console service.

Windows

The installer provides a Start menu entry and an optional desktop shortcut. Automatic launch at Windows sign-in is a separate operating-system setup step.

A few checks before the show.

• Cannot edit scenes on Windows: use the recommended C:\ergs\player folder or another writable location outside Program Files.
• Linux command not found: check the package's executable name with command -v ergsplayer || command -v ergs-player.
• Missing media: check base_path, the media/assets/ directory and exact filename case.
• No MQTT response: check broker connectivity and unique device/client IDs. The MQTT reference lists commands and status topics.
• Windows video does not play: keep the installed runtime files and plugins/ directory with the Player. Back up your scenes before running the installer again.
• No Pi display output: check DRM/KMS support and device access from the local console before trying a service.
• No Linux audio: verify ALSA output and mixer settings. One-shot MP3 uses mpg321, WAV uses aplay, and OGG/FLAC uses ogg123.