# Lightweight Linux player

The player is compiled for Linux ARM64 (aarch64) and x86-64 (Intel/AMD), with the same pairing, schedules, media cache and dashboard APIs as Windows. Use a 64-bit Debian 13 or compatible OS image with X11 and mpv 0.40 or newer. This package sets up an existing OS; it is not a bootable disk image.

Start with one 1080p output. Hardware decoding and the number/resolution of simultaneous outputs depend on the GPU, codec and installed drivers. CPU architecture alone does not prove playback compatibility. There is no browser or full desktop environment in the signage session. mpv uses simple scaling and no interpolation.

## Which download and OS?

| Hardware | OS image | Player download |
| --- | --- | --- |
| Intel/AMD 64-bit PCs | Debian 13 minimal, amd64 | dsigns-linux-x64.deb |
| Raspberry Pi with 64-bit support | Raspberry Pi OS Lite 64-bit, based on Debian 13 | dsigns-linux-arm64.deb |
| Other ARM64 boards | Vendor-supported Debian-compatible 64-bit image with X11/EGL drivers | dsigns-linux-arm64.deb |

Download the players and this guide from the public setup page at https://dsigns-dev.bitprecision.chatgpt.site/install. Install the matching OS first, then add dsigns with its application installer. 32-bit-only x86 or ARM devices are unsupported. The controller is portable across these CPU families; the OS, kernel and graphics drivers must suit the board.

Official base-image instructions: [Debian installation](https://www.debian.org/releases/trixie/installmanual), [Raspberry Pi Imager](https://www.raspberrypi.com/software/) and [Raspberry Pi OS](https://www.raspberrypi.com/documentation/computers/os.html).

## Prepare one device or a reusable image

The installer and image-preparation scripts include the player and its supervisor as ready-to-install files. Connection codes and automatic-playback choices are handled on first launch. When preparing a master image, use the current release from the downloads page; no prebuilt dsigns ISO is supplied.

1. Install the appropriate base OS. Configure networking, time synchronisation and your administrator account. Raspberry Pi Imager can configure these before writing the SD card. Use Lite; dsigns installs its own small X11 session.
2. Install the board/GPU's supported firmware and graphics/video drivers. Keep the vendor kernel on ARM.
3. Download the matching `.deb` installer onto the target device. Open it in the OS software installer, or run one of:

   ```sh
   sudo apt install ./dsigns-linux-x64.deb
   # ARM64 / Raspberry Pi instead:
   sudo apt install ./dsigns-linux-arm64.deb
   ```

4. The package manager installs dependencies. The installer creates a standard `signage` account and configures the small X11 session, LightDM automatic login, first-launch setup and watchdog. Internet access is required for dependencies. This changes login configuration on the dedicated device. No separate setup script is needed.
5. For a single device, reboot and follow the next section. For a master image, shut down and capture the disk **before entering any setup code**. No dsigns device identity or customer credential is stored in this template. Never clone an onboarded player. Generalise hostnames, OS machine identities and SSH host keys using your imaging tool; don't copy a technician's credentials or customer Wi-Fi settings into a shared image.
6. Restore the master only onto its supported hardware/OS family. An Intel disk image cannot boot a Pi. Each clone needs networking and its own dsigns setup code.

## Onboarding: one code per player

1. In the dashboard, create a customer and group under **Customers**. Select the group's default playlist/schedule if ready; a group without content uses the neutral fallback.
2. Open **Players → Add player**, choose the customer/group, optionally name the player, and click **Generate setup code**.
3. Copy the code or save `dsigns-setup.txt` to a USB drive. It contains the server address plus a secret credential, expires after 24 hours, and connects one device. Treat the unused file as a password; delete it after setup.
4. Boot the player. On its fullscreen setup screen, confirm its name and paste the code or open the text file. Choose **Start playback automatically when I sign in**, then select **Save and start player**. Setup runs in dsigns after installation; the package manager never waits for a code.
5. The first check-in assigns all detected active monitors to the selected group and publishes its current content. The player gets a permanent ID and a separate revocable token, retained across reboots. The visible name is editable; the generated ID distinguishes machines with the same name.
6. If the network interrupts setup, retry the same code on that same device. Its saved claim secret prevents another device collecting its credentials. Cancel unused codes in Add player and generate replacements. A used code cannot onboard another device.
7. Adjust individual screen settings from the player detail page and **Publish** changes. Verify image/video playback and a schedule boundary before unattended use.

Open **dsigns Settings** from the application menu to change automatic playback. When it is off, the signage session waits at the setup screen until you select **Save and start player**. On a regular desktop, use **dsigns Player** to start playback.

For existing installations, installing a newer `.deb` updates the template; the newer player is copied into the signage account at its next login, retaining identity/cache. A newer application installed remotely is preserved. Manual `.tar.gz` archives remain available under earlier/manual downloads; those include `install.sh` and `prepare-image.sh` for technicians. They are not the primary installer.

The kiosk script changes the display manager's automatic-login configuration. Use it on a dedicated signage installation. It does not overwrite the OS, partition disks or configure networking. Configure firmware power restoration separately. Some ARM boards power on when power returns; verify the particular board and display.

Debian packages supply `/usr/bin/mpv` and the graphics libraries, so one controller binary does not need to bundle every GPU driver. Existing installations must have a working hardware decode path before commissioning. Check the dashboard's actual decoder report; software decoding can consume substantially more CPU. Raspberry Pi and other ARM models have different codec capabilities: do not assume that support for HEVC implies hardware support for H.264.

## Screens

One supervised fullscreen mpv process runs per assigned, active monitor. Identification combines the connector and the panel EDID. Enumeration order is irrelevant; reconnect to the same physical port. Moving a cable to a different connector requires reassignment. Missing monitors retain their assignments; their content is not moved elsewhere.

Arrange monitors once with the OS's `xrandr` settings. Only connected outputs with an active mode are reported. Video walls, Wayland and cross-device synchronisation remain outside this MVP.

## Recovery and updates

After setup, automatic playback starts the systemd user service at sign-in. Manual mode starts it only when you launch playback. A completed controller loop sends the 60-second watchdog acknowledgement; an independent supervisor handles exited controllers and staged updates. systemd kills the entire service group when its watchdog expires, preventing orphan decoders. Timed maintenance suspends this recovery until its persisted expiry.

Use the public update ZIP URL and SHA-256 from **Downloads & setup → Updates & older releases** in **Update player**. The public release URL works without dashboard credentials; device and management APIs remain authenticated. You can also host the matching `dsigns-linux-arm64-update.zip` or `dsigns-linux-x64-update.zip` on your own HTTPS host. The player verifies the download and executable architecture, retains the previous application, and rolls back if the new controller does not report progress. The update ZIP has `dsigns` and `release.json` at its root. The installer archive is not an update ZIP.

Linux remote updates replace the Go controller, setup screen and brand assets. mpv, the supervisor copy, OS packages and drivers are maintained through the OS/installer; automatic OS updates and fleet rollout management are not included. Updating the installer refreshes the supervisor. Test rollback on each hardware family before a wider rollout. Power loss during replacement can require manual recovery from `previous-app`.

## Diagnostics and removal

Run `~/.local/share/dsigns/collect-diagnostics.sh` as the signage user to collect redacted logs, service state, display properties and mpv version. Data is under `~/.local/share/dsigns/data`. Do not share `config.json`; it contains the device token.

Useful commands on the player:

```sh
systemctl --user status dsigns.service
journalctl --user -u dsigns.service -n 100
systemctl --user restart dsigns.service
```

To disable signage, stop the user service and remove `/etc/lightdm/lightdm.conf.d/90-dsigns.conf` using administrator access. Keep the data directory until you decide whether to preserve the pairing/cache. Removing `/etc/sudoers.d/dsigns-reboot` revokes its reboot permission.

## Validation required on hardware

Compilation is separate from playback validation. Check fullscreen placement, image/video decoding, audio, display reconnects, offline reboot, controller termination/hang, maintenance expiry, corrupt media, fallback, update/rollback and reboot allowance on each target. A 48-hour soak test and actual power measurements are still required. Measure power use and verify playback on each hardware model before choosing it for a rollout.

## Remove the package

Run `sudo apt remove dsigns-player`. The signage account and its cached content, logs and identity are retained. Revoke the device in the dashboard if retiring it.