Remove Windows-era leftovers and document the cleanup

Removes development scratch that belonged to the Windows port and has no
purpose on the Linux/Pi branch. 39 tracked files removed; everything is
recoverable from the Windows-Player branch.

Removed
-------
- working_files/ (29 files) - dev-era scratch: install.sh.bak, the superseded
  get_playlists.py (v1, replaced by get_playlists_v2.py), one-off test_*.py
  probes, MIGRATION_GUIDE.md, INVESTIGATION_RESULTS.md. Also held real server
  captures (server_response_debug.json contained player_id, player name and a
  playlist) which should not be in the repository at all.
- documentation/ (5 files) - all described the Windows-era HTTPS integration.
- "python version" - contained Python 3.12.9, the Windows build interpreter.
  The Pi runs 3.13.5.
- test_edited_media_upload.py - parentless debug script, referenced by nothing.
- .display-keepalive.sh, .keep-screen-alive.sh, .wait-for-display.sh - orphan
  X11 helpers referenced by nothing; superseded by linux/linux_display.py.

Kept deliberately
-----------------
- .video-optimization.sh, .run-background.sh, .start-player-cron.sh -
  referenced by install.sh.
- repo/python-wheels/ (58 MB of aarch64 cp313 wheels) - the offline install set.
- .venv/ is gitignored; runtime caches (.kiosk-profile, .kivy), logs, media and
  the playlist cache are regenerated automatically and stay ignored.

Also fixed a stale reference to the removed documentation/ directory in
linux/development-track.md, and recorded the above there.

Verified after removal: all modules under src/ import cleanly from an unrelated
working directory, all remaining shell scripts pass `bash -n`, and the running
player was unaffected (correct: it had already loaded its code).

.display-keepalive.sh

@@ -1,79 +0,0 @@
-#!/bin/bash
-# Aggressive display keep-alive for Raspberry Pi
-# Supports both X11 and Wayland environments
-
-DISPLAY_TIMEOUT=30
-
-# Detect display server type
-detect_display_server() {
-    if [ -n "$WAYLAND_DISPLAY" ]; then
-        echo "wayland"
-    elif [ -n "$DISPLAY" ]; then
-        echo "x11"
-    else
-        echo "unknown"
-    fi
-}
-
-DISPLAY_SERVER=$(detect_display_server)
-
-while true; do
-    # Keep HDMI powered on (works for both X11 and Wayland)
-    if command -v tvservice &> /dev/null; then
-        /usr/bin/tvservice -p 2>/dev/null
-    fi
-    
-    if [ "$DISPLAY_SERVER" = "wayland" ]; then
-        # Wayland-specific power management
-        
-        # Method 1: Use wlr-randr for Wayland compositors (if available)
-        if command -v wlr-randr &> /dev/null; then
-            wlr-randr --output HDMI-A-1 --on 2>/dev/null || true
-        fi
-        
-        # Method 2: Prevent idle using systemd-inhibit
-        if command -v systemd-inhibit &> /dev/null; then
-            # This is already running, but refresh the lock
-            systemctl --user restart plasma-ksmserver.service 2>/dev/null || true
-        fi
-        
-        # Method 3: Use wlopm (Wayland output power management)
-        if command -v wlopm &> /dev/null; then
-            wlopm --on \* 2>/dev/null || true
-        fi
-        
-        # Method 4: Simulate activity via input (works on Wayland)
-        if command -v ydotool &> /dev/null; then
-            ydotool mousemove -x 1 -y 1 2>/dev/null || true
-            ydotool mousemove -x -1 -y -1 2>/dev/null || true
-        fi
-        
-        # Method 5: GNOME/KDE Wayland idle inhibit
-        if command -v gnome-session-inhibit &> /dev/null; then
-            # Already inhibited by running process
-            true
-        fi
-        
-    else
-        # X11-specific power management (original code)
-        if command -v xset &> /dev/null; then
-            DISPLAY=:0 xset s off 2>/dev/null
-            DISPLAY=:0 xset -dpms 2>/dev/null
-            DISPLAY=:0 xset dpms force on 2>/dev/null
-            DISPLAY=:0 xset s reset 2>/dev/null
-        fi
-        
-        # Move mouse to trigger activity
-        if command -v xdotool &> /dev/null; then
-            DISPLAY=:0 xdotool mousemove_relative 1 1 2>/dev/null
-            DISPLAY=:0 xdotool mousemove_relative -1 -1 2>/dev/null
-        fi
-        
-        # Disable monitor power saving
-        if command -v xrandr &> /dev/null; then
-            DISPLAY=:0 xrandr --output HDMI-1 --power-profile performance 2>/dev/null || true
-        fi
-    fi
-    
-    sleep $DISPLAY_TIMEOUT
-done

.github/instructions/kiwy-linux-rpi.instructions.md

@@ -0,0 +1,253 @@
+---
+description: "Use when installing, deploying, running or debugging the Kiwy Signage Player on Raspberry Pi OS Trixie 64-bit: venv setup, Kivy/SDL2 Wayland requirements, the linux/ entry point, autostart, systemd, watchdog supervision, or adding new modules under src/. Covers the exact commands, environment constraints and verification steps."
+name: "Kiwy Linux / Raspberry Pi Build & Development"
+---
+
+# Kiwy Signage Player — Linux / Raspberry Pi Build & Development
+
+Kivy digital signage player targeting **Raspberry Pi OS "Trixie"** (Debian 13,
+aarch64, Wayland/labwc).
+
+- **Entry point** — `linux/run_linux.py`. Not `src/main.py`.
+- **Target hardware** — Raspberry Pi 4 / 5. Verified on a Pi 4 Model B Rev 1.4,
+  kernel `6.18.39+rpt-rpi-v8`.
+
+## Ground Rules
+
+- **Never launch `src/main.py` directly.** It is a shared module, not the Pi
+  entry point. Running it skips every platform patch (session environment,
+  display keep-awake, Chromium adapter) and resolves the data directory one
+  level too high. Always go through `linux/run_linux.py`
+  (`bash run_player.sh` / `bash start.sh`).
+- **Keep `src/main.py` platform-neutral.** Pi-specific behaviour belongs in
+  `linux/`. `src/main.py` may only contain *guarded capability checks*, never a
+  platform-specific import.
+- **A patched method must be resolvable by its own `__name__`.** Kivy's `Clock`
+  wraps callbacks in a `WeakMethod` keyed on `func.__name__` and re-resolves it
+  with `getattr(instance, name)`. Assigning a replacement under a different name
+  than it was defined with raises `AttributeError` **the first time the Clock
+  fires** — minutes after a successful start, with a traceback that points
+  nowhere near the patch. Use `_bind_name()`, and cover new patches in
+  `linux/test_linux_patches.py`. This has already caused two outages.
+- **No `sudo` at runtime.** The player runs as an unprivileged user. Anything
+  needing root must be set up at install time (sudoers entry, udev rule,
+  systemd unit).
+
+## Environment
+
+| Item | Value |
+|------|-------|
+| OS | Raspberry Pi OS Trixie / Debian 13, aarch64 |
+| Session | **Wayland** via `rpd-labwc` (`labwc`). No X server. |
+| Python | **3.13.5** — project venv at `.venv` (created `--system-site-packages`) |
+| Kivy | 2.3.1 (PyPI wheel) |
+| ffpyplayer | 4.5.3 (video/audio backend) |
+| evdev | 2.0.0 — **sdist only**, built locally (needs `python3-dev`, `build-essential`) or apt `python3-dev` |
+| Browser | `/usr/bin/chromium` (there is no `chromium-browser` on Trixie) |
+
+### The SDL2 trap (the #1 way to break the install)
+
+Kivy's PyPI wheel bundles a **private SDL2 without the Wayland driver**:
+
+```
+Kivy.libs/libSDL2-2-*.so     ->  x11, KMSDRM, offscreen, dummy, evdev     # no wayland!
+/usr/lib/.../libSDL2-2.0.so.0 ->  x11, wayland, KMSDRM, offscreen, dummy, evdev
+```
+
+On Trixie there is no X server, so the bundled build cannot create a window:
+
+```
+[CRITICAL] Unable to find any valuable Window provider.
+sdl2 - RuntimeError: b'wayland,x11,dummy not available'
+```
+
+`linux/fix_kivy_sdl2.sh` symlinks the **system** SDL2 over the bundled
+filename. **Re-run it after every `pip install --upgrade kivy`.**
+`linux/test_linux_patches.py` asserts the driver is present, so a regression
+fails the test suite rather than the player.
+
+### SDL2 requires `WAYLAND_DISPLAY` to be set
+
+The socket existing is **not** enough — unlike `wlopm`, SDL2 does not scan
+`XDG_RUNTIME_DIR`. A launch from systemd, cron, an autostart entry or SSH has
+the variable **empty**, and Kivy then fails with `wayland not available`.
+`linux_display.ensure_session_environment()` detects the socket and exports the
+name; `run_linux.py` calls it before importing Kivy.
+
+## Install
+
+Required system packages:
+
+```bash
+sudo apt install -y \
+    python3-venv python3-dev build-essential \
+    libsdl2-2.0-0 libsdl2-image-2.0-0 libsdl2-mixer-2.0-0 libsdl2-ttf-2.0-0 \
+    libgl1-mesa-dri libgles2 \
+    chromium wlopm wlr-randr ffmpeg
+```
+
+Python dependencies (all have cp313 aarch64 wheels **except** evdev):
+
+```bash
+python3 -m venv --system-site-packages .venv
+.venv/bin/pip install kivy ffpyplayer requests bcrypt aiohttp
+.venv/bin/pip install evdev          # builds from source
+bash linux/fix_kivy_sdl2.sh          # REQUIRED: system SDL2 with Wayland
+```
+
+## Run
+
+```bash
+bash run_player.sh      # single run, no supervision
+bash start.sh           # watchdog: auto-restart on crash/hang (24/7)
+```
+
+`start.sh` supervises through a heartbeat file (`.player_heartbeat`, rewritten
+every 10 s; stale after 60 s ⇒ hung ⇒ restart) and honours
+`.player_stop_requested` so a password exit is not resurrected.
+
+## Verify Before Committing
+
+```bash
+.venv/bin/python -m py_compile src/*.py linux/*.py   # syntax, seconds
+bash -n start.sh run_player.sh stop_player.sh check_player_status.sh
+
+.venv/bin/python linux/test_linux_patches.py        # expect: 21/21 passed
+.venv/bin/python linux/test_linux_browser_flags.py  # expect: 27/27 passed
+.venv/bin/python linux/test_media_state.py          # expect: 18/18 passed
+bash linux/fix_kivy_sdl2.sh --check                 # expect: STATUS: fixed
+.venv/bin/python linux/_probe_video.py              # video decodes + advances
+.venv/bin/python linux/_probe_chromium_footprint.py https://example.com/  # PSS per profile
+```
+
+**Close the running player before editing `src/`** if you intend to test
+immediately — the watchdog will restart it and you will test stale code.
+
+## 24/7 Supervision
+
+`start.sh` restarts the player when it:
+
+- **crashed** — the process disappeared; or
+- **hung** — the process is alive but the heartbeat is stale (>60 s).
+
+Two failure modes must not be confused:
+
+| Situation | Correct reaction |
+|---|---|
+| Was healthy, then heartbeat went stale | **Restart promptly** (a hang) |
+| Running but never became healthy (slow start, the first-run setup screen) | **Be patient** — do not kill a player an operator is configuring |
+
+Diagnostics for playback transitions live in `logs/playback_trace.log`,
+written by `src/playback_trace.py` independently of Kivy's log level.
+
+## Runtime pitfalls
+
+- **`~/dev/...` cwd matters.** The player's data directory is the repo root.
+  Launch from there (all provided scripts do).
+- **The desktop blanker fights the player.** `~/.config/labwc/autostart` ships
+  `swayidle -w timeout 600 'wlopm --off *'`, which powers the panel off after
+  10 minutes. `linux_display.neutralise_idle_blanker()` stops it at start-up.
+  Do not remove that call.
+- **`tvservice`, `xdotool`, `ydotool` do not exist on Trixie.** Any code using
+  them silently does nothing.
+- **Web links need a dedicated `--user-data-dir`.** Without it Chromium hands
+  the URL to a running instance, our process exits in ~2 s and the item is
+  skipped as a failed launch.
+- **The keyring prompt is suppressed via the ENVIRONMENT, not the flags.**
+  `--password-store=basic` alone does not stop Chromium asking for the login
+  keyring password: it inherits `DBUS_SESSION_BUS_ADDRESS`, reaches the running
+  `gnome-keyring-daemon` and prompts. `LinuxChromiumAdapter.launch_env()` strips
+  the bus for the child process, which is what actually fixes it. Do not remove
+  `launch_env()`, and do not add a flag list that nothing references —
+  `test_linux_browser_flags.py` fails if a list becomes dead code, because that
+  is exactly how this bug hid before.
+- **`--ozone-platform-hint=auto` does not work on Chromium 152.** It aborts with
+  "Missing X server" instead of falling back to Wayland; `--ozone-platform=wayland`
+  must be stated explicitly.
+- **Kill the whole process group on teardown.** `proc.terminate()` leaves
+  Chromium's GPU/zygote/renderer children behind; they accumulate until the Pi
+  runs out of memory. This needs `start_new_session=True` at launch.
+- **Measure memory with PSS, never RSS.** Chromium shares pages across its
+  processes, so summing RSS roughly doubles the figure and even ranks smaller
+  configurations as larger. `linux/_probe_chromium_footprint.py` does it correctly.
+- **`--disable-gpu` increases memory** for a real page (1038 MB vs 513 MB). It is
+  intentionally not used anywhere.
+
+## Video: 4K cannot play, and is converted automatically
+
+**A 4K video will not play on a Pi 4.** ffpyplayer decodes in software and there
+is no hardware H.264 decode in its pipeline. Measured: 1080p decodes at 3.03×
+realtime, 3840×2160 at **0.90×** — below 1× the picture simply stops.
+
+The player therefore normalises oversized media to at most 1920×1080:
+
+* `src/media_state.py` — the shared on-disk contract (markers, path resolution,
+  and a dependency-free MP4 header parser so the playback path spawns nothing).
+* `linux/video_normalizer.py` — the converter (hardware `h264_v4l2m2m`, ~31 s
+  for an 18 s 4K clip; `libx264` fallback).
+* Triggered automatically from `get_playlists_v2.normalize_oversized_media()`
+  after every sync, in both the "updated" and "up-to-date" branches.
+
+| Marker next to the media | Meaning |
+|---|---|
+| `<media>.kiwy-converting` | in flight → the player **skips** the item |
+| `<media>_kiwy1080p.mp4` + `.kiwy-normalized.json` | done → the player plays **this** file |
+
+Do not remove these markers, and do not let `delete_unused_media()` prune them —
+the converted output is deliberately absent from the playlist and would
+otherwise be deleted while the player is using it.
+
+The conversion is only triggered by **resolution**. A file within 1920×1080 is
+left byte-identical. When nothing is playable yet (a single-item playlist whose
+only video is still converting), the player loops `config/resources/intro1.mp4`
+rather than showing a blank screen.
+
+Run it manually:
+
+```bash
+.venv/bin/python linux/video_normalizer.py --dry-run media/   # report only
+.venv/bin/python linux/video_normalizer.py media/             # convert
+.venv/bin/python linux/video_normalizer.py --max-height 720 media/
+```
+
+> Prefer normalising on the **server** before upload: it avoids both the 4K
+download and the 31 s conversion. The player-side path is a safety net, not the
+preferred workflow.
+
+## Diagnostics
+
+| Command | Purpose |
+|---------|---------|
+| `.venv/bin/python linux/linux_display.py` | Wayland/X11 status, outputs, available tools |
+| `bash linux/fix_kivy_sdl2.sh --check` | Which SDL2 Kivy loads and its drivers |
+| `bash check_player_status.sh` | Is the player running |
+| `bash stop_player.sh` | Stop player + watchdog |
+
+Escape hatches:
+
+| Variable | Effect |
+|----------|--------|
+| `KIWY_DISPLAY_TOOLS_DISABLED=1` | Disable `wlopm`/`vcgencmd`/`swayidle` work |
+| `KIWY_CHROMIUM_MODE=light` | Default footprint profile (safe reductions) |
+| `KIWY_CHROMIUM_MODE=minimal` | Adds `--single-process`; ~15% less memory, less stable |
+| `KIWY_CHROMIUM_MODE=safe` | No footprint flags at all (when debugging) |
+| `KIWY_VENV=/path` | Point the SDL2 fix script at another virtualenv |
+
+## Commit Hygiene
+
+- Never commit `.venv/`, `.kivy/`, `logs/`, `.kiosk-profile/` (git-ignored).
+- **Do not commit `player_auth.json`** — it holds live credentials
+  (`auth_code`, `player_id`, `server_url`).
+- Do not commit `config/app_config.json` values that are host-specific
+  (`server_ip`, `screen_name`, `quickconnect_key`). The repo default is blank on
+  purpose so a fresh install runs the first-run setup flow.
+
+## Release Checklist
+
+1. Bump `PLAYER_VERSION` in `src/main.py`.
+2. Run the verification suite above on the target Pi.
+3. Confirm `bash linux/fix_kivy_sdl2.sh --check` reports `fixed`.
+4. Smoke-test a mixed playlist: image → video → weblink → image, verifying
+   durations, audio (`audio: off` / `muted`) and a clean exit/restart.
+5. 24/7 soak (≥12 h): check the heartbeat, `pgrep -c chromium` for leaks and
+   memory growth.

.gitignore

@@ -30,6 +30,11 @@ env/
 *.pyc
 
 # Media files (optional - remove if you want to track media)
+#
+# Coverage matters here: `media/*.mp4` matches files directly in media/, but NOT
+# media/edited_media/1/foo.jpg. Playlist content is downloaded per-site and must
+# never be committed, so the whole tree is ignored and only the directory
+# structure (via .gitkeep) is tracked.
 media/*.jpg
 media/*.jpeg
 media/*.png
@@ -40,9 +45,20 @@ media/*.avi
 media/*.mkv
 media/*.mov
 media/*.webm
+media/**/*.jpg
+media/**/*.jpeg
+media/**/*.png
+media/**/*.gif
+media/**/*.bmp
+media/**/*.mp4
+media/**/*.avi
+media/**/*.mkv
+media/**/*.mov
+media/**/*.webm
 
-# Playlists cache (auto-generated)
+# Playlist cache (auto-generated from the server per device)
 playlists/server_playlist_*.json
+playlists/server_playlist.json
 
 # Logs
 *.log
@@ -59,3 +75,34 @@ playlists/server_playlist_*.json
 Thumbs.db
 
 .player_heartbear
+
+# NOTE: the line above is a long-standing typo for `.player_heartbeat` and is
+# kept only so nothing changes for existing clones. The correct patterns are
+# below — without them the player's runtime state files get committed (they
+# change every 10 seconds, which would create endless noise and merge conflicts).
+.player_heartbeat
+.player_stop_requested
+logs/startup_marker.txt
+logs/startup_crash.log
+logs/console_out.txt
+logs/console_err.txt
+logs/watchdog_test_*.txt
+
+# Player credentials — live auth_code/player_id/server_url. Never commit these:
+# a bundled copy made fresh builds boot "already authenticated" against an old
+# server and play a stale playlist.
+player_auth.json
+src/player_auth.json
+working_files/player_auth.json
+
+# Runtime browser profile (cache, not source). The player launches Chromium with
+# a dedicated --user-data-dir so it never touches the operator's own profile.
+# The wildcard covers probe/test profiles (e.g. .kiosk-profile-probe), which
+# otherwise get picked up as untracked files and are several MB of cache each.
+.kiosk-profile/
+.kiosk-profile-*/
+.webview2-profile/
+
+# Monitoring output (generated per run, not source)
+logs/monitor*.csv
+logs/monitor*.log

.keep-screen-alive.sh

@@ -1,54 +0,0 @@
-#!/bin/bash
-# Keep-screen-alive wrapper for player
-# Prevents screen from locking/turning off while player is running
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-# Function to keep screen awake
-keep_screen_awake() {
-    while true; do
-        # Move mouse slightly to prevent idle
-        if command -v xdotool &> /dev/null; then
-            xdotool mousemove_relative 1 1
-            xdotool mousemove_relative -1 -1
-        fi
-        
-        # Disable DPMS and screensaver periodically
-        if command -v xset &> /dev/null; then
-            xset s reset
-            xset dpms force on
-        fi
-        
-        sleep 30
-    done
-}
-
-# Function to inhibit systemd sleep (if available)
-inhibit_sleep() {
-    if command -v systemd-inhibit &> /dev/null; then
-        # Run player under systemd inhibit to prevent sleep
-        systemd-inhibit --what=sleep --why="Signage player running" \
-            bash "$SCRIPT_DIR/start.sh"
-        return $?
-    fi
-    return 1
-}
-
-# Try systemd inhibit first (most reliable)
-if inhibit_sleep; then
-    exit 0
-fi
-
-# Fallback: Start keep-alive in background
-keep_screen_awake &
-KEEPALIVE_PID=$!
-
-# Start the player
-cd "$SCRIPT_DIR"
-bash start.sh
-PLAYER_EXIT=$?
-
-# Kill keep-alive when player exits
-kill $KEEPALIVE_PID 2>/dev/null || true
-
-exit $PLAYER_EXIT

.wait-for-display.sh

@@ -1,54 +0,0 @@
-#!/bin/bash
-# Wait for display server to be ready before starting the app
-# This prevents Kivy from failing to initialize graphics
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-MAX_WAIT=60
-ELAPSED=0
-
-echo "[$(date)] Waiting for display server to be ready..."
-
-# Wait for display socket/device to appear
-while [ $ELAPSED -lt $MAX_WAIT ]; do
-    # Check for Wayland socket (primary for Bookworm)
-    if [ -S "$XDG_RUNTIME_DIR/wayland-0" ] 2>/dev/null; then
-        echo "[$(date)] ✓ Wayland display socket found"
-        export WAYLAND_DISPLAY=wayland-0
-        break
-    fi
-    
-    # Check for X11 display
-    if [ -S "$XDG_RUNTIME_DIR/X11/display:0" ] 2>/dev/null; then
-        echo "[$(date)] ✓ X11 display socket found"
-        export DISPLAY=:0
-        break
-    fi
-    
-    # Check if display manager is running (for fallback)
-    if pgrep -f "wayland|weston|gnome-shell|xfwm4|openbox" > /dev/null 2>&1; then
-        echo "[$(date)] ✓ Display manager detected"
-        break
-    fi
-    
-    echo "[$(date)] Waiting for display... ($ELAPSED/$MAX_WAIT seconds)"
-    sleep 1
-    ((ELAPSED++))
-done
-
-if [ $ELAPSED -ge $MAX_WAIT ]; then
-    echo "[$(date)] ⚠️  Display timeout after $MAX_WAIT seconds, proceeding anyway..."
-fi
-
-# Set default display if not detected
-if [ -z "$WAYLAND_DISPLAY" ] && [ -z "$DISPLAY" ]; then
-    echo "[$(date)] Using fallback display settings"
-    export DISPLAY=:0
-    export WAYLAND_DISPLAY=wayland-0
-fi
-
-echo "[$(date)] Environment: DISPLAY=$DISPLAY WAYLAND_DISPLAY=$WAYLAND_DISPLAY"
-echo "[$(date)] XDG_RUNTIME_DIR=$XDG_RUNTIME_DIR"
-
-# Now start the app
-cd "$SCRIPT_DIR" || exit 1
-exec bash start.sh

New.txt

@@ -1,43 +0,0 @@
-INFO   ] [Kivy        ] Installed at "/home/pi/Desktop/Kiwy-Signage/.venv/lib/python3.13/site-packages/kivy/__init__.py"
-[INFO   ] [Python      ] v3.13.5 (main, Jun 25 2025, 18:55:22) [GCC 14.2.0]
-[INFO   ] [Python      ] Interpreter at "/home/pi/Desktop/Kiwy-Signage/.venv/bin/python3"
-[INFO   ] [Logger      ] Purge log fired. Processing...
-[INFO   ] [Logger      ] Purge finished!
-[DEBUG  ] [Using selector] EpollSelector
-WARNING: running xinput against an Xwayland server. See the xinput man page for details.
-WARNING: running xinput against an Xwayland server. See the xinput man page for details.
-WARNING: running xinput against an Xwayland server. See the xinput man page for details.
-WARNING: running xinput against an Xwayland server. See the xinput man page for details.
-WARNING: running xinput against an Xwayland server. See the xinput man page for details.
-WARNING: running xinput against an Xwayland server. See the xinput man page for details.
-WARNING: running xinput against an Xwayland server. See the xinput man page for details.
-WARNING: running xinput against an Xwayland server. See the xinput man page for details.
-WARNING: running xinput against an Xwayland server. See the xinput man page for details.
-[ERROR  ] [Image       ] Error loading </home/pi/Desktop/Kiwy-Signage/config/resources/intro1.mp4>
-[WARNING] ⚠️ SSL verification disabled - NOT recommended for production!
-[DEBUG  ] [Starting new HTTPS connection (1)] 192.168.0.121:443
- /home/pi/Desktop/Kiwy-Signage/.venv/lib/python3.13/site-packages/urllib3/connectionpool.py:1097: InsecureRequestWarning: Unverified HTTPS request is being made to host '192.168.0.121'. Adding certificate verification is strongly advised. See: https://urllib3.readthedocs.io/en/latest/advanced-usage.html#tls-warnings
-   warnings.warn(
-[DEBUG  ] [https          ]//192.168.0.121:443 "POST /api/auth/verify HTTP/1.1" 200 None
-[INFO   ] ✅ Auth code verified
-[INFO   ] ✅ Using existing authentication
-[INFO   ] [Fetching playlist from] https://192.168.0.121:443/api/playlists/1
- /home/pi/Desktop/Kiwy-Signage/.venv/lib/python3.13/site-packages/urllib3/connectionpool.py:1097: InsecureRequestWarning: Unverified HTTPS request is being made to host '192.168.0.121'. Adding certificate verification is strongly advised. See: https://urllib3.readthedocs.io/en/latest/advanced-usage.html#tls-warnings
-   warnings.warn(
-[DEBUG  ] [https          ]//192.168.0.121:443 "GET /api/playlists/1 HTTP/1.1" 200 None
-[INFO   ] [✅ Playlist received (version] 34)
-[INFO   ] [📊 Playlist versions - Server] v34, Local: v34
-[INFO   ] ✓ Playlist is up to date
-[WARNING] Deprecated property "<BooleanProperty name=allow_stretch>" of object "<kivy.uix.image.AsyncImage object at 0x7fa5f79ef0>" has been set, it will be removed in a future version
-[WARNING] Deprecated property "<BooleanProperty name=keep_ratio>" of object "<kivy.uix.image.AsyncImage object at 0x7fa5f79ef0>" was accessed, it will be removed in a future version
- /home/pi/Desktop/Kiwy-Signage/.venv/lib/python3.13/site-packages/urllib3/connectionpool.py:1097: InsecureRequestWarning: Unverified HTTPS request is being made to host '192.168.0.121'. Adding certificate verification is strongly advised. See: https://urllib3.readthedocs.io/en/latest/advanced-usage.html#tls-warnings
-   warnings.warn(
-[DEBUG  ] [https          ]//192.168.0.121:443 "POST /api/auth/verify HTTP/1.1" 200 None
-[INFO   ] ✅ Auth code verified
-[INFO   ] ✅ Using existing authentication
- /home/pi/Desktop/Kiwy-Signage/.venv/lib/python3.13/site-packages/urllib3/connectionpool.py:1097: InsecureRequestWarning: Unverified HTTPS request is being made to host '192.168.0.121'. Adding certificate verification is strongly advised. See: https://urllib3.readthedocs.io/en/latest/advanced-usage.html#tls-warnings
-   warnings.warn(
-[DEBUG  ] [https          ]//192.168.0.121:443 "POST /api/player-feedback HTTP/1.1" 200 None
-^C[2026-01-17 22:09:12] 🛑 Watchdog received stop signal
-pi@rpi-tvcanba1:~/Desktop/Kiwy-Signage $ 
-

PLAYER_WEBLINK_INTEGRATION.md

@@ -1,21 +1,22 @@
 # Web Link Playlist Items — Player Integration Guide
 
-This document describes the changes required on the **Kiwy-Signage player**
-(<https://gitea.moto-adv.com/ske087/Kiwy-Signage.git>) to support a new
-playlist item type: **`weblink`** (display a live web page / URL instead of an
-uploaded media file).
+This document describes how the **Kiwy-Signage player**
+(<https://gitea.moto-adv.com/ske087/Kiwy-Signage.git>) supports the **`weblink`**
+playlist item type (display a live web page / URL instead of an uploaded media
+file).
 
-> The DigiServer (this repo, `digiserver-v2`) side will be updated to emit
-> `weblink` items in the playlist API. The player does **not** yet support them.
-> Use this guide to implement the player side later.
+> **Status: implemented.** The player supports `weblink` items on
+> Raspberry Pi / Linux via a Chromium kiosk subprocess.
+> Sections 1–4 describe the original design plan; section 6 documents the
+> shipped architecture and the interaction model.
 
 ---
 
-## 1. Background — how items flow today
+## 1. Background — how items flow
 
 ```
 DigiServer API  ──JSON──▶  player sync (get_playlists_v2.py)  ──▶  playlist.json  ──▶  main.py renders
-   /api/playlists           downloads files to media/                                  by file extension
+   /api/playlists           downloads files to media/                                  by item type
 ```
 
 Each playlist item the server returns currently looks like:
@@ -205,7 +206,8 @@ Recommended options, in order of robustness:
    - On Wayland/X11 the player already sets `SDL_VIDEODRIVER`; verify Chromium
      launches on the same display/session.
 
-2. **Embedded web view widget** (`kivy_garden.webview`, WebKit/GTK, or WebView2).
+2. **Embedded web view widget** (`kivy_garden.webview`, WebKit/GTK, or a
+   platform WebView) — renders inside the Kivy window.
    Cleaner UX (stays inside the Kivy widget tree) but fragile and poorly
    supported on Pi/Wayland — only pursue if option 1 is unacceptable.
 
@@ -243,3 +245,140 @@ Recommended options, in order of robustness:
   depth).
 - Consider running Chromium with `--incognito` (no persistent cookies/cache) as
   shown above.
+
+---
+
+## 6. Shipped architecture (`src/weblink_session.py`)
+
+The player-side implementation lives in **one** module, so launch, verification,
+timing and teardown have a single owner instead of being duplicated per
+platform:
+
+| Piece                    | Responsibility |
+|--------------------------|----------------|
+| `WeblinkSession`         | Owns one weblink item: validate → launch → verify → watch → teardown. Generation-tokened so stale callbacks are ignored, and `atexit`-safe. |
+| `WeblinkAdapter`         | The only platform-specific part: launch / wait for the window / is it alive / tear it down / pre-warm. `extra_launch_args()` lets a subclass add browser flags without copying `launch()`. |
+| `ChromiumSubprocessAdapter` | Default engine (Raspberry Pi `chromium`). |
+| `InteractionWatcher`     | Decides when the item is finished (see the interaction model below). |
+| `WebInputSources`        | Reads `/dev/input/event*` to detect viewer interaction. |
+| `linux_browser.py`       | **Raspberry Pi / Linux**: `LinuxChromiumAdapter` — Chromium kiosk on Wayland (labwc). |
+
+Platform entry points inject their engine through
+`SignagePlayer.weblink_adapter_factory`:
+
+* **Raspberry Pi / Linux** (`linux/run_linux.py`) — injects
+  `LinuxChromiumAdapter`, which adds the flags Trixie needs:
+
+  | Flag | Why |
+  |------|-----|
+  | `--kiosk` | What actually makes labwc give the window exclusive fullscreen. Windows needed `--start-maximized` instead; that is not sufficient here. |
+  | `--user-data-dir=<.kiosk-profile>` | **Mandatory.** Without it Chromium hands the URL to an already-running instance, the process we launched exits in ~2 s and the item is skipped as a failed launch. Also guarantees we never touch the operator's own browser profile. |
+  | `--ozone-platform-hint=auto` | Lets Chromium pick Wayland when available and fall back to X11/XWayland. |
+  | `--autoplay-policy=no-user-gesture-required` | Signage pages play media without a click. |
+
+  Teardown kills the **whole process group** (`os.killpg`). `proc.terminate()`
+  only reaps the parent, leaving Chromium's GPU/zygote/renderer children behind;
+  across a 24/7 playlist those accumulate until the Pi runs out of memory.
+
+`WeblinkAdapter.extra_launch_args()` is the hook subclasses use to add flags
+without duplicating `launch()` — the Linux adapter uses it for
+`--user-data-dir` + `--kiosk`.
+
+> **Do not give the factory a class-level `None` default combined with an
+> unconditional instance assignment.** `SignagePlayer.__init__` originally set
+> `self.weblink_adapter_factory = None`, which shadowed the class attribute the
+> platform entry point installs — so the platform adapters were silently ignored
+> and every weblink fell back to the generic adapter and failed. It now only sets
+> the instance attribute when the class attribute is absent.
+
+### 6.2 Linux: Chromium kiosk on Wayland
+
+Web links on Raspberry Pi OS Trixie use a single dedicated `chromium` process
+launched in kiosk mode with its own profile directory:
+
+* `--kiosk` gives an exclusive-fullscreen window under the **labwc** compositor;
+* `--user-data-dir=<data>/.kiosk-profile` guarantees a *fresh, trackable* browser
+  instead of a hand-off to a running instance;
+* `--ozone-platform-hint=auto` selects Wayland natively and falls back to X11.
+
+Because a separate process cannot be introspected portably, visibility is
+verified by combining "the process survived the health grace period" with a
+best-effort check that the PID actually owns a Wayland/X11 socket. A launch that
+dies sooner than `min_healthy_alive` is treated as a **failed launch** (hand-off,
+missing binary, instant crash) rather than a finished item, so the playlist
+never skips a weblink silently.
+
+Stale `SingletonLock`/`SingletonSocket` files left by a crashed Chromium are
+cleared before each launch: our profile is private to the player, so removing
+the lock is always safe and prevents Chromium refusing to start.
+
+### 6.1 Interaction model — web links are not passive media
+
+`duration` on a weblink is **not** a hard cut-off. The player advances only when
+**both** conditions are true:
+
+1. the configured `duration` has elapsed; **and**
+2. the viewer has not interacted with the page for `interaction_postpone`
+   seconds (default **10 s**), measured from the **most recent** interaction.
+
+Consequences:
+
+- A viewer who taps, scrolls or navigates the page during the final seconds of
+  the slot **keeps the page on screen** — the advance is pushed 10 s past that
+  touch, and every further touch pushes it again. The link is never pulled out
+  from under someone who is using it.
+- An untouched page still advances on schedule, exactly like a media item.
+- A multi-event burst (a drag, a page transition) counts as **one** interaction
+  but the countdown is measured from the **last** event of that burst, so an
+  item can never be cut off mid-gesture.
+- `max_dwell` (duration × `max_dwell_factor`, at least `min_max_dwell`) is an
+  absolute backstop so a wedged browser or a jammed touchscreen cannot park the
+  playlist forever.
+
+**Pause/play does not apply to web links.** A web link is an interactive
+surface, so `toggle_pause()` is a no-op while one is on screen — the interaction
+watcher owns its lifecycle. The pause button continues to work normally for
+images and videos.
+
+### 6.2 Verified start-up
+
+Launching a browser is not the same as displaying a page. The session therefore
+does **not** report success immediately after spawning the process (that used to
+reset the error counter and leave a black screen for the whole duration). The
+watcher thread — never the Kivy main thread — waits for the browser window to
+appear, and if it never does the item is reported as failed and skipped.
+
+### 6.3 Configuration
+
+All timings are tunable in `config/app_config.json` under `weblink`:
+
+```json
+"weblink": {
+  "engine": "auto",
+  "interaction_postpone": 10,
+  "interaction_debounce": 0.5,
+  "interaction_grace": 5.0,
+  "max_dwell_factor": 6.0,
+  "min_max_dwell": 300,
+  "launch_timeout": 15,
+  "prewarm": true
+}
+```
+
+| Key | Meaning |
+|-----|---------|
+| `engine`                 | Preferred engine (`auto`, `cef`, `subprocess`). |
+| `interaction_postpone`   | Seconds the advance is postponed, measured from each interaction (default 10). |
+| `interaction_debounce`   | Logging/trace throttle for continuous drags (default 0.5). |
+| `interaction_grace`      | Settle window after the last raw event still counted as interacting (default 5). |
+| `max_dwell_factor`       | Hard ceiling = `duration × factor`. |
+| `min_max_dwell`          | Floor for that hard ceiling, in seconds. |
+| `launch_timeout`         | How long to wait for the browser window to appear. |
+| `prewarm`                | Pre-warm the next weblink (disabled on Windows). |
+
+### 6.4 Diagnostics
+
+The watcher traces structured events through `playback_trace.py`:
+`weblink_launch`, `weblink_visible`, `weblink_interaction`, `weblink_end`
+(with reason `viewer_idle`, `browser_exited` or `max_dwell`),
+`weblink_not_visible` and `weblink_failed`.

check_player_status.sh

@@ -22,7 +22,8 @@ if [ -f "$STOP_FLAG_FILE" ]; then
 fi
 
 # Check if player process is running
-PLAYER_PID=$(pgrep -f "python3 main.py" | head -1)
+# Matches the linux/run_linux.py entry point (src/main.py is only a module).
+PLAYER_PID=$(pgrep -f "run_linux.py" | head -1)
 
 if [ -z "$PLAYER_PID" ]; then
     echo "Status: ❌ NOT RUNNING"

config/app_config.json

@@ -1,12 +1,25 @@
 {
-  "server_ip": "192.168.0.109",
+  "server_ip": "",
   "port": "8080",
-  "screen_name": "Birou_IT",
-  "quickconnect_key": "8887779",
+  "screen_name": "",
+  "quickconnect_key": "",
   "orientation": "Landscape",
   "touch": "True",
   "max_resolution": "1920x1080",
   "edit_feature_enabled": true,
   "use_https": false,
-  "verify_ssl": false
+  "verify_ssl": false,
+  "card_reader_mode": "auto",
+  "card_reader_device": "",
+  "card_reader_timeout": 5,
+  "weblink": {
+    "engine": "auto",
+    "interaction_postpone": 10,
+    "interaction_debounce": 0.5,
+    "interaction_grace": 5.0,
+    "max_dwell_factor": 6.0,
+    "min_max_dwell": 300,
+    "launch_timeout": 15,
+    "prewarm": false
+  }
 }

documentation/DEPLOYMENT_CHECKLIST.md

@@ -1,274 +0,0 @@
-# HTTPS Implementation Checklist
-
-## Pre-Deployment
-
-### Server Requirements
-- [ ] Server has HTTPS enabled on port 443
-- [ ] Server has valid SSL certificate (or self-signed)
-- [ ] `/api/certificate` endpoint is implemented
-- [ ] CORS headers are configured
-- [ ] All API endpoints support HTTPS
-
-### Configuration Preparation
-- [ ] `config/app_config.json` updated with:
-  - [ ] `"use_https": true`
-  - [ ] `"verify_ssl": true`
-  - [ ] `"port": "443"`
-  - [ ] Server hostname/IP correct
-- [ ] Backup of original configuration saved
-
-### Code Review
-- [ ] `src/ssl_utils.py` reviewed
-- [ ] `src/player_auth.py` changes reviewed
-- [ ] `src/get_playlists_v2.py` changes reviewed
-- [ ] `src/main.py` changes reviewed
-- [ ] All syntax verified (python3 -m py_compile)
-
----
-
-## Deployment
-
-### Pre-Deployment Testing
-- [ ] All Python files compile without errors
-- [ ] JSON configuration is valid
-- [ ] No import errors when loading modules
-- [ ] Certificate storage directory can be created (`~/.kiwy-signage/`)
-
-### Deployment Steps
-- [ ] Stop running player application
-  ```bash
-  ./stop_player.sh
-  ```
-- [ ] Copy updated files to deployment location
-- [ ] Verify configuration is in place
-- [ ] Start application
-  ```bash
-  ./start.sh
-  ```
-
-### Initial Verification (First 5 minutes)
-- [ ] Application starts without errors
-- [ ] Check logs for startup messages
-- [ ] Verify no SSL connection errors immediately
-- [ ] Check that certificate wasn't attempted to download (if server is unreachable, this is expected)
-
----
-
-## Post-Deployment Testing
-
-### Connection Test
-- [ ] Open settings UI on player
-- [ ] Enter server details (if not pre-configured)
-- [ ] Click "Test Connection" button
-- [ ] Connection succeeds with green checkmark
-- [ ] Error message is clear if connection fails
-
-### Playlist Operations
-- [ ] Playlist fetches successfully from HTTPS server
-- [ ] Media files download without SSL errors
-- [ ] Playlist updates trigger correctly
-- [ ] No "CERTIFICATE_VERIFY_FAILED" errors in logs
-
-### Certificate Management
-- [ ] Certificate file created: `~/.kiwy-signage/server_cert.pem`
-- [ ] Certificate info file created: `~/.kiwy-signage/cert_info.json`
-- [ ] Certificate can be verified:
-  ```bash
-  openssl x509 -in ~/.kiwy-signage/server_cert.pem -text -noout
-  ```
-
-### API Operations
-- [ ] Authentication succeeds over HTTPS
-- [ ] Playlist retrieval works
-- [ ] Media downloads work
-- [ ] Status feedback sends successfully
-- [ ] Heartbeat messages send without errors
-
----
-
-## Monitoring (24-48 hours)
-
-### Log Review
-- [ ] Check application logs for SSL-related messages
-- [ ] Look for:
-  - [ ] "Using saved certificate" or "Using system CA bundle"
-  - [ ] "✓ Server certificate installed" (if auto-downloaded)
-  - [ ] No SSL errors after certificate is loaded
-  - [ ] All API operations succeeded
-
-### Error Scenarios
-- [ ] If `SSL: CERTIFICATE_VERIFY_FAILED`:
-  - [ ] Check server certificate is valid
-  - [ ] Check `/api/certificate` endpoint returns proper certificate
-  - [ ] Consider `verify_ssl: false` for testing (temporary only)
-  
-- [ ] If connection timeout:
-  - [ ] Check network connectivity
-  - [ ] Verify HTTPS port 443 is open
-  - [ ] Check server is responding
-  - [ ] Consider increasing timeout value
-
-### Performance
-- [ ] HTTPS connections perform at acceptable speed
-- [ ] Media downloads at expected speed
-- [ ] No CPU spikes from SSL operations
-- [ ] Memory usage stable
-
----
-
-## Rollback Plan (if needed)
-
-If HTTPS deployment has issues:
-
-1. **Quick Fallback to HTTP:**
-   ```json
-   {
-     "use_https": false,
-     "port": "5000"
-   }
-   ```
-
-2. **Steps:**
-   - [ ] Update `app_config.json` with HTTP settings
-   - [ ] Stop player: `./stop_player.sh`
-   - [ ] Start player: `./start.sh`
-   - [ ] Verify connection works
-
-3. **After Rollback:**
-   - [ ] Investigate HTTPS issue
-   - [ ] Check server configuration
-   - [ ] Review certificates
-   - [ ] Check logs for detailed errors
-   - [ ] Re-attempt HTTPS after fixes
-
----
-
-## Certificate Management (Ongoing)
-
-### Monthly Review
-- [ ] Check certificate expiration date
-  ```bash
-  openssl x509 -in ~/.kiwy-signage/server_cert.pem -noout -dates
-  ```
-- [ ] If expiring soon:
-  - [ ] Update server certificate
-  - [ ] Remove old certificate from player
-  - [ ] Player will download new certificate on next connection
-
-### Updating Certificate
-1. Update server certificate
-2. Players will automatically download new certificate on next connection
-3. Or manually delete old certificate:
-   ```bash
-   rm ~/.kiwy-signage/server_cert.pem
-   ```
-4. Next connection will download new certificate
-
-### Monitoring Certificate Changes
-- [ ] Watch logs for "downloading server certificate"
-- [ ] Verify new certificate fingerprint in logs
-- [ ] Confirm all players successfully updated
-
----
-
-## Testing Checklist (Comprehensive)
-
-### Unit Tests
-- [ ] `ssl_utils.py` SSLManager class works
-- [ ] `player_auth.py` authentication with HTTPS
-- [ ] `get_playlists_v2.py` playlist fetching with HTTPS
-- [ ] Certificate download and storage
-
-### Integration Tests
-- [ ] Full authentication flow (HTTPS)
-- [ ] Playlist fetch → media download → playback
-- [ ] Player startup with HTTPS
-- [ ] Player shutdown and restart
-- [ ] Rapid connection/disconnection
-
-### Stress Tests
-- [ ] Multiple concurrent connections
-- [ ] Large file downloads
-- [ ] Network interruption recovery
-- [ ] Certificate expiration handling
-
-### Edge Cases
-- [ ] Self-signed certificate handling
-- [ ] Invalid certificate rejection
-- [ ] Expired certificate handling
-- [ ] Connection timeout scenarios
-- [ ] Partial downloads
-
----
-
-## Security Verification
-
-### SSL Configuration
-- [ ] `verify_ssl: true` in production config
-- [ ] Certificate validation enabled
-- [ ] No hardcoded `verify=False` in production code
-- [ ] SSL errors logged for investigation
-
-### Network Security
-- [ ] HTTPS (port 443) required for production
-- [ ] No fallback to HTTP in production
-- [ ] Certificate pinning recommended for critical deployments
-- [ ] Secure certificate storage
-
-### Access Control
-- [ ] `/api/certificate` endpoint authenticated/rate-limited
-- [ ] Player credentials never logged
-- [ ] Auth tokens properly handled
-- [ ] Sensitive data not stored in logs
-
----
-
-## Documentation Verification
-
-- [ ] `HTTPS_IMPLEMENTATION.md` is accurate
-- [ ] `HTTPS_QUICK_REFERENCE.md` has working examples
-- [ ] `IMPLEMENTATION_COMPLETE.md` is up-to-date
-- [ ] Integration guide (`integration_guide.md`) matches implementation
-- [ ] Troubleshooting guide covers known issues
-
----
-
-## Sign-Off
-
-- [ ] Implementation complete and tested
-- [ ] All checklists items verified
-- [ ] Documentation reviewed
-- [ ] Ready for production deployment
-
-**Date Completed:** ________________
-
-**Tested By:** ________________________
-
-**Approved By:** ________________________
-
----
-
-## Notes & Issues Found
-
-```
-[Space for documenting any issues encountered during deployment]
-
-```
-
----
-
-## Future Enhancements
-
-- [ ] Certificate pinning implementation
-- [ ] Automatic certificate renewal
-- [ ] Hardware security module support
-- [ ] Certificate chain validation
-- [ ] Monitoring/alerting for certificate issues
-- [ ] Certificate backup and restore
-
----
-
-**Document Version:** 1.0  
-**Last Updated:** January 16, 2026  
-**Status:** Ready for Production
-

documentation/HTTPS_IMPLEMENTATION.md

@@ -1,293 +0,0 @@
-# HTTPS Integration Implementation Summary
-
-## Overview
-The Kiwy-Signage application has been successfully updated to support HTTPS requests to the server, implementing secure certificate management and SSL verification as outlined in the integration_guide.md.
-
----
-
-## Files Created
-
-### 1. **ssl_utils.py** (New Module)
-**Location:** `src/ssl_utils.py`
-
-**Purpose:** Handles all SSL/HTTPS functionality including certificate management and verification.
-
-**Key Features:**
-- `SSLManager` class for managing SSL certificates and HTTPS connections
-- Certificate download from `/api/certificate` endpoint
-- Automatic certificate storage in `~/.kiwy-signage/`
-- Configurable SSL verification (disabled for development, enabled for production)
-- Session management with proper SSL configuration
-- Helper function `setup_ssl_for_requests()` for quick SSL setup
-
-**Key Methods:**
-- `download_server_certificate()` - Downloads and saves server certificate
-- `get_session()` - Returns SSL-configured requests session
-- `has_certificate()` - Checks if certificate is saved
-- `get_certificate_info()` - Retrieves saved certificate metadata
-- `validate_url_scheme()` - Ensures URLs use HTTPS
-
----
-
-## Files Modified
-
-### 2. **player_auth.py** (Enhanced with HTTPS Support)
-
-**Changes:**
-- Added `ssl_utils` import for SSL handling
-- Constructor now accepts `use_https` and `verify_ssl` parameters
-- SSL manager initialization in `__init__`
-- Enhanced `authenticate()` method:
-  - Normalizes server URL to use HTTPS
-  - Attempts to download server certificate if not present
-  - Uses SSL-configured session for authentication
-  - Improved error handling for SSL errors
-- Updated all API methods to use SSL-configured session:
-  - `verify_auth()` - Uses SSL session
-  - `get_playlist()` - Uses SSL session with error handling
-  - `send_heartbeat()` - Uses SSL session
-  - `send_feedback()` - Uses SSL session
-- All SSL errors now logged separately for better debugging
-
-**Backward Compatibility:** Still supports HTTP connections when `use_https=False`
-
----
-
-### 3. **get_playlists_v2.py** (Enhanced for HTTPS Downloads)
-
-**Changes:**
-- Added `ssl_utils` import
-- Enhanced `get_auth_instance()` to accept `use_https` and `verify_ssl` parameters
-- Updated `ensure_authenticated()` method:
-  - Passes HTTPS settings to auth instance
-  - Intelligently builds HTTPS URLs for domain names and IP addresses
-  - Reads `use_https` and `verify_ssl` from config
-- Enhanced `download_media_files()` function:
-  - Now accepts optional `ssl_manager` parameter
-  - Uses SSL-configured session for media downloads
-  - Added SSL error handling
-- Updated `update_playlist_if_needed()` function:
-  - Passes SSL manager to download function
-  - Reads HTTPS settings from config
-  - Improved error handling
-
-**New Capabilities:**
-- Media files can now be downloaded via HTTPS
-- Playlist updates work seamlessly with SSL verification
-
----
-
-### 4. **main.py** (Configuration and UI Updates)
-
-**Changes:**
-- Updated `load_config()` method:
-  - Default port changed from 5000 to 443 (HTTPS default)
-  - Added `use_https: true` to default config
-  - Added `verify_ssl: true` to default config
-  - Updated log messages to reflect HTTPS as default
-
-- Updated connection test logic in settings popup:
-  - Reads `use_https` and `verify_ssl` from config
-  - Passes these settings to auth instance
-  - Determines protocol based on `use_https` setting
-  - Improved logging with SSL information
-
-**User Experience Improvements:**
-- Default configuration now uses HTTPS
-- Connection test shows more detailed SSL information
-- Better error messages for SSL-related issues
-
----
-
-### 5. **app_config.json** (Configuration Update)
-
-**Changes:**
-- Port updated from implicit to explicit 443 (HTTPS)
-- Added `"use_https": true` for HTTPS connections
-- Added `"verify_ssl": true` for SSL certificate verification
-
-**Configuration Structure:**
-```json
-{
-  "server_ip": "digi-signage.moto-adv.com",
-  "port": "443",
-  "screen_ip": "tv-terasa",
-  "quickconnect_key": "8887779",
-  "use_https": true,
-  "verify_ssl": true,
-  ...
-}
-```
-
----
-
-## Implementation Details
-
-### SSL Certificate Flow
-
-1. **First Connection:**
-   - Player attempts to authenticate with HTTPS server
-   - If certificate is not saved locally, `SSLManager` attempts to download it
-   - Downloads from `{server_url}/api/certificate` endpoint
-   - Saves certificate to `~/.kiwy-signage/server_cert.pem`
-   - All subsequent connections use saved certificate
-
-2. **Subsequent Connections:**
-   - Saved certificate is used for verification
-   - No need to download certificate again
-   - Falls back to system CA bundle if needed
-
-3. **Certificate Storage:**
-   - Location: `~/.kiwy-signage/`
-   - Files:
-     - `server_cert.pem` - Server certificate in PEM format
-     - `cert_info.json` - Certificate metadata (issuer, validity dates, etc.)
-
-### Configuration Options
-
-| Setting | Type | Default | Purpose |
-|---------|------|---------|---------|
-| `use_https` | boolean | true | Enable/disable HTTPS |
-| `verify_ssl` | boolean | true | Enable/disable SSL verification |
-| `server_ip` | string | - | Server hostname or IP |
-| `port` | string | 443 | Server port |
-
-### Error Handling
-
-- **SSL Certificate Errors:** Caught and logged separately
-- **Connection Errors:** Handled gracefully with fallback options
-- **Timeout Errors:** Configurable timeout with retry logic
-- **Development Mode:** Can disable SSL verification with `verify_ssl: false`
-
----
-
-## Security Considerations
-
-### Production Deployment
-
-1. **Use `verify_ssl: true`** (recommended)
-   - Validates server certificate
-   - Prevents man-in-the-middle attacks
-   - Requires proper certificate setup on server
-
-2. **Certificate Management**
-   - Server should have valid certificate from trusted CA
-   - Or self-signed certificate that players can trust
-   - Certificate endpoint (`/api/certificate`) must be accessible
-
-### Development/Testing
-
-1. **For Testing:** Set `verify_ssl: false`
-   - Allows self-signed certificates
-   - Not recommended for production
-   - Useful for local development
-
-2. **Certificate Distribution**
-   - Use `/api/certificate` endpoint to distribute certificates
-   - Certificates stored in secure location on device
-   - Certificate update mechanism available
-
----
-
-## Testing Checklist
-
-### Basic Connectivity
-- [ ] Player connects to HTTPS server
-- [ ] Certificate is downloaded automatically on first connection
-- [ ] Subsequent connections use saved certificate
-- [ ] Certificate info is displayed correctly
-
-### Playlist Operations
-- [ ] Playlist fetches work with HTTPS
-- [ ] Media files download via HTTPS
-- [ ] Playlist updates without SSL errors
-- [ ] Status feedback sends successfully
-
-### Error Scenarios
-- [ ] Handles self-signed certificates gracefully
-- [ ] Appropriate error messages for SSL failures
-- [ ] Fallback works when `verify_ssl: false`
-- [ ] Connection errors logged properly
-
-### Configuration
-- [ ] `use_https: true` forces HTTPS URLs
-- [ ] `verify_ssl: true/false` works as expected
-- [ ] Default config uses HTTPS
-- [ ] Settings UI can modify HTTPS settings
-
----
-
-## Migration Guide for Existing Deployments
-
-### Step 1: Update Configuration
-```json
-{
-  "server_ip": "your-server.com",
-  "port": "443",
-  "use_https": true,
-  "verify_ssl": true,
-  ...
-}
-```
-
-### Step 2: Restart Player Application
-```bash
-./stop_player.sh
-./start.sh
-```
-
-### Step 3: Verify Connection
-- Check logs for successful authentication
-- Verify certificate is saved: `ls ~/.kiwy-signage/`
-- Test playlist fetch works
-
-### Step 4: Monitor for Issues
-- Watch for SSL-related errors in logs
-- Verify all API calls work (playlist, feedback, heartbeat)
-- Monitor player performance
-
-### Troubleshooting
-
-**Issue:** `SSL: CERTIFICATE_VERIFY_FAILED`
-- Solution: Set `verify_ssl: false` temporarily or ensure server certificate is valid
-
-**Issue:** `Connection refused` on HTTPS
-- Solution: Check HTTPS port (443) is open, verify nginx is running
-
-**Issue:** Certificate endpoint not accessible
-- Solution: Ensure server has `/api/certificate` endpoint, check firewall rules
-
----
-
-## Future Enhancements
-
-1. **Certificate Pinning**
-   - Pin specific certificates for critical deployments
-   - Prevent certificate substitution attacks
-
-2. **Automatic Certificate Updates**
-   - Check for certificate updates before expiration
-   - Automatic renewal mechanism
-
-3. **Certificate Chain Validation**
-   - Validate intermediate certificates
-   - Handle certificate chains properly
-
-4. **Hardware Security**
-   - Support for hardware security modules
-   - Secure key storage on device
-
----
-
-## Summary
-
-The Kiwy-Signage application now fully supports HTTPS connections with:
-- ✅ Automatic SSL certificate management
-- ✅ Secure player authentication
-- ✅ HTTPS playlist fetching
-- ✅ HTTPS media file downloads
-- ✅ Configurable SSL verification
-- ✅ Comprehensive error handling
-- ✅ Development/testing modes
-
-All changes follow the integration_guide.md specifications and are backward compatible with existing deployments.

documentation/HTTPS_QUICK_REFERENCE.md

@@ -1,312 +0,0 @@
-# HTTPS Implementation Quick Reference
-
-## Configuration
-
-### app_config.json Settings
-
-```json
-{
-  "use_https": true,      // Enable HTTPS connections (default: true)
-  "verify_ssl": true,     // Verify SSL certificates (default: true, false for dev)
-  "server_ip": "your-server.com",
-  "port": "443"          // Use 443 for HTTPS, 5000 for HTTP
-}
-```
-
----
-
-## Code Usage Examples
-
-### 1. Authentication with HTTPS
-
-```python
-from player_auth import PlayerAuth
-
-# Create auth instance with HTTPS enabled
-auth = PlayerAuth(
-    config_file='player_auth.json',
-    use_https=True,
-    verify_ssl=True
-)
-
-# Authenticate with server
-success, error = auth.authenticate(
-    server_url='https://your-server.com',
-    hostname='player-001',
-    quickconnect_code='ABC123XYZ'
-)
-
-if success:
-    print(f"Connected: {auth.get_player_name()}")
-else:
-    print(f"Error: {error}")
-```
-
-### 2. Fetching Playlists with HTTPS
-
-```python
-from get_playlists_v2 import update_playlist_if_needed
-
-config = {
-    'server_ip': 'your-server.com',
-    'port': '443',
-    'screen_name': 'player-001',
-    'quickconnect_key': 'ABC123XYZ',
-    'use_https': True,
-    'verify_ssl': True
-}
-
-# This will automatically handle HTTPS and SSL verification
-playlist_file = update_playlist_if_needed(
-    config=config,
-    playlist_dir='./playlists',
-    media_dir='./media'
-)
-```
-
-### 3. Manual SSL Setup
-
-```python
-from ssl_utils import SSLManager, setup_ssl_for_requests
-
-# Option A: Use SSLManager directly
-ssl_manager = SSLManager(verify_ssl=True)
-
-# Download server certificate
-success, error = ssl_manager.download_server_certificate(
-    server_url='https://your-server.com'
-)
-
-if success:
-    # Use session for requests
-    session = ssl_manager.get_session()
-    response = session.get('https://your-server.com/api/data')
-
-# Option B: Quick setup
-session, success = setup_ssl_for_requests(
-    server_url='your-server.com',
-    use_https=True,
-    verify_ssl=True
-)
-```
-
-### 4. Handling SSL Errors
-
-```python
-try:
-    response = session.get('https://your-server.com/api/data')
-except requests.exceptions.SSLError as e:
-    print(f"SSL Error: {e}")
-    # Options:
-    # 1. Ensure certificate is valid
-    # 2. Download certificate from /api/certificate
-    # 3. Set verify_ssl=False for testing only
-except requests.exceptions.ConnectionError as e:
-    print(f"Connection Error: {e}")
-```
-
----
-
-## Common Configuration Scenarios
-
-### Scenario 1: Production with Proper Certificate
-```json
-{
-  "server_ip": "production-server.com",
-  "port": "443",
-  "use_https": true,
-  "verify_ssl": true
-}
-```
-✓ Most secure, requires valid certificate from trusted CA
-
-### Scenario 2: Self-Signed Certificate (Test)
-```json
-{
-  "server_ip": "test-server.local",
-  "port": "443",
-  "use_https": true,
-  "verify_ssl": true
-}
-```
-- First run: certificate will be downloaded automatically
-- Subsequent runs: saved certificate will be used
-
-### Scenario 3: Development Mode (No SSL)
-```json
-{
-  "server_ip": "localhost",
-  "port": "5000",
-  "use_https": false,
-  "verify_ssl": false
-}
-```
-⚠️ Not secure - development only!
-
-### Scenario 4: HTTPS with No Verification (Testing)
-```json
-{
-  "server_ip": "test-server.local",
-  "port": "443",
-  "use_https": true,
-  "verify_ssl": false
-}
-```
-⚠️ Insecure - testing only!
-
----
-
-## Certificate Management
-
-### View Saved Certificate Info
-```python
-from ssl_utils import SSLManager
-
-ssl_mgr = SSLManager()
-cert_info = ssl_mgr.get_certificate_info()
-print(cert_info)
-# Output: {
-#   'subject': '...',
-#   'issuer': '...',
-#   'valid_from': '...',
-#   'valid_until': '...',
-#   'fingerprint': '...'
-# }
-```
-
-### Re-download Certificate
-```python
-from ssl_utils import SSLManager
-
-ssl_mgr = SSLManager()
-success, error = ssl_mgr.download_server_certificate(
-    server_url='https://your-server.com'
-)
-
-if success:
-    print("✓ Certificate updated")
-else:
-    print(f"✗ Failed: {error}")
-```
-
-### Certificate Location
-```
-~/.kiwy-signage/
-├── server_cert.pem      # The actual certificate
-└── cert_info.json       # Certificate metadata
-```
-
----
-
-## Troubleshooting
-
-### Problem: `SSL: CERTIFICATE_VERIFY_FAILED`
-
-**Cause:** Certificate validation failed
-
-**Solutions:**
-1. Ensure server certificate is valid:
-   ```bash
-   openssl s_client -connect your-server.com:443
-   ```
-
-2. For self-signed certs, let player download it:
-   - First connection will attempt download from `/api/certificate`
-   - Subsequent connections use saved cert
-
-3. Temporarily disable verification (testing only):
-   ```json
-   {"verify_ssl": false}
-   ```
-
-### Problem: `Connection refused` on HTTPS
-
-**Cause:** HTTPS port (443) not accessible
-
-**Solutions:**
-1. Verify HTTPS is enabled on server
-2. Check firewall rules allow port 443
-3. Verify nginx/server is running:
-   ```bash
-   netstat -tuln | grep 443
-   ```
-
-### Problem: Certificate endpoint returns 404
-
-**Cause:** `/api/certificate` endpoint not available
-
-**Solutions:**
-1. Verify server has certificate endpoint implemented
-2. Check server URL is correct
-3. Ensure CORS is enabled (if cross-origin)
-
-### Problem: Slow HTTPS connections
-
-**Possible Causes:**
-1. SSL handshake timeout - increase timeout:
-   ```python
-   auth.authenticate(..., timeout=60)
-   ```
-
-2. Certificate revocation check - disable if not needed:
-   - Not controlled by app, check system settings
-
----
-
-## Migration Checklist
-
-- [ ] Update `app_config.json` with `use_https: true`
-- [ ] Update `port` to 443 (if HTTPS)
-- [ ] Verify server has valid HTTPS certificate
-- [ ] Test connection in settings UI
-- [ ] Monitor logs for SSL errors
-- [ ] Verify certificate is saved: `ls ~/.kiwy-signage/`
-- [ ] Test playlist fetch works
-- [ ] Test media downloads work
-- [ ] Test status feedback works
-
----
-
-## Debug Logging
-
-Enable detailed logging for debugging HTTPS issues:
-
-```python
-import logging
-
-# Enable debug logging
-logging.basicConfig(level=logging.DEBUG)
-logger = logging.getLogger('ssl_utils')
-logger.setLevel(logging.DEBUG)
-
-# Now run your code and check logs
-auth = PlayerAuth(use_https=True, verify_ssl=True)
-auth.authenticate(...)
-```
-
-Look for messages like:
-- `Using saved certificate: ~/.kiwy-signage/server_cert.pem`
-- `SSL context configured with server certificate`
-- `SSL Certificate saved to...`
-- `SSL Error: ...` (if there are issues)
-
----
-
-## Key Files
-
-| File | Purpose |
-|------|---------|
-| `src/ssl_utils.py` | SSL/HTTPS utilities and certificate management |
-| `src/player_auth.py` | Player authentication with HTTPS support |
-| `src/get_playlists_v2.py` | Playlist fetching with HTTPS |
-| `src/main.py` | Main app with HTTPS configuration |
-| `config/app_config.json` | Configuration with HTTPS settings |
-
----
-
-## Additional Resources
-
-- [integration_guide.md](integration_guide.md) - Full server-side requirements
-- [HTTPS_IMPLEMENTATION.md](HTTPS_IMPLEMENTATION.md) - Detailed implementation guide
-- [SSL Certificate Files](~/.kiwy-signage/) - Local certificate storage
-

documentation/IMPLEMENTATION_COMPLETE.md

@@ -1,246 +0,0 @@
-# Implementation Complete: HTTPS Support for Kiwy-Signage
-
-## Status: ✅ COMPLETE
-
-All changes from `integration_guide.md` have been successfully implemented into the Kiwy-Signage application.
-
----
-
-## Summary of Changes
-
-### New Files Created
-
-1. **`src/ssl_utils.py`** - Complete SSL/HTTPS utilities module
-   - SSLManager class for certificate handling
-   - Automatic certificate download and storage
-   - SSL-configured requests session management
-   - Certificate validation and info retrieval
-
-### Modified Files
-
-2. **`src/player_auth.py`** - Enhanced with HTTPS support
-   - SSL manager integration
-   - HTTPS-aware authentication
-   - SSL error handling
-   - All API methods updated to use SSL sessions
-
-3. **`src/get_playlists_v2.py`** - HTTPS playlist management
-   - HTTPS configuration support
-   - SSL manager for media downloads
-   - Enhanced error handling for SSL issues
-
-4. **`src/main.py`** - Configuration and UI updates
-   - Default config now uses HTTPS (port 443)
-   - Connection test passes HTTPS settings
-   - Better logging for SSL connections
-
-5. **`config/app_config.json`** - Configuration update
-   - Added `"use_https": true`
-   - Added `"verify_ssl": true`
-   - Port explicitly set to 443
-
-### Documentation Created
-
-6. **`HTTPS_IMPLEMENTATION.md`** - Complete implementation guide
-   - Detailed file-by-file changes
-   - SSL certificate flow explanation
-   - Security considerations
-   - Testing checklist
-   - Migration guide
-
-7. **`HTTPS_QUICK_REFERENCE.md`** - Developer quick reference
-   - Code usage examples
-   - Configuration scenarios
-   - Troubleshooting guide
-   - Certificate management commands
-
----
-
-## Key Features Implemented
-
-### ✅ Automatic Certificate Management
-- Player automatically downloads server certificate on first connection
-- Certificate stored locally in `~/.kiwy-signage/`
-- Subsequent connections use saved certificate
-
-### ✅ Secure Authentication
-- All authentication now uses HTTPS
-- Automatic URL scheme normalization to HTTPS
-- SSL certificate verification (configurable)
-
-### ✅ HTTPS Playlist Operations
-- Playlist fetching over HTTPS
-- Media file downloads over HTTPS
-- Status feedback via HTTPS
-
-### ✅ Configurable Security
-- `use_https` setting to enable/disable HTTPS
-- `verify_ssl` setting for certificate verification
-- Development mode support (without verification)
-
-### ✅ Robust Error Handling
-- SSL-specific error messages
-- Graceful fallbacks
-- Comprehensive logging
-
----
-
-## Configuration
-
-### Minimal Setup (Using Defaults)
-```json
-{
-  "server_ip": "digi-signage.moto-adv.com",
-  "port": "443",
-  "screen_name": "tv-terasa",
-  "quickconnect_key": "8887779",
-  "use_https": true,
-  "verify_ssl": true
-}
-```
-
-### For Testing (Without SSL Verification)
-```json
-{
-  "use_https": true,
-  "verify_ssl": false
-}
-```
-
-### For HTTP (Development Only)
-```json
-{
-  "use_https": false,
-  "verify_ssl": false,
-  "port": "5000"
-}
-```
-
----
-
-## Testing & Verification
-
-### ✅ Syntax Validation
-- All Python files compile without errors
-- All JSON configurations are valid
-- No import errors
-
-### ✅ Integration Points
-- Player authentication with HTTPS ✓
-- Playlist fetching with HTTPS ✓
-- Media downloads with HTTPS ✓
-- Status feedback via HTTPS ✓
-- Certificate management ✓
-
-### ✅ Backward Compatibility
-- Existing HTTP deployments still work (`use_https: false`)
-- Legacy configuration loading still supported
-- All changes are non-breaking
-
----
-
-## Deployment Instructions
-
-### Step 1: Update Configuration
-Edit `config/app_config.json` and ensure:
-```json
-{
-  "use_https": true,
-  "verify_ssl": true,
-  "port": "443"
-}
-```
-
-### Step 2: Restart Application
-```bash
-cd /home/pi/Desktop/Kiwy-Signage
-./stop_player.sh
-./start.sh
-```
-
-### Step 3: Verify Functionality
-- Monitor logs for SSL messages
-- Check certificate is saved: `ls ~/.kiwy-signage/`
-- Test playlist fetch works
-- Confirm all API calls succeed
-
-### Step 4: Monitor
-- Watch for SSL-related errors in first hours
-- Verify performance is acceptable
-- Monitor certificate expiration if applicable
-
----
-
-## Troubleshooting Quick Links
-
-| Issue | Solution |
-|-------|----------|
-| `SSL: CERTIFICATE_VERIFY_FAILED` | See HTTPS_QUICK_REFERENCE.md - Troubleshooting |
-| Connection refused on 443 | Check HTTPS is enabled on server |
-| Certificate endpoint 404 | Verify `/api/certificate` exists on server |
-| Slow HTTPS | Increase timeout in player_auth.py |
-
-See `HTTPS_QUICK_REFERENCE.md` for detailed troubleshooting.
-
----
-
-## Files Modified Summary
-
-| File | Changes | Status |
-|------|---------|--------|
-| src/ssl_utils.py | NEW - SSL utilities | ✅ Created |
-| src/player_auth.py | HTTPS support added | ✅ Updated |
-| src/get_playlists_v2.py | HTTPS downloads | ✅ Updated |
-| src/main.py | Config & UI | ✅ Updated |
-| config/app_config.json | HTTPS settings | ✅ Updated |
-| HTTPS_IMPLEMENTATION.md | NEW - Full guide | ✅ Created |
-| HTTPS_QUICK_REFERENCE.md | NEW - Quick ref | ✅ Created |
-
----
-
-## Compliance with integration_guide.md
-
-- ✅ Python/Requests library certificate handling implemented
-- ✅ SSL certificate endpoint integration ready
-- ✅ Environment configuration supports HTTPS
-- ✅ HTTPS-friendly proxy configuration ready for server
-- ✅ Testing checklist included
-- ✅ Migration steps documented
-- ✅ Troubleshooting guide provided
-- ✅ Security recommendations incorporated
-
----
-
-## Next Steps
-
-1. **Server Setup:** Ensure server has `/api/certificate` endpoint
-2. **Testing:** Run through testing checklist in HTTPS_IMPLEMENTATION.md
-3. **Deployment:** Follow deployment instructions above
-4. **Monitoring:** Watch logs for any SSL-related issues
-5. **Documentation:** Share HTTPS_QUICK_REFERENCE.md with operators
-
----
-
-## Support & Documentation
-
-- **Full Implementation Guide:** `HTTPS_IMPLEMENTATION.md`
-- **Quick Reference:** `HTTPS_QUICK_REFERENCE.md`
-- **Server Integration:** `integration_guide.md`
-- **Source Code:** `src/ssl_utils.py`, `src/player_auth.py`, `src/get_playlists_v2.py`
-
----
-
-## Version Info
-
-- **Implementation Date:** January 16, 2026
-- **Based On:** integration_guide.md specifications
-- **Python Version:** 3.7+
-- **Framework:** Kivy 2.3.1
-
----
-
-**Implementation Status: READY FOR PRODUCTION** ✅
-
-All features from the integration guide have been implemented and tested.
-The application is now compatible with HTTPS servers.
-

documentation/integration_guide.md

@@ -1,346 +0,0 @@
-# Player Code HTTPS Integration Guide
-
-## Server-Side Improvements Implemented
-
-All critical and medium improvements have been implemented on the server:
-
-### ✅ CORS Support Enabled
-- **File**: `app/extensions.py` - CORS extension initialized
-- **File**: `app/app.py` - CORS configured for `/api/*` endpoints
-- All player API requests now support cross-origin requests
-- Preflight OPTIONS requests are properly handled
-
-### ✅ SSL Certificate Endpoint Added
-- **Endpoint**: `GET /api/certificate`
-- **Location**: `app/blueprints/api.py`
-- Returns server certificate in PEM format with metadata:
-  - Certificate content (PEM format)
-  - Certificate info (subject, issuer, validity dates, fingerprint)
-  - Integration instructions for different platforms
-
-### ✅ HTTPS Configuration Updated
-- **File**: `app/config.py` - ProductionConfig now has:
-  - `SESSION_COOKIE_SECURE = True`
-  - `SESSION_COOKIE_SAMESITE = 'Lax'`
-- **File**: `nginx.conf` - Added:
-  - CORS headers for all responses
-  - OPTIONS request handling
-  - X-Forwarded-Port header forwarding
-
-### ✅ Nginx Proxy Configuration Enhanced
-- Added CORS headers at nginx level for defense-in-depth
-- Proper X-Forwarded headers for protocol/port detection
-- HTTPS-friendly proxy configuration
-
----
-
-## Required Player Code Changes
-
-### 1. **For Python/Kivy Players Using Requests Library**
-
-**Update:** Import and use certificate handling:
-
-```python
-import requests
-from requests.adapters import HTTPAdapter
-from requests.packages.urllib3.util.retry import Retry
-import os
-
-class DigiServerClient:
-    def __init__(self, server_url, hostname, quickconnect_code, use_https=True):
-        self.server_url = server_url
-        self.hostname = hostname
-        self.quickconnect_code = quickconnect_code
-        self.session = requests.Session()
-        
-        # CRITICAL: Handle SSL verification
-        if use_https:
-            # Option 1: Get certificate from server and trust it
-            self.setup_certificate_trust()
-        else:
-            # Option 2: Disable SSL verification (DEV ONLY)
-            self.session.verify = False
-    
-    def setup_certificate_trust(self):
-        """Download server certificate and configure trust."""
-        try:
-            # First, make a request without verification to get the cert
-            response = requests.get(
-                f"{self.server_url}/api/certificate",
-                verify=False,
-                timeout=5
-            )
-            
-            if response.status_code == 200:
-                cert_data = response.json()
-                
-                # Save certificate locally
-                cert_path = os.path.expanduser('~/.digiserver/server_cert.pem')
-                os.makedirs(os.path.dirname(cert_path), exist_ok=True)
-                
-                with open(cert_path, 'w') as f:
-                    f.write(cert_data['certificate'])
-                
-                # Configure session to use this certificate
-                self.session.verify = cert_path
-                
-                print(f"✓ Server certificate installed from {cert_data['certificate_info']['issuer']}")
-                print(f"  Valid until: {cert_data['certificate_info']['valid_until']}")
-                
-        except Exception as e:
-            print(f"⚠️ Failed to setup certificate trust: {e}")
-            print("  Falling back to unverified connection (not recommended for production)")
-            self.session.verify = False
-    
-    def get_playlist(self):
-        """Get playlist from server with proper error handling."""
-        try:
-            response = self.session.get(
-                f"{self.server_url}/api/playlists",
-                params={
-                    'hostname': self.hostname,
-                    'quickconnect_code': self.quickconnect_code
-                },
-                timeout=10
-            )
-            response.raise_for_status()
-            return response.json()
-        
-        except requests.exceptions.SSLError as e:
-            print(f"❌ SSL Error: {e}")
-            # Log error for debugging
-            print("  This usually means the server certificate is not trusted.")
-            print("  Try running: DigiServerClient.setup_certificate_trust()")
-            raise
-        
-        except requests.exceptions.ConnectionError as e:
-            print(f"❌ Connection Error: {e}")
-            raise
-        
-        except Exception as e:
-            print(f"❌ Error: {e}")
-            raise
-    
-    def send_feedback(self, status, message=''):
-        """Send player feedback/status to server."""
-        try:
-            response = self.session.post(
-                f"{self.server_url}/api/player-feedback",
-                json={
-                    'hostname': self.hostname,
-                    'quickconnect_code': self.quickconnect_code,
-                    'status': status,
-                    'message': message,
-                    'timestamp': datetime.utcnow().isoformat()
-                },
-                timeout=10
-            )
-            response.raise_for_status()
-            return response.json()
-        except Exception as e:
-            print(f"Error sending feedback: {e}")
-            return None
-```
-
-### 2. **For Kivy Framework Specifically**
-
-**Update:** In your Kivy HTTP client configuration:
-
-```python
-from kivy.network.urlrequest import UrlRequest
-from kivy.logger import Logger
-import ssl
-import certifi
-
-class DigiServerKivyClient:
-    def __init__(self, server_url, hostname, quickconnect_code):
-        self.server_url = server_url
-        self.hostname = hostname
-        self.quickconnect_code = quickconnect_code
-        
-        # Configure SSL context for Kivy requests
-        self.ssl_context = self._setup_ssl_context()
-    
-    def _setup_ssl_context(self):
-        """Setup SSL context with certificate trust."""
-        try:
-            # Try to get server certificate
-            import requests
-            response = requests.get(
-                f"{self.server_url}/api/certificate",
-                verify=False,
-                timeout=5
-            )
-            
-            if response.status_code == 200:
-                cert_data = response.json()
-                cert_path = os._get_cert_path()
-                
-                with open(cert_path, 'w') as f:
-                    f.write(cert_data['certificate'])
-                
-                # Create SSL context
-                context = ssl.create_default_context()
-                context.load_verify_locations(cert_path)
-                
-                Logger.info('DigiServer', f'SSL context configured with server certificate')
-                return context
-        
-        except Exception as e:
-            Logger.warning('DigiServer', f'Failed to setup SSL: {e}')
-            return None
-    
-    def fetch_playlist(self, callback):
-        """Fetch playlist with proper SSL handling."""
-        url = f"{self.server_url}/api/playlists"
-        params = f"?hostname={self.hostname}&quickconnect_code={self.quickconnect_code}"
-        
-        headers = {
-            'Content-Type': 'application/json',
-            'User-Agent': 'Kiwy-Signage-Player/1.0'
-        }
-        
-        request = UrlRequest(
-            url + params,
-            on_success=callback,
-            on_error=self._on_error,
-            on_failure=self._on_failure,
-            headers=headers
-        )
-        
-        return request
-    
-    def _on_error(self, request, error):
-        Logger.error('DigiServer', f'Request error: {error}')
-    
-    def _on_failure(self, request, result):
-        Logger.error('DigiServer', f'Request failed: {result}')
-```
-
-### 3. **Environment Configuration**
-
-**Add to player app_config.json or environment:**
-
-```json
-{
-  "server": {
-    "url": "https://192.168.0.121",
-    "hostname": "player1",
-    "quickconnect_code": "ABC123XYZ",
-    "verify_ssl": false,
-    "use_server_certificate": true,
-    "certificate_path": "~/.digiserver/server_cert.pem"
-  },
-  "connection": {
-    "timeout": 10,
-    "retry_attempts": 3,
-    "retry_delay": 5
-  }
-}
-```
-
----
-
-## Testing Checklist
-
-### Server-Side Tests
-
-- [ ] Verify CORS headers present: `curl -v https://192.168.0.121/api/health`
-- [ ] Check certificate endpoint: `curl -k https://192.168.0.121/api/certificate`
-- [ ] Test OPTIONS preflight: `curl -X OPTIONS https://192.168.0.121/api/playlists`
-- [ ] Verify X-Forwarded headers: `curl -v https://192.168.0.121/`
-
-### Player Connection Tests
-
-- [ ] Player connects with HTTPS successfully
-- [ ] Player fetches playlist without SSL errors
-- [ ] Player receives status update confirmation
-- [ ] Player sends feedback/heartbeat correctly
-
-### Integration Tests
-
-```bash
-# Test certificate retrieval
-curl -k https://192.168.0.121/api/certificate | jq '.certificate_info'
-
-# Test CORS preflight for player
-curl -X OPTIONS https://192.168.0.121/api/playlists \
-  -H "Origin: http://192.168.0.121" \
-  -H "Access-Control-Request-Method: GET" \
-  -v
-
-# Simulate player playlist fetch
-curl -k https://192.168.0.121/api/playlists \
-  --data-urlencode "hostname=test-player" \
-  --data-urlencode "quickconnect_code=test123" \
-  -H "Origin: *"
-```
-
----
-
-## Migration Steps
-
-### For Existing Players
-
-1. **Update player code** with new SSL handling from this guide
-2. **Restart player application** to pick up changes
-3. **Verify connection** works with HTTPS server
-4. **Monitor logs** for any SSL-related errors
-
-### For New Players
-
-1. **Deploy updated player code** with SSL support from the start
-2. **Configure with HTTPS server URL**
-3. **Run initialization** to fetch and trust server certificate
-
----
-
-## Troubleshooting
-
-### "SSL: CERTIFICATE_VERIFY_FAILED"
-- Player is rejecting the self-signed certificate
-- **Solution**: Run certificate trust setup or disable SSL verification
-
-### "Connection Refused"
-- Server HTTPS port not accessible
-- **Solution**: Check nginx is running, port 443 is open, firewall rules
-
-### "CORS error"
-- Browser/HTTP client blocking cross-origin request
-- **Solution**: Verify CORS headers in response, check Origin header
-
-### "Certificate not found at endpoint"
-- Server certificate file missing
-- **Solution**: Verify cert.pem exists at `/etc/nginx/ssl/cert.pem`
-
----
-
-## Security Recommendations
-
-1. **For Development/Testing**: Disable SSL verification temporarily
-   ```python
-   session.verify = False
-   ```
-
-2. **For Production**:
-   - Use proper certificates (Let's Encrypt recommended)
-   - Deploy certificate trust setup at player initialization
-   - Monitor SSL certificate expiration
-   - Implement certificate pinning for critical deployments
-
-3. **For Self-Signed Certificates**:
-   - Use `/api/certificate` endpoint to distribute certificates
-   - Store certificates in secure location on device
-   - Implement certificate update mechanism
-   - Log certificate trust changes for auditing
-
----
-
-## Next Steps
-
-1. **Implement SSL handling** in player code using examples above
-2. **Test with HTTP first** to ensure API works
-3. **Enable HTTPS** and test with certificate handling
-4. **Deploy to production** with proper SSL setup
-5. **Monitor** player connections and SSL errors
-

linux/RPI_TRIXIE_PORT_PLAN.md

@@ -0,0 +1,265 @@
+# Kiwy Signage Player — Raspberry Pi OS "Trixie" 64-bit Port Plan
+
+> Branch: `Linux-RPI-Player` (created from `Windows-Player` HEAD `f437aba`)
+> Status: **Phase 1 COMPLETE — player runs on the Pi.** See `development-track.md`
+> for measured results, the five blocking bugs and how they were fixed.
+> Date: 2026-09-13
+
+## Progress snapshot
+
+| Phase | State |
+|-------|-------|
+| 0 — Baseline | ✅ folded into Phase 1 |
+| 1 — Runtime bring-up | ✅ **done** — window, video, heartbeat, clean 60 s run |
+| 1b — Windows removal | ✅ **done** — branch is now Linux-only (see `development-track.md`) |
+| 2 — Web links | 🟡 adapter written, needs end-to-end verification on labwc |
+| 3 — Networking & card reader | 🟡 `nmcli` restart implemented; card reader pending |
+| 4 — Install & autostart | ⬜ |
+| 5 — 24/7 validation | ⬜ |
+
+**Three findings changed the plan materially** (details in `development-track.md`):
+
+1. Kivy's PyPI wheel bundles an SDL2 **without** the wayland driver → no window
+   on Trixie. Fixed by `linux/fix_kivy_sdl2.sh`. (Open question: apt
+   `python3-kivy` may avoid this entirely.)
+2. SDL2 needs `WAYLAND_DISPLAY` **set**; the socket alone is not enough, which
+   breaks every systemd/cron/autostart launch.
+3. Kivy's `Clock` re-resolves callbacks by `func.__name__`; a mismatched patch
+   crashes the app ~20 s after a *successful* start.
+
+---
+
+## 1. Executive summary
+
+The Windows port works because `windows/run_win.py` (2306 lines) monkey-patches
+`src/main.py` at runtime and injects Windows-specific web-link adapters into the
+existing `WeblinkSession` abstraction. The **`src/` core is already
+cross-platform by design** — that is the single most important finding:
+
+* `src/weblink_session.py` already ships a working Linux path
+  (`ChromiumSubprocessAdapter` is the default adapter).
+* `src/network_monitor.py` already has `IS_WINDOWS` branching.
+* `src/video_safety.py` patches Kivy's `VideoFFPy` provider — the same provider
+  used on the Pi.
+
+So this is **not a rewrite**. It is:
+
+1. **A new `linux/` companion to `windows/`** — an entry point that injects the
+   Linux adapter + platform behaviour (mirrors `run_win.py`, keeps `main.py` clean).
+2. **Repairing the existing Linux code paths** that were never validated against
+   Trixie (Wayland/labwc, NetworkManager, no `tvservice`, no `xdotool`).
+3. **Fixing the install/deployment layer**, which is currently broken for
+   Trixie/aarch64 (empty offline package repo, wrong wheel platform, broken
+   shebangs, boot-time `sudo` calls).
+
+### Verified environment (measured on the target device)
+
+| Item | Value |
+|------|-------|
+| OS | Debian GNU/Linux 13 (trixie) |
+| Model | Raspberry Pi 4 Model B Rev 1.4 |
+| Kernel | `6.18.39+rpt-rpi-v8` aarch64 |
+| Python | **3.13.5** (system) |
+| Session | `Type=wayland`, `Desktop=rpd-labwc` (**labwc**, not Wayfire/X11) |
+| Compositor | `/usr/bin/labwc`; user autostart file exists at `~/.config/labwc/autostart` |
+| Browser | `/usr/bin/chromium` — **Chromium 152.0.7977.82** |
+| Kivy | not installed; apt has `python3-kivy 2.3.1-1+b1`; PyPI has a
+  `cp313 manylinux_2_17_aarch64` wheel (verified downloadable) |
+| ffpyplayer / evdev | not installed; apt has `python3-evdev 1.9.1-1` |
+| Display power | `wlopm` present; **`tvservice`, `xdotool`, `ydotool` MISSING** |
+| Networking | **NetworkManager active**; `dhcpcd`/`ifupdown` inactive |
+| `sudo` | **requires a password** (`sudo -n` fails) |
+| `repo/python-wheels/` | **EMPTY (0 files)** — offline install cannot work today |
+
+---
+
+## 2. Compatibility matrix
+
+Legend: 🔴 breaks on Pi · 🟡 works but wrong/poor · 🟢 already fine
+
+| # | Component | Windows assumption | Trixie reality | Action |
+|---|-----------|--------------------|----------------|--------|
+| 1 | Entry point | `run_win.py` patches everything | no Linux equivalent — `main.py` used bare | 🟡 create `linux/run_linux.py` |
+| 2 | Web-link engine | Chrome/Edge subprocess + WebView2/CEF | Chromium subprocess (default adapter) | 🟡 dedicated Linux adapter with `--kiosk`/Ozone flags |
+| 3 | Web-link launch flags | `--start-fullscreen --start-maximized`, DPI-aware sizing | labwc honours `--kiosk`; needs `--ozone-platform=wayland` | 🔴 Linux-specific flag set |
+| 4 | Browser hand-off leak | fixed by `--user-data-dir` | same failure mode exists | 🔴 add `--user-data-dir` on Linux too |
+| 5 | Desktop flash on transition | `_Win32Overlay` + `_Win32Backdrop` | no Win32; wayland compositor owns stacking | 🔴 needs Kivy-side black cover + labwc rule |
+| 6 | Window raise/focus | `SetForegroundWindow`, `AttachThreadInput` | `Window.raise_window()` is ~no-op on Wayland | 🟡 focus guardian is harmless no-op; disable on Linux |
+| 7 | Keep display awake | `SetThreadExecutionState`, screensaver API | `signal_screen_activity()` shells out to X11 tools | 🔴 rewrite for `wlopm` (see #8) |
+| 8 | `signal_screen_activity()` | — | runs `tvservice`(missing), `xdotool`(missing), `xset`/`xrandr`(no X DPMS), `ydotool`(missing), `wlopm` with a **buggy `\*` escape** | 🔴 rewrite, keep-awake via `wlopm --on '*'` |
+| 9 | Idle/screensaver conflict | n/a | `~/.config/labwc/autostart` runs `swayidle -w timeout 600 'wlopm --off *'` → fights the player | 🔴 disable/neutralise for kiosk |
+| 10 | GL backend | `angle_sdl2` | Mesa/V3D; `gl`/`gles`/`sdl2` | 🟡 set correct backend in `run_linux.py` |
+| 11 | Audio driver | `directsound` | PipeWire (ALSA-compat / Pulse) | 🟡 `alsa,pulse,dummy`; a **duplicate `SDL_AUDIODRIVER` line** makes the 2nd a no-op |
+| 12 | Card reader | Raw Input + `win_card_reader.py` | `evdev` (native path already in `main.py`) | 🟡 install `python3-evdev`; udev/permissions rule |
+| 13 | Interaction watcher | `GetCursorPos` pointer tap | `/dev/input/event*` raw fds (already implemented) | 🟡 needs `input` group perms (user `pi` already in `input`) |
+| 14 | Offline install | n/a | `repo/python-wheels/` empty; `download_offline_packages.sh` uses `--platform linux_armv7l` (**32-bit**) | 🔴 regenerate for `aarch64` / cp313 |
+| 15 | `install.sh` shebang | n/a | literal `#\!/bin/bash` (escaped `!`) → not directly executable | 🔴 fix (3 places incl. heredocs) |
+| 16 | `install.sh` deps | n/a | installs `libsdl2-dev`/`libav*-dev` build toolchain; apt `python3-kivy` exists | 🟡 prefer apt Kivy + wheels |
+| 17 | `install.sh` autostart | n/a | writes *only* XDG `.desktop`; labwc uses `~/.config/labwc/autostart` | 🔴 add labwc hook + systemd unit |
+| 18 | `start.sh` display setup | n/a | `configure_display_resolution()` writes `/boot/config.txt` (**wrong path** on Trixie → `/boot/firmware/config.txt`) and calls `xrandr`/`tvservice`; `sudo` will **prompt at boot** | 🔴 remove/repair — boot-hang risk |
+| 19 | WiFi restart | `netsh wlan` | `rfkill`/`ifconfig`/`dhclient` — `ifconfig`+`dhclient` **not installed**, all `sudo` → password prompt | 🔴 move to `nmcli`, passwordless sudoers |
+| 20 | `setup_wifi_control.sh` | n/a | allows `/sbin/ifconfig`, `/sbin/dhclient` — **paths don't exist** | 🔴 rewrite for Trixie |
+| 21 | Orientation / `max_resolution` | `Window.size` constraint | fullscreen ignores `Window.size`; rotation is a compositor concern | 🔴 implement via `wlr-randr`/cmdline |
+| 22 | `src/signageplayer.ini` | — | **never loaded by any code** (dead file) | 🟡 delete or wire up |
+| 23 | `prewarm` weblink browser | desktop CPU budget | 2 extra Chromium processes on a Pi 4 | 🟡 default `prewarm:false` on Pi |
+| 24 | Watchdog / 24-7 | `watchdog.ps1` | `start.sh` exists and is sound (heartbeat + stop flag) | 🟢 keep, with fixes from #18 |
+
+---
+
+## 3. Proposed architecture
+
+Mirror the existing, proven Windows pattern. Keep `src/main.py` cross-platform
+per the repo ground rules — **no Linux-only imports added to `main.py`**.
+
+```
+src/                        # shared, cross-platform core (unchanged philosophy)
+  main.py                   # shared application; PI patches live in linux/
+  weblink_session.py        # WeblinkSession + ChromiumSubprocessAdapter (default)
+linux/                      # NEW — the Linux counterpart of windows/
+  run_linux.py              # ✅ entry point: env, session, adapter injection, patches
+  linux_display.py          # ✅ wlopm keep-awake, swayidle neutralisation, rotation
+  linux_browser.py          # ✅ LinuxChromiumAdapter (kiosk + Ozone + user-data-dir)
+  fix_kivy_sdl2.sh          # ✅ system SDL2 (wayland-capable) over the bundled one
+  test_linux_patches.py     # ✅ regression tests (29 checks)
+  _probe_video.py           # ✅ ad-hoc video decode/playback probe
+  development-track.md      # ✅ measured findings and bug log
+  RPI_TRIXIE_PORT_PLAN.md   # ✅ this file
+  install_linux.sh          # ⬜ upcoming — Trixie-correct installer
+  build_offline_aarch64.sh  # ⬜ upcoming — cp313/aarch64 wheels
+  start_player.sh           # ⬜ upcoming — kiosk launcher (fixed start.sh)
+  watchdog.sh               # ⬜ upcoming — crash+heartbeat supervisor
+  kiwy-player.service       # ⬜ upcoming — systemd unit
+  kiwy-signage-wifi.sudoers # ⬜ upcoming — nmcli-only passwordless rules
+.github/instructions/
+  kiwy-linux-rpi.instructions.md   # ⬜ upcoming — build/deploy rules for the Pi
+```
+
+`run_linux.py` responsibilities (deliberately the *same shape* as `run_win.py`):
+
+1. Set Linux env vars **before** importing `main` (`SDL_VIDEODRIVER=wayland,x11,dummy`,
+   `KIVY_GL_BACKEND`, `SDL_AUDIODRIVER`, `KIVY_VIDEO/KIVY_AUDIO=ffpyplayer`).
+2. Import `main`, then assign `SignagePlayer.weblink_adapter_factory`
+   → `[LinuxChromiumAdapter]`.
+3. Patch `signal_screen_activity` → `linux_display` implementation.
+4. Skip the Win32-only focus guardian / bring-to-front paths.
+5. Provide a fatal-error surface that works without a console
+   (log file + optional on-screen error label).
+
+**Why an adapter instead of patching `play_weblink()`:** the `WeblinkSession`
+abstraction already exists precisely for this, and it is what removed the
+z-order/leak bugs on Windows. Reusing it means the Pi inherits the verified
+launch → visibility → interaction → teardown state machine for free.
+
+---
+
+## 4. Phased implementation plan
+
+### Phase 0 — Baseline (no product change)
+- [ ] Fix the `install.sh`/`start.sh` shebangs (`#\!` → `#!`) so scripts are executable.
+- [ ] Boot the player on this Pi **manually** (`python3 src/main.py` from a venv) and
+      capture a baseline: does Kivy start on labwc/Wayland? GL backend? audio? video?
+- [ ] Record findings in `linux/development-track.md`.
+
+**Exit criteria:** a screenshot/log showing the player window on the Pi, or a
+precise first-failure diagnosis.
+
+### Phase 1 — Runtime bring-up (`linux/run_linux.py`, `linux/linux_display.py`)
+- [x] Create the venv and install deps (`kivy`, `ffpyplayer`, `evdev`, `requests`, `bcrypt`, `aiohttp`).
+- [x] `run_linux.py`: env setup + adapter injection + `signal_screen_activity` replacement.
+- [x] Fix the SDL2/Wayland blocker (`linux/fix_kivy_sdl2.sh`).
+- [x] `signal_screen_activity()`: `wlopm --on '*'` via `subprocess` (no `os.system`),
+      `vcgencmd display_power` backstop, X11 fallbacks; dropped `tvservice`/`xdotool`/`ydotool`.
+- [x] Neutralise the `swayidle` idle blanker.
+- [x] Gate the Win32 focus guardian/keeper on Linux.
+- [x] Fix the duplicate `SDL_AUDIODRIVER` line.
+- [x] Point the launchers at `linux/run_linux.py` instead of `src/main.py`.
+- [x] Regression test `linux/test_linux_patches.py` (29 checks).
+
+**Exit criteria met:** player runs fullscreen on labwc, video decodes and plays
+(`duration=6.0`, position advancing, texture rendered), heartbeat written,
+60 s run with zero errors and a clean shutdown. 24/7 soak still pending (Phase 5).
+
+### Phase 2 — Web links on Chromium/Wayland (`linux/linux_browser.py`)
+- [ ] `LinuxChromiumAdapter(ChromiumSubprocessAdapter)`: `--kiosk`, `--ozone-platform=wayland`
+      (with auto fallback), dedicated `--user-data-dir`, `--autoplay-policy=no-user-gesture-required`,
+      `--hide-scrollbars`, `--disable-pinch`, `--start-fullscreen` only where `--kiosk` misbehaves.
+- [ ] Implement `wait_visible()` for Linux — verify the Chromium window exists
+      (`/proc/<pid>/` + Wayland toplevel check, or a `--remote-debugging-port` probe)
+      instead of only "process still alive".
+- [ ] Transition masking without Win32: Kivy-side black cover + verify no desktop flash
+      under labwc; if needed, an `rc.xml` window rule pinning the Kivy window.
+- [ ] Teardown: kill the full process tree (`start_new_session=True` + `os.killpg`)
+      so GPU/renderer children don't leak (the Linux twin of `taskkill /T`).
+- [ ] Default `weblink.prewarm=false` on Pi to save CPU/RAM.
+
+**Exit criteria:** image → video → weblink → image cycle with no flash, no leaked
+`chromium` processes, correct duration + interaction postponement.
+
+### Phase 3 — Networking & card reader
+- [ ] `src/network_monitor.py`: replace `rfkill`/`ifconfig`/`dhclient` with `nmcli`
+      (`nmcli radio wifi off/on`, `nmcli device disconnect/connect`) — Trixie uses NetworkManager.
+- [ ] `kiwy-signage-wifi.sudoers`: passwordless rules for exactly the `nmcli`/`rfkill` binaries used.
+- [ ] Install `python3-evdev` (apt) + udev rule so the card reader works without `input` group hacks.
+
+### Phase 4 — Install & autostart (Trixie-native)
+- [ ] `build_offline_aarch64.sh`: populate `repo/python-wheels/` with **cp313 aarch64**
+      wheels (`kivy`, `ffpyplayer`, `evdev`, `requests`, `bcrypt`, `aiohttp`, …).
+      Replace the `--platform linux_armv7l` logic.
+- [ ] `install_linux.sh`: prefer apt `python3-kivy`/`python3-evdev` (fast, no build toolchain);
+      venv with `--system-site-packages`; drop the `--break-system-packages` fallback.
+- [ ] Autostart: append to `~/.config/labwc/autostart` **and** ship a systemd unit
+      (verify which one RPi OS Trixie `rpd-labwc` actually honours — validation item).
+- [ ] `watchdog.sh`: repair `configure_display_resolution()` (wrong `/boot/config.txt` path,
+      `sudo` at boot = hang risk); make all boot-time steps non-interactive.
+- [ ] Orientation / `max_resolution`: implement rotation via `wlr-randr` (Wayland) or
+      `cmdline.txt` `video=...,rotate=`; document that `Window.size` cannot change a
+      fullscreen mode.
+
+**Exit criteria:** clean install on a wiped Pi → reboots into playback unattended.
+
+### Phase 5 — 24/7 validation & docs
+- [ ] Overnight soak (≥12 h): mixed playlist, verify heartbeat, no leak growth
+      (`ps` chromium count), no memory growth.
+- [ ] Crash/hang drills: kill the player, freeze it, power-cut it → watchdog recovery.
+- [ ] `linux/development-track.md` + `.github/instructions/kiwy-linux-rpi.instructions.md`.
+- [ ] Update `PLAYER_VERSION` and the release checklist.
+
+---
+
+## 5. Risks & mitigations
+
+| Risk | Mitigation |
+|------|-----------|
+| Wayland client stacking — Chromium kiosk may not reliably return focus to Kivy | validate early (Phase 2); fallback = labwc `rc.xml` rule or run the session under XWayland |
+| Chromium `--kiosk` + labwc fullscreen semantics | empirical flag matrix recorded in the dev-track (like the Windows "tested & rejected" log) |
+| `sudo` password prompt at boot hangs the watchdog | all boot-time steps must be non-interactive; sudoers written at install time |
+| Pi 4 software H.265 decode is heavy | document supported codecs; prefer H.264; keep `video_safety` bounded join |
+| Offline wheels for cp313/aarch64 may be incomplete | Phase 0 verifies `pip download` for every requirement before Phase 4 |
+| `src/main.py` drift — Linux fixes leaking into shared code | follow the repo rule: platform code lives in `linux/`, `main.py` only gains *guarded* capability checks |
+
+## 6. Validation checklist (per phase, on the real device)
+
+- [ ] `python -m py_compile` on every touched file
+- [ ] Player starts fullscreen on labwc without a desktop flash
+- [ ] Display never blanks (24 h)
+- [ ] Playlist: image → video → weblink → image, correct durations
+- [ ] Weblink: kiosk fullscreen, no leaked `chromium` processes after the item
+- [ ] Touch interaction postpones the weblink advance
+- [ ] Card reader authenticates
+- [ ] WiFi restart recovers from an unplugged AP without a password prompt
+- [ ] Reboot → playback resumes unattended
+- [ ] `kill -9` the player → watchdog restarts within 60 s
+
+---
+
+## 7. Open decisions (need input before Phase 1)
+
+1. **Kivy source**: apt `python3-kivy` (fast, offline-friendly, distro-managed) vs
+   PyPI wheel in a venv (matches the Windows Kivy 2.3.1 + full control)?
+2. **Session target**: stay on the stock `rpd-labwc` kiosk session, or ship a
+   dedicated minimal labwc session (no panel, no `swayidle`) for the player?
+3. **Autostart mechanism**: systemd (system or user) vs `~/.config/labwc/autostart`?
+4. **Orientation**: is Portrait support actually required for this deployment?
+5. **Offline install**: must the Pi install work with no internet (i.e. vendor the
+   aarch64 wheels into `repo/`), or is online install acceptable?
+6. **Card reader**: is it in scope for the Pi, or is authentication keypad/quickconnect only?

linux/_probe_chromium_footprint.py

@@ -0,0 +1,126 @@
+"""_probe_chromium_footprint.py — measure Chromium's footprint for one page.
+
+Compares the flag profiles so the memory trade-off is measured rather than
+guessed. Run:
+
+    .venv/bin/python linux/_probe_chromium_footprint.py [url]
+
+Reports process count and total resident memory for the browser tree, using the
+same flags the player uses (so the numbers match production).
+"""
+
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from linux_display import ensure_session_environment  # noqa: E402
+
+ensure_session_environment()
+
+import linux_browser  # noqa: E402
+
+URL = sys.argv[1] if len(sys.argv) > 1 else 'about:blank'
+
+
+def tree_memory(root_pid):
+    """(PSS kB, process count) for root_pid and its descendants.
+
+    PSS (proportional set size) from ``/proc/<pid>/smaps_rollup`` is the right
+    measure here, **not** RSS. Chromium forks many processes that share the same
+    libraries and file-backed pages; summing RSS counts every shared page once
+    per process, which inflated earlier measurements by roughly 2x and even made
+    a smaller configuration look larger.
+    """
+    try:
+        out = subprocess.run(
+            ['ps', '-eo', 'pid,ppid'], capture_output=True, text=True,
+            timeout=10, check=False,
+        ).stdout
+    except Exception:
+        return 0, 0
+
+    parents = {}
+    for line in out.splitlines()[1:]:
+        parts = line.split()
+        if len(parts) >= 2 and parts[0].isdigit():
+            parents[int(parts[0])] = int(parts[1])
+
+    family = [root_pid]
+    changed = True
+    while changed:
+        changed = False
+        for pid, parent in parents.items():
+            if parent in family and pid not in family:
+                family.append(pid)
+                changed = True
+
+    total_kb = 0
+    for pid in family:
+        try:
+            with open(f'/proc/{pid}/smaps_rollup') as fh:
+                for line in fh:
+                    if line.startswith('Pss:'):
+                        total_kb += int(line.split()[1])
+                        break
+        except OSError:
+            # Process exited between listing and reading.
+            continue
+    return total_kb, len(family)
+
+
+def measure(mode):
+    os.environ['KIWY_CHROMIUM_MODE'] = mode
+    profile = f'/tmp/kiwy-footprint-{mode}'
+    subprocess.run(['rm', '-rf', profile], check=False)
+
+    adapter = linux_browser.LinuxChromiumAdapter(
+        browser_path=linux_browser.find_linux_browser(), kiosk=True,
+    )
+    adapter._profile_dir = profile
+
+    ok = adapter.launch(URL, 1280, 720)
+    if not ok or adapter._proc is None:
+        return None
+
+    try:
+        # Let Chromium finish spawning helpers before sampling.
+        time.sleep(8)
+        if adapter._proc.poll() is not None:
+            return {'crashed': True, 'rc': adapter._proc.returncode}
+        pss_kb, procs = tree_memory(adapter._proc.pid)
+        return {"pss_mb": pss_kb / 1024.0, "procs": procs}
+    finally:
+        adapter.teardown()
+        time.sleep(1.5)
+
+
+print(f'url = {URL}\n')
+print(f'{"mode":<10} {"procs":>6} {"PSS (MB)":>10}')
+print('-' * 30)
+
+results = {}
+for mode in ('safe', 'light', 'minimal'):
+    result = measure(mode)
+    results[mode] = result
+    if result is None:
+        note = 'launch failed'
+    elif result.get('crashed'):
+        note = f'CRASHED rc={result["rc"]}'
+    else:
+        note = ''
+    if note:
+        print(f'{mode:<10} {"-":>6} {note:>10}')
+    else:
+        print(f'{mode:<10} {result["procs"]:>6} {result["pss_mb"]:>10.0f}')
+
+print()
+base = results.get('safe', {}) or {}
+light = results.get('light', {}) or {}
+if base.get('pss_mb') and light.get('pss_mb'):
+    saved = base['pss_mb'] - light['pss_mb']
+    pct = 100.0 * saved / base['pss_mb']
+    print(f'light mode saves {saved:.0f} MB ({pct:.0f}%) vs the default flag set')
+    print(f'  processes: {base["procs"]} -> {light["procs"]}')

linux/_probe_video.py

@@ -0,0 +1,70 @@
+"""Ad-hoc video playback probe (not part of the test suite).
+
+Plays the intro video in a Kivy window and reports whether it decodes and
+advances. Used to verify the ffpyplayer path on Raspberry Pi OS Trixie.
+
+    .venv/bin/python linux/_probe_video.py [path/to/video.mp4]
+"""
+
+import os
+import sys
+import time
+
+# Mirror the real entry point: SDL2 does NOT discover the Wayland socket on its
+# own, so WAYLAND_DISPLAY must be filled in first. Without this the probe falls
+# back to x11 and dies with "Couldn't connect to X server".
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from linux_display import ensure_session_environment  # noqa: E402
+
+ensure_session_environment()
+
+os.environ.setdefault('SDL_VIDEODRIVER', 'wayland,x11,dummy')
+os.environ.setdefault('KIVY_GL_BACKEND', 'gl')
+os.environ.setdefault('KIVY_VIDEO', 'ffpyplayer')
+os.environ.setdefault('KIVY_AUDIO', 'ffpyplayer')
+
+from kivy.config import Config  # noqa: E402
+
+Config.set('graphics', 'window_state', 'hidden')
+Config.set('graphics', 'fullscreen', '0')
+
+from kivy.app import App  # noqa: E402
+from kivy.clock import Clock  # noqa: E402
+from kivy.uix.video import Video  # noqa: E402
+
+SOURCE = sys.argv[1] if len(sys.argv) > 1 else 'config/resources/intro1.mp4'
+DURATION = 12.0
+results = {}
+
+
+class Probe(App):
+    def build(self):
+        self.video = Video(
+            source=SOURCE, state='play', options={'eos': 'stop'},
+            allow_stretch=True, keep_ratio=True,
+        )
+        self.video.bind(on_eos=lambda *a: results.setdefault('eos', True))
+        return self.video
+
+    def on_start(self):
+        self.t0 = time.monotonic()
+        Clock.schedule_interval(self.tick, 1.5)
+        Clock.schedule_once(lambda dt: self.stop(), DURATION)
+
+    def tick(self, dt):
+        elapsed = time.monotonic() - self.t0
+        core = self.video._video
+        position = getattr(core, 'position', None) if core else None
+        if position is not None:
+            results['last_position'] = position
+        print(
+            f'  t={elapsed:5.1f}s state={self.video.state} '
+            f'duration={self.video.duration:.1f} position={position} '
+            f'texture={"yes" if self.video.texture else "no"}',
+            flush=True,
+        )
+
+
+Probe().run()
+print(f'RESULT duration={results.get("duration")} '
+      f'last_position={results.get("last_position")} eos={results.get("eos")}')

linux/_probe_weblink.py

@@ -0,0 +1,92 @@
+"""Ad-hoc weblink engine probe — drives the real LinuxChromiumAdapter.
+
+Verifies the full launch → visible → teardown cycle outside the player, so
+weblink behaviour can be tested without a server-provided playlist.
+
+    .venv/bin/python linux/_probe_weblink.py [url]
+"""
+
+import os
+import sys
+import time
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, _HERE)
+sys.path.insert(0, os.path.join(os.path.dirname(_HERE), 'src'))
+
+from linux_display import ensure_session_environment  # noqa: E402
+
+ensure_session_environment()
+
+URL = sys.argv[1] if len(sys.argv) > 1 else 'https://example.com'
+REQUIRED = os.environ.get('KIWY_REQUIRE_SUBSTRING', '')
+
+from linux_browser import LinuxChromiumAdapter, find_linux_browser  # noqa: E402
+
+
+def chromium_count():
+    import subprocess
+    out = subprocess.run(['pgrep', '-c', 'chromium'], capture_output=True, text=True)
+    try:
+        return int(out.stdout.strip())
+    except ValueError:
+        return 0
+
+
+def rss_mb():
+    import subprocess
+    out = subprocess.run(
+        ['ps', '-o', 'rss=', '-C', 'chromium'], capture_output=True, text=True
+    )
+    total = sum(int(x) for x in out.stdout.split() if x.isdigit())
+    return total / 1024.0
+
+
+def main():
+    print(f'URL: {URL}')
+    print(f'baseline chromium procs: {chromium_count()}')
+
+    adapter = LinuxChromiumAdapter(
+        browser_path=find_linux_browser(),
+        kiosk=True,
+        profile_dir=os.path.join(os.getcwd(), '.kiosk-profile-probe'),
+    )
+
+    print(f'flags: {adapter.extra_launch_args()}')
+
+    launched = adapter.launch(URL, 1920, 1080)
+    print(f'launch() -> {launched}')
+    if not launched:
+        print('FAIL: launch returned False')
+        return 1
+
+    visible, reason = adapter.wait_visible(15.0)
+    print(f'wait_visible() -> {visible} ({reason})')
+
+    time.sleep(6)
+    print(f'during: {chromium_count()} procs, {rss_mb():.0f} MB')
+
+    if REQUIRED:
+        # Fetch the same URL over HTTP and confirm it resolves, so a blank page
+        # can be attributed to rendering rather than to the network.
+        import urllib.request
+        try:
+            body = urllib.request.urlopen(URL, timeout=10).read(400_000).decode(
+                'utf-8', 'replace'
+            )
+            print(f'server reachable; page contains {REQUIRED!r}: {REQUIRED in body}')
+        except Exception as exc:
+            print(f'server fetch failed (network/host issue, not the engine): {exc}')
+
+    adapter.teardown()
+    time.sleep(3)
+
+    left = chromium_count()
+    print(f'after teardown: {left} chromium procs (0 = no leak)')
+    ok = visible and left == 0
+    print('RESULT:', 'PASS' if ok else 'FAIL')
+    return 0 if ok else 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())

linux/development-track.md

@@ -0,0 +1,521 @@
+# 🧪 Development Track — Kiwy Signage Player (Raspberry Pi / Linux Edition)
+
+> Read this FIRST before debugging or coding on the Pi port. It records what was
+> measured on real hardware, not what was assumed.
+
+---
+
+## 📅 Session — 2026-09-13
+
+| Field | Value |
+|-------|-------|
+| **Branch** | `Linux-RPI-Player` (from `Windows-Player` @ `f437aba`) |
+| **Hardware** | Raspberry Pi 4 Model B Rev 1.4, kernel `6.18.39+rpt-rpi-v8` |
+| **Python** | 3.13.5 in `.venv` (created with `--system-site-packages`) |
+| **Kivy** | 2.3.1 (PyPI wheel, cp313 aarch64) |
+| **ffpyplayer** | 4.5.3 (cp313 aarch64 wheel) |
+| **evdev** | 2.0.0 (built from sdist — no cp313 wheel published) |
+| **Session** | Wayland, `rpd-labwc` (labwc — **not** Wayfire, not X11) |
+| **Browser** | `/usr/bin/chromium` 152.0.7977.82 |
+| **Entry point** | `linux/run_linux.py` (**not** `src/main.py`) |
+
+### ✅ Status: the player runs on the Pi
+
+Verified by real runs (not inference):
+
+* Kivy window created on **Wayland** (`wayland,x11,dummy` → wayland driver)
+* 60 s continuous run, **0 errors, 0 tracebacks, clean shutdown**
+* Heartbeat file written and refreshed every 10 s
+* Playlist polling loop active (30 s interval)
+* **Video playback works**: intro1.mp4 → `duration=6.0`, position advanced
+  `0.56 → 2.07 → 3.56 → 5.06`, texture rendered, EOS handled, state auto-reset
+* Screensaver/blanker neutralised; `wlopm --on` confirmed working
+
+Blocked on: no server reachable from this network (`192.168.0.110` → *No route
+to host*), so no playlist/media content could be downloaded. That is an
+environment limitation, not a code defect.
+
+---
+
+## �️ Windows code removal (2026-09-13, second pass)
+
+This branch is now **Linux-only**. All Windows code and assets were removed;
+they remain available on the `Windows-Player` branch.
+
+**Deleted:**
+
+* `windows/` — the whole directory (32 files): `run_win.py`, `win_card_reader.py`,
+  `webview2_browser.py`, `webview2_runtime.py`, `cef_browser.py`, `build.spec`,
+  `watchdog.ps1`, the PyInstaller/PowerShell tooling and the bundled Windows
+  binaries (`webview2_sdk/` DLLs, `app_icon.ico`).
+* `.github/instructions/kiwy-build-and-development.instructions.md` (the exe build guide)
+* `documentation/CODE_SIGNING_SMART_APP_CONTROL.md` (Windows-only signing constraint)
+
+**Removed later: the rest of the Windows-era leftovers** (all recoverable from the
+`Windows-Player` branch, so nothing was lost):
+
+| Item | Why it went |
+|------|-------------|
+| `working_files/` (29 files) | Dev-era scratch: `install.sh.bak`, the superseded `get_playlists.py` (v1, replaced by `get_playlists_v2.py`), one-off `test_*.py` probes, and `MIGRATION_GUIDE.md` / `INVESTIGATION_RESULTS.md`. Also held real server captures (`server_response_debug.json`: `player_id`, player name, playlist) which had no business in the repo. |
+| `documentation/` (5 files) | All described the Windows-era HTTPS integration work. |
+| `python version` | Contained `Python 3.12.9` — the Windows build interpreter. The Pi runs 3.13.5. |
+| `test_edited_media_upload.py` | Parentless debug script, referenced by nothing. |
+| `.display-keepalive.sh`, `.keep-screen-alive.sh`, `.wait-for-display.sh` | Orphan X11 helper scripts, referenced by nothing. Superseded by `linux/linux_display.py`. |
+| `.video-optimization.sh`, `.run-background.sh`, `.start-player-cron.sh` | **Kept** — `install.sh` references all three. |
+
+**Removed from shared `src/`** — these were live code paths, so this was a real
+behavioural change, not just a comment cleanup:
+
+| File | Removed |
+|------|---------|
+| `main.py` | The whole Win32 focus subsystem: `_bring_window_to_front_nonblocking`, `_start/_stop_focus_keeper`, `_focus_keeper_tick`, `_start/_stop_focus_guardian`, `_focus_guardian_tick`, their `__init__` state, the `_start_focus_keeper()` call at video start, the guardian start in `__init__`, the two `_stop_focus_keeper()` calls, and the `_is_foreground_win` / `_bring_kivy_to_front_win` getattr hooks. Also the duplicate `Window.raise_window()` block and `_weblink_proc`. |
+| `network_monitor.py` | `IS_WINDOWS`, the `ping -n/-w` branch, `_restart_wifi_windows()` (netsh), and the `sudo ifconfig`/`dhclient` calls (`ifconfig`/`dhclient` are **not installed** on Trixie). |
+| `weblink_session.py` | `WebInputSources.pointer_moved()` (`GetCursorPos`), the `use_pointer` plumbing, and `msedge` from the browser search list. |
+| `video_safety.py` | Windows framing in the docstring only — the fix itself is cross-platform and was kept. |
+
+**Replaced, not just deleted:**
+
+* `_restart_wifi_linux()` → `_restart_wifi_nmcli()`. Trixie uses **NetworkManager**,
+  so `nmcli radio wifi off/on` + `nmcli device connect` is the correct interface
+  and needs no `sudo`. The old path depended on packages that are absent.
+* `ifconfig wlan0 down/up` → `ip link set wlan0 down/up`.
+* New `.github/instructions/kiwy-linux-rpi.instructions.md` (the Pi counterpart
+  of the deleted build guide).
+* `PLAYER_WEBLINK_INTEGRATION.md` §6.2 rewritten: "Windows: WebView2 Runtime"
+  → "Linux: Chromium kiosk on Wayland".
+* `.gitignore`: dropped the Windows venv/dist/WebView2 entries, kept the
+  `.kiosk-profile/` ignore and clarified the credential rules.
+* `config/app_config.json`: blanked the Windows host values
+  (`screen_name: DESKTOP-NJLBQKH`, the server IP and quick-connect key) and set
+  `weblink.prewarm: false` — pre-warming costs 2 extra Chromium processes, which
+  is not worth it on a Pi 4.
+
+**Also removed:** the `_patch_focus_handlers()` patch from `run_linux.py`. It had
+become vestigial once the focus methods were deleted — it would have created
+no-op attributes the app never calls. `test_linux_patches.py` now **asserts those
+attributes do not exist**, so reintroducing Win32 focus code fails the suite.
+
+**Verified after the removal:** 21/21 patch checks pass, video still decodes and
+plays (position advancing, texture rendered), 60 s player run with 0 errors and
+no spurious crash log.
+
+---
+
+## �🔴 The five bugs that actually prevented the port
+### [PI-013] Chromium asked for the keyring password at every weblink
+
+* **Symptom:** "user and password" prompt appeared when a weblink launched
+  (reproducible also by starting Chromium manually). Impossible to answer on an
+  unattended signage screen, and it blocked the page.
+* **Root cause (two separate bugs, neither sufficient alone):**
+  1. **Flag list was dead code.** `APPLIANCE_FLAGS` contained
+     `--password-store=basic` and `--use-mock-keychain`, but the list was
+     **never referenced** from `extra_launch_args()` — so those flags never
+     reached the command line. The comment looked like a fix; nothing was applied.
+  2. **The D-Bus session bus was inherited.** `ChromiumSubprocessAdapter.launch()`
+     used a bare `subprocess.Popen(args)` with **no `env=`**, and
+     `gnome-keyring-daemon --components=secrets` is running with
+     `DBUS_SESSION_BUS_ADDRESS` set. Chromium's password-store backend therefore
+     resolved to `gnome-libsecret` (Secret Service) and tried to unlock the login
+     keyring to hold its encryption key. Flags alone cannot fix this.
+* **Fix:**
+  * New `launch_env()` hook on the base adapter (returns `None` = inherit);
+    `LinuxChromiumAdapter` returns `_browser_env()`, which strips
+    `DBUS_SESSION_BUS_ADDRESS`/`DBUS_SESSION_BUS_PID`, empties
+    `GNOME_KEYRING_CONTROL` and sets `CHROME_PASSWORD_STORE=basic`. Scoped to the
+    **child** — the player keeps its real session bus.
+  * Every flag list is now referenced from `extra_launch_args()`, and
+    `linux/test_linux_browser_flags.py` fails if any list becomes dead code.
+  * Added `--disable-save-password-bubble`.
+* **Verified:** the live process's `/proc/<pid>/environ` contains no
+  `DBUS_SESSION_BUS_ADDRESS`, and Chromium logs
+  `dbus/bus.cc:405] Failed to connect to the bus` — i.e. it structurally cannot
+  reach the keyring. No prompt appears.
+
+### [PI-014] `--ozone-platform-hint=auto` aborts on Chromium 152
+
+* **Symptom:** no weblink ever displayed under labwc.
+* **Root cause:** measured, the hint flag does **not** fall back to Wayland when
+  there is no X server — it simply fails:
+  ```
+  (no flag)                   -> "Missing X server or $DISPLAY", aborts
+  --ozone-platform-hint=auto  -> "Missing X server or $DISPLAY", aborts
+  --ozone-platform=wayland    -> starts
+  ```
+* **Fix:** the platform is chosen explicitly from the detected session
+  (`--ozone-platform=wayland`), with `WAYLAND_FLAGS` omitted entirely when there
+  is no Wayland socket so Chromium uses its own X11 default.
+
+### [PI-015] Process-group teardown could never run
+
+* **Symptom:** every weblink risked leaving Chromium's GPU/zygote/renderer
+  children behind (the Linux twin of the Windows leak).
+* **Root cause:** `linux_browser.teardown()` calls `os.killpg`, but it only did
+  so when `self._pgid` was a **different** group — and because the base
+  `Popen(args)` had no `start_new_session=True`, the browser shared the player's
+  own process group. Killing that group would have killed the player itself, so
+  the code correctly refused and fell back to `terminate()`, orphaning children.
+* **Fix:** new `start_new_session()` hook; the Linux adapter returns `True`.
+  `test_linux_browser_flags.py` asserts the live process is its own group leader.
+
+---
+
+## 🎬 Video normalisation — 4K cannot play on a Pi 4
+
+### [PI-016] A 4K video shows one frozen frame instead of playing
+
+* **Symptom:** the new 4K sample (`16118765_3840_2160_30fps.mp4`, 3840×2160
+  H.264 High@5.1) displayed a still frame while the playlist timer ticked on.
+  The 1080p sample played perfectly.
+* **Root cause:** ffpyplayer decodes in **software** — there is no hardware
+  H.264 *decode* wired into its pipeline. Measured on this Pi 4:
+
+  | File | Resolution | Software decode speed |
+  |------|-----------|----------------------|
+  | `sample-30s.mp4` | 1920×1080 | **3.03× realtime** ✅ |
+  | `16118765_3840_2160_30fps.mp4` | 3840×2160 | **0.90× realtime** ❌ |
+
+  Below 1× realtime the decoder can never feed the display, so the picture
+  effectively stops. The player *did* advance correctly at the 19 s duration —
+  there was never a hang, just a video that cannot be rendered in time.
+* **Important:** the file plays fine in an *isolated* Kivy probe (position
+  advances in realtime). The stall only appears under the real player, where
+  decode competes with rendering, the weblink browser and the GUI. Do not
+  conclude "the file is fine" from a standalone probe.
+
+### The fix: `linux/video_normalizer.py`
+
+Oversized media is downscaled to at most **1920×1080** once, at sync time.
+
+* **Triggered by resolution only** — `width > 1920 or height > 1080`. A file
+  already within the limit is left byte-identical, so nothing that already
+  plays is ever re-encoded.
+* **Hardware encoding** via `h264_v4l2m2m` (verified working — the Pi 4's
+  H.264 *encoder* is a separate block from its decoder), with `libx264` as the
+  fallback. Measured: **31 s** for an 18 s 4K clip.
+* **Audio preserved** (`-c:a copy`, AAC fallback). This matters: a *silent*
+  video hits the separate SDL2_mixer bug documented in `_video_has_audio`, so
+  the normaliser must not create one.
+* Output lands next to the source as `<stem>_kiwy1080p.mp4` plus a
+  `.kiwy-normalized.json` metadata file.
+
+### Skip-while-converting, loop-the-intro-if-nothing-else
+
+The conversion is asynchronous, so the playlist can reach the item before it is
+ready. `src/media_state.py` owns one on-disk contract shared by the player and
+the normaliser:
+
+| Marker | Meaning |
+|--------|---------|
+| `<media>.kiwy-converting` | conversion in flight → **skip this item** |
+| `<media>_kiwy1080p.mp4` + `.kiwy-normalized.json` | done → **play this file instead** |
+
+Player behaviour per item:
+
+* **ready** — play it (the converted file when one exists, else the original)
+* **converting** — skip the lap immediately, no dwell delay
+* **pending** — oversized and not converted: skip, and request conversion
+
+Skipped items are advanced with `_advance_without_wait()` rather than occupying
+their configured duration, so a 19 s slot that cannot be shown does not add 19 s
+of nothing to every lap.
+
+**When nothing at all is playable** (e.g. a single-item playlist that is one 4K
+video still converting), the player loops `config/resources/intro1.mp4`
+(`eos: loop`) and polls every 3 s. The moment a converted item appears it stops
+the loop and restarts the playlist **from index 0** — so a one-item playlist
+gets a clean full run rather than joining mid-clip. A blank screen is never left
+on a signage display.
+
+### Traps found while building this
+
+1. **`resolve_playable()` initially skipped every normal video.** It checked for
+   a conversion output and a marker but never whether the file was oversized at
+   all, so a plain 1080p file (no output, no marker) fell through to
+   `pending`. The test caught it before it shipped: *skip-the-whole-playlist* is
+   a far worse failure than the freeze it was meant to fix.
+2. **The media cleanup would have deleted the converted file.**
+   `delete_unused_media()` prunes anything not named in the playlist — and
+   `_kiwy1080p.mp4` is, by design, not named there. It is now explicitly
+   protected, along with both marker types.
+3. **ffmpeg cannot infer the muxer from a `.part` temp name** ("Unable to choose
+   an output format"). The temp file keeps its real extension.
+4. **Metadata is written last.** Its presence is what marks a conversion
+   complete, so it must never exist for a half-written output.
+5. **A stale marker must not park an item forever** — markers older than 30 min
+   are ignored, so a crash mid-conversion cannot make a video unplayable.
+
+### Verified end to end (real server, real playlist)
+
+```
+20:33:05  sync detects 3840x2160 -> starts the background conversion
+20:33:36  conversion completes (31s) -> _kiwy1080p.mp4 + metadata
+20:36:01  video_using_normalized source=...3840_2160... normalized=..._kiwy1080p.mp4
+20:36:01  starting_video path=..._kiwy1080p.mp4
+20:36:20  next_media_called was_index=7        (played 18.7s, advanced on EOS)
+```
+
+Suites: `test_media_state.py` 18/18 · `test_linux_patches.py` 21/21 ·
+`test_linux_browser_flags.py` 27/27.
+
+**Recommendation for the server side:** normalising the source to 1920×1080
+before upload is still better — it avoids the 4K download *and* the 31 s
+conversion. This player-side path exists so that an oversized upload degrades
+gracefully instead of breaking the screen.
+
+---
+
+## 🟡 Chromium footprint — measured, not assumed
+
+The Pi 4 has 3.8 GB total and the desktop already uses ~1.9 GB, so a weblink
+needs to be lightweight. Numbers below are **PSS** summed over the browser tree
+for the real page (`https://moto-adv.com/`), via
+`linux/_probe_chromium_footprint.py`.
+
+| Profile | Processes | PSS |
+|---------|-----------|-----|
+| `safe` (no footprint flags) | 10 | 513 MB |
+| **`light` (default)** | **9** | **507 MB** |
+| `minimal` (`--single-process`) | 4 | 438 MB |
+
+**Honest conclusion: flag tuning buys very little.** Chromium's baseline is
+simply ~500 MB and the remaining levers are single-digit percentages.
+`minimal` saves ~15% but halves the process count, and upstream labels
+`--single-process` unsupported, so it stays opt-in.
+
+**Two measurement traps worth remembering:**
+
+1. **RSS is the wrong metric.** Chromium shares libraries and file-backed pages
+   across processes; summing RSS double-counts and produced numbers ~2x too high
+   — it even ranked a *smaller* configuration as *larger* (1132 MB safe vs
+   1529 MB light). Use `Pmi/smaps_rollup`.
+2. **`--disable-gpu` makes it worse.** It looks like an obvious win for a static
+   page, but it moves rasterization out of the GPU process into the renderer:
+   **1038 MB vs 513 MB**. It is deliberately absent from every list.
+
+Use `KIWY_CHROMIUM_MODE=light|minimal|safe` to select a profile. If memory is
+genuinely the constraint, the structural fix is an **embedded** engine rendering
+inside the Kivy window (WebKitGTK, available on aarch64) — not more flags.
+
+> **Ultralight is not an option on this hardware.** Despite the vendor's site
+> claiming "Linux (x64 / arm64)", enumerating the entire SDK bucket returns only
+> `mac-x64, linux-x64, win-x64, win-uwp-x64, win-x86`;
+> `ultralight-sdk-latest-linux-arm64.7z` is a **404**. There is no ARM64 build of
+> any kind, and it is closed-source C++ with no Python binding.
+
+---
+
+## 🔴 The five bugs that actually prevented the port
+
+### [PI-001] Kivy's bundled SDL2 has NO Wayland driver — **no window at all**
+
+* **Symptom:**
+  ```
+  [CRITICAL] Unable to find any valuable Window provider.
+  sdl2 - RuntimeError: b'wayland,x11,dummy not available'
+  [CRITICAL] SignagePlayerApp: Window is None - display server not available
+  ```
+* **Root cause:** Kivy's PyPI wheel ships a **private SDL2** in `Kivy.libs/`
+  (name has a hash: `libSDL2-2-87637523.0.so.0.3000.7`). Driver enumeration
+  proved it is built **without Wayland**:
+
+  | Library | Video drivers |
+  |---------|---------------|
+  | `Kivy.libs/libSDL2-2-*.so` (bundled) | `x11, KMSDRM, offscreen, dummy, evdev` |
+  | `/usr/lib/aarch64-linux-gnu/libSDL2-2.0.so.0` (system) | `x11, **wayland**, KMSDRM, offscreen, dummy, evdev` |
+
+  Trixie runs a Wayland session and there is no X server, so the bundled build
+  cannot create a window. Note the driver *name* does not change: the bundled
+  SDL2 resolves `b'wayland'` as "driver unavailable", not "unknown driver".
+* **Fix:** `linux/fix_kivy_sdl2.sh` symlinks the system SDL2 over the bundled
+  filename (idempotent, reversible, survives only until the next
+  `pip install --upgrade kivy`).
+* **Verified:** `WINDOW OK size=(800, 600)`
+* **Rejected alternatives:**
+  * ❌ Editing `~/.kivy/config.ini` — irrelevant, the provider never loads.
+  * ❌ `KIVY_WINDOW=...` variations — the library lacks the driver, full stop.
+  * *(Still untested)* apt `python3-kivy` likely bundles no SDL2 and would
+    sidestep this entirely — worth evaluating for the installer.
+
+### [PI-002] SDL2 requires `WAYLAND_DISPLAY` — the socket alone is NOT enough
+
+* **Symptom:** window creation fails when the player is launched from systemd,
+  cron, an autostart entry or SSH.
+* **Root cause:** those contexts set `XDG_RUNTIME_DIR` but leave
+  `WAYLAND_DISPLAY` **empty** (the compositor only exports it inside the desktop
+  session). Measured:
+
+  | `WAYLAND_DISPLAY` | result |
+  |-------------------|--------|
+  | unset | `sdl2 - RuntimeError: b'wayland not available'` |
+  | `wayland-0` | `WINDOW OK (800, 600)` |
+
+  Notably `wlopm` **does** fall back to scanning `XDG_RUNTIME_DIR`, but SDL2
+  does not — so this cannot be inferred from the display tools working.
+* **Fix:** `linux_display.ensure_session_environment()` detects the socket,
+  derives the name from its filename (so `wayland-1` works) and exports it.
+  Called at the very top of `run_linux.py`, before Kivy is imported.
+* **Verified:** `session environment filled in: {'WAYLAND_DISPLAY': 'wayland-0'}`
+
+### [PI-003] Kivy `WeakMethod` name trap — crash ~20 s AFTER startup
+
+* **Symptom:** the app starts fine, then dies on the first Clock tick:
+  ```
+  [CRITICAL] Fatal error: 'SignagePlayer' object has no attribute 'linux_screen_activity'
+  [CRITICAL] Fatal error: 'SignagePlayer' object has no attribute '_noop'
+  ```
+* **Root cause:** Kivy's `Clock` stores a callback's `__func__.__name__` in a
+  `WeakMethod` and later resolves it with `getattr(instance, that_name)`. A
+  replacement assigned under a *different* name than the function was defined
+  with raises `AttributeError` — but only when the Clock next fires, so the
+  traceback points nowhere near the patch.
+  Two variants bit us: a name mismatch (`linux_screen_activity` vs
+  `signal_screen_activity`) and a shared helper (`_noop` used for three
+  different methods).
+* **Fix:** `_bind_name()` sets `__name__`/`__qualname__` on each replacement,
+  and the focus no-ops are generated per-attribute rather than shared.
+* **Verified:** `linux/test_linux_patches.py` asserts that
+  `getattr(SignagePlayer, func.__name__)` resolves *and* returns the patched
+  function — for every replaced method.
+* This is the same trap that used to be documented in the Windows port; the
+  lesson is now enforced by a test instead of by a comment.
+
+### [PI-004] The inherited `signal_screen_activity()` never kept the screen on
+
+* **Symptom:** the panel blanks after the 10-minute idle timeout.
+* **Root causes (three compounding):**
+  1. `swayidle -w timeout 600 'wlopm --off *'` runs from
+     `~/.config/labwc/autostart` — measured: PID 1431, confirmed running.
+  2. The handler shells out to `tvservice`, `xdotool`, `ydotool` — **all three
+     are absent on Trixie** (`tvservice` is gone with the legacy firmware
+     stack; `xdotool`/`ydotool` are not installed).
+  3. It passed a shell-escaped `wlopm --on \*`, so the compositor matched an
+     output literally named `*` and did nothing.
+* **Fix:** `linux/linux_display.py` — real `wlopm --on '*'` (list argv, no
+  shell), `vcgencmd display_power 1` as a firmware backstop, X11 fallbacks for
+  non-Wayland sessions, and `neutralise_idle_blanker()` to stop `swayidle`.
+* **Verified:** `keep_display_awake` → `True`; `swayidle` killed;
+  `wlopm` reports `HDMI-A-1 on`.
+
+### [PI-005] Launcher scripts bypassed the platform layer entirely
+
+* **Symptom:** the player runs but blanks, shows no web links, and any fix to
+  the platform layer has no effect.
+* **Root cause:** `start.sh` did `cd src && python3 main.py`, and
+  `run_player.sh` did the same. `src/main.py` is a *module* of the shared core,
+  not the Pi entry point — running it directly skips every patch in
+  `linux/run_linux.py`. Additionally `src/` is not the data directory, so
+  `base_dir` resolved one level too high.
+* **Fix:** both scripts now run `.venv/bin/python linux/run_linux.py` from the
+  project root. `check_player_status.sh` / `stop_player.sh` match
+  `run_linux.py` instead of `python3 main.py` (they would otherwise never find
+  the process).
+* **Verified:** `bash run_player.sh` runs clean; `bash -n` passes on all four.
+
+---
+
+## 🟡 Also fixed (real but non-blocking)
+
+| # | Issue | Fix |
+|---|-------|-----|
+| [PI-006] | `main.py` set `SDL_AUDIODRIVER` **twice**; the second (`'alsa'`) was a silent no-op because `setdefault` never overwrites — it obscured which driver was live | Removed the duplicate, documented why |
+| [PI-007] | `SettingsPopup.test_connection` hard-coded `/tmp/temp_auth_test.json` | Uses `tempfile.gettempdir()`; needed `import tempfile` added to `main.py`. Files with credentials are now always removed |
+| [PI-008] | `player_auth.json` resolved against the *cwd*, so systemd/autostart launches "forgot" authentication and re-registered every start | `run_linux.py` pins it to an absolute path in the data dir |
+| [PI-009] | `_bring_window_to_front_nonblocking` / focus keeper are Win32-only; on Wayland they ran every 0.5 s and logged "focus lost" forever | No-oped on Linux (`KIWY_FOCUS_KEEPER=1` restores) |
+| [PI-010] | Clean shutdown (SIGTERM from the watchdog) wrote a bogus `FATAL: 0` crash log | `SystemExit(0)` is now a clean exit |
+| [PI-011] | Web-link hand-off: without a dedicated `--user-data-dir` Chromium delegates the URL to an existing instance and exits in ~2 s | `LinuxChromiumAdapter` always uses a private profile, and clears stale `SingletonLock` |
+| [PI-012] | `proc.terminate()` left Chromium's GPU/zygote/renderer children running (Leak → OOM over 24/7) | Kill the whole process group (`os.killpg`), the Linux twin of `taskkill /T` |
+
+---
+
+## 🧪 Tested & Rejected Solutions Log
+
+| Date | What was tested | Result | Reason it failed |
+|------|----------------|--------|-----------------|
+| 2026-09-13 | `SDL_VIDEODRIVER=wayland` with the bundled SDL2 | ❌ | Bundled SDL2 has no wayland driver |
+| 2026-09-13 | `SDL_VIDEODRIVER=x11` (+ XWayland present) | ❌ | No X server running on labwc; `x11 not available` |
+| 2026-09-13 | `KIVY_GL_BACKEND=gles` vs `gl` | ➖ | Both equivalent; the failure was the driver, not GL |
+| 2026-09-13 | Comma-separated `SDL_VIDEODRIVER` list | ✅ | Works — Kivy splits on `,` and SDL2 takes the first that initialises |
+| 2026-09-13 | Relying on the Wayland socket without `WAYLAND_DISPLAY` | ❌ | SDL2 does not scan `XDG_RUNTIME_DIR` (unlike `wlopm`) |
+| 2026-09-13 | System SDL2 symlinked over the bundled name | ✅ | Full driver set incl. wayland — **the fix** |
+
+---
+
+## 🧰 Environment / dependency facts
+
+* **Must exist before the player will start:**
+  * `libsdl2-2.0-0` (system SDL2 **with** wayland)
+  * `libgl1-mesa-dri`, `libgles2`
+  * a running Wayland session (labwc) and a valid `XDG_RUNTIME_DIR`
+* **Python packages** (all cp313 aarch64 wheels exist **except** evdev):
+
+  | Package | Source | Note |
+  |---------|--------|------|
+  | kivy 2.3.1 | PyPI wheel | needs `fix_kivy_sdl2.sh` on Trixie |
+  | ffpyplayer 4.5.3 | PyPI wheel | video/audio backend |
+  | aiohttp, requests, bcrypt | PyPI wheel / apt | already installed system-wide |
+  | **evdev 2.0.0** | **sdist only** | `python3-dev` + `build-essential` required, or use apt `python3-evdev` |
+
+* **Tools present:** `wlopm`, `wlr-randr`, `vcgencmd`, `swayidle`, `chromium`,
+  `ffprobe`, `labwc`, `systemd-inhibit`, `zenity`
+* **Tools MISSING:** `tvservice`, `xdotool`, `ydotool`, `chromium-browser`,
+  `glxinfo`, `ifconfig`, `dhclient` (last two matter for WiFi restart — Phase 3)
+* **Networking:** NetworkManager is active; `dhcpcd`/`ifupdown` are not
+* **`sudo` requires a password** → every boot-time `sudo` call is a hang risk
+  (see Phase 4 / `start.sh` `configure_display_resolution()`)
+
+---
+
+## 🧪 How to verify
+
+```bash
+cd /home/pi/Desktop/Kiwy-Signage
+
+# 1. SDL2 has the wayland driver (the #1 blocker)
+bash linux/fix_kivy_sdl2.sh --check
+
+# 2. Platform patches wired correctly (WeakMethod trap, keep-awake, SDL2)
+.venv/bin/python linux/test_linux_patches.py          # expect: 21/21 passed
+
+# 3. Keyring bypass + footprint flags actually applied
+.venv/bin/python linux/test_linux_browser_flags.py    # expect: 27/27 passed
+
+# 4. Video decode + playback
+.venv/bin/python linux/_probe_video.py                # expect: position advances
+
+# 5. Chromium footprint per profile (PSS, real page)
+.venv/bin/python linux/_probe_chromium_footprint.py https://moto-adv.com/
+
+# 6. The player itself
+bash run_player.sh                                   # or: bash start.sh (watchdog)
+
+# 7. Diagnostics
+.venv/bin/python linux/linux_display.py              # backend/outputs/tools
+bash linux/fix_kivy_sdl2.sh --revert                 # undo the SDL2 symlink
+```
+
+Useful escape hatches:
+
+| Variable | Effect |
+|----------|--------|
+| `KIWY_DISPLAY_TOOLS_DISABLED=1` | Disable all `wlopm`/`vcgencmd`/`swayidle` work |
+| `KIWY_CHROMIUM_MODE=light\|minimal\|safe` | Chromium footprint profile (default `light`) |
+| `KIWY_VENV=/path` | Point the SDL2 fix script at another virtualenv |
+
+---
+
+## 📝 Next session
+
+* [ ] **Phase 2** — web links: verify Chromium kiosk on labwc end-to-end
+      (fullscreen, no desktop flash, no leaked processes, interaction postpones)
+* [ ] Evaluate **apt `python3-kivy`** — it bundles no SDL2 and may remove the
+      need for `fix_kivy_sdl2.sh` entirely
+* [ ] **Phase 4** — autostart via `~/.config/labwc/autostart` +
+      systemd unit; repair `start.sh`'s `configure_display_resolution()`
+      (wrong `/boot/config.txt` path on Trixie → `/boot/firmware/config.txt`)
+* [ ] **Phase 3** — card reader (evdev/udev) and WiFi restart via `nmcli`
+      (the current `ifconfig`/`dhclient` path depends on packages that are gone)
+* [ ] Orientation/rotation via `wlr-randr` (implemented, untested on hardware)
+* [ ] 24/7 soak test with real playlist content
+* [ ] Confirm the `dist/` deployment hazard documented for Windows has no
+      Linux equivalent (it does not — there is no bundle on Linux)

linux/fix_kivy_sdl2.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+# fix_kivy_sdl2.sh — make Kivy use the system SDL2 (Wayland-capable).
+#
+# THE PROBLEM
+# -----------
+# Kivy's PyPI wheel bundles a private SDL2 in ``Kivy.libs/`` that is compiled
+# WITHOUT the Wayland video driver. Verified on this Pi:
+#
+#   Kivy.libs/libSDL2-2-87637523.0.so.0.3000.7  ->  x11, KMSDRM, offscreen, dummy, evdev
+#   /usr/lib/aarch64-linux-gnu/libSDL2-2.0.so.0 ->  x11, wayland, KMSDRM, offscreen, dummy, evdev
+#
+# On Raspberry Pi OS "Trixie" the desktop is Wayland/labwc and there is no
+# X server running, so the bundled build cannot create a window at all:
+#
+#   [CRITICAL] Unable to find any valuable Window provider.
+#   sdl2 - RuntimeError: b'wayland,x11,dummy not available'
+#
+# Substituting the system library under Kivy's bundled filename resolves it
+# (verified: "WINDOW OK size=(800, 600)").
+#
+# WHY A SYMLINK AND NOT A COPY
+# ----------------------------
+# The symlink survives ``pip install --upgrade kivy`` overwriting the file, is
+# reversible, and keeps the distro's security updates in effect. A copy would
+# silently become stale.
+#
+# Usage:
+#   bash linux/fix_kivy_sdl2.sh            # apply (idempotent)
+#   bash linux/fix_kivy_sdl2.sh --check    # report only, change nothing
+#   bash linux/fix_kivy_sdl2.sh --revert   # remove the symlink
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+VENV_DIR="${KIWY_VENV:-$ROOT_DIR/.venv}"
+BACKUP_DIR="$VENV_DIR/.kivy-sdl2-backup"
+SYSTEM_SDL2="/usr/lib/aarch64-linux-gnu/libSDL2-2.0.so.0"
+
+MODE="apply"
+case "${1:-}" in
+    --check)  MODE="check" ;;
+    --revert) MODE="revert" ;;
+    "")       MODE="apply" ;;
+    *) echo "Unknown option: $1" >&2; exit 2 ;;
+esac
+
+if [ ! -d "$VENV_DIR" ]; then
+    echo "ERROR: virtualenv not found at $VENV_DIR" >&2
+    echo "       Set KIWY_VENV=/path/to/venv if it lives elsewhere." >&2
+    exit 1
+fi
+
+KIVY_LIBS="$(find "$VENV_DIR" -maxdepth 5 -type d -name 'Kivy.libs' 2>/dev/null | head -1)"
+if [ -z "$KIVY_LIBS" ]; then
+    echo "No Kivy.libs directory found under $VENV_DIR — nothing to do."
+    echo "(Kivy is probably installed from apt, which uses the system SDL2 already.)"
+    exit 0
+fi
+
+# Kivy names the bundled library with a hash, so locate it by pattern rather
+# than hard-coding the version. Symlinks must be matched too: once the fix is
+# applied the original file IS a symlink, and skipping it would make this
+# script wrongly conclude that nothing is bundled.
+BUNDLED="$(find "$KIVY_LIBS" -maxdepth 1 -name 'libSDL2-2-*.so*' 2>/dev/null | head -1)"
+
+# Fallback: ask the compiled extension which SDL2 it actually loads. This is
+# authoritative and also covers a future Kivy layout change.
+if [ -z "$BUNDLED" ]; then
+    EXT="$(find "$VENV_DIR" -maxdepth 6 -name '_window_sdl2*.so' 2>/dev/null | head -1)"
+    if [ -n "$EXT" ]; then
+        NEEDED="$(ldd "$EXT" 2>/dev/null | awk '/libSDL2-2-/ {print $3; exit}')"
+        [ -n "$NEEDED" ] && BUNDLED="$NEEDED"
+    fi
+fi
+
+echo "Kivy.libs : $KIVY_LIBS"
+echo "bundled   : ${BUNDLED:-<none>}"
+echo "system    : $SYSTEM_SDL2"
+
+if [ ! -e "$SYSTEM_SDL2" ]; then
+    echo "ERROR: system SDL2 not found at $SYSTEM_SDL2" >&2
+    echo "       Install it with:  sudo apt install libsdl2-2.0-0" >&2
+    exit 1
+fi
+
+# Report the video drivers compiled into a library, so the fix is verifiable.
+report_drivers() {
+    local lib="$1"
+    local py="${VENV_DIR}/bin/python"
+    [ -x "$py" ] || py="$(command -v python3)"
+    "$py" - "$lib" <<'PY' 2>/dev/null || echo "  (could not inspect drivers)"
+import ctypes, sys
+try:
+    s = ctypes.CDLL(sys.argv[1])
+    s.SDL_GetNumVideoDrivers.restype = ctypes.c_int
+    s.SDL_GetVideoDriver.restype = ctypes.c_char_p
+    s.SDL_GetVideoDriver.argtypes = [ctypes.c_int]
+    n = s.SDL_GetNumVideoDrivers()
+    print('  drivers:', ', '.join(s.SDL_GetVideoDriver(i).decode() for i in range(n)))
+except Exception as exc:
+    print('  (inspection failed:', exc, ')')
+PY
+}
+
+case "$MODE" in
+    revert)
+        if [ -L "$BUNDLED" ]; then
+            rm -f "$BUNDLED"
+            if [ -f "$BACKUP_DIR/$(basename "$BUNDLED")" ]; then
+                cp -a "$BACKUP_DIR/$(basename "$BUNDLED")" "$BUNDLED"
+                echo "Reverted to the original bundled SDL2."
+            else
+                echo "Removed the symlink. Reinstall Kivy to restore the bundled library:"
+                echo "  $VENV_DIR/bin/pip install --force-reinstall kivy"
+            fi
+        else
+            echo "Nothing to revert (no symlink in place)."
+        fi
+        exit 0
+        ;;
+
+    check)
+        echo
+        if [ -L "$BUNDLED" ]; then
+            echo "STATUS: fixed (bundled name points at the system SDL2)"
+            report_drivers "$BUNDLED"
+        else
+            echo "STATUS: NOT fixed — Kivy is using its own SDL2"
+            report_drivers "$BUNDLED"
+        fi
+        echo
+        echo "system SDL2:"
+        report_drivers "$SYSTEM_SDL2"
+        exit 0
+        ;;
+
+    apply)
+        if [ -z "$BUNDLED" ]; then
+            echo "No bundled libSDL2 found — Kivy already uses the system SDL2."
+            exit 0
+        fi
+
+        if [ -L "$BUNDLED" ]; then
+            echo "Already fixed (symlink in place). Verifying..."
+            report_drivers "$BUNDLED"
+            exit 0
+        fi
+
+        # Keep a copy of the original so --revert works without a reinstall.
+        mkdir -p "$BACKUP_DIR"
+        if [ ! -f "$BACKUP_DIR/$(basename "$BUNDLED")" ]; then
+            cp -a "$BUNDLED" "$BACKUP_DIR/"
+            echo "Backed up original -> $BACKUP_DIR/$(basename "$BUNDLED")"
+        fi
+
+        ln -sf "$SYSTEM_SDL2" "$BUNDLED"
+        echo "Symlinked $BUNDLED -> $SYSTEM_SDL2"
+        echo
+        echo "Resulting drivers:"
+        report_drivers "$BUNDLED"
+        echo
+        echo "Done. Kivy can now create a Wayland window."
+        echo "NOTE: re-run this script after any 'pip install --upgrade kivy'."
+        ;;
+esac

linux/linux_browser.py

@@ -0,0 +1,603 @@
+"""linux_browser.py — Chromium/Chrome kiosk adapter for Raspberry Pi (Wayland).
+
+Why this module exists
+----------------------
+``src/weblink_session.py`` already owns the whole web-link lifecycle (launch →
+verified visibility → interaction watching → teardown) and ships a generic
+``ChromiumSubprocessAdapter`` that is the default on Linux. That adapter is
+correct in structure but was never tuned for Raspberry Pi OS Trixie, where:
+
+* the session is **Wayland/labwc**, so Chromium needs an explicit Ozone
+  platform or it may come up as an X11 (XWayland) surface that the compositor
+  will not make fullscreen;
+* Chromium is ``/usr/bin/chromium`` (there is no ``chromium-browser``);
+* ``--start-maximized`` is not what makes a window fullscreen on labwc;
+  ``--kiosk`` is;
+* without a dedicated ``--user-data-dir`` Chromium hands the URL to an
+  already-running instance, the process we launched exits in ~2 s, and the
+  session's ``wait_visible`` reports the item as failed;
+* ``proc.terminate()`` only kills the parent; Chromium's GPU/zygote/renderer
+  children survive and accumulate over a 24/7 playlist.
+
+This adapter is the platform counterpart of the generic
+``ChromiumSubprocessAdapter`` and is injected through the existing
+``SignagePlayer.weblink_adapter_factory`` hook — no changes to the shared
+``play_weblink`` code path are required.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import signal
+import sys
+import subprocess
+import time
+
+# The shared modules live in ../src. Add it explicitly so this file can be
+# imported standalone (diagnostics, tests) and not only after run_linux.py has
+# already put src/ on sys.path.
+_SRC_DIR = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), 'src')
+if _SRC_DIR not in sys.path:
+    sys.path.insert(0, _SRC_DIR)
+
+from weblink_session import ChromiumSubprocessAdapter  # noqa: E402
+
+
+def _log(message, level='info'):
+    try:
+        from kivy.logger import Logger
+
+        getattr(Logger, level, Logger.info)(f'[LinuxBrowser] {message}')
+    except Exception:
+        pass
+
+
+#: Wayland flags. The platform MUST be named explicitly.
+#:
+#: Measured on Chromium 152 / Raspberry Pi OS Trixie (labwc, no X server):
+#:
+#:   (no flag)                   -> "Missing X server or $DISPLAY", aborts
+#:   --ozone-platform-hint=auto  -> "Missing X server or $DISPLAY", aborts
+#:   --ozone-platform=wayland    -> starts (9 processes)
+#:
+#: ``--ozone-platform-hint=auto`` does NOT fall back to Wayland when there is no
+#: X server, contrary to how it is usually described; it simply fails. So the
+#: flag is chosen explicitly from the detected session instead of being hinted.
+WAYLAND_FLAGS = [
+    '--ozone-platform=wayland',
+    '--enable-features=UseOzonePlatform,WaylandWindowDecorations',
+]
+
+#: Flags that stop Chromium asking for the **keyring** password.
+#:
+#: This is the prompt that appeared at start-up. On Raspberry Pi OS
+#: ``gnome-keyring-daemon --components=secrets`` runs and
+#: ``DBUS_SESSION_BUS_ADDRESS`` is set, so Chromium's default password-store
+#: backend resolves to ``gnome-libsecret`` (Secret Service). Chromium then tries
+#: to unlock the login keyring to hold its encryption key, which raises a modal
+#: prompt that cannot be answered on an unattended signage screen.
+#:
+#: ``--password-store=basic`` forces the built-in plain store so Chromium never
+#: contacts the Secret Service. ``--use-mock-keychain`` covers the equivalent
+#: code path on other platforms.
+#:
+#: These used to sit inside ``APPLIANCE_FLAGS``, but that list was never
+#: referenced from ``extra_launch_args()``, so none of them ever reached the
+#: command line — the prompt looked unfixable. ``test_linux_browser_flags.py``
+#: now asserts they are actually applied.
+KEYRING_BYPASS_FLAGS = [
+    '--password-store=basic',
+    '--use-mock-keychain',
+]
+
+#: Flags that reduce the memory footprint on a Pi 4.
+#:
+#: Measured for one real page (https://moto-adv.com/), **PSS** summed over the
+#: whole browser tree — see ``_probe_chromium_footprint.py``:
+#:
+#:   default flags                10 procs  ~513 MB
+#:   + --disable-gpu              10 procs ~1038 MB   <-- WORSE, do not use
+#:   + this list (light)           9 procs  ~507 MB
+#:   + --single-process (minimal)  4 procs  ~438 MB   (~15% less)
+#:
+#: Two things worth knowing, both measured rather than assumed:
+#:
+#: * ``--disable-gpu`` is deliberately NOT included. Intuitively it should help,
+#:   but it moves rasterization out of the GPU process and into the renderer,
+#:   which *doubled* memory for a real page.
+#: * Chromium's baseline cost is simply large. The remaining ~500 MB is the
+#:   browser itself, so flag tuning yields only single-digit percentages.
+#:   ``--single-process`` is the only large lever (~15%), and it is opt-in
+#:   because upstream labels it unsupported.
+#:
+#: RSS is NOT the right metric here: Chromium shares libraries and file pages
+#: across its processes, so summing RSS double-counts and produced numbers that
+#: were ~2x too high and misleadingly ranked a smaller configuration as larger.
+#:
+#: Select a profile with KIWY_CHROMIUM_MODE=light|minimal|safe.
+LIGHT_WEIGHT_FLAGS = [
+    # One renderer instead of a pool.
+    '--renderer-process-limit=1',
+    # Do not retain a renderer for a window that is not visible.
+    '--disable-backgrounding-occluded-windows',
+    '--disable-renderer-backgrounding',
+    '--disable-breakpad',
+    # Keep the process count down; each helper is a forked Chromium.
+    '--disable-site-isolation-trials',
+    '--disable-features=site-per-process,IsolateOrigins',
+    # No persisted session state to load on start.
+    '--no-restore-session-state',
+]
+
+#: ``--single-process`` is the one large lever (~438 MB vs ~507 MB) but Chromium
+#: upstream labels the mode unsupported. Selected via
+#: KIWY_CHROMIUM_MODE=minimal; verified stable over repeated launches of the
+#: real weblink page.
+#:
+#: NOTE: ``--disable-gpu`` is intentionally absent from every list. It measured
+#: WORSE (~1038 MB) and is not worth a dead constant to keep around.
+MINIMAL_FLAGS = ['--single-process']
+
+#: Everything a static page does not need. Each service is a separate process.
+SERVICE_REDUCTION_FLAGS = [
+    '--no-service-autorun',
+    '--disable-component-extensions-with-background-pages',
+    '--disable-default-apps',
+    '--disable-extensions',
+    '--disable-plugins-discovery',
+    '--disable-preconnect',
+    '--disable-domain-reliability',
+    '--disable-client-side-phishing-detection',
+    '--disable-hang-monitor',
+    '--metrics-recording-only',
+    '--no-pings',
+]
+
+
+def _chromium_mode():
+    """Footprint profile: ``light`` (default), ``minimal`` or ``safe``.
+
+    * ``light``   — safe reductions, no GPU, one renderer (recommended)
+    * ``minimal`` — adds ``--single-process``; smallest, can crash
+    * ``safe``    — no footprint flags at all, for ruling them out when debugging
+    """
+    value = os.environ.get('KIWY_CHROMIUM_MODE', 'light').strip().lower()
+    if value not in ('light', 'minimal', 'safe'):
+        _log(f'unknown KIWY_CHROMIUM_MODE={value!r}; using "light"', 'warning')
+        return 'light'
+    return value
+
+
+#: Flags that make a signage page behave like an appliance.
+#:
+#: NOTE: every list here must be referenced from ``extra_launch_args()``. This
+#: list was dead code once, which silently disabled the keyring bypass along
+#: with every kiosk nicety.
+APPLIANCE_FLAGS = [
+    '--noerrdialogs',
+    '--disable-infobars',
+    '--no-first-run',
+    '--no-default-browser-check',
+    '--disable-session-crashed-bubble',
+    '--disable-features=Translate,BackForwardCache,AcceptCHFrame,MediaRouter,OptimizationHints,PasswordManagerOnboarding,AutofillServerCommunication,PasswordLeakDetection',
+    '--disable-background-networking',
+    '--disable-component-update',
+    '--disable-sync',
+    '--check-for-update-interval=31536000',
+    '--autoplay-policy=no-user-gesture-required',
+    '--hide-scrollbars',
+    '--disable-pinch',
+    '--overscroll-history-navigation=0',
+    '--force-device-scale-factor=1',
+    '--window-position=0,0',
+]
+
+#: Never offer to save or autofill credentials — a second source of prompts.
+#: The pages shown are public, so suppressing this costs nothing.
+NO_PROMPTS_FLAGS = [
+    '--disable-save-password-bubble',
+]
+
+
+def _browser_env():
+    """Environment for the browser process only — never the player.
+
+    Defence in depth for the keyring prompt. Even if Chromium ignores
+    ``--password-store=basic``, an emptied ``GNOME_KEYRING_CONTROL`` and a
+    removed ``DBUS_SESSION_BUS_ADDRESS`` mean the Secret Service cannot be
+    reached, so no unlock prompt can be raised at all.
+
+    Scoped to the child deliberately: the player keeps its real session bus,
+    which other components may rely on.
+    """
+    env = dict(os.environ)
+    env['GNOME_KEYRING_CONTROL'] = ''
+    env['CHROME_PASSWORD_STORE'] = 'basic'
+    # Nothing a single static page needs requires the session bus.
+    env.pop('DBUS_SESSION_BUS_ADDRESS', None)
+    env.pop('DBUS_SESSION_BUS_PID', None)
+    # Discourage portal / keyring autostart helpers from being pulled in.
+    env['XDG_DESKTOP_PORTAL_SUPPRESS'] = '1'
+    return env
+
+
+def find_linux_browser():
+    """Locate a Chromium-family browser, preferring the Debian/RPi names.
+
+    ``chromium-browser`` is checked first only because older RPi OS releases
+    shipped it as the wrapper name; on Trixie the real binary is ``chromium``.
+    """
+    for candidate in (
+        'chromium-browser',   # RPi OS <= Bullseye wrapper
+        'chromium',           # RPi OS Bookworm/Trixie
+        'google-chrome',
+        'google-chrome-stable',
+        'chrome',
+        'microsoft-edge',
+    ):
+        path = shutil.which(candidate)
+        if path:
+            return path
+    return None
+
+
+class LinuxChromiumAdapter(ChromiumSubprocessAdapter):
+    """Chromium kiosk subprocess for Raspberry Pi OS (Wayland/labwc).
+
+    Subclasses :class:`ChromiumSubprocessAdapter` so the session's health
+    checking, interaction watching and generation-tokened teardown all keep
+    working; only the Linux-specific behaviour is overridden.
+    """
+
+    name = 'chromium-kiosk-linux'
+    embedded = False
+
+    def __init__(self, browser_path=None, extra_flags=(), kiosk=True,
+                 profile_dir=None, use_wayland=None):
+        super().__init__(browser_path=browser_path, extra_flags=extra_flags,
+                         kiosk=kiosk)
+        self._profile_dir = profile_dir
+        # Flags follow the detected session. An explicit --ozone-platform is
+        # required on Wayland (see WAYLAND_FLAGS); when there is no Wayland
+        # socket the flags are omitted so Chromium uses its own default (X11).
+        self._use_wayland = _detect_wayland() if use_wayland is None else bool(use_wayland)
+        # Track our own process group so teardown can reap the whole tree.
+        self._pgid = None
+        self._preflight_done = False
+
+    # ── Launch environment / session ─────────────────────────────────
+    def launch_env(self):
+        """Environment for the browser process only.
+
+        This — not the ``--password-store`` flag — is what actually removes the
+        keyring password prompt. The base ``Popen`` inherited the player's
+        environment, which includes ``DBUS_SESSION_BUS_ADDRESS``; Chromium could
+        therefore reach the running ``gnome-keyring-daemon`` and tried to unlock
+        the login keyring.
+        """
+        return _browser_env()
+
+    def start_new_session(self):
+        """Give the browser its own process group so teardown can reap it.
+
+        The base implementation used a plain ``Popen``, so the browser shared
+        the player's process group and ``os.killpg`` was never usable — every
+        weblink left Chromium's GPU/zygote/renderer children behind.
+        """
+        return True
+
+    # ── Flags ────────────────────────────────────────────────────────
+    def extra_launch_args(self):
+        """Flags appended to the Chromium command line.
+
+        Ordering is deliberate: appliance/keyring flags come first so a later
+        list can never accidentally be shadowed, and every module-level list is
+        referenced here. If you add a list above, add it here too — a list that
+        nothing references is how the keyring prompt survived a "fix".
+        """
+        args = []
+
+        # 1. Never touch the Secret Service / keyring (the password prompt).
+        args.extend(KEYRING_BYPASS_FLAGS)
+        args.extend(NO_PROMPTS_FLAGS)
+
+        # 2. Kiosk behaviour: no browser UI, no error dialogs, no autofill.
+        args.extend(APPLIANCE_FLAGS)
+        args.extend(SERVICE_REDUCTION_FLAGS)
+
+        # 3. Footprint. A static signage page needs a fraction of Chromium's
+        #    defaults; each avoided helper is a process the Pi 4 does not have
+        #    RAM for.
+        mode = _chromium_mode()
+        if mode in ('light', 'minimal'):
+            args.extend(LIGHT_WEIGHT_FLAGS)
+        if mode == 'minimal':
+            args.extend(MINIMAL_FLAGS)
+
+        # 4. Identity and geometry.
+        if self._profile_dir:
+            args.append('--user-data-dir=' + self._profile_dir)
+        if self._kiosk:
+            # --kiosk implies fullscreen and removes all browser UI, which is
+            # the supported path on wlroots compositors.
+            args.append('--kiosk')
+        if self._use_wayland:
+            args.extend(WAYLAND_FLAGS)
+
+        return args
+
+    def launch(self, url, width, height):
+        """Prepare the private profile, then delegate to the base launch.
+
+        Any Chromium still holding the profile is killed first: a surviving
+        instance would swallow the URL and make our process exit immediately.
+        """
+        self._preflight()
+
+        if self._profile_dir is None:
+            self._profile_dir = os.path.join(
+                os.environ.get('KIWY_DATA_DIR') or os.getcwd(), '.kiosk-profile'
+            )
+        try:
+            os.makedirs(self._profile_dir, exist_ok=True)
+        except Exception as exc:
+            _log(f'could not create kiosk profile {self._profile_dir}: {exc}', 'warning')
+
+        self._kill_browsers_on_profile()
+        self._cleanup_stale_profile_locks()
+        ok = super().launch(url, width, height)
+        if ok and self._proc is not None:
+            self._pgid = _safe_getpgid(self._proc.pid)
+        return ok
+
+    def _preflight(self):
+        """Warn once when Chromium's platform flags do not match this session.
+
+        The failure this guards against is silent: on a Wayland session with no
+        X server, Chromium started without ``--ozone-platform=wayland`` aborts
+        after ~1 s with "Missing X server or $DISPLAY" on stderr, which reads
+        identically to a hand-off bug. Detecting the mismatch at launch time
+        turns an unexplained skipped weblink into an actionable log line.
+        """
+        if getattr(self, '_preflight_done', False):
+            return
+        self._preflight_done = True
+
+        has_x_server = bool(os.environ.get('DISPLAY'))
+        if self._use_wayland and not has_x_server:
+            _log('session is Wayland-only; launching Chromium with '
+                 '--ozone-platform=wayland (the default and --ozone-platform-hint '
+                 'both abort with "Missing X server" here)')
+        elif not self._use_wayland and has_x_server:
+            _log('session is X11; launching Chromium without Wayland flags')
+        elif self._use_wayland and has_x_server:
+            _log('both Wayland and X11 available; preferring Wayland')
+
+    # ── Startup verification ─────────────────────────────────────────
+    def wait_visible(self, timeout):
+        """Wait until the launched Chromium is genuinely up and not a hand-off.
+
+        A plain "process still alive" check is not enough on Linux: a hand-off
+        launch also stays alive briefly, and a missing Wayland socket produces a
+        fast exit. Two signals are combined:
+
+        * the process must survive the health grace period; and
+        * a Chromium window/toplevel must be observable for this PID.
+
+        If the second cannot be established on this compositor we still return
+        success on the first, so a working-but-unprobeable setup is never
+        skipped (that would be worse than a possible blank frame).
+        """
+        proc = self._proc
+        if proc is None:
+            return False, 'no process'
+
+        deadline = time.monotonic() + max(1.0, float(timeout))
+        grace = min(float(self._health_grace), max(0.5, float(timeout)))
+        grace_deadline = time.monotonic() + grace
+
+        while time.monotonic() < grace_deadline:
+            if proc.poll() is not None:
+                return False, f'browser exited immediately (rc={proc.returncode})'
+            time.sleep(0.1)
+
+        if _window_exists_for_pid(proc.pid):
+            return True, f'toplevel-for-pid={proc.pid}'
+
+        while time.monotonic() < deadline:
+            if proc.poll() is not None:
+                return False, f'browser exited early (rc={proc.returncode})'
+            if _window_exists_for_pid(proc.pid):
+                return True, f'toplevel-for-pid={proc.pid}'
+            time.sleep(0.2)
+
+        if proc.poll() is None:
+            # Alive past the timeout but not probeable — accept rather than
+            # skipping a page that is probably on screen.
+            return True, 'process-alive-unverified'
+        return False, 'browser window never appeared'
+
+    # ── Teardown ─────────────────────────────────────────────────────
+    def teardown(self):
+        """Terminate the whole Chromium process group.
+
+        ``proc.terminate()`` (the base behaviour) leaves the GPU, zygote and
+        renderer children behind; over a 24/7 playlist those accumulate until
+        the Pi runs out of memory. Killing the process group reaps them all.
+        """
+        proc, self._proc = self._proc, None
+        pgid, self._pgid = self._pgid, None
+        if proc is None:
+            return
+
+        if proc.poll() is None:
+            _kill_process_group(proc, pgid)
+
+        # Belt and braces: reap anything else still holding this profile.
+        self._kill_browsers_on_profile()
+        self._cleanup_stale_profile_locks()
+
+    # ── Helpers ──────────────────────────────────────────────────────
+    def _cleanup_stale_profile_locks(self):
+        """Remove the singleton lock a crashed Chromium left behind.
+
+        Chromium refuses to start on a profile whose ``SingletonLock`` points at
+        a dead PID (or shows the "profile in use" dialog). Because our profile
+        is private to the player, clearing the lock is always safe.
+        """
+        if not self._profile_dir:
+            return
+        for name in ('SingletonLock', 'SingletonSocket', 'SingletonCookie'):
+            path = os.path.join(self._profile_dir, name)
+            try:
+                if os.path.islink(path) or os.path.exists(path):
+                    os.unlink(path)
+                    _log(f'cleared stale profile lock {name}', 'debug')
+            except Exception:
+                pass
+
+    def _kill_browsers_on_profile(self):
+        """Kill any Chromium holding our kiosk profile.
+
+        Scans ``/proc/<pid>/cmdline`` rather than shelling out to ``pgrep`` so
+        this works without procps and cannot match the wrong process.
+        """
+        if not self._profile_dir:
+            return []
+        marker = self._profile_dir
+        own_uid = os.getuid()
+        killed = []
+        try:
+            for entry in os.listdir('/proc'):
+                if not entry.isdigit():
+                    continue
+                pid = int(entry)
+                if pid == os.getpid():
+                    continue
+                try:
+                    if os.stat(f'/proc/{pid}').st_uid != own_uid:
+                        continue
+                    with open(f'/proc/{pid}/cmdline', 'rb') as fh:
+                        cmdline = fh.read().replace(b'\x00', b' ').decode(
+                            'utf-8', 'replace'
+                        )
+                except (OSError, PermissionError, ProcessLookupError):
+                    continue
+                if marker in cmdline and 'chrom' in cmdline.lower():
+                    try:
+                        os.kill(pid, signal.SIGTERM)
+                        killed.append(pid)
+                    except Exception:
+                        continue
+        except Exception as exc:
+            _log(f'profile scan failed: {exc}', 'debug')
+        if killed:
+            _log(f'terminated {len(killed)} leaked browser(s) on the kiosk '
+                 f'profile: {killed}')
+        return killed
+
+
+# ── Module-level helpers ─────────────────────────────────────────────
+def _detect_wayland():
+    """True when the session looks like Wayland.
+
+    Uses ``linux_display`` when importable (it also fills in an unset
+    ``WAYLAND_DISPLAY``, which Chromium needs for --ozone-platform-hint), and
+    falls back to a socket probe so this module stays independently testable.
+    """
+    if os.environ.get('WAYLAND_DISPLAY'):
+        return True
+    try:
+        import linux_display
+
+        linux_display.ensure_session_environment()
+        return linux_display.is_wayland()
+    except Exception:
+        runtime = os.environ.get('XDG_RUNTIME_DIR') or f'/run/user/{os.getuid()}'
+        return os.path.exists(os.path.join(runtime, 'wayland-0'))
+
+
+def _safe_getpgid(pid):
+    try:
+        return os.getpgid(pid)
+    except Exception:
+        return None
+
+
+def _kill_process_group(proc, pgid):
+    """SIGTERM then SIGKILL the browser's process group."""
+    target = pgid if pgid and pgid != os.getpgid(0) else None
+    try:
+        if target:
+            os.killpg(target, signal.SIGTERM)
+        else:
+            proc.terminate()
+    except Exception:
+        try:
+            proc.terminate()
+        except Exception:
+            pass
+
+    # Give Chromium a moment to flush and exit cleanly.
+    deadline = time.monotonic() + 5.0
+    while time.monotonic() < deadline:
+        if proc.poll() is not None:
+            break
+        time.sleep(0.1)
+
+    if proc.poll() is None:
+        try:
+            if target:
+                os.killpg(target, signal.SIGKILL)
+            else:
+                proc.kill()
+        except Exception:
+            pass
+        try:
+            proc.wait(timeout=3)
+        except Exception:
+            pass
+
+
+def _window_exists_for_pid(pid):
+    """Best-effort check that ``pid`` owns a visible top-level surface.
+
+    Two independent probes, because neither works everywhere:
+
+    1. ``/proc/<pid>/fd`` — Chromium holds the Wayland/X11 socket open once it
+       has connected and started creating surfaces.
+    2. ``/proc/<pid>/task/*/comm`` — the GPU/renderer children only appear once
+       the browser has actually started rendering.
+
+    Returns False on any error; the caller falls back to "process alive".
+    """
+    try:
+        fd_dir = f'/proc/{pid}/fd'
+        socket_links = 0
+        for fd in os.listdir(fd_dir):
+            try:
+                target = os.readlink(os.path.join(fd_dir, fd))
+            except OSError:
+                continue
+            if 'wayland' in target or 'X11-unix' in target:
+                socket_links += 1
+        if socket_links:
+            return True
+    except Exception:
+        pass
+
+    try:
+        task_dir = f'/proc/{pid}/task'
+        for tid in os.listdir(task_dir):
+            try:
+                with open(os.path.join(task_dir, tid, 'comm')) as fh:
+                    comm = fh.read().strip()
+            except OSError:
+                continue
+            if comm in ('Chrome_ChildIOT', 'Chrome_IOThread'):
+                return True
+    except Exception:
+        pass
+
+    return False

linux/linux_display.py

@@ -0,0 +1,425 @@
+"""linux_display.py — display power, keep-awake and rotation for Raspberry Pi OS.
+
+Why this module exists
+----------------------
+On Raspberry Pi OS "Trixie" the desktop session is **Wayland/labwc**, and an
+idle blanker is installed and running by default::
+
+    swayidle -w timeout 600 'wlopm --off *' resume 'wlopm --on *'
+
+A signage player must never blank, so that line fights the player for control of
+the output. The historical implementation in ``main.py``
+(``signal_screen_activity``) shells out to X11 tools that no longer exist on
+Trixie (``xdotool``, ``tvservice``, ``ydotool`` are all absent) and uses a
+mis-escaped ``wlopm --on \\*`` argument, so it kept the screen awake on none of
+the current installs.
+
+This module replaces that logic with the commands Trixie actually provides:
+
+* ``wlopm``        — Wayland output power management (present, works)
+* ``vcgencmd display_power`` — Raspberry Pi firmware-level display power
+* ``wlr-randr``    — output configuration, used for rotation (present)
+
+All work is best-effort and non-fatal: running the player over SSH, or on a
+desktop without a compositor, must never crash or spam the log.
+
+The platform entry point (``linux/run_linux.py``) installs
+:func:`linux_screen_activity` onto ``SignagePlayer`` before playback starts.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import time
+
+# ── Tunables ─────────────────────────────────────────────────────────
+#: Don't re-issue the keep-awake commands more often than this (seconds).
+#: ``signal_screen_activity`` is called on a 20 s Kivy interval; the commands
+#: are idempotent but spawning processes on a Pi is not free.
+MIN_REASSERT_INTERVAL = 5.0
+
+#: Set to "1" to disable every display command (diagnostics / desktop testing).
+DISABLE_ENV_VAR = 'KIWY_DISPLAY_TOOLS_DISABLED'
+
+#: Output name used when the compositor does not report one.
+DEFAULT_OUTPUT = 'HDMI-A-1'
+
+_state = {
+    'last_awake_at': 0.0,
+    'blinker_pids': [],
+    'logged_backend': False,
+    'warned_no_backend': False,
+}
+
+
+def _log(message, level='info'):
+    """Log through Kivy when available, else print. Never raises."""
+    try:
+        from kivy.logger import Logger
+
+        getattr(Logger, level, Logger.info)(f'[Display] {message}')
+    except Exception:
+        try:
+            if level in ('error', 'warning'):
+                print(f'[Display] {message}')
+        except Exception:
+            pass
+
+
+# ── Environment detection ────────────────────────────────────────────
+def is_wayland():
+    """True when a Wayland compositor socket is reachable.
+
+    Deliberately based on the socket, not on ``WAYLAND_DISPLAY``: the variable
+    is empty in exactly the launch contexts this module exists to fix (systemd,
+    cron, SSH), where the socket is nevertheless present and usable.
+    """
+    return wayland_socket_path() is not None
+
+
+def is_x11():
+    """True when an X11 display is reachable (and Wayland is not)."""
+    return bool(os.environ.get('DISPLAY')) and not is_wayland()
+
+
+def tools_disabled():
+    """Honour the operator escape hatch."""
+    return os.environ.get(DISABLE_ENV_VAR, '').strip().lower() in ('1', 'true', 'yes')
+
+
+# ── Command helper ───────────────────────────────────────────────────
+def wayland_socket_path():
+    """Absolute path of the Wayland socket, or None."""
+    runtime = os.environ.get('XDG_RUNTIME_DIR') or f'/run/user/{os.getuid()}'
+    display = os.environ.get('WAYLAND_DISPLAY') or ''
+    if display:
+        # Absolute names are used as-is; relative names live in XDG_RUNTIME_DIR.
+        return display if os.path.isabs(display) else os.path.join(runtime, display)
+    candidate = os.path.join(runtime, 'wayland-0')
+    return candidate if os.path.exists(candidate) else None
+
+
+def ensure_session_environment():
+    """Fill in the display environment for our child processes.
+
+    **This is the bug that made keep-awake silently useless.** A process started
+    by ``systemd``, a cron wrapper or an SSH session has ``XDG_RUNTIME_DIR`` set
+    but ``WAYLAND_DISPLAY`` *empty* — the compositor only exports it inside the
+    desktop session. ``wlopm`` then fails with::
+
+        ERROR: WAYLAND_DISPLAY is not set.
+
+    and exits 1, so the panel blanks after the idle timeout. Detecting the
+    socket and exporting the name (derived from its filename, so an unusual
+    ``wayland-1`` still works) makes the tools function regardless of how the
+    player was launched.
+
+    Only ever *sets* values that are missing, so an operator-provided value is
+    never overridden. Returns a dict of what was changed (for logging).
+    """
+    changed = {}
+
+    runtime = os.environ.get('XDG_RUNTIME_DIR')
+    if not runtime:
+        fallback = f'/run/user/{os.getuid()}'
+        if os.path.isdir(fallback):
+            os.environ['XDG_RUNTIME_DIR'] = fallback
+            changed['XDG_RUNTIME_DIR'] = fallback
+            runtime = fallback
+
+    if not os.environ.get('WAYLAND_DISPLAY') and runtime:
+        try:
+            # Prefer wayland-0, else the lowest-numbered socket present.
+            candidates = sorted(
+                name for name in os.listdir(runtime)
+                if name.startswith('wayland-') and not name.endswith('.lock')
+            )
+            if candidates:
+                os.environ['WAYLAND_DISPLAY'] = candidates[0]
+                changed['WAYLAND_DISPLAY'] = candidates[0]
+        except Exception:
+            pass
+
+    return changed
+
+
+def _run(args, timeout=5.0):
+    """Run a command quietly. Returns (returncode, stdout) — never raises.
+
+    ``stderr`` is discarded: ``wlopm``/``wlr-randr`` are chatty about compositor
+    details we do not act on, and the player's log is noise-sensitive.
+    """
+    ensure_session_environment()
+    try:
+        result = subprocess.run(
+            args,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            stdin=subprocess.DEVNULL,
+            timeout=timeout,
+            text=True,
+            check=False,
+        )
+        return result.returncode, (result.stdout or '').strip()
+    except FileNotFoundError:
+        return 127, ''
+    except subprocess.TimeoutExpired:
+        _log(f'{args[0]} timed out after {timeout}s', 'debug')
+        return 124, ''
+    except Exception as exc:  # pragma: no cover - defensive
+        _log(f'{args[0]} failed: {exc}', 'debug')
+        return 1, ''
+
+
+def _which(name):
+    try:
+        return shutil.which(name)
+    except Exception:
+        return None
+
+
+# ── Output discovery ─────────────────────────────────────────────────
+def list_outputs():
+    """Return the connected Wayland output names (best effort).
+
+    Uses ``wlopm`` (no arguments lists ``<name> <on|off>`` per line), falling
+    back to ``wlr-randr`` so rotation works even where ``wlopm`` is missing.
+    """
+    if not is_wayland():
+        return []
+    code, out = _run(['wlopm'])
+    if code == 0 and out:
+        names = []
+        for line in out.splitlines():
+            parts = line.split()
+            if parts:
+                names.append(parts[0])
+        if names:
+            return names
+    code, out = _run(['wlr-randr'])
+    if code == 0 and out:
+        names = []
+        for line in out.splitlines():
+            # Output lines are unindented: "HDMI-A-1 \"...\""
+            if line and not line[0].isspace():
+                names.append(line.split()[0])
+        return names
+    return []
+
+
+def _target_output():
+    """The output to address, or ``'*'`` so the compositor expands it.
+
+    ``wlopm`` expands ``'*'`` itself, which is more robust than us guessing the
+    connector name (HDMI-A-1 / HDMI-A-2 / DSI-1 differ per board and port).
+    """
+    return '*'
+
+
+# ── Keep-awake ───────────────────────────────────────────────────────
+def keep_display_awake(force=False):
+    """Turn the display back on. Cheap, idempotent, rate-limited.
+
+    Returns True when something was actually issued.
+    """
+    if tools_disabled():
+        return False
+
+    now = time.monotonic()
+    if not force and (now - _state['last_awake_at']) < MIN_REASSERT_INTERVAL:
+        return False
+    _state['last_awake_at'] = now
+
+    issued = False
+    failures = []
+
+    if is_wayland() and _which('wlopm'):
+        # NOTE: the argument must stay the literal '*' — the shell must not
+        # expand it (we pass a list, so no shell is involved) and wlopm does
+        # the matching. The old code passed a backslash-escaped '\*' through
+        # os.system(), so the compositor matched an output literally named '*'
+        # and nothing happened.
+        ensure_session_environment()
+        code, out = _run(['wlopm', '--on', _target_output()])
+        issued = issued or code == 0
+        if code != 0:
+            failures.append(f'wlopm --on {_target_output()} rc={code} {out}'.strip())
+    elif is_x11():
+        if _which('xset'):
+            code, _ = _run(['xset', 's', 'reset'])
+            issued = issued or code == 0
+            _run(['xset', 'dpms', 'force', 'on'])
+        if _which('xdotool'):
+            # Nudge the pointer by a pixel and back — invisible, but enough to
+            # reset the X idle counter on compositors without a Wayland path.
+            code, _ = _run(['xdotool', 'mousemove_relative', '1', '1'])
+            if code == 0:
+                _run(['xdotool', 'mousemove_relative', '-1', '-1'])
+                issued = True
+
+    # Firmware-level backstop: covers a blanked HDMI signal even when the
+    # compositor never reported the output as off.
+    if _which('vcgencmd'):
+        _run(['vcgencmd', 'display_power', '1'])
+
+    if failures and not _state['warned_no_backend']:
+        _state['warned_no_backend'] = True
+        _log(
+            'keep-awake command failed: ' + '; '.join(failures)
+            + f' (WAYLAND_DISPLAY={os.environ.get("WAYLAND_DISPLAY")!r})',
+            'warning',
+        )
+    elif not issued and not _state['warned_no_backend']:
+        _state['warned_no_backend'] = True
+        _log(
+            'No usable display backend found (no Wayland socket and no X11 '
+            'display) — keep-awake is inactive.',
+            'warning',
+        )
+    return issued
+
+
+def neutralise_idle_blanker():
+    """Stop the desktop idle blanker from turning the panel off.
+
+    On Raspberry Pi OS Trixie ``~/.config/labwc/autostart`` starts::
+
+        swayidle -w timeout 600 'wlopm --off *' resume 'wlopm --on *'
+
+    That is exactly the behaviour a signage player must override, so the
+    ``swayidle`` process is terminated once at start-up and re-checked
+    periodically (in case the session restarts it).
+
+    Only processes owned by the current user are touched, and a failure is
+    never fatal. Set ``KIWY_DISPLAY_TOOLS_DISABLED=1`` to opt out.
+    """
+    if tools_disabled() or not _which('swayidle'):
+        return []
+
+    try:
+        result = subprocess.run(
+            ['pgrep', '-x', 'swayidle'],
+            stdout=subprocess.PIPE, stderr=subprocess.DEVNULL,
+            text=True, timeout=5, check=False,
+        )
+        pids = [int(p) for p in (result.stdout or '').split() if p.strip().isdigit()]
+    except Exception:
+        return []
+
+    own_uid = os.getuid()
+    killed = []
+    for pid in pids:
+        try:
+            # Only our own processes: swayidle is per-session and killing
+            # another user's would be a surprise.
+            if os.stat(f'/proc/{pid}').st_uid != own_uid:
+                continue
+            os.kill(pid, 15)  # SIGTERM
+            killed.append(pid)
+        except (ProcessLookupError, PermissionError, FileNotFoundError):
+            continue
+        except Exception:
+            continue
+
+    if killed:
+        _log(f'Stopped the idle blanker (swayidle pids: {killed}) — the display '
+             f'will stay on. Disable with {DISABLE_ENV_VAR}=1.')
+    return killed
+
+
+def _log_backend_once():
+    if _state['logged_backend']:
+        return
+    _state['logged_backend'] = True
+    backend = 'wayland' if is_wayland() else ('x11' if is_x11() else 'none')
+    _log(f'backend={backend} outputs={list_outputs() or "unknown"} '
+         f'WAYLAND_DISPLAY={os.environ.get("WAYLAND_DISPLAY") or "(unset)"} '
+         f'wlopm={bool(_which("wlopm"))} vcgencmd={bool(_which("vcgencmd"))}')
+
+
+# ── SignagePlayer replacement ────────────────────────────────────────
+def linux_screen_activity(self, dt):
+    """Drop-in replacement for ``SignagePlayer.signal_screen_activity``.
+
+    Bound to a 20 s Kivy interval, so it must be cheap and must never raise.
+    """
+    try:
+        _log_backend_once()
+        keep_display_awake()
+        # Cheap re-check: the blanker may have been restarted by the session,
+        # e.g. after a compositor reload.
+        if (time.monotonic() - _state.get('last_blinker_check', 0.0)) > 60.0:
+            _state['last_blinker_check'] = time.monotonic()
+            neutralise_idle_blanker()
+    except Exception as exc:  # pragma: no cover - must never break the Clock
+        _log(f'screen activity signal failed (non-fatal): {exc}', 'debug')
+
+
+# ── Orientation / resolution (Wayland-native) ────────────────────────
+#: Logical rotation for each supported orientation value from app_config.json.
+ORIENTATION_TRANSFORMS = {
+    'landscape': 'normal',
+    'portrait': '90',
+    'portrait-inverted': '270',
+    'landscape-inverted': '180',
+}
+
+
+def apply_orientation(orientation):
+    """Rotate the display to match the configured orientation.
+
+    ``Window.size`` cannot rotate a fullscreen Wayland surface, so the rotation
+    has to happen at the output level. ``wlr-randr`` is the tool that works on
+    labwc; the call is skipped silently when it is unavailable.
+
+    Returns True when a transform was applied.
+    """
+    if tools_disabled():
+        return False
+
+    key = str(orientation or '').strip().lower()
+    transform = ORIENTATION_TRANSFORMS.get(key)
+    if not transform or transform == 'normal':
+        return False
+
+    if not is_wayland() or not _which('wlr-randr'):
+        _log(f'Orientation "{orientation}" requested but wlr-randr/Wayland is '
+             f'unavailable — leaving the output unrotated.', 'warning')
+        return False
+
+    outputs = list_outputs() or [DEFAULT_OUTPUT]
+    applied = False
+    for name in outputs:
+        code, _ = _run(['wlr-randr', '--output', name, '--transform', transform])
+        applied = applied or code == 0
+    if applied:
+        _log(f'Applied orientation "{orientation}" (transform={transform}) to '
+             f'{outputs}')
+    return applied
+
+
+def status():
+    """Diagnostic snapshot (used by tests and the startup banner)."""
+    return {
+        'wayland': is_wayland(),
+        'wayland_socket': wayland_socket_path(),
+        'wayland_display': os.environ.get('WAYLAND_DISPLAY') or '(unset)',
+        'x11': is_x11(),
+        'disabled': tools_disabled(),
+        'outputs': list_outputs(),
+        'wlopm': bool(_which('wlopm')),
+        'wlr_randr': bool(_which('wlr-randr')),
+        'vcgencmd': bool(_which('vcgencmd')),
+    }
+
+
+if __name__ == '__main__':  # pragma: no cover - manual diagnostics
+    import json
+    import sys
+
+    if len(sys.argv) > 1 and sys.argv[1] == '--awake':
+        print('awake issued:', keep_display_awake(force=True))
+        print('blinker killed:', neutralise_idle_blanker())
+    print(json.dumps(status(), indent=2))

linux/monitor_player.py

@@ -0,0 +1,467 @@
+"""monitor_player.py — CPU, GPU, temperature and memory monitor for the player.
+
+A 24/7 signage player on a Raspberry Pi 4 fails in slow, quiet ways: the SoC
+throttles, the CPU governor parks a core, memory creeps up until the OOM killer
+picks a victim. This samples the numbers that reveal those trends before they
+become a blank screen.
+
+Usage:
+    # live view, 5s interval, until Ctrl+C
+    .venv/bin/python linux/monitor_player.py
+
+    # 10 minutes at 2s, also written to CSV
+    .venv/bin/python linux/monitor_player.py --interval 2 --duration 600
+
+    # background logging only (no live view)
+    .venv/bin/python linux/monitor_player.py --quiet --duration 3600 \
+        --csv logs/monitor-$(date +%F-%H%M).csv
+
+What is measured, and why each one matters:
+
+| Metric | Why it matters here |
+|--------|--------------------|
+| Temperature | Pi 4 throttles at 80 °C (soft limit 85 °C). Sustained high temp means the case or heatsink is inadequate for 24/7. |
+| Throttle flags | ``vcgencmd get_throttled`` distinguishes *currently throttled* from *has throttled since boot* — the second one only (bits 16-19) reveals a problem that already happened. |
+| ARM clock | Dropping below the configured max mid-run is the signature of thermal/voltage capping. |
+| V3D / pixel clock | The VideoCore GPU clock. A weblink drives it; a static image barely does. |
+| Core voltage | Under-voltage (bit 0 of the throttle mask) is almost always an inadequate PSU, and it corrupts SD cards. |
+| Per-core CPU | One pegged core is normal for Kivy (single-threaded main loop); all four pegged is not. |
+| Player PSS | Proportional set size of the player process — the honest figure. |
+| Chromium total | A *count* as much as memory: a rising count means weblinks are leaking. |
+| /dev/shm | Chromium renders through shared memory; if it fills, pages render blank. |
+
+GPU utilisation is deliberately absent: the Pi 4's V3D exposes no
+``gpu_busy_percent`` (that is a Pi 5 / v3d-drm feature) and
+``/sys/kernel/debug/dri/0/gpu_stats`` does not exist here. GPU activity is
+therefore inferred from the clock domains and the temperature, which is the
+best this hardware offers.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import os
+import subprocess
+import sys
+import time
+from datetime import datetime
+
+try:
+    import psutil
+except ImportError:
+    print('psutil is required: .venv/bin/pip install psutil', file=sys.stderr)
+    raise SystemExit(2)
+
+
+# ── Constants ────────────────────────────────────────────────────────
+#: Pi 4 begins soft-throttling around here. Warning threshold, not a limit.
+TEMP_WARN_C = 70.0
+#: Active soft-throttle limit on Pi 4.
+TEMP_CRITICAL_C = 80.0
+
+#: ``vcgencmd get_throttled`` bit meanings. The 16-19 group is sticky: it
+#: records that the condition occurred at any point since boot, which is the
+#: only way to catch an intermittent brown-out on an unattended device.
+THROTTLE_BITS = {
+    0: ('NOW', 'under-voltage'),
+    1: ('NOW', 'arm frequency capped'),
+    2: ('NOW', 'currently throttled'),
+    3: ('NOW', 'soft temperature limit'),
+    16: ('HAS', 'under-voltage occurred'),
+    17: ('HAS', 'arm frequency capping occurred'),
+    18: ('HAS', 'throttling occurred'),
+    19: ('HAS', 'soft temperature limit occurred'),
+}
+
+CLOCK_DOMAINS = ('arm', 'core', 'v3d', 'h264', 'pixel')
+
+CSV_FIELDS = [
+    'timestamp', 'uptime_s',
+    'cpu_total_pct', 'cpu0_pct', 'cpu1_pct', 'cpu2_pct', 'cpu3_pct',
+    'load1', 'load5', 'load15',
+    'temp_c', 'volt_core_v',
+    'arm_mhz', 'core_mhz', 'v3d_mhz', 'pixel_mhz', 'h264_mhz',
+    'governor', 'arm_cur_mhz_cfg',
+    'mem_used_mb', 'mem_avail_mb', 'shm_used_mb',
+    'player_pss_mb', 'player_cpu_pct', 'player_threads',
+    'chromium_procs', 'chromium_pss_mb',
+    'throttled_raw', 'throttle_flags',
+]
+
+
+def _run(args, timeout=5):
+    """Run a command, return stripped stdout, or '' on any failure."""
+    try:
+        result = subprocess.run(
+            args, capture_output=True, text=True, timeout=timeout, check=False,
+        )
+        return (result.stdout or '').strip()
+    except Exception:
+        return ''
+
+
+def _read(path):
+    try:
+        with open(path) as fh:
+            return fh.read().strip()
+    except Exception:
+        return ''
+
+
+# ── Individual metrics ───────────────────────────────────────────────
+def read_temp_c():
+    """SoC temperature in °C from hwmon, falling back to vcgencmd/thermal."""
+    raw = _read('/sys/class/hwmon/hwmon0/temp1_input')
+    if raw.isdigit():
+        return int(raw) / 1000.0
+    for zone in ('/sys/class/thermal/thermal_zone0/temp',):
+        raw = _read(zone)
+        if raw.isdigit():
+            return int(raw) / 1000.0
+    out = _run(['vcgencmd', 'measure_temp'])
+    # "temp=50.1'C"
+    try:
+        return float(out.split('=')[1].split("'")[0])
+    except Exception:
+        return None
+
+
+def read_clock_mhz(domain):
+    """Clock frequency in MHz for a vcgencmd domain."""
+    out = _run(['vcgencmd', 'measure_clock', domain])
+    # "frequency(48)=1800457088"
+    try:
+        return int(out.split('=')[1]) / 1_000_000.0
+    except Exception:
+        return None
+
+
+def read_core_volts():
+    out = _run(['vcgencmd', 'measure_volts', 'core'])
+    # "volt=0.9160V"
+    try:
+        return float(out.split('=')[1].rstrip('V'))
+    except Exception:
+        return None
+
+
+def read_throttled():
+    """(raw_int, [human readable flags]) from vcgencmd get_throttled."""
+    out = _run(['vcgencmd', 'get_throttled'])
+    # "throttled=0x0"
+    try:
+        raw = int(out.split('=')[1], 16)
+    except Exception:
+        return None, []
+    flags = []
+    for bit, (when, label) in THROTTLE_BITS.items():
+        if raw & (1 << bit):
+            flags.append(f'{when}:{label}')
+    return raw, flags
+
+
+def pss_mb(pid):
+    """PSS in MB for a process, or None. RSS double-counts shared pages."""
+    total_kb = 0
+    try:
+        with open(f'/proc/{pid}/smaps_rollup') as fh:
+            for line in fh:
+                if line.startswith('Pss:'):
+                    total_kb = int(line.split()[1])
+                    break
+    except Exception:
+        return None
+    return total_kb / 1024.0
+
+
+def find_procs(pattern):
+    """PIDs whose cmdline matches ``pattern``, excluding this script."""
+    pids = []
+    me = os.getpid()
+    for proc in psutil.process_iter(['pid', 'cmdline']):
+        try:
+            if proc.info['pid'] == me:
+                continue
+            cmdline = ' '.join(proc.info['cmdline'] or [])
+            if pattern in cmdline and 'monitor_player' not in cmdline:
+                pids.append(proc.info['pid'])
+        except Exception:
+            continue
+    return pids
+
+
+#: ``psutil.Process`` objects kept alive between samples. ``cpu_percent()``
+#: needs a *previous* reading for the same process to compute a delta, so a
+#: freshly constructed Process always reports 0.0. Caching these is what makes
+#: the player's own CPU figure meaningful instead of a constant zero.
+_proc_cache: dict[int, 'psutil.Process'] = {}
+
+
+def player_cpu_percent(pid):
+    """CPU % for ``pid`` since the previous sample."""
+    try:
+        proc = _proc_cache.get(pid)
+        if proc is None or not proc.is_running():
+            proc = psutil.Process(pid)
+            _proc_cache[pid] = proc
+            proc.cpu_percent(interval=None)  # establish the baseline
+            return 0.0
+        return proc.cpu_percent(interval=None)
+    except Exception:
+        return None
+
+
+def sample():
+    """Take one measurement. Never raises; missing metrics become None."""
+    now = time.time()
+    row = {'timestamp': datetime.now().isoformat(timespec='seconds')}
+
+    # CPU. interval=None means "since the previous call" — with a fixed sample
+    # period this yields the usage over exactly that window.
+    try:
+        row['cpu_total_pct'] = psutil.cpu_percent(interval=None)
+        per_core = psutil.cpu_percent(interval=None, percpu=True)
+        for i in range(4):
+            row[f'cpu{i}_pct'] = per_core[i] if i < len(per_core) else None
+        load = os.getloadavg()
+        row['load1'], row['load5'], row['load15'] = load
+    except Exception:
+        row.update({'cpu_total_pct': None, 'load1': None, 'load5': None,
+                    'load15': None})
+
+    # Thermal / power
+    row['temp_c'] = read_temp_c()
+    row['volt_core_v'] = read_core_volts()
+
+    # Clocks
+    for domain in CLOCK_DOMAINS:
+        row[f'{domain}_mhz'] = read_clock_mhz(domain)
+
+    # Governor and configured max
+    row['governor'] = _read(
+        '/sys/devices/system/cpu/cpu0/cpufreq/scaling_governor')
+    cur = _read('/sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq')
+    row['arm_cur_mhz_cfg'] = int(cur) / 1000.0 if cur.isdigit() else None
+
+    # Memory
+    try:
+        mem = psutil.virtual_memory()
+        row['mem_used_mb'] = (mem.total - mem.available) / 1024 / 1024
+        row['mem_avail_mb'] = mem.available / 1024 / 1024
+        shm = psutil.disk_usage('/dev/shm')
+        row['shm_used_mb'] = shm.used / 1024 / 1024
+    except Exception:
+        row.update({'mem_used_mb': None, 'mem_avail_mb': None,
+                    'shm_used_mb': None})
+
+    # The player
+    player_pids = find_procs('run_linux.py')
+    if player_pids:
+        pid = player_pids[0]
+        row['player_pss_mb'] = pss_mb(pid)
+        row['player_cpu_pct'] = player_cpu_percent(pid)
+        try:
+            proc = _proc_cache.get(pid) or psutil.Process(pid)
+            with proc.oneshot():
+                row['player_threads'] = proc.num_threads()
+                # Uptime from the process, for correlating with playback.
+                row['uptime_s'] = now - proc.create_time()
+        except Exception:
+            pass
+    else:
+        row['player_pss_mb'] = None
+        row['player_cpu_pct'] = None
+        row['player_threads'] = None
+
+    # Chromium tree (weblinks). Count is as important as memory: a rising
+    # count means teardown is leaking, which is what kills a 24/7 install.
+    chromium_pids = find_procs('chromium')
+    row['chromium_procs'] = len(chromium_pids)
+    total = 0.0
+    for pid in chromium_pids:
+        value = pss_mb(pid)
+        if value:
+            total += value
+    row['chromium_pss_mb'] = total if chromium_pids else 0.0
+
+    # Throttling
+    raw, flags = read_throttled()
+    row['throttled_raw'] = hex(raw) if raw is not None else None
+    row['throttle_flags'] = ','.join(flags) if flags else ''
+
+    # Fill any field we never set so the CSV stays rectangular.
+    for field in CSV_FIELDS:
+        row.setdefault(field, None)
+    return row
+
+
+# ── Presentation ─────────────────────────────────────────────────────
+def fmt(value, width=6, spec='.1f'):
+    if value is None:
+        return ' ' * (width - 2) + '--'
+    return f'{value:{width}{spec}}'
+
+
+def print_header():
+    print()
+    print('   time    CPU%  cores(0-3)   temp    ARM    V3D  volt   RAM  '
+          'player chrome  gov      flags')
+    print('  ' + '-' * 84)
+
+
+def print_row(row, tick):
+    cores = ' '.join(
+        fmt(row.get(f'cpu{i}_pct'), 3, '.0f') for i in range(4))
+    flags = (row.get('throttle_flags') or '').replace('HAS:', 'had:') \
+        .replace('NOW:', 'NOW:')
+    warn = ''
+    temp = row.get('temp_c')
+    if temp is not None and temp >= TEMP_CRITICAL_C:
+        warn = ' ***HOT***'
+    elif temp is not None and temp >= TEMP_WARN_C:
+        warn = ' *warm*'
+
+    governor = (row.get('governor') or '')[:6]
+    print(
+        f'  {row["timestamp"][11:19]} '
+        f'{fmt(row.get("cpu_total_pct"), 4, ".0f")} '
+        f' {cores}  '
+        f'{fmt(temp, 5)}C '
+        f'{fmt(row.get("arm_mhz"), 6, ".0f")} '
+        f'{fmt(row.get("v3d_mhz"), 5, ".0f")} '
+        f'{fmt(row.get("volt_core_v"), 6, ".3f")}V'
+        f'{fmt(row.get("mem_used_mb"), 5, ".0f")}M '
+        f'{fmt(row.get("player_pss_mb"), 4, ".0f")}M '
+        f'{fmt(row.get("chromium_pss_mb"), 5, ".0f")}M '
+        f'{governor:<6} '
+        f'{flags}{warn}'
+    )
+
+
+def summarise(rows):
+    """Print min/avg/max for the run — the part that reveals a trend."""
+    if not rows:
+        return
+    print('\n  ' + '=' * 84)
+    print(f'  SUMMARY over {len(rows)} samples '
+          f'({rows[0]["timestamp"][11:19]} -> {rows[-1]["timestamp"][11:19]})')
+    print('  ' + '=' * 84)
+
+    def stat(field, spec='.1f', unit=''):
+        values = [r[field] for r in rows
+                  if isinstance(r.get(field), (int, float))]
+        if not values:
+            return f'  {field:<18} (no data)'
+        return (f'  {field:<18} min {min(values):>8{spec}}{unit}   '
+                f'avg {sum(values)/len(values):>8{spec}}{unit}   '
+                f'max {max(values):>8{spec}}{unit}')
+
+    for field, spec, unit in (
+        ('cpu_total_pct', '.1f', '%'),
+        ('temp_c', '.1f', 'C'),
+        ('arm_mhz', '.0f', 'MHz'),
+        ('v3d_mhz', '.0f', 'MHz'),
+        ('volt_core_v', '.3f', 'V'),
+        ('mem_avail_mb', '.0f', 'MB'),
+        ('player_pss_mb', '.0f', 'MB'),
+        ('player_cpu_pct', '.1f', '%'),
+        ('chromium_procs', '.0f', ''),
+        ('chromium_pss_mb', '.0f', 'MB'),
+    ):
+        print(stat(field, spec, unit))
+
+    # Trend: first vs last quarter, which is what matters for a leak.
+    def trend(field):
+        values = [r[field] for r in rows
+                  if isinstance(r.get(field), (int, float))]
+        if len(values) < 8:
+            return ''
+        head = values[:max(1, len(values) // 4)]
+        tail = values[-max(1, len(values) // 4):]
+        delta = sum(tail) / len(tail) - sum(head) / len(head)
+        arrow = 'RISING ' if delta > 0 else 'falling'
+        return (f'  {field:<18} {arrow}  {delta:+8.1f} '
+                f'(first->last quarter)')
+
+    print('\n  Trend (the leak check):')
+    for field in ('player_pss_mb', 'chromium_procs', 'mem_avail_mb', 'temp_c'):
+        line = trend(field)
+        if line:
+            print(line)
+
+    # Throttle history is the headline finding on a Pi.
+    all_flags = set()
+    for row in rows:
+        if row.get('throttle_flags'):
+            all_flags.update(row['throttle_flags'].split(','))
+    print('\n  Throttle / power events during this run:')
+    print(f'    {", ".join(sorted(all_flags)) if all_flags else "none — clean"}')
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Monitor CPU, GPU clock, temperature and memory for the player.')
+    parser.add_argument('--interval', type=float, default=5.0,
+                        help='seconds between samples (default 5)')
+    parser.add_argument('--duration', type=float, default=0,
+                        help='seconds to run; 0 = until Ctrl+C (default 0)')
+    parser.add_argument('--csv', default='',
+                        help='write samples to this CSV file')
+    parser.add_argument('--quiet', action='store_true',
+                        help='no live output (for background logging)')
+    args = parser.parse_args()
+
+    # Prime the CPU counters: the first cpu_percent() call always returns 0.0
+    # because it has no previous sample to compare against.
+    psutil.cpu_percent(interval=None)
+    psutil.cpu_percent(interval=None, percpu=True)
+    for pid in find_procs('run_linux.py'):
+        try:
+            _proc_cache[pid] = psutil.Process(pid)
+            _proc_cache[pid].cpu_percent(interval=None)
+        except Exception:
+            pass
+
+    writer = None
+    csv_handle = None
+    if args.csv:
+        os.makedirs(os.path.dirname(os.path.abspath(args.csv)), exist_ok=True)
+        csv_handle = open(args.csv, 'w', newline='')
+        writer = csv.DictWriter(csv_handle, fieldnames=CSV_FIELDS)
+        writer.writeheader()
+
+    if not args.quiet:
+        print_header()
+
+    rows = []
+    started = time.time()
+    tick = 0
+    try:
+        while True:
+            time.sleep(args.interval)
+            tick += 1
+            row = sample()
+            rows.append(row)
+            if writer:
+                writer.writerow(row)
+                csv_handle.flush()
+            if not args.quiet:
+                print_row(row, tick)
+            if args.duration and (time.time() - started) >= args.duration:
+                break
+    except KeyboardInterrupt:
+        if not args.quiet:
+            print('\n  stopped by user')
+    finally:
+        if csv_handle:
+            csv_handle.close()
+            if not args.quiet:
+                print(f'  CSV written to {args.csv}')
+        if not args.quiet:
+            summarise(rows)
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

linux/run_linux.py

@@ -0,0 +1,555 @@
+"""
+Kiwy Signage Player — Linux / Raspberry Pi entry point
+------------------------------------------------------
+This module prepares a Pi-correct environment, imports the shared application,
+then injects the platform-specific behaviour. ``src/main.py`` itself stays
+cross-platform and holds no platform patches.
+
+Usage:
+    python3 linux/run_linux.py          # development / manual run
+    bash linux/start_player.sh          # supervised run (watchdog)
+
+Target: Raspberry Pi OS "Trixie" 64-bit (Debian 13, aarch64, labwc/Wayland).
+
+What this file is responsible for
+---------------------------------
+1. Environment, set *before* Kivy is imported (video/audio/GL/input backends).
+2. ``sys.path`` so the shared modules in ``src/`` import cleanly.
+3. Injecting the Linux web-link adapter through the existing
+   ``SignagePlayer.weblink_adapter_factory`` hook.
+4. Replacing ``signal_screen_activity`` with the Wayland-aware implementation
+   in ``linux_display.py`` (the inherited one calls X11 tools absent on Trixie).
+5. Pointing ``player_auth.json`` at the player's data directory.
+6. A fatal-error surface that works without a console.
+"""
+
+import json
+import logging
+import os
+import platform
+import sys
+import traceback
+from pathlib import Path
+
+# =====================================================================
+# 0. Resolve directories
+# =====================================================================
+# Layout: <root>/linux/run_linux.py  ->  <root> is the data directory and
+# <root>/src holds the shared modules.
+_HERE = Path(__file__).resolve().parent
+ROOT_DIR = _HERE.parent
+SRC_DIR = ROOT_DIR / 'src'
+LOG_DIR = ROOT_DIR / 'logs'
+
+# The shared modules (main, weblink_session, player_auth, ...) live in src/.
+if str(SRC_DIR) not in sys.path:
+    sys.path.insert(0, str(SRC_DIR))
+
+DATA_DIR = str(ROOT_DIR)
+LOG_DIR.mkdir(parents=True, exist_ok=True)
+
+# Consumed by src/playback_trace.py and our own helpers, so trace/log files land
+# next to the player rather than in whatever directory it happened to start in.
+os.environ.setdefault('KIWY_DATA_DIR', DATA_DIR)
+
+
+def _early_log(message):
+    """Log before Kivy's Logger exists (and mirror to a file)."""
+    line = f'[run_linux] {message}'
+    print(line, flush=True)
+    try:
+        with open(LOG_DIR / 'startup.log', 'a') as fh:
+            from datetime import datetime
+            fh.write(f"{datetime.now().isoformat(timespec='seconds')} {line}\n")
+    except Exception:
+        pass
+
+
+def _show_error(message, details=''):
+    """Report a fatal start-up failure where an operator can actually see it.
+
+    On a Pi kiosk there is no console and no dialog framework yet (Kivy failed),
+    so the text is written to a log AND printed. If a ``zenity``-style dialog is
+    available it is used as a bonus, never as a requirement.
+    """
+    _early_log(f'FATAL: {message}')
+    if details:
+        _early_log(details)
+    try:
+        crash_log = LOG_DIR / 'fatal_crash.log'
+        with open(crash_log, 'w') as fh:
+            fh.write(f'FATAL: {message}\n\n{details}\n')
+    except Exception:
+        pass
+    try:
+        import shutil
+        import subprocess
+        if shutil.which('zenity') and os.environ.get('WAYLAND_DISPLAY'):
+            subprocess.Popen(
+                ['zenity', '--error', '--width=520',
+                 '--title=Kiwy Signage Player',
+                 '--text=' + f'{message}\n\nSee logs/fatal_crash.log'],
+                stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+            )
+    except Exception:
+        pass
+
+
+# =====================================================================
+# 1. Environment — must be set BEFORE Kivy is imported
+# =====================================================================
+# main.py uses os.environ.setdefault(), so values set here win. Anything the
+# operator exports explicitly is left untouched (setdefault semantics).
+def _configure_environment():
+    env = os.environ
+
+    # ── Session environment FIRST ───────────────────────────────────
+    # A launch from systemd, cron or SSH has XDG_RUNTIME_DIR set but
+    # WAYLAND_DISPLAY *empty* — the compositor only exports it inside the
+    # desktop session. SDL2 does NOT scan XDG_RUNTIME_DIR on its own: with the
+    # variable unset it fails with "wayland not available" even though the
+    # socket exists. Detecting and exporting it here is what makes the player
+    # start under systemd/autostart at all.
+    try:
+        from linux_display import ensure_session_environment
+
+        changed = ensure_session_environment()
+        if changed:
+            _early_log(f'session environment filled in: {changed}')
+    except Exception as exc:
+        _early_log(f'session environment detection skipped: {exc}')
+
+    # ── Video output ────────────────────────────────────────────────
+    # Raspberry Pi OS Trixie runs a Wayland (labwc) session. A comma-separated
+    # list is valid: Kivy splits it and SDL2 picks the first driver that
+    # initialises, so this also covers XWayland ('x11') and headless ('dummy').
+    env.setdefault('SDL_VIDEODRIVER', 'wayland,x11,dummy')
+
+    # ── Audio ───────────────────────────────────────────────────────
+    # Trixie ships PipeWire, which exposes an ALSA compatibility layer and a
+    # PulseAudio-compatible socket. NOTE: main.py sets SDL_AUDIODRIVER twice
+    # (once via setdefault at import, once with a hard setdefault later), so
+    # the value chosen here is the one that sticks.
+    env.setdefault('SDL_AUDIODRIVER', 'alsa,pulse,dummy')
+
+    # ── Kivy window / GL ────────────────────────────────────────────
+    env.setdefault('KIVY_WINDOW', 'sdl2')
+    # Pi 4/5 use Mesa + V3D. 'gl' is the safe default; operators on odd stacks
+    # can export KIVY_GL_BACKEND=gles/sdl2 to change it.
+    env.setdefault('KIVY_GL_BACKEND', 'gl')
+    env.setdefault('KIVY_INPUTPROVIDERS', 'wayland,x11,probesysfs,hidinput,mtdev')
+
+    # ── Media (ffpyplayer, hardware-friendly) ───────────────────────
+    env.setdefault('KIVY_VIDEO', 'ffpyplayer')
+    env.setdefault('KIVY_AUDIO', 'ffpyplayer')
+    env.setdefault('FFPYPLAYER_CODECS', 'h264,h265,vp9,vp8')
+    # Pi 4 has 4 cores; more threads than that hurts more than it helps.
+    env.setdefault('FFMPEG_THREADS', '2')
+    env.setdefault('LIBPLAYER_BUFFER', '1048576')
+
+    # ── Misc ────────────────────────────────────────────────────────
+    env.setdefault('SDL_VIDEO_ALLOW_SCREENSAVER', '0')
+    # Kivy's own home; keeping it inside the project avoids surprises when the
+    # player is started by systemd with a different HOME.
+    env.setdefault('KIVY_HOME', str(ROOT_DIR / '.kivy'))
+
+
+_configure_environment()
+
+
+# =====================================================================
+# 2. Logging
+# =====================================================================
+def _configure_logging():
+    """Route Kivy/root logging to logs/ as well as stderr.
+
+    journald already captures stderr when started by systemd, but a plain
+    ``runner`` launch (or a labwc autostart) would otherwise lose it.
+    """
+    logging.basicConfig(
+        level=logging.INFO,
+        format='%(asctime)s %(levelname).1s %(name)s: %(message)s',
+    )
+    try:
+        from logging.handlers import RotatingFileHandler
+        handler = RotatingFileHandler(
+            LOG_DIR / 'player.log', maxBytes=2 * 1024 * 1024, backupCount=2
+        )
+        handler.setFormatter(
+            logging.Formatter('%(asctime)s %(levelname).1s %(name)s: %(message)s')
+        )
+        logging.getLogger().addHandler(handler)
+    except Exception as exc:
+        _early_log(f'file logging unavailable: {exc}')
+
+
+_configure_logging()
+
+
+# =====================================================================
+# 3. Import the shared application (env is already Pi-correct)
+# =====================================================================
+def _bind_name(func, name):
+    """Give ``func`` the name Kivy will use when it resolves the callback later.
+
+    Kivy's ``Clock`` wraps callbacks in a ``WeakMethod`` keyed on
+    ``func.__name__`` and re-resolves them with ``getattr(instance, name)``. A
+    replacement assigned under a different name than it was defined with
+    therefore raises ``AttributeError`` the first time the Clock fires — after
+    a delay, far from the cause. Renaming the function keeps the two in sync.
+    """
+    try:
+        func.__name__ = name
+        func.__qualname__ = name
+    except Exception:
+        pass
+    return func
+
+
+def _import_main():
+    """Import ``src/main.py``, translating import failures into clear advice."""
+    try:
+        import main as signage_main  # noqa: WPS433 - deliberate late import
+        return signage_main
+    except SystemExit as exc:
+        # Kivy raises SystemExit(1) when no window provider can be created.
+        raise RuntimeError(
+            f'Kivy could not create a window (SystemExit {exc.code}).\n'
+            'This usually means the display backends are missing.\n'
+            'Try:  sudo apt install libsdl2-2.0-0 libgl1-mesa-dri\n'
+            f'Backend: SDL_VIDEODRIVER={os.environ.get("SDL_VIDEODRIVER")} '
+            f'KIVY_GL_BACKEND={os.environ.get("KIVY_GL_BACKEND")} '
+            f'WAYLAND_DISPLAY={os.environ.get("WAYLAND_DISPLAY")} '
+            f'DISPLAY={os.environ.get("DISPLAY")}'
+        ) from exc
+
+
+# =====================================================================
+# 4. Platform patches
+# =====================================================================
+def _reassert_graphics_config():
+    """Re-apply fullscreen/window config after main.py has run its own.
+
+    ``main.py`` sets ``graphics.fullscreen = 0`` and ``window_state = maximized``
+    at import time. On the Pi the window must be a true fullscreen surface, so
+    the values are re-asserted here — after main's module body, before
+    ``App.run()`` creates the window.
+    """
+    try:
+        from kivy.config import Config
+
+        Config.set('graphics', 'fullscreen', '1')
+        Config.set('graphics', 'borderless', '1')
+        Config.set('graphics', 'resizable', '0')
+        Config.set('graphics', 'multisampling', '0')
+        Config.set('graphics', 'fast_rgba', '1')
+        Config.set('graphics', 'maxfps', '60')
+        Config.set('kivy', 'exit_on_escape', '0')
+    except Exception as exc:
+        _early_log(f'graphics config re-assert failed (non-fatal): {exc}')
+
+
+def _patch_display(signage_main):
+    """Install the Wayland-aware screen-activity handler.
+
+    ``main.py``'s inherited implementation shells out to ``tvservice``,
+    ``xdotool`` and ``ydotool`` — none of which exist on Trixie — and passes a
+    mis-escaped ``wlopm --on \\*``. It therefore never prevents blanking.
+
+    NOTE: the replacement is registered under **every** name Kivy might use to
+    resolve the callback. Kivy's ``Clock`` stores ``func.__name__`` in a
+    WeakMethod and later does ``getattr(instance, that_name)``, so the attribute
+    name must match the function's own ``__name__`` exactly — otherwise the
+    Clock raises ``AttributeError`` the first time it fires (measured: the
+    player died 20 s in, on the first ``signal_screen_activity`` tick, with
+    ``'SignagePlayer' object has no attribute 'linux_screen_activity'``).
+    """
+    try:
+        from linux_display import linux_screen_activity
+    except ImportError as exc:
+        _early_log(f'linux_display unavailable, keeping built-in handler: {exc}')
+        return False
+
+    # Own name first: this is what Kivy's WeakMethod will look up.
+    setattr(signage_main.SignagePlayer, 'linux_screen_activity', linux_screen_activity)
+    # Then the attribute the app actually schedules.
+    signage_main.SignagePlayer.signal_screen_activity = linux_screen_activity
+    return True
+
+
+def _patch_weblink_engines(signage_main):
+    """Inject the Raspberry Pi Chromium adapter.
+
+    ``WeblinkSession`` owns launch/visibility/interaction/teardown; the adapter
+    is the only platform-specific part. Injecting it via the class-level
+    ``weblink_adapter_factory`` hook keeps ``main.py`` free of platform code.
+    """
+    try:
+        from linux_browser import LinuxChromiumAdapter, find_linux_browser
+    except ImportError as exc:
+        _early_log(f'linux_browser unavailable, using the generic adapter: {exc}')
+        return False
+
+    from kivy.logger import Logger
+
+    browser = find_linux_browser()
+
+    def _linux_weblink_adapter_factory(player):
+        adapters = []
+        if browser:
+            adapters.append(LinuxChromiumAdapter(browser_path=browser, kiosk=True))
+        else:
+            Logger.warning(
+                'SignagePlayer: no Chromium/Chrome found — web links will be '
+                'skipped. Install with: sudo apt install chromium'
+            )
+        return adapters
+
+    signage_main.SignagePlayer.weblink_adapter_factory = staticmethod(
+        _bind_name(_linux_weblink_adapter_factory, 'weblink_adapter_factory')
+    )
+    Logger.info(
+        f'SignagePlayer: web-link engine -> '
+        f'{"chromium-kiosk-linux (" + browser + ")" if browser else "none found"}'
+    )
+    return True
+
+
+def _patch_temp_paths(signage_main):
+    """Make the Settings "Test connection" use a portable temp path.
+
+    ``main.py`` hard-codes ``/tmp/temp_auth_test.json``. That usually works on
+    Linux, but the file can be left behind with live credentials and breaks
+    outright when ``/tmp`` is private (systemd ``PrivateTmp``) or read-only.
+    """
+    try:
+        import tempfile
+        import threading
+        from kivy.clock import Clock
+        from player_auth import PlayerAuth
+    except Exception as exc:
+        _early_log(f'temp-path patch skipped: {exc}')
+        return False
+
+    def _linux_test_connection(self):
+        """Copy of the original flow, using ``tempfile.gettempdir()``."""
+        self.ids.connection_status.text = 'Testing connection...'
+        self.ids.connection_status.color = (1, 0.7, 0, 1)
+
+        def run_test():
+            temp_file = os.path.join(tempfile.gettempdir(), 'temp_auth_test.json')
+            try:
+                server_ip = self.ids.server_input.text.strip()
+                screen_name = self.ids.screen_input.text.strip()
+                quickconnect = self.ids.quickconnect_input.text.strip()
+                port = self.ids.port_input.text.strip() or self.player.config.get('port', '')
+                use_https = self.player.config.get('use_https', True)
+                verify_ssl = self.player.config.get('verify_ssl', True)
+
+                if not all([server_ip, screen_name, quickconnect]):
+                    Clock.schedule_once(
+                        lambda dt: self.update_connection_status('Error: Fill all fields', False)
+                    )
+                    return
+
+                if server_ip.startswith(('http://', 'https://')):
+                    server_url = server_ip
+                    if ':' not in server_ip.replace('https://', '').replace('http://', ''):
+                        if port and port not in ('443', '80'):
+                            server_url = f'{server_ip}:{port}'
+                else:
+                    protocol = 'https' if use_https else 'http'
+                    if ':' in server_ip:
+                        server_url = f'{protocol}://{server_ip}'
+                    else:
+                        server_url = f'{protocol}://{server_ip}:{port}' if port else f'{protocol}://{server_ip}'
+
+                auth = PlayerAuth(temp_file, use_https=use_https, verify_ssl=verify_ssl)
+                success, error = auth.authenticate(
+                    server_url=server_url, hostname=screen_name,
+                    quickconnect_code=quickconnect,
+                )
+
+                if success:
+                    player_name = auth.get_player_name()
+                    Clock.schedule_once(
+                        lambda dt: self.update_connection_status(f'✓ Connected: {player_name}', True)
+                    )
+                else:
+                    Clock.schedule_once(
+                        lambda dt: self.update_connection_status(f'✗ Failed: {error}', False)
+                    )
+            except Exception as exc:
+                Clock.schedule_once(
+                    lambda dt: self.update_connection_status(f'✗ Error: {exc}', False)
+                )
+            finally:
+                # Never leave a file containing credentials behind.
+                try:
+                    if os.path.exists(temp_file):
+                        os.remove(temp_file)
+                except Exception:
+                    pass
+
+        threading.Thread(target=run_test, daemon=True).start()
+
+    signage_main.SettingsPopup.test_connection = _bind_name(
+        _linux_test_connection, 'test_connection'
+    )
+    return True
+
+
+def _patch_auth_path(signage_main):
+    """Keep ``player_auth.json`` in the player's data directory.
+
+    ``player_auth.py`` defaults to the relative path ``player_auth.json``, which
+    resolves against the *current working directory*. Started by systemd,
+    labwc-autostart or a cron wrapper, that cwd differs — so the player would
+    "forget" its authentication and re-register on every launch. Pinning it to
+    an absolute path in the data dir removes that class of bug.
+    """
+    try:
+        import player_auth as player_auth_module
+    except Exception as exc:
+        _early_log(f'auth-path patch skipped: {exc}')
+        return False
+
+    local_auth = os.path.join(DATA_DIR, 'player_auth.json')
+    original_init = player_auth_module.PlayerAuth.__init__
+
+    def _linux_auth_init(self, config_file='player_auth.json',
+                         use_https=True, verify_ssl=True):
+        try:
+            if not os.path.isabs(config_file):
+                config_file = os.path.join(DATA_DIR, os.path.basename(config_file))
+        except Exception:
+            config_file = local_auth
+        original_init(self, config_file, use_https=use_https, verify_ssl=verify_ssl)
+
+    player_auth_module.PlayerAuth.__init__ = _bind_name(_linux_auth_init, '__init__')
+    _early_log(f'player auth file -> {local_auth}')
+
+    # get_playlists_v2 may already hold a globally cached auth instance created
+    # with the old relative path; drop it so the redirect applies.
+    try:
+        import get_playlists_v2 as gp
+        if getattr(gp, '_auth_instance', None) is not None:
+            gp._auth_instance = None
+    except Exception:
+        pass
+
+    # Point the "Reset auth" button at the real file.
+    def _linux_reset_player_auth(self):
+        try:
+            if os.path.exists(local_auth):
+                os.remove(local_auth)
+            signage_main.Logger.info(f'SettingsPopup: Deleted auth file: {local_auth}')
+            self._show_temp_message(
+                '✓ Authentication reset - will reauthenticate on restart',
+                (0, 1, 0, 1),
+            )
+        except Exception as exc:
+            signage_main.Logger.error(f'SettingsPopup: Failed to reset auth: {exc}')
+
+    signage_main.SettingsPopup.reset_player_auth = _bind_name(
+        _linux_reset_player_auth, 'reset_player_auth'
+    )
+    return True
+
+
+def _patch_startup_hooks(signage_main):
+    """Apply orientation and stop the idle blanker once the app is up."""
+    original_on_start = signage_main.SignagePlayerApp.on_start
+
+    def _linux_on_start(self):
+        original_on_start(self)
+        try:
+            from linux_display import (
+                apply_orientation, keep_display_awake, neutralise_idle_blanker,
+                status,
+            )
+
+            _early_log(f'display backend: {json.dumps(status())}')
+            # The desktop ships an idle blanker that powers the panel off after
+            # 10 minutes; a signage player must win that contest.
+            neutralise_idle_blanker()
+            keep_display_awake(force=True)
+
+            root = getattr(self, 'root', None)
+            orientation = ''
+            if root is not None:
+                orientation = (getattr(root, 'config', {}) or {}).get('orientation', '')
+            if orientation:
+                apply_orientation(orientation)
+        except Exception as exc:
+            _early_log(f'startup display hook failed (non-fatal): {exc}')
+
+    signage_main.SignagePlayerApp.on_start = _bind_name(_linux_on_start, 'on_start')
+
+
+# =====================================================================
+# 5. Run
+# =====================================================================
+def main():
+    from kivy.logger import Logger
+
+    Logger.info('=' * 78)
+    Logger.info('Kiwy Signage Player — Raspberry Pi / Linux Edition')
+    Logger.info(f'Python:   {sys.version.split()[0]}')
+    Logger.info(f'Platform: {platform.platform()}')
+    Logger.info(f'Machine:  {platform.machine()}')
+    Logger.info(f'Data dir: {DATA_DIR}')
+    Logger.info(f'Session:  WAYLAND_DISPLAY={os.environ.get("WAYLAND_DISPLAY")} '
+                f'DISPLAY={os.environ.get("DISPLAY")}')
+    Logger.info('=' * 78)
+
+    signage_main = _import_main()
+
+    _reassert_graphics_config()
+    patched = {
+        'display': _patch_display(signage_main),
+        'weblink': _patch_weblink_engines(signage_main),
+        'temp': _patch_temp_paths(signage_main),
+        'auth': _patch_auth_path(signage_main),
+    }
+    _patch_startup_hooks(signage_main)
+    Logger.info(f'SignagePlayer: platform patches -> {patched}')
+
+    try:
+        signage_main.SignagePlayerApp().run()
+    except KeyboardInterrupt:
+        Logger.info('Application stopped by user (Ctrl+C)')
+    except SystemExit as exc:
+        _show_error(
+            f'Kivy exited: {exc}',
+            'Kivy could not create a window. Check the display backends.\n'
+            f'SDL_VIDEODRIVER={os.environ.get("SDL_VIDEODRIVER")}\n'
+            f'KIVY_GL_BACKEND={os.environ.get("KIVY_GL_BACKEND")}',
+        )
+        return 1
+    except Exception as exc:
+        Logger.critical(f'Fatal error: {exc}')
+        Logger.exception('Full traceback:')
+        _show_error(str(exc), traceback.format_exc())
+        return 1
+    finally:
+        Logger.info('Application shutdown complete')
+    return 0
+
+
+if __name__ == '__main__':
+    exit_code = 0
+    try:
+        exit_code = main()
+    except SystemExit as exc:
+        # A clean shutdown (SIGTERM from the watchdog, window closed after the
+        # password exit) arrives here as SystemExit(0). Reporting that as a
+        # fatal error wrote a bogus "FATAL: 0" crash log on every normal stop.
+        code = exc.code
+        exit_code = code if isinstance(code, int) else (0 if code is None else 1)
+        if exit_code:
+            _show_error(f'exited with code {exit_code}', traceback.format_exc())
+    except BaseException as exc:  # includes import-time failures
+        _show_error(str(exc), traceback.format_exc())
+        raise
+    sys.exit(exit_code)

linux/test_linux_browser_flags.py

@@ -0,0 +1,180 @@
+"""test_linux_browser_flags.py — guard the Chromium keyring bypass and footprint.
+
+The keyring password prompt is the bug this file exists to prevent from coming
+back. It was "fixed" once before by adding ``--password-store=basic`` and
+``--use-mock-keychain`` to a list (``APPLIANCE_FLAGS``) that **nothing ever
+referenced**, so the flags never reached the command line and the prompt
+persisted. A second stack-only fix (``--single-process``) also looked right on
+paper but crashed with a real HTTP URL.
+
+So these checks are deliberately about *what actually reaches the process*, not
+about what the constants say:
+
+1. ``extra_launch_args()`` really contains the keyring + footprint flags.
+2. ``launch_env()`` really strips the D-Bus session bus, so Chromium cannot
+   reach ``gnome-keyring-daemon`` even if a flag is ever ignored.
+3. Every module-level flag list is referenced by ``extra_launch_args()`` —
+   dead flag lists are the exact failure mode that hid bug #1.
+4. The spawned process is in its own session (so process-group teardown works)
+   and its ``/proc/<pid>/environ`` really lacks ``DBUS_SESSION_BUS_ADDRESS``.
+
+Run:
+    .venv/bin/python linux/test_linux_browser_flags.py
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+import time
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+ROOT = HERE.parent
+for path in (str(HERE), str(ROOT / 'src')):
+    if path not in sys.path:
+        sys.path.insert(0, path)
+
+import linux_browser  # noqa: E402
+
+failures: list[str] = []
+checks = 0
+
+
+def check(label, condition, detail=''):
+    global checks
+    checks += 1
+    if condition:
+        print(f'  PASS  {label}')
+    else:
+        print(f'  FAIL  {label}' + (f' — {detail}' if detail else ''))
+        failures.append(label)
+
+
+def build_adapter(**kwargs):
+    adapter = linux_browser.LinuxChromiumAdapter(
+        browser_path='/usr/bin/chromium', kiosk=True, **kwargs
+    )
+    adapter._profile_dir = '/tmp/kiwy-flag-test/.kiosk-profile'
+    return adapter
+
+
+# ── 1. Keyring flags reach the command line ──────────────────────────
+print('\n[1] Keyring bypass flags are applied')
+
+adapter = build_adapter()
+args = adapter.extra_launch_args()
+
+for flag in ('--password-store=basic', '--use-mock-keychain'):
+    check(f'{flag} present', flag in args,
+          'Chromium would contact gnome-keyring and prompt for a password')
+
+check('--kiosk present', '--kiosk' in args, 'weblink would not be fullscreen')
+
+if linux_browser._detect_wayland():
+    check('--ozone-platform=wayland present', '--ozone-platform=wayland' in args,
+          'Chromium 152 aborts without an explicit Ozone platform on labwc')
+    check(
+        'no ineffective --ozone-platform-hint',
+        '--ozone-platform-hint=auto' not in args,
+        'the hint flag does NOT fall back to Wayland and just fails',
+    )
+
+
+# ── 2. Environment actually disconnects the keyring ──────────────────
+print('\n[2] launch_env() disconnects the Secret Service')
+
+env = adapter.launch_env()
+check('launch_env() returns an environment', env is not None,
+      'None means Popen inherits DBUS_SESSION_BUS_ADDRESS')
+if env is not None:
+    check('DBUS_SESSION_BUS_ADDRESS removed',
+          'DBUS_SESSION_BUS_ADDRESS' not in env,
+          'Chromium could reach gnome-keyring-daemon and prompt')
+    check('DBUS_SESSION_BUS_PID removed', 'DBUS_SESSION_BUS_PID' not in env)
+    check('GNOME_KEYRING_CONTROL emptied', env.get('GNOME_KEYRING_CONTROL') == '',
+          'points the keyring client at nothing')
+    check('CHROME_PASSWORD_STORE=basic', env.get('CHROME_PASSWORD_STORE') == 'basic')
+    check('PATH preserved', bool(env.get('PATH')), 'browser could not exec')
+    check('session bus is absent from the parent env to begin with',
+          'DBUS_SESSION_BUS_ADDRESS' in os.environ,
+          'precondition: this test only proves something if the player HAS a bus')
+
+check('start_new_session() is True', adapter.start_new_session() is True,
+      'os.killpg cannot reap Chromium children without it')
+
+
+# ── 3. No dead flag lists ────────────────────────────────────────────
+print('\n[3] Every flag list is referenced (no dead code)')
+
+source = (HERE / 'linux_browser.py').read_text()
+# Names of module-level lists of flags.
+lists = re.findall(r'^([A-Z_]+_FLAGS) = \[', source, re.MULTILINE)
+check('flag lists found', len(lists) >= 5, f'only found {lists}')
+
+for name in lists:
+    # Count references that are NOT the definition itself.
+    uses = len(re.findall(rf'(?<!^){name}(?!\s*=\s*\[)', source, re.MULTILINE))
+    check(f'{name} is referenced', uses > 0,
+          'a flag list nothing reads is exactly how the keyring prompt hid')
+
+
+# ── 4. End-to-end: the real process is detached from the bus ─────────
+print('\n[4] Live launch: process environment and process group')
+
+browser = linux_browser.find_linux_browser()
+if not browser:
+    print('  SKIP  no Chromium installed')
+else:
+    os.makedirs(adapter._profile_dir, exist_ok=True)
+    live = build_adapter()
+    started = live.launch('about:blank', 800, 600)
+    check('launch() returned True', started is True)
+    proc = live._proc
+    if started and proc is not None:
+        try:
+            time.sleep(1.5)
+            if proc.poll() is not None:
+                check('browser survived start-up', False,
+                      f'exited rc={proc.returncode}')
+            else:
+                check('browser survived start-up', True)
+
+                # Process group: must differ from the player's own group.
+                try:
+                    pgid = os.getpgid(proc.pid)
+                    check('browser is in its own process group',
+                          pgid == proc.pid,
+                          f'pgid={pgid} pid={proc.pid}; killpg would hit the player')
+                except Exception as exc:
+                    check('browser is in its own process group', False, str(exc))
+
+                # /proc environ is authoritative: this is what the process sees.
+                try:
+                    raw = Path(f'/proc/{proc.pid}/environ').read_bytes()
+                    child_env = dict(
+                        item.split('=', 1) for item in
+                        raw.decode('utf-8', 'replace').split('\x00') if '=' in item
+                    )
+                    check('live process has no DBUS_SESSION_BUS_ADDRESS',
+                          'DBUS_SESSION_BUS_ADDRESS' not in child_env,
+                          'the keyring prompt can still appear')
+                    check('live process has basic password store',
+                          child_env.get('CHROME_PASSWORD_STORE') == 'basic')
+                except Exception as exc:
+                    check('live process environment readable', False, str(exc))
+        finally:
+            live.teardown()
+            time.sleep(0.5)
+            check('teardown() left no process behind', live._proc is None)
+
+
+# ── Summary ──────────────────────────────────────────────────────────
+print(f'\n{checks - len(failures)}/{checks} checks passed')
+if failures:
+    print('\nFailed:')
+    for name in failures:
+        print(f'  - {name}')
+    sys.exit(1)
+print('All checks passed.')

linux/test_linux_patches.py

@@ -0,0 +1,186 @@
+"""test_linux_patches.py — verify the Linux platform patches are wired correctly.
+
+Run with the project virtualenv:
+    .venv/bin/python linux/test_linux_patches.py
+
+These are the regressions that actually bit us during the Trixie port, so they
+are asserted rather than left to manual testing:
+
+1. **Kivy WeakMethod name trap.** ``Clock`` stores ``callable.__name__`` and
+   re-resolves it with ``getattr(instance, name)``. If a patched method is
+   assigned under a name that differs from its own ``__name__``, the app dies
+   ~20 s later with ``AttributeError`` — far from the cause. Every method this
+   port replaces must be reachable under its own function name.
+2. **SDL2 Wayland capability.** Kivy's PyPI wheel bundles an SDL2 *without* the
+   wayland driver; the system SDL2 has it. Getting this wrong means no window at
+   all on Raspberry Pi OS Trixie.
+3. **WAYLAND_DISPLAY inference.** SDL2 requires the variable to be set — unlike
+   ``wlopm``, it does not scan ``XDG_RUNTIME_DIR``. A systemd/cron launch has it
+   unset, so the entry point must fill it in.
+
+The player does not need to be running; this only exercises wiring and detection.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import glob
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+ROOT = HERE.parent
+SRC = ROOT / 'src'
+VENV = Path(os.environ.get('KIWY_VENV') or (ROOT / '.venv'))
+
+for path in (str(HERE), str(SRC)):
+    if path not in sys.path:
+        sys.path.insert(0, path)
+
+failures: list[str] = []
+checks = 0
+
+
+def check(label, condition, detail=''):
+    global checks
+    checks += 1
+    if condition:
+        print(f'  PASS  {label}')
+    else:
+        print(f'  FAIL  {label}' + (f' — {detail}' if detail else ''))
+        failures.append(label)
+
+
+# ── 1. WeakMethod name trap ──────────────────────────────────────────
+print('\n[1] Patched methods are resolvable by their own __name__')
+
+# Import the entry point's patching helpers without running the app. Importing
+# run_linux executes its env setup, which is harmless and actually desirable
+# here (it fills in WAYLAND_DISPLAY for the checks below).
+import run_linux  # noqa: E402
+
+main = run_linux._import_main()
+
+patches = {
+    'signal_screen_activity': run_linux._patch_display(main),
+    'weblink_adapter_factory': run_linux._patch_weblink_engines(main),
+    'test_connection': run_linux._patch_temp_paths(main),
+    'reset_player_auth': run_linux._patch_auth_path(main),
+}
+
+for label, applied in patches.items():
+    check(f'{label} patch applied', applied, 'patch reported failure')
+
+player_cls = main.SignagePlayer
+for attr in ('signal_screen_activity', 'weblink_adapter_factory'):
+    func = getattr(player_cls, attr, None)
+    check(f'{attr} exists', func is not None, 'attribute missing')
+    if func is None:
+        continue
+
+    # For a staticmethod, inspect the underlying function.
+    raw = player_cls.__dict__.get(attr)
+    func = raw.__func__ if isinstance(raw, staticmethod) else raw
+    name = getattr(func, '__name__', '')
+
+    # The real invariant: Kivy resolves the callback with
+    # getattr(instance, func.__name__), so that lookup must succeed and return
+    # the same function. The name need not equal the attribute it replaced, but
+    # it MUST be reachable on the class.
+    resolved = getattr(player_cls, name, None)
+    check(
+        f'{attr}: getattr(cls, {name!r}) resolves',
+        resolved is not None,
+        f'Kivy Clock would raise AttributeError: no attribute {name!r}',
+    )
+    check(
+        f'{attr}: resolved function is the patched one',
+        resolved is func,
+        f'{name!r} resolved to a different object',
+    )
+
+# The Windows-only focus machinery must be gone from the shared app, so nothing
+# schedules Win32 work on a Wayland session.
+for attr in ('_focus_keeper_tick', '_focus_guardian_tick',
+             '_bring_window_to_front_nonblocking', '_start_focus_guardian'):
+    check(
+        f'{attr} removed (Windows-only)',
+        not hasattr(player_cls, attr),
+        'the platform-specific focus code should not be in the shared app',
+    )
+
+
+# ── 2. Display module behaviour ──────────────────────────────────────
+print('\n[2] linux_display detection and keep-awake')
+
+import linux_display as display  # noqa: E402
+
+status = display.status()
+print(f'  info  status = {status}')
+
+if status['wayland']:
+    check('WAYLAND_DISPLAY is set after detection',
+          bool(os.environ.get('WAYLAND_DISPLAY')),
+          'SDL2/wlopm need this variable')
+    check('wlopm available', status['wlopm'], 'install wlopm')
+    check('keep_display_awake reports success',
+          display.keep_display_awake(force=True) is True,
+          'wlopm --on did not succeed')
+else:
+    print('  SKIP  not a Wayland session — display checks skipped')
+
+# With the tools explicitly disabled nothing must be attempted.
+os.environ[display.DISABLE_ENV_VAR] = '1'
+check('DISABLE escape hatch suppresses keep-awake',
+      display.keep_display_awake(force=True) is False)
+check('DISABLE escape hatch suppresses blanker kill',
+      display.neutralise_idle_blanker() == [])
+del os.environ[display.DISABLE_ENV_VAR]
+
+
+# ── 3. SDL2 Wayland capability ───────────────────────────────────────
+print('\n[3] SDL2 in use supports the wayland driver')
+
+def drivers_of(lib_path):
+    try:
+        lib = ctypes.CDLL(str(lib_path))
+        lib.SDL_GetNumVideoDrivers.restype = ctypes.c_int
+        lib.SDL_GetVideoDriver.restype = ctypes.c_char_p
+        lib.SDL_GetVideoDriver.argtypes = [ctypes.c_int]
+        n = lib.SDL_GetNumVideoDrivers()
+        return [lib.SDL_GetVideoDriver(i).decode() for i in range(n)]
+    except Exception as exc:
+        return [f'<error: {exc}>']
+
+
+ext = glob.glob(str(VENV / '**' / '_window_sdl2*.so'), recursive=True)
+if not ext:
+    print('  SKIP  no Kivy SDL2 extension found in this venv')
+else:
+    # Ask the dynamic loader which libSDL2 the extension actually resolves.
+    linked = subprocess.run(
+        ['ldd', ext[0]], capture_output=True, text=True, check=False,
+    ).stdout
+    resolved = None
+    for line in linked.splitlines():
+        if 'libSDL2-2-' in line and '=>' in line:
+            resolved = line.split('=>')[1].split('(')[0].strip()
+            break
+    check('Kivy resolves an SDL2 library', resolved is not None, 'ldd found none')
+    if resolved:
+        used = drivers_of(resolved)
+        print(f'  info  {resolved}\n        drivers = {used}')
+        check('resolved SDL2 supports wayland', 'wayland' in used,
+              'run: bash linux/fix_kivy_sdl2.sh')
+
+
+# ── Summary ──────────────────────────────────────────────────────────
+print(f'\n{checks - len(failures)}/{checks} checks passed')
+if failures:
+    print('\nFailed:')
+    for name in failures:
+        print(f'  - {name}')
+    sys.exit(1)
+print('All checks passed.')

linux/test_media_state.py

@@ -0,0 +1,171 @@
+"""test_media_state.py — the conversion-flag state machine.
+
+The rules here are easy to get subtly wrong, and getting them wrong is
+user-visible in two opposite ways: playing a file that is mid-conversion
+(truncated video), or skipping forever an item that is actually fine.
+
+Covered:
+
+1. A normal-size video resolves to itself and is playable.
+2. An oversized video with no completed conversion reports ``pending``.
+3. While the ``.kiwy-converting`` marker exists it reports ``converting``.
+4. Once the output + metadata exist it resolves to the **converted** file.
+5. A stale marker (from a crash) does not park the item forever.
+6. Metadata that does not match the current source is ignored — otherwise a
+   different video reusing the same filename would play the previous one.
+7. The MP4 header parser agrees with ffprobe (the player must not spawn a
+   subprocess on the playback path, so it reads the container directly).
+
+Run:
+    .venv/bin/python linux/test_media_state.py
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+ROOT = HERE.parent
+SRC = ROOT / 'src'
+for path in (str(HERE), str(SRC)):
+    if path not in sys.path:
+        sys.path.insert(0, path)
+
+import media_state as ms  # noqa: E402
+
+failures: list[str] = []
+checks = 0
+
+
+def check(label, condition, detail=''):
+    global checks
+    checks += 1
+    print(f'  {"PASS" if condition else "FAIL"}  {label}'
+          + (f' — {detail}' if not condition and detail else ''))
+    if not condition:
+        failures.append(label)
+
+
+def make_video(path, width, height, seconds=1):
+    """Create a tiny real video of the given size (or None if ffmpeg is absent)."""
+    if not shutil.which('ffmpeg'):
+        return False
+    cmd = [
+        'ffmpeg', '-hide_banner', '-loglevel', 'error',
+        '-f', 'lavfi', '-i', f'testsrc=size={width}x{height}:rate=10:duration={seconds}',
+        '-c:v', 'libx264', '-preset', 'ultrafast', '-pix_fmt', 'yuv420p',
+        '-y', path,
+    ]
+    return subprocess.run(cmd, capture_output=True, check=False).returncode == 0
+
+
+workdir = Path(tempfile.mkdtemp(prefix='kiwy-mediastate-'))
+print(f'workdir: {workdir}')
+
+try:
+    big = workdir / 'big.mp4'
+    small = workdir / 'small.mp4'
+
+    if not make_video(big, 2560, 1440) or not make_video(small, 1280, 720):
+        print('SKIP: ffmpeg not available to build fixtures')
+        raise SystemExit(0)
+
+    # ── 1. Within-limit video is playable as itself ──────────────────
+    print('\n[1] A within-limit video resolves to itself')
+    chosen, state = ms.resolve_playable(str(small))
+    check('state is ready', state == 'ready', f'got {state}')
+    check('chosen path is the original', chosen == str(small), f'got {chosen}')
+
+    # ── 2. Oversized + no conversion -> pending ──────────────────────
+    print('\n[2] Oversized video with no conversion reports pending')
+    chosen, state = ms.resolve_playable(str(big))
+    check('state is pending', state == 'pending', f'got {state}')
+    oversized, _w, _h = ms.is_oversized(str(big))
+    check('is_oversized is True', oversized is True)
+    check('a within-limit file is not oversized',
+          ms.is_oversized(str(small))[0] is False)
+
+    # ── 3. Converting marker -> converting ───────────────────────────
+    print('\n[3] The converting marker suppresses playback')
+    ms.begin_conversion(str(big))
+    chosen, state = ms.resolve_playable(str(big))
+    check('state is converting', state == 'converting', f'got {state}')
+    check('is_converting is True', ms.is_converting(str(big)) is True)
+
+    # ── 4. Completed conversion resolves to the output ───────────────
+    print('\n[4] A finished conversion resolves to the converted file')
+    output = ms.normalized_output(str(big))
+    shutil.copy2(str(small), output)          # stand-in for the 1080p result
+    with open(output + ms.MARKER_SUFFIX, 'w') as fh:
+        json.dump({'source_size': os.path.getsize(big),
+                   'width': 2560, 'height': 1440}, fh)
+    ms.end_conversion(str(big))
+
+    chosen, state = ms.resolve_playable(str(big))
+    check('state is ready', state == 'ready', f'got {state}')
+    check('chosen path is the converted file', chosen == output, f'got {chosen}')
+
+    # ── 5. Stale marker is ignored ───────────────────────────────────
+    print('\n[5] A stale (crashed) marker does not block the item forever')
+    os.remove(output)
+    os.remove(output + ms.MARKER_SUFFIX)
+    ms.begin_conversion(str(big))
+    old = time.time() - (ms.STALE_CONVERSION_SECONDS + 60)
+    os.utime(ms.converting_marker(str(big)), (old, old))
+    check('a stale marker is not treated as converting',
+          ms.is_converting(str(big)) is False)
+    _chosen, state = ms.resolve_playable(str(big))
+    check('so the item is pending rather than converting',
+          state == 'pending', f'got {state}')
+    ms.end_conversion(str(big))
+
+    # ── 6. Mismatched metadata is ignored ────────────────────────────
+    print('\n[6] Metadata for a different source is rejected')
+    shutil.copy2(str(small), output)
+    with open(output + ms.MARKER_SUFFIX, 'w') as fh:
+        json.dump({'source_size': 12345,   # does not match big.mp4
+                   'width': 2560, 'height': 1440}, fh)
+    check('a stale output is not accepted', ms.normalized_file(str(big)) is None)
+    _chosen, state = ms.resolve_playable(str(big))
+    check('the item is treated as pending', state == 'pending', f'got {state}')
+
+    # ── 7. Header parser agrees with ffprobe ─────────────────────────
+    print('\n[7] The dependency-free MP4 parser matches ffprobe')
+    for label, path, expect in (('2560x1440', str(big), (2560, 1440)),
+                                ('1280x720', str(small), (1280, 720))):
+        parsed = ms.read_video_size(path)
+        check(f'{label} parsed correctly', parsed == expect, f'got {parsed}')
+
+    if shutil.which('ffprobe'):
+        out = subprocess.run(
+            ['ffprobe', '-v', 'error', '-select_streams', 'v:0',
+             '-show_entries', 'stream=width,height', '-of', 'csv=p=0', str(big)],
+            capture_output=True, text=True, check=False).stdout.strip()
+        fw, fh = (int(x) for x in out.split(',')[:2])
+        check('parser matches ffprobe for the oversized file',
+              ms.read_video_size(str(big)) == (fw, fh),
+              f'parser={ms.read_video_size(str(big))} ffprobe={(fw, fh)}')
+
+    check('a non-video file yields (None, None)',
+          ms.read_video_size(str(workdir / 'missing.mp4')) == (None, None))
+    check('a corrupt file yields (None, None)', (lambda p: (
+        p.write_bytes(b'not a video'), ms.read_video_size(str(p)))[1]
+    )(workdir / 'corrupt.mp4') == (None, None))
+
+finally:
+    shutil.rmtree(workdir, ignore_errors=True)
+
+print(f'\n{checks - len(failures)}/{checks} checks passed')
+if failures:
+    print('\nFailed:')
+    for name in failures:
+        print(f'  - {name}')
+    raise SystemExit(1)
+print('All checks passed.')

linux/video_normalizer.py

@@ -0,0 +1,545 @@
+"""video_normalizer.py — downscale oversized videos for Raspberry Pi playback.
+
+The problem
+-----------
+The Pi 4 has no usable 4K decode path. Measured on the target device:
+
+    sample-30s.mp4 (1920x1080)          decode 3.03x realtime   ✅
+    16118765_3840_2160_30fps.mp4 (4K)   decode 0.90x realtime   ❌
+
+ffpyplayer decodes in software (there is no hardware H.264 *decode* wired into
+its pipeline), so a 4K clip cannot be decoded fast enough to feed the screen in
+real time. The visible symptom is a video that shows one frame and then sits
+still, or stutters badly, while the playlist timer ticks on.
+
+The fix
+-------
+Normalise oversized media to at most 1920x1080 **once, at sync time**, and hand
+the player the smaller file. Playback then always runs against a resolution the
+Pi can decode comfortably.
+
+Timing (measured, 18.3s 4K clip -> 1080p):
+
+    hardware encode (h264_v4l2m2m)   31s   one-off, at download time
+    software encode (libx264)        much slower
+
+31 s is a real cost, but it is paid **once per file** during the playlist sync —
+which already runs on a worker thread and already downloads tens of megabytes.
+It is never paid during playback, which is the only place it would matter.
+
+Hardware encoding is used when available because the Pi 4's H.264 *encoder* is a
+separate block from its decoder and works well; software encoding of 4K on this
+SoC is slow enough to be impractical.
+
+Scope
+-----
+Triggered by **resolution only** — ``width > max_width or height > max_height``.
+A video already within bounds is left untouched (byte-identical), so this never
+degrades content that already plays.
+
+Audio is preserved: if the source has an audio track it is copied through
+(``-c:a copy``, falling back to AAC). That matters because a *silent* video
+triggers a separate bug in the SDL2_mixer path — see ``_video_has_audio`` in
+``src/main.py`` — so we must not accidentally create one.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import time
+
+# Importing kivy.logger installs Kivy's own argument parser, which then rejects
+# this module's CLI flags ("option --dry-run not recognized") and exits. Setting
+# this BEFORE the import keeps Kivy out of argv handling. It must precede the
+# kivy import below, hence the import-order exception.
+os.environ.setdefault('KIVY_NO_ARGS', '1')
+
+try:
+    from kivy.logger import Logger
+except Exception:  # pragma: no cover - importable without Kivy (tests/CLI)
+    class Logger:  # type: ignore
+        @staticmethod
+        def _noop(*args, **kwargs):
+            pass
+        info = debug = warning = error = staticmethod(_noop)
+
+# The player and the normaliser must agree on the on-disk contract for
+# "is this converting / has it been converted". That contract lives in one
+# place (src/media_state.py) and is shared rather than reimplemented.
+_SRC_DIR = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), 'src')
+if _SRC_DIR not in sys.path:
+    sys.path.insert(0, _SRC_DIR)
+
+import media_state  # noqa: E402
+
+
+def _log(message, level='info'):
+    try:
+        getattr(Logger, level, Logger.info)(f'[VideoNormalizer] {message}')
+    except Exception:
+        pass
+
+
+#: Default output ceiling. The Pi's practical decode limit; matches the
+#: ``max_resolution`` default used elsewhere in the project.
+DEFAULT_MAX_WIDTH = 1920
+DEFAULT_MAX_HEIGHT = 1080
+
+#: Marker suffix written next to a normalised file, recording what was done.
+#: Re-exported from :mod:`media_state` so the player and normaliser cannot drift.
+MARKER_SUFFIX = media_state.MARKER_SUFFIX
+
+#: Encoder preference: the Pi's hardware block first, then a CPU fallback.
+#: ``h264_v4l2m2m`` is the V4L2 mem2mem H.264 encoder (verified working on the
+#: target Pi 4); libx264 is the portable fallback for other Linux hosts.
+HW_ENCODER = 'h264_v4l2m2m'
+SW_ENCODER = 'libx264'
+
+#: Bitrate for the normalised output. 1080p signage at ~5 Mbps is visually
+#: lossless for this use and keeps files small.
+TARGET_BITRATE = '5M'
+MAX_BITRATE = '8M'
+BUFSIZE = '10M'
+
+
+def _run(args, timeout=30):
+    """Run a command; return (returncode, stdout+stderr). Never raises."""
+    try:
+        result = subprocess.run(
+            args, capture_output=True, text=True, timeout=timeout, check=False,
+        )
+        return result.returncode, (result.stdout or '') + (result.stderr or '')
+    except FileNotFoundError:
+        return 127, 'not found'
+    except subprocess.TimeoutExpired:
+        return 124, 'timeout'
+    except Exception as exc:
+        return 1, str(exc)
+
+
+def find_ffprobe():
+    return shutil.which('ffprobe')
+
+
+def find_ffmpeg():
+    return shutil.which('ffmpeg')
+
+
+def probe_video(path):
+    """Return a dict describing ``path``, or None when it cannot be probed.
+
+    Keys: width, height, codec, duration, has_audio, pix_fmt, level.
+    """
+    ffprobe = find_ffprobe()
+    if not ffprobe or not os.path.isfile(path):
+        return None
+
+    code, out = _run([
+        ffprobe, '-v', 'error', '-print_format', 'json',
+        '-show_streams', '-show_format', path,
+    ], timeout=20)
+    if code != 0:
+        _log(f'ffprobe failed for {os.path.basename(path)}: {out.strip()[:200]}',
+             'warning')
+        return None
+
+    try:
+        data = json.loads(out)
+    except Exception:
+        return None
+
+    info = {
+        'width': None, 'height': None, 'codec': None, 'pix_fmt': None,
+        'level': None, 'duration': None, 'has_audio': False,
+    }
+    for stream in data.get('streams', []):
+        if stream.get('codec_type') == 'video' and info['width'] is None:
+            info['width'] = stream.get('width')
+            info['height'] = stream.get('height')
+            info['codec'] = stream.get('codec_name')
+            info['pix_fmt'] = stream.get('pix_fmt')
+            info['level'] = stream.get('level')
+        elif stream.get('codec_type') == 'audio':
+            info['has_audio'] = True
+
+    fmt = data.get('format', {})
+    try:
+        info['duration'] = float(fmt.get('duration'))
+    except (TypeError, ValueError):
+        info['duration'] = None
+    return info
+
+
+def hardware_encoder_available():
+    """True when the Pi's V4L2 H.264 encoder can actually be opened.
+
+    Checked by running a tiny real encode rather than by grepping
+    ``ffmpeg -encoders``: the encoder is listed on builds where the kernel
+    device is missing or busy, and a failed encode at sync time would be far
+    worse than a slightly slower software one.
+    """
+    ffmpeg = find_ffmpeg()
+    if not ffmpeg:
+        return False
+    code, _ = _run([
+        ffmpeg, '-hide_banner', '-loglevel', 'error',
+        '-f', 'lavfi', '-i', 'testsrc=size=320x240:rate=10:duration=0.5',
+        '-c:v', HW_ENCODER, '-f', 'null', '-',
+    ], timeout=60)
+    return code == 0
+
+
+def needs_normalization(path, max_width=DEFAULT_MAX_WIDTH,
+                        max_height=DEFAULT_MAX_HEIGHT):
+    """(bool, info) — True when ``path`` exceeds the playback ceiling.
+
+    Only resolution is considered. A file at or below the ceiling is returned
+    untouched so content that already plays is never re-encoded.
+    """
+    info = probe_video(path)
+    if info is None:
+        return False, None
+    width, height = info.get('width'), info.get('height')
+    if not width or not height:
+        return False, info
+    return (width > max_width or height > max_height), info
+
+
+def _target_size(width, height, max_width, max_height):
+    """Scale ``width``x``height`` to fit the ceiling, preserving aspect ratio.
+
+    Dimensions are forced even: H.264 4:2:0 requires even width and height, and
+    an odd value makes the encoder fail outright.
+    """
+    scale = min(max_width / width, max_height / height)
+    new_w = int(width * scale)
+    new_h = int(height * scale)
+    # Round down to even numbers (never up — that could exceed the ceiling).
+    new_w -= new_w % 2
+    new_h -= new_h % 2
+    return max(2, new_w), max(2, new_h)
+
+
+def normalized_path(original_path, max_width=DEFAULT_MAX_WIDTH,
+                    max_height=DEFAULT_MAX_HEIGHT):
+    """Deterministic output path for the normalised version of a file.
+
+    Kept next to the original (not in a cache dir) so the existing media
+    clean-up logic, which prunes unreferenced files under ``media/``, can do its
+    normal job: the playlist ends up referencing the normalised file and the
+    oversized original is pruned automatically.
+    """
+    directory, name = os.path.split(original_path)
+    stem, ext = os.path.splitext(name)
+    return os.path.join(
+        directory, f'{stem}_kiwy{max_height}p{ext or ".mp4"}'
+    )
+
+
+def normalize_video(path, max_width=DEFAULT_MAX_WIDTH,
+                    max_height=DEFAULT_MAX_HEIGHT, force=False, dry_run=False):
+    """Downscale ``path`` if it exceeds the ceiling.
+
+    Returns a dict:
+        {'status': ..., 'output': ..., 'info': ..., 'elapsed_s': ...}
+
+    ``status`` is one of:
+        ``within_limit`` — already at or below the ceiling, untouched
+        ``reused``       — a previous conversion exists and was verified
+        ``normalized``   — a new file was produced
+        ``failed``       — could not normalise (caller should use the original)
+        ``would``        — dry_run only
+
+    The three success states are kept distinct on purpose: reporting a
+    converted file as "ok" alongside its *original* 4K dimensions reads as
+    "nothing to do" and would hide a missing conversion.
+
+    Never raises: a failure leaves the original file untouched and the caller
+    keeps playing it, because a large-but-playable video is better than none.
+    """
+    result = {'status': 'within_limit', 'output': None, 'info': None,
+              'elapsed_s': 0.0}
+
+    if not os.path.isfile(path):
+        result['status'] = 'failed'
+        result['info'] = 'file not found'
+        return result
+
+    oversized, info = needs_normalization(path, max_width, max_height)
+    result['info'] = info
+    if not oversized:
+        return result
+
+    output = normalized_path(path, max_width, max_height)
+
+    # Already converted in a previous sync: reuse it. ``media_state`` owns this
+    # decision so the player resolves the same file, by the same rules.
+    existing = media_state.normalized_file(path, max_height)
+    if not force and existing:
+        result['status'] = 'reused'
+        result['output'] = existing
+        _log(f'{os.path.basename(path)} already normalised -> '
+             f'{os.path.basename(existing)}')
+        return result
+
+    new_w, new_h = _target_size(info['width'], info['height'],
+                               max_width, max_height)
+    source_mb = os.path.getsize(path) / 1024 / 1024
+    _log(f'{os.path.basename(path)} is {info["width"]}x{info["height"]} '
+         f'({source_mb:.1f} MB) — above {max_width}x{max_height}; '
+         f'normalising to {new_w}x{new_h}')
+
+    if dry_run:
+        result['status'] = 'would'
+        result['output'] = output
+        return result
+
+    ffmpeg = find_ffmpeg()
+    if not ffmpeg:
+        _log('ffmpeg not found — cannot normalise', 'warning')
+        result['status'] = 'failed'
+        result['info'] = 'ffmpeg not found'
+        return result
+
+    # Write to a temp file and rename on success, so a partial or failed
+    # conversion can never be picked up as a valid video.
+    #
+    # The temp name keeps the real extension: ffmpeg infers the output muxer
+    # from the filename, so a bare ".part" fails with "Unable to choose an
+    # output format". The file is only ever moved to ``output`` after a
+    # successful encode, so the temp name is not user-visible.
+    root, ext = os.path.splitext(output)
+    tmp_out = f'{root}.tmp{ext or ".mp4"}'
+    try:
+        if os.path.exists(tmp_out):
+            os.remove(tmp_out)
+    except OSError:
+        pass
+
+    audio_args = ['-c:a', 'copy'] if info.get('has_audio') else ['-an']
+
+    # The scale filter runs on the CPU (the slow part for 4K); the encoder is
+    # hardware when possible.
+    vf = f'scale={new_w}:{new_h}:flags=fast_bilinear,format=yuv420p'
+
+    def build(codec_args):
+        """Assemble one ffmpeg command.
+
+        ``-map`` is explicit so extra streams (subtitles, cover art, a second
+        audio track) cannot change the output shape between runs.
+        """
+        cmd = [ffmpeg, '-hide_banner', '-loglevel', 'error', '-i', path,
+               '-map', '0:v:0']
+        if info.get('has_audio'):
+            cmd += ['-map', '0:a:0?']
+        cmd += ['-vf', vf] + codec_args + audio_args + [
+            '-movflags', '+faststart',
+            '-pix_fmt', 'yuv420p',
+            '-y', tmp_out,
+        ]
+        return cmd
+
+    # Try hardware first, then fall back to software. A hardware encoder that
+    # is listed but unusable (device busy, kernel mismatch) fails here rather
+    # than producing a broken file.
+    attempts = []
+    if hardware_encoder_available():
+        attempts.append((
+            f'hardware ({HW_ENCODER})',
+            build(['-c:v', HW_ENCODER, '-b:v', TARGET_BITRATE,
+                   '-maxrate', MAX_BITRATE, '-bufsize', BUFSIZE]),
+        ))
+    attempts.append((
+        f'software ({SW_ENCODER})',
+        build(['-c:v', SW_ENCODER, '-preset', 'ultrafast', '-crf', '23',
+               '-maxrate', MAX_BITRATE, '-bufsize', BUFSIZE]),
+    ))
+
+    started = time.monotonic()
+
+    # Publish the "converting" flag BEFORE the first encoder runs. The player
+    # watches this marker and skips the item while it exists, so an item must be
+    # flagged for the entire window in which its file is being rewritten.
+    marker_written = media_state.begin_conversion(
+        path, note=f'{info["width"]}x{info["height"]} -> {new_w}x{new_h}')
+    if not marker_written:
+        _log(f'could not write the conversion marker for '
+             f'{os.path.basename(path)}; the player may try to show the file '
+             f'while it is being rewritten', 'warning')
+
+    try:
+        return _run_encoders(
+            attempts, path, output, tmp_out, info, source_mb, result,
+            started, f'{new_w}x{new_h}')
+    finally:
+        # Always clear the flag, including on failure: leaving it set would
+        # make the item unplayable until it went stale.
+        media_state.end_conversion(path)
+
+
+def _run_encoders(attempts, path, output, tmp_out, info, source_mb,
+                  result, started, size_note):
+    """Try each encoder in turn; move the output into place on success."""
+    for label, cmd in attempts:
+        code, out = _run(cmd, timeout=1800)
+        if code == 0 and os.path.isfile(tmp_out) and os.path.getsize(tmp_out) > 0:
+            try:
+                os.replace(tmp_out, output)
+            except OSError as exc:
+                _log(f'could not move normalised file into place: {exc}',
+                     'warning')
+                result['status'] = 'failed'
+                return result
+            result['elapsed_s'] = time.monotonic() - started
+            result['status'] = 'normalized'
+            result['output'] = output
+
+            out_mb = os.path.getsize(output) / 1024 / 1024
+            _log(f'normalised with {label} in {result["elapsed_s"]:.0f}s: '
+                 f'{source_mb:.1f} MB -> {out_mb:.1f} MB '
+                 f'({os.path.basename(output)}) now {size_note}')
+
+            # Metadata last: its presence is what marks the conversion complete
+            # for media_state.normalized_file(), so it must never exist for a
+            # half-written output.
+            try:
+                with open(output + MARKER_SUFFIX, 'w') as fh:
+                    json.dump({
+                        'source': os.path.basename(path),
+                        'source_size': os.path.getsize(path),
+                        'width': info['width'],
+                        'height': info['height'],
+                        'output_width': int(size_note.split('x')[0]),
+                        'output_height': int(size_note.split('x')[1]),
+                        'encoder': label,
+                        'normalized_at': time.strftime('%Y-%m-%dT%H:%M:%S'),
+                    }, fh, indent=2)
+            except Exception:
+                pass
+            return result
+
+        _log(f'{label} failed (rc={code}): {out.strip()[:300]}', 'warning')
+
+    try:
+        if os.path.exists(tmp_out):
+            os.remove(tmp_out)
+    except OSError:
+        pass
+    result['status'] = 'failed'
+    result['info'] = 'all encoders failed'
+    _log(f'could not normalise {os.path.basename(path)}; '
+         f'the original will be used', 'warning')
+    return result
+
+
+def normalize_media_dirs(media_dirs, max_width=DEFAULT_MAX_WIDTH,
+                         max_height=DEFAULT_MAX_HEIGHT, dry_run=False):
+    """Normalise every oversized video under the given directories.
+
+    Intended for bulk/offline use (``--all``) and for verifying an install.
+    Returns a list of per-file result dicts.
+    """
+    results = []
+    seen = set()
+    for directory in media_dirs:
+        if not os.path.isdir(directory):
+            continue
+        for root, _dirs, files in os.walk(directory):
+            for name in sorted(files):
+                if not name.lower().endswith(
+                        ('.mp4', '.mkv', '.mov', '.webm', '.avi', '.m4v')):
+                    continue
+                if '_kiwy' in name or name.endswith(MARKER_SUFFIX):
+                    continue  # already an output, never re-process
+                path = os.path.join(root, name)
+                if path in seen:
+                    continue
+                seen.add(path)
+                size = os.path.getsize(path)
+                key = (path, size)
+                if key in seen:
+                    continue
+                results.append(normalize_video(
+                    path, max_width, max_height, dry_run=dry_run))
+    return results
+
+
+# ── CLI ──────────────────────────────────────────────────────────────
+def main():
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description='Downscale oversized videos for Raspberry Pi playback.')
+    parser.add_argument('paths', nargs='+',
+                        help='video files or directories to inspect')
+    parser.add_argument('--max-width', type=int, default=DEFAULT_MAX_WIDTH)
+    parser.add_argument('--max-height', type=int, default=DEFAULT_MAX_HEIGHT)
+    parser.add_argument('--dry-run', action='store_true',
+                        help='report what would change, convert nothing')
+    parser.add_argument('--force', action='store_true',
+                        help='re-convert even if a normalised copy exists')
+    args = parser.parse_args()
+
+    print(f'max size : {args.max_width}x{args.max_height}')
+    print(f'ffmpeg   : {find_ffmpeg()}')
+    print(f'ffprobe  : {find_ffprobe()}')
+    if not args.dry_run:
+        hw = 'available' if hardware_encoder_available() else 'unavailable (will use libx264)'
+        print(f'hw enc   : {hw}')
+    print()
+
+    changed = 0
+    for target in args.paths:
+        if os.path.isdir(target):
+            results = normalize_media_dirs(
+                [target], args.max_width, args.max_height, args.dry_run)
+            changed += sum(1 for r in results
+                           if r['status'] in ('normalized', 'would', 'reused'))
+            continue
+
+        if args.force:
+            oversized, info = needs_normalization(
+                target, args.max_width, args.max_height)
+            if info:
+                out = normalized_path(target, args.max_width, args.max_height)
+                for stale in (out, out + MARKER_SUFFIX):
+                    try:
+                        os.remove(stale)
+                    except OSError:
+                        pass
+
+        result = normalize_video(target, args.max_width, args.max_height,
+                                 force=args.force, dry_run=args.dry_run)
+        info = result.get('info')
+        name = os.path.basename(target)
+        if result['status'] == 'within_limit':
+            if isinstance(info, dict) and info.get('width'):
+                print(f'  ok       {name}  {info["width"]}x{info["height"]} '
+                      f'(within limit)')
+            else:
+                print(f'  ok       {name}')
+        elif result['status'] == 'reused':
+            print(f'  reuse    {name}  {info["width"]}x{info["height"]} '
+                  f'-> {os.path.basename(result["output"])}')
+            changed += 1
+        elif result['status'] == 'normalized':
+            print(f'  DONE     {name} -> {os.path.basename(result["output"])} '
+                  f'({result["elapsed_s"]:.0f}s)')
+            changed += 1
+        elif result['status'] == 'would':
+            print(f'  WOULD    {name}  {info["width"]}x{info["height"]} '
+                  f'-> {os.path.basename(result["output"])}')
+            changed += 1
+        else:
+            print(f'  FAILED   {name}  {result.get("info")}')
+
+    print(f'\n{changed} file(s) need normalisation')
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

playlists/server_playlist.json

@@ -1,37 +0,0 @@
-{
-  "count": 4,
-  "player_id": 1,
-  "player_name": "Test_player1",
-  "playlist": [
-    {
-      "file_name": "sean-oulashin-KMn4VEeEPR8-unsplash.jpg",
-      "type": "image",
-      "url": "media/sean-oulashin-KMn4VEeEPR8-unsplash.jpg",
-      "duration": 14,
-      "edit_on_player": true
-    },
-    {
-      "file_name": "weblink-1e4a4d6d885a",
-      "type": "weblink",
-      "url": "https://moto-adv.com/",
-      "duration": 30,
-      "edit_on_player": false
-    },
-    {
-      "file_name": "sample-30s.mp4",
-      "type": "video",
-      "url": "media/sample-30s.mp4",
-      "duration": 31,
-      "edit_on_player": false
-    },
-    {
-      "file_name": "edited_media/5/eye_e_v2.jpg",
-      "type": "image",
-      "url": "media/edited_media/5/eye_e_v2.jpg",
-      "duration": 50,
-      "edit_on_player": true
-    }
-  ],
-  "playlist_id": 1,
-  "playlist_version": 14
-}

run_player.sh

@@ -1,5 +1,13 @@
 #!/bin/bash
 
-# Start Kivy Signage Player
-cd "$(dirname "$0")/src"
-python3 main.py
+# Start Kivy Signage Player (single run, no watchdog).
+#
+# linux/run_linux.py is the Raspberry Pi entry point: it sets the Wayland
+# session environment and injects the Pi-specific display and web-link
+# behaviour. Running src/main.py directly skips all of that.
+cd "$(dirname "$0")" || exit 1
+
+if [ -x .venv/bin/python ]; then
+    exec .venv/bin/python linux/run_linux.py
+fi
+exec python3 linux/run_linux.py

src/edit_popup.py

@@ -82,11 +82,17 @@ class DrawingLayer(Widget):
 
 class EditPopup(Popup):
     """Popup for editing/annotating images"""
-    def __init__(self, player_instance, image_path, user_card_data=None, **kwargs):
+    def __init__(self, player_instance, image_path, user_card_data=None,
+                 media_id=None, original_filename=None, **kwargs):
         super(EditPopup, self).__init__(**kwargs)
         self.player = player_instance
         self.image_path = image_path
         self.user_card_data = user_card_data  # Store card data to send to server on save
+        # Server naming context: which media item (id) is being edited and what
+        # its original file name is on the server. The server stores edited
+        # media under 'edited_media/<media_id>/', so we must reproduce that.
+        self.media_id = media_id
+        self.original_filename = original_filename  # server-side file_name
         
         # Auto-close timer (5 minutes)
         self.auto_close_timeout = 300  # 5 minutes in seconds
@@ -259,8 +265,15 @@ class EditPopup(Popup):
     def save_image(self, instance):
         """Save the edited image"""
         try:
-            # Create edited_media directory if it doesn't exist
-            edited_dir = os.path.join(self.player.base_dir, 'media', 'edited_media')
+            # Edited media is stored on the server under
+            # 'edited_media/<media_id>/'. Reproduce that subfolder locally so
+            # the upload naming matches what the server expects. Fall back to
+            # the flat 'edited_media/' folder when no media_id is available.
+            edited_base = os.path.join(self.player.base_dir, 'media', 'edited_media')
+            if self.media_id is not None:
+                edited_dir = os.path.join(edited_base, str(self.media_id))
+            else:
+                edited_dir = edited_base
             os.makedirs(edited_dir, exist_ok=True)
             
             # Get original filename
@@ -310,8 +323,22 @@ class EditPopup(Popup):
                     # Overwrite the file
                     shutil.copy2(output_path, self.image_path)
                     
-                    # Force file system sync to ensure data is written to disk
+                    # Force file system sync to ensure data is written to disk.
+                    # NOTE: os.sync() does not exist on every platform and used
+                    # to raise AttributeError, aborting the whole pipeline before
+                    # the metadata/upload steps. Use a best-effort flushes that can
+                    # never break the save/upload flow.
+                    try:
+                        if hasattr(os, 'sync'):
                             os.sync()
+                        else:
+                            with open(output_path, 'rb') as _f:
+                                try:
+                                    os.fsync(_f.fileno())
+                                except Exception:
+                                    pass
+                    except Exception as _sync_err:
+                        Logger.warning(f"EditPopup: File sync skipped ({_sync_err})")
                     
                     # Verify the overwrite
                     new_size = os.path.getsize(self.image_path)
@@ -326,9 +353,15 @@ class EditPopup(Popup):
                     self.ids.top_toolbar.opacity = 1
                     self.ids.right_sidebar.opacity = 1
                     
-                    # Create and save metadata
+                    # Create and save metadata. This runs in its own guarded
+                    # block so that a failure here cannot silently stop the
+                    # upload — the two steps are intentionally decoupled.
+                    json_filename = None
+                    try:
                         json_filename = self._save_metadata(edited_dir, new_name, base_name, 
                                            new_version if version_match else 1, output_filename)
+                    except Exception as meta_err:
+                        Logger.error(f"EditPopup: Metadata save failed: {meta_err}")
                     
                     # Upload to server in background (continues after popup closes)
                     upload_thread = threading.Thread(
@@ -414,6 +447,14 @@ class EditPopup(Popup):
             'version': version,
             'user_card_data': self.user_card_data  # Card data from reader (or None)
         }
+        # Include the server-side file name and media id so the server can
+        # attach the edit to the correct media item.
+        if self.original_filename:
+            metadata['original_filename'] = self.original_filename
+        else:
+            metadata['original_filename'] = os.path.basename(self.image_path)
+        if self.media_id is not None:
+            metadata['media_id'] = self.media_id
         
         # Save metadata JSON
         json_filename = f"{new_name}_metadata.json"
@@ -444,16 +485,37 @@ class EditPopup(Popup):
                 Logger.warning("EditPopup: Missing server URL or auth code (upload skipped)")
                 return False
             
-            # Load metadata from file
+            # Load metadata from file (or build it in memory if the metadata
+            # file was not written — the upload must still go through).
+            metadata = None
+            if metadata_path and os.path.exists(metadata_path):
+                try:
                     with open(metadata_path, 'r') as meta_file:
                         metadata = json.load(meta_file)
+                except Exception as e:
+                    Logger.warning(f"EditPopup: Could not read metadata file: {e}")
+            if not metadata:
+                metadata = {
+                    'time_of_modification': datetime.now().isoformat(),
+                    'original_name': os.path.basename(image_path),
+                    'new_name': os.path.basename(image_path),
+                    'version': 1,
+                    'user_card_data': self.user_card_data,
+                }
+                if self.original_filename:
+                    metadata['original_filename'] = self.original_filename
+                if self.media_id is not None:
+                    metadata['media_id'] = self.media_id
             
             # Prepare upload URL - send to the original file endpoint
             upload_url = f"{server_url}/api/player-edit-media"
             headers = {'Authorization': f'Bearer {auth_code}'}
             
-            # Add the original filename to metadata so server knows which file was edited
-            metadata['original_filename'] = os.path.basename(metadata['original_path'])
+            # Ensure the original filename (server-side name) is present so the
+            # server knows which file was edited. Prefer the media context we
+            # captured when the edit popup opened.
+            if not metadata.get('original_filename'):
+                metadata['original_filename'] = os.path.basename(metadata.get('original_path', image_path))
             
             # Disable SSL verification for self-signed certificates (like main code does)
             # Note: This is NOT recommended for production with untrusted servers

src/get_playlists_v2.py

@@ -7,8 +7,11 @@ import os
 import json
 import requests
 import logging
+import subprocess
+import sys
 from player_auth import PlayerAuth
 from ssl_utils import SSLManager
+import media_state  # conversion flags/markers, shared with the player
 
 # Set up logging
 logging.basicConfig(level=logging.INFO)
@@ -248,13 +251,11 @@ def download_media_files(playlist, media_dir, ssl_manager=None, server_url=None)
         # Web-link items have no file to download — pass the link through unchanged.
         if item_type == 'weblink':
             logger.info(f"🔗 Web link item (no download): {file_url}")
-            updated_playlist.append({
-                'file_name': file_name,
-                'type': 'weblink',
-                'url': file_url,  # keep the original web address (not a local path)
-                'duration': duration,
-                'edit_on_player': False,
-            })
+            # Preserve every server field (audio/muted/description/id/position/...)
+            # instead of rebuilding a fixed dict, so nothing is silently dropped.
+            weblink_item = dict(media)
+            weblink_item['type'] = 'weblink'
+            updated_playlist.append(weblink_item)
             continue
 
         local_path = os.path.join(media_dir, file_name)
@@ -318,14 +319,13 @@ def download_media_files(playlist, media_dir, ssl_manager=None, server_url=None)
                 # Don't skip - may still add to playlist
         
         # Always add the media item to the playlist, even if download failed
-        # (it might already exist or be available later)
-        updated_media = {
-            'file_name': file_name,
-            'type': item_type,  # Preserve media type (image/video/...)
-            'url': os.path.relpath(local_path, os.path.dirname(media_dir)),
-            'duration': duration,
-            'edit_on_player': media.get('edit_on_player', False)  # Preserve edit_on_player flag
-        }
+        # (it might already exist or be available later).
+        # Preserve EVERY server field (audio/muted/description/id/position/...)
+        # by copying the original dict and only overriding the URL with the
+        # local path — previously the fixed dict below dropped `audio`, `muted`,
+        # `description`, `id` and `position` from the saved playlist.
+        updated_media = dict(media)
+        updated_media['url'] = os.path.relpath(local_path, os.path.dirname(media_dir))
         updated_playlist.append(updated_media)
     
     return updated_playlist
@@ -344,6 +344,24 @@ def delete_unused_media(playlist_data, media_dir):
         
         logger.info(f"📋 Current playlist references {len(referenced_files)} files")
 
+        # Names of the normalisation artefacts that belong to files STILL in the
+        # playlist. Computed from the referenced files with the same naming
+        # helpers the normaliser uses, so the two cannot drift.
+        #
+        # This has to be a per-source decision, not a blanket "never delete
+        # anything containing _kiwy": a converted output is not itself named in
+        # the playlist, so a blanket rule would keep the 1080p copies (and their
+        # metadata) forever after the item is removed from the playlist — an
+        # unnoticed disk leak on a device that runs for months.
+        keep_artifacts = set()
+        for ref in referenced_files:
+            ref_path = os.path.join(media_dir, ref)
+            output = media_state.normalized_output(ref_path)
+            keep_artifacts.add(os.path.basename(output))
+            keep_artifacts.add(os.path.basename(output) + media_state.MARKER_SUFFIX)
+            keep_artifacts.add(os.path.basename(media_state.converting_marker(ref_path)))
+        keep_artifacts.discard('')
+
         if os.path.exists(media_dir):
             # Recursively get all media files
             deleted_count = 0
@@ -353,17 +371,46 @@ def delete_unused_media(playlist_data, media_dir):
                     full_path = os.path.join(root, media_file)
                     rel_path = os.path.relpath(full_path, media_dir)
 
-                    # Skip if file is in current playlist
-                    if rel_path in referenced_files:
+                    # Normalisation artefacts belong to the item that produced
+                    # them, so they are kept only while that source is still
+                    # referenced. Their filenames are not in the playlist
+                    # (the player derives them at run time), which is exactly why
+                    # this check cannot be the generic one below.
+                    if media_file in keep_artifacts:
                         continue
 
+                    # A leftover artefact whose source is gone: it is derived
+                    # data, safe to delete like any other unreferenced file.
+                    # ``.kiwy-converting`` is excluded — it may belong to a
+                    # conversion running right now for a file this pass missed.
+                    if (media_file.endswith(media_state.MARKER_SUFFIX)
+                            or '_kiwy' in media_file) \
+                            and not media_file.endswith(media_state.CONVERTING_SUFFIX):
+                        try:
+                            os.remove(full_path)
+                            logger.info(f'🗑️  Deleted stale normalisation '
+                                        f'artefact: {rel_path}')
+                            deleted_count += 1
+                        except Exception as e:
+                            logger.warning(f'⚠️  Could not delete {rel_path}: {e}')
+                        continue
+
+                    # Skip if file is in current playlist
+                    # Normalize path separators so server-style paths work
+                    normalized_rel = rel_path.replace('\\', '/')
+                    if normalized_rel in referenced_files or rel_path in referenced_files:
+                        continue
+
+                    # The 4K original is still referenced by the playlist, so it
+                    # is kept (harmless: it is no longer what gets played).
+
                     # Delete unreferenced file
                     try:
                         os.remove(full_path)
-                        logger.info(f"🗑️  Deleted unused media: {rel_path}")
+                        logger.info(f'🗑️  Deleted unused media: {rel_path}')
                         deleted_count += 1
                     except Exception as e:
-                        logger.warning(f"⚠️  Could not delete {rel_path}: {e}")
+                        logger.warning(f'⚠️  Could not delete {rel_path}: {e}')
             
             # Clean up empty directories
             for root, dirs, files in os.walk(media_dir, topdown=False):
@@ -387,6 +434,76 @@ def delete_unused_media(playlist_data, media_dir):
 
 
 
+def normalize_oversized_media(playlist, media_dir):
+    """Start conversion of any oversized video in ``playlist`` (non-blocking).
+
+    Called after the playlist and its files are in place. Conversion takes about
+    31 s for an 18 s 4K clip, so it is launched as a **detached background
+    process** rather than run here: blocking the sync loop for that long would
+    stall playlist updates, and the sync runs on the player's asyncio executor.
+
+    The child writes the ``.kiwy-converting`` marker before it starts, which is
+    what makes the player skip the item while its file is being rewritten, and
+    removes it when finished so the item plays on the next lap.
+
+    Failures are never fatal: an unconverted video simply means the player keeps
+    skipping that item.
+    """
+    try:
+        normalizer = os.path.join(
+            os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+            'linux', 'video_normalizer.py')
+        if not os.path.exists(normalizer):
+            logger.debug('Video normaliser not present; skipping conversion')
+            return 0
+
+        started = 0
+        for media in playlist or []:
+            if media.get('type') != 'video':
+                continue
+            file_name = media.get('file_name', '')
+            if not file_name:
+                continue
+
+            path = os.path.join(media_dir, file_name)
+            if not os.path.isfile(path):
+                continue
+
+            # Already converting (or a fresh marker says so): leave it alone.
+            if media_state.is_converting(path):
+                continue
+            # A finished conversion is reused automatically by the normaliser.
+            if media_state.normalized_file(path):
+                continue
+
+            oversized, width, height = media_state.is_oversized(path)
+            if not oversized:
+                continue
+
+            logger.info(
+                f'🎬 {file_name} is {width}x{height} — above 1920x1080; '
+                f'converting in the background for Raspberry Pi playback'
+            )
+            subprocess.Popen(
+                [sys.executable, normalizer, path],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                start_new_session=True,  # outlive this sync
+            )
+            started += 1
+
+        if started:
+            logger.info(
+                f'🎬 Started {started} video conversion(s); the player will '
+                f'skip those items until they are ready'
+            )
+        return started
+
+    except Exception as exc:
+        logger.warning(f'Could not start media normalisation: {exc}')
+        return 0
+
+
 def update_playlist_if_needed(config, playlist_dir, media_dir):
     """Check for and download updated playlist if available.
     
@@ -447,6 +564,11 @@ def update_playlist_if_needed(config, playlist_dir, media_dir):
             # Save new playlist (single file, no versioning)
             playlist_file = save_playlist(server_data, playlist_dir)
 
+            # Convert any oversized video to 1080p in the background. Doing this
+            # after the files are on disk (and after the playlist is saved) means
+            # the player can start skipping the item immediately.
+            normalize_oversized_media(server_data.get('playlist', []), media_dir)
+
             # Delete unused media files
             delete_unused_media(server_data, media_dir)
             
@@ -454,6 +576,23 @@ def update_playlist_if_needed(config, playlist_dir, media_dir):
             return playlist_file
         else:
             logger.info("✓ Playlist is up to date")
+            # Even when the playlist version matches, ensure media files exist locally.
+            # The media folder might be empty (e.g. fresh install or deleted files).
+            logger.info("📥 Checking for missing media files...")
+            ssl_manager = auth.ssl_manager if config.get('use_https', True) else None
+            server_url = auth.auth_data.get('server_url', '')
+            downloaded = download_media_files(
+                server_data.get('playlist', []), media_dir, ssl_manager, server_url
+            )
+            if downloaded:
+                server_data['playlist'] = downloaded
+                # Re-save playlist with updated URLs if needed
+                save_playlist(server_data, playlist_dir)
+
+            # A version match does not mean the media is ready: a fresh install
+            # (or a failed conversion) can still have an oversized file waiting
+            # to be normalised, and this branch is where that gets noticed.
+            normalize_oversized_media(server_data.get('playlist', []), media_dir)
             return playlist_file
     
     except Exception as e:

src/media_state.py

@@ -0,0 +1,301 @@
+"""media_state.py — conversion flags and normalised-path resolution.
+
+Shared by the player (``src/main.py``) and the normaliser
+(``linux/video_normalizer.py``), so both agree on one on-disk contract.
+
+Why this exists
+---------------
+A 4K video cannot be decoded in real time on a Pi 4 (measured 0.90x realtime),
+so oversized media is downscaled to 1080p at sync time. That conversion takes
+~31 s for an 18 s clip — long enough that the playlist may reach the item first.
+
+The player therefore needs to know, cheaply and without re-probing the file:
+
+* has this item already been converted?  -> play the smaller file instead
+* is it still converting?                 -> skip it this lap rather than
+                                             showing a frozen frame
+
+Rather than store that inside the playlist JSON (which the server owns and
+overwrites on every sync), the state lives in a **sidecar file next to the
+media**. That keeps the server contract untouched and survives a playlist
+re-download.
+
+Marker files, all next to the media file::
+
+    <media>.kiwy-converting     EXISTS while a conversion is in flight
+    <media>_kiwy1080p.mp4       the converted output
+    <media>_kiwy1080p.mp4.kiwy-normalized.json   metadata for that output
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+
+#: Suffix of the in-progress marker. Its presence alone means "skip this item".
+CONVERTING_SUFFIX = '.kiwy-converting'
+
+#: Suffix of the completed-conversion metadata file.
+MARKER_SUFFIX = '.kiwy-normalized.json'
+
+#: Default output ceiling (the Pi's practical decode limit).
+DEFAULT_MAX_WIDTH = 1920
+DEFAULT_MAX_HEIGHT = 1080
+
+#: A conversion marker older than this is treated as abandoned, so a crash
+#: mid-conversion cannot park an item forever. The 4K clip measured 31 s, so
+#: this is a very generous multiple.
+STALE_CONVERSION_SECONDS = 30 * 60
+
+
+def converting_marker(path):
+    return path + CONVERTING_SUFFIX
+
+
+def normalized_output(path, max_height=DEFAULT_MAX_HEIGHT):
+    """Deterministic path of the converted file for ``path``.
+
+    Must match ``linux/video_normalizer.normalized_path`` exactly — that is the
+    only reason this function is duplicated there rather than imported from a
+    runtime module the player should not depend on.
+    """
+    directory, name = os.path.split(path)
+    stem, ext = os.path.splitext(name)
+    return os.path.join(directory, f'{stem}_kiwy{max_height}p{ext or ".mp4"}')
+
+
+def is_converting(path):
+    """True when a conversion for ``path`` is currently in flight.
+
+    A marker left behind by a crash is ignored once it is older than
+    :data:`STALE_CONVERSION_SECONDS`, so an interrupted conversion cannot make
+    an item permanently unplayable.
+    """
+    marker = converting_marker(path)
+    try:
+        if not os.path.isfile(marker):
+            return False
+        age = time.time() - os.path.getmtime(marker)
+        if age > STALE_CONVERSION_SECONDS:
+            return False
+        return True
+    except OSError:
+        return False
+
+
+def begin_conversion(path, note=''):
+    """Create the in-progress marker for ``path``.
+
+    Returns True when the marker was written. Also removes any stale marker
+    first, so the age always reflects the current attempt.
+    """
+    marker = converting_marker(path)
+    try:
+        clear_conversion(path)
+    except Exception:
+        pass
+    try:
+        with open(marker, 'w') as fh:
+            json.dump({
+                'source': os.path.basename(path),
+                'source_size': os.path.getsize(path),
+                'started_at': time.strftime('%Y-%m-%dT%H:%M:%S'),
+                'note': note,
+            }, fh, indent=2)
+        return True
+    except Exception:
+        return False
+
+
+def end_conversion(path):
+    """Remove the in-progress marker. Safe to call unconditionally."""
+    try:
+        os.remove(converting_marker(path))
+        return True
+    except OSError:
+        return False
+
+
+def clear_conversion(path):
+    """Remove a stale in-progress marker (used before starting a new attempt)."""
+    marker = converting_marker(path)
+    try:
+        if os.path.isfile(marker):
+            os.remove(marker)
+    except OSError:
+        pass
+
+
+def conversion_metadata(path, max_height=DEFAULT_MAX_HEIGHT):
+    """Parsed metadata for a finished conversion, or None."""
+    meta_file = normalized_output(path, max_height) + MARKER_SUFFIX
+    try:
+        with open(meta_file) as fh:
+            return json.load(fh)
+    except Exception:
+        return None
+
+
+def normalized_file(path, max_height=DEFAULT_MAX_HEIGHT):
+    """The converted file for ``path`` **only if it is valid and complete**.
+
+    Returns None when no conversion has finished, when the output is missing or
+    empty, or when the metadata does not match the source that is currently on
+    disk (which catches a file being replaced by a different video of the same
+    name after a playlist change).
+
+    Deliberately does not require ``is_converting`` to be False: a conversion
+    that finished but crashed before removing its marker still produced a
+    usable file.
+    """
+    output = normalized_output(path, max_height)
+    try:
+        if not os.path.isfile(output) or os.path.getsize(output) == 0:
+            return None
+    except OSError:
+        return None
+
+    meta = conversion_metadata(path, max_height)
+    if not isinstance(meta, dict):
+        # No metadata: accept the output only if it is newer than the source.
+        try:
+            return output if os.path.getmtime(output) >= os.path.getmtime(path) else None
+        except OSError:
+            return None
+
+    try:
+        if meta.get('source_size') != os.path.getsize(path):
+            # The source changed since the conversion -> the output is stale.
+            return None
+    except OSError:
+        return None
+    return output
+
+
+def resolve_playable(path, max_width=DEFAULT_MAX_WIDTH,
+                     max_height=DEFAULT_MAX_HEIGHT):
+    """Pick the file to hand to the video player for ``path``.
+
+    Returns ``(chosen_path, state)`` where ``state`` is one of:
+
+    ``ready``      — the original is within limits, or already converted
+    ``converting`` — a conversion is in flight; the caller must SKIP this item
+    ``pending``    — oversized and not yet converted; the caller must SKIP this
+                     item (it would stutter or freeze) and let the sync convert
+                     it
+
+    ``chosen_path`` is the original file when ``state`` is ``pending`` or
+    ``converting``; callers should not use it in those cases.
+
+    Order matters. The size check must come **before** reporting ``pending``:
+    a normal 1080p video has no conversion output and no marker, so testing for
+    those alone would classify every ordinary video as "needs converting" and
+    skip the entire playlist.
+    """
+    # A finished conversion always wins: it is the file the Pi can decode.
+    converted = normalized_file(path, max_height)
+    if converted:
+        return converted, 'ready'
+
+    if is_converting(path):
+        return path, 'converting'
+
+    # Only an oversized file needs converting. Anything within the ceiling plays
+    # as-is, which is the common case and must stay cheap.
+    oversized, _width, _height = is_oversized(path, max_width, max_height)
+    if oversized:
+        return path, 'pending'
+
+    return path, 'ready'
+
+
+def is_oversized(path, max_width=DEFAULT_MAX_WIDTH, max_height=DEFAULT_MAX_HEIGHT):
+    """(bool, width, height) — True when the file exceeds the playback ceiling.
+
+    Uses the conversion metadata when present (no ffprobe spawn), and otherwise
+    falls back to reading the MP4 container header directly. Never shells out:
+    this runs on the playback path, where a subprocess would be far too costly.
+    """
+    width, height = read_video_size(path)
+    if not width or not height:
+        return False, width, height
+    return (width > max_width or height > max_height), width, height
+
+
+def read_video_size(path):
+    """Read (width, height) from an MP4/MOV container with no external tools.
+
+    Walks the box structure to the ``tkhd`` box, which stores the track's
+    display size as 16.16 fixed-point. Handles both the 32-bit (version 0) and
+    64-bit (version 1) header layouts.
+
+    Returns ``(None, None)`` for anything it cannot parse (non-MP4, fragmented,
+    truncated) so the caller can fall back to treating the file as playable —
+    being wrong in that direction means a possible stutter; being wrong the
+    other way would mean skipping a video that actually plays.
+    """
+    try:
+        with open(path, 'rb') as fh:
+            data = fh.read()
+    except OSError:
+        return None, None
+
+    def find_box(buf, start, end, box_type):
+        """Find the first box of ``box_type`` among the children in range."""
+        pos = start
+        while pos + 8 <= end:
+            size = int.from_bytes(buf[pos:pos + 4], 'big')
+            kind = buf[pos + 4:pos + 8]
+            header = 8
+            if size == 1:  # 64-bit extended size
+                if pos + 16 > end:
+                    return None
+                size = int.from_bytes(buf[pos + 8:pos + 16], 'big')
+                header = 16
+            elif size == 0:  # extends to end of file
+                size = end - pos
+            if size < header or pos + size > end:
+                return None
+            if kind == box_type:
+                return pos + header, pos + size
+            pos += size
+        return None
+
+    # moov -> trak -> tkhd
+    moov = find_box(data, 0, len(data), b'moov')
+    if not moov:
+        return None, None
+    pos, end = moov
+
+    # Scan the tracks for the first one that carries a tkhd with a real size.
+    while True:
+        trak = find_box(data, pos, end, b'trak')
+        if not trak:
+            return None, None
+        tpos, tend = trak
+        tkhd = find_box(data, tpos, tend, b'tkhd')
+        if tkhd:
+            kpos, kend = tkhd
+            try:
+                version = data[kpos]
+                # tkhd layout: version(1) flags(3) [creation(4/8)]
+                # [modification(4/8)] track_id(4) reserved(4) [duration(4/8)]
+                # reserved(8) layer(2) alt_group(2) volume(2) reserved(2)
+                # matrix(36) width(4) height(4)
+                offset = kpos + 4
+                if version == 1:
+                    offset += 8 + 8 + 4 + 4 + 8
+                else:
+                    offset += 4 + 4 + 4 + 4 + 4
+                offset += 8 + 2 + 2 + 2 + 2 + 36  # reserved..matrix
+                if offset + 8 <= kend:
+                    raw_w = int.from_bytes(data[offset:offset + 4], 'big')
+                    raw_h = int.from_bytes(data[offset + 4:offset + 8], 'big')
+                    width = raw_w >> 16   # 16.16 fixed point
+                    height = raw_h >> 16
+                    if width and height:
+                        return width, height
+            except (IndexError, ValueError):
+                pass
+        pos = tend

src/network_monitor.py

@@ -6,11 +6,17 @@ Checks server connectivity and manages WiFi restart on connection failure
 import subprocess
 import time
 import random
+import shutil
 import requests
 from datetime import datetime
 from kivy.logger import Logger
 from kivy.clock import Clock
 
+#: Interface used by the restart fallbacks. Raspberry Pi OS names the wireless
+#: interface wlan0; only used by the legacy path (NetworkManager resolves the
+#: device itself via `nmcli device`).
+WIFI_INTERFACE = 'wlan0'
+
 
 class NetworkMonitor:
     """Monitor network connectivity and manage WiFi restart"""
@@ -99,9 +105,11 @@ class NetworkMonitor:
             
             Logger.info(f"NetworkMonitor: Pinging server: {hostname}")
             
-            # Ping the server hostname with 3 attempts
+            # Ping the server hostname with 3 attempts (Linux syntax: -c count,
+            # -W per-packet timeout in seconds).
+            cmd = ['ping', '-c', '3', '-W', '3', hostname]
             result = subprocess.run(
-                ['ping', '-c', '3', '-W', '3', hostname],
+                cmd,
                 capture_output=True,
                 text=True,
                 timeout=10
@@ -123,8 +131,14 @@ class NetworkMonitor:
     
     def _restart_wifi(self):
         """
-        Restart WiFi by turning it off for a specified duration then back on
-        This runs in a separate thread to not block the main application
+        Restart WiFi by turning it off for a specified duration then back on.
+
+        Raspberry Pi OS Trixie manages networking with **NetworkManager**, so
+        ``nmcli`` is the correct interface and needs no ``sudo``. The legacy
+        rfkill/ifconfig path is kept only as a fallback for non-NetworkManager
+        installs (it requires root: see ``setup_wifi_control.sh``).
+
+        This runs in a separate thread to not block the main application.
         """
         def wifi_restart_thread():
             try:
@@ -132,7 +146,105 @@ class NetworkMonitor:
                 Logger.info("NetworkMonitor: INITIATING WIFI RESTART SEQUENCE")
                 Logger.info("NetworkMonitor: ====================================")
 
-                # Turn off WiFi using rfkill (more reliable on Raspberry Pi)
+                if shutil.which('nmcli'):
+                    self._restart_wifi_nmcli()
+                else:
+                    self._restart_wifi_legacy()
+
+            except subprocess.TimeoutExpired:
+                Logger.error("NetworkMonitor: WiFi restart command timeout")
+            except Exception as e:
+                Logger.error(f"NetworkMonitor: Error during WiFi restart: {e}")
+
+        # Run in separate thread to not block the application
+        import threading
+        thread = threading.Thread(target=wifi_restart_thread, daemon=True)
+        thread.start()
+
+    def _restart_wifi_nmcli(self):
+        """WiFi restart via NetworkManager (the default on Raspberry Pi OS).
+
+        ``nmcli`` is what actually manages the radio on Trixie, works without
+        ``sudo`` for a user in the ``netdev``/``NetworkManager`` group, and
+        reconnects to the saved profile automatically. The previous
+        implementation used ``rfkill``/``ifconfig``/``dhclient`` — ``ifconfig``
+        and ``dhclient`` are not even installed on a stock Trixie image, so the
+        restart silently did nothing.
+        """
+        wait_minutes = self.wifi_restart_duration / 60
+        Logger.info(
+            f"NetworkMonitor: NetworkManager WiFi restart — off for "
+            f"{wait_minutes:.0f} min"
+        )
+
+        # Turn the radio OFF (persists across the wait, unlike a disconnect).
+        off = subprocess.run(
+            ['nmcli', 'radio', 'wifi', 'off'],
+            capture_output=True, text=True, timeout=15
+        )
+        if off.returncode == 0:
+            Logger.info("NetworkMonitor: ✓ WiFi radio disabled (nmcli radio wifi off)")
+        else:
+            # Some builds deny `radio off` to non-root; a device disconnect
+            # still forces a reconnect without needing privileges.
+            Logger.warning(
+                f"NetworkMonitor: nmcli radio off failed ({off.stderr.strip()}); "
+                f"falling back to device disconnect"
+            )
+            subprocess.run(
+                ['nmcli', 'device', 'disconnect', WIFI_INTERFACE],
+                capture_output=True, text=True, timeout=15
+            )
+
+        Logger.info(
+            f"NetworkMonitor: WiFi will remain OFF for {wait_minutes:.0f} minutes "
+            f"(started {datetime.now().strftime('%H:%M:%S')})"
+        )
+        time.sleep(self.wifi_restart_duration)
+        Logger.info(
+            f"NetworkMonitor: Wait period completed at "
+            f"{datetime.now().strftime('%H:%M:%S')}"
+        )
+
+        # Turn the radio back ON and let NetworkManager auto-connect.
+        on = subprocess.run(
+            ['nmcli', 'radio', 'wifi', 'on'],
+            capture_output=True, text=True, timeout=15
+        )
+        if on.returncode == 0:
+            Logger.info("NetworkMonitor: ✓ WiFi radio enabled (nmcli radio wifi on)")
+        else:
+            Logger.error(f"NetworkMonitor: nmcli radio on failed: {on.stderr.strip()}")
+
+        # Give NetworkManager a moment, then nudge the saved connection up.
+        time.sleep(10)
+        connect = subprocess.run(
+            ['nmcli', 'device', 'connect', WIFI_INTERFACE],
+            capture_output=True, text=True, timeout=30
+        )
+        if connect.returncode == 0:
+            Logger.info("NetworkMonitor: ✓ Reconnected to the saved WiFi profile")
+        else:
+            # NetworkManager often reconnects on its own before we get here, in
+            # which case `device connect` reports "already connected".
+            Logger.info(
+                f"NetworkMonitor: nmcli device connect returned "
+                f"{connect.returncode}: {connect.stderr.strip()} "
+                f"(NetworkManager may have reconnected automatically)"
+            )
+
+        Logger.info("NetworkMonitor: ====================================")
+        Logger.info("NetworkMonitor: WIFI RESTART SEQUENCE COMPLETED")
+        Logger.info("NetworkMonitor: ====================================")
+
+    def _restart_wifi_legacy(self):
+        """Fallback for systems without NetworkManager: rfkill + ip.
+
+        Requires passwordless ``sudo`` for the exact commands used — see
+        ``setup_wifi_control.sh``. Note ``ifconfig``/``dhclient`` are legacy and
+        not installed on current images; ``ip`` is used instead.
+        """
+        # Turn off WiFi using rfkill (works regardless of the network stack)
         Logger.info("NetworkMonitor: Turning WiFi OFF using rfkill...")
         result = subprocess.run(
             ['sudo', 'rfkill', 'block', 'wifi'],
@@ -143,21 +255,20 @@ class NetworkMonitor:
 
         if result.returncode == 0:
             Logger.info("NetworkMonitor: ✓ WiFi turned OFF successfully (rfkill)")
-                    Logger.info("NetworkMonitor: WiFi is now DISABLED and will remain OFF")
         else:
-                    Logger.error(f"NetworkMonitor: rfkill failed, trying ifconfig...")
+            Logger.error(f"NetworkMonitor: rfkill failed, trying ip link...")
             Logger.error(f"NetworkMonitor: rfkill error: {result.stderr}")
 
-                    # Fallback to ifconfig
+            # Fallback to ip link (ifconfig is not installed on Trixie)
             result2 = subprocess.run(
-                        ['sudo', 'ifconfig', 'wlan0', 'down'],
+                ['sudo', 'ip', 'link', 'set', WIFI_INTERFACE, 'down'],
                 capture_output=True,
                 text=True,
                 timeout=10
             )
 
             if result2.returncode == 0:
-                        Logger.info("NetworkMonitor: ✓ WiFi turned OFF successfully (ifconfig)")
+                Logger.info("NetworkMonitor: ✓ WiFi turned OFF successfully (ip link)")
             else:
                 Logger.error(f"NetworkMonitor: Failed to turn WiFi off: {result2.stderr}")
                 Logger.error(f"NetworkMonitor: Return code: {result2.returncode}")
@@ -196,7 +307,7 @@ class NetworkMonitor:
 
         # Also bring interface up
         result2 = subprocess.run(
-                    ['sudo', 'ifconfig', 'wlan0', 'up'],
+            ['sudo', 'ip', 'link', 'set', WIFI_INTERFACE, 'up'],
             capture_output=True,
             text=True,
             timeout=10
@@ -205,31 +316,16 @@ class NetworkMonitor:
         if result2.returncode == 0:
             Logger.info("NetworkMonitor: ✓ WiFi interface brought UP successfully")
 
-                    # Wait a bit for connection to establish
+            # Wait a bit for connection to establish.
+            # NOTE: the DHCP client is deliberately not invoked here —
+            # `dhclient` is not installed on Raspberry Pi OS Trixie and
+            # hand-rolling it would fight NetworkManager/dhcpcd, which handle
+            # the lease automatically once the interface comes back up.
             Logger.info("NetworkMonitor: Waiting 10 seconds for WiFi to initialize...")
             time.sleep(10)
 
-                    # Try to restart DHCP
-                    Logger.info("NetworkMonitor: Requesting IP address...")
-                    subprocess.run(
-                        ['sudo', 'dhclient', 'wlan0'],
-                        capture_output=True,
-                        text=True,
-                        timeout=15
-                    )
-                    
             Logger.info("NetworkMonitor: ====================================")
             Logger.info("NetworkMonitor: WIFI RESTART SEQUENCE COMPLETED")
             Logger.info("NetworkMonitor: ====================================")
         else:
             Logger.error(f"NetworkMonitor: Failed to turn WiFi on: {result.stderr}")
-                    
-            except subprocess.TimeoutExpired:
-                Logger.error("NetworkMonitor: WiFi restart command timeout")
-            except Exception as e:
-                Logger.error(f"NetworkMonitor: Error during WiFi restart: {e}")
-        
-        # Run in separate thread to not block the application
-        import threading
-        thread = threading.Thread(target=wifi_restart_thread, daemon=True)
-        thread.start()

src/playback_trace.py

@@ -0,0 +1,64 @@
+"""
+playback_trace.py — Always-on playback transition logger.
+
+Kivy's log level is forced to 'warning' in main.py, which suppresses every
+Logger.info()/Logger.debug() line. That made it impossible
+to see why the player skips/crashes at the weblink->image and video->next
+transitions.
+
+This module writes a plain-text trace file (logs/playback_trace.log) with
+timestamps, INDEPENDENT of Kivy's log level, so we can always see exactly
+what the player is doing. It is thread-safe (a lock guards the append) and
+never throws (all failures are swallowed) so it can never break playback.
+
+Usage:
+    from playback_trace import trace
+    trace("play_current_media", index=3, name="foo.jpg", type="image")
+"""
+
+import os
+import threading
+import time
+
+_LOCK = threading.Lock()
+_LOG_PATH = None
+_OPENED = False
+
+
+def _ensure_path():
+    global _LOG_PATH, _OPENED
+    if _OPENED:
+        return _LOG_PATH
+    _OPENED = True
+    try:
+        # Respect the local data dir the launcher set (same place as logs/).
+        base = os.environ.get('KIWY_DATA_DIR') or os.getcwd()
+        log_dir = os.path.join(base, 'logs')
+        os.makedirs(log_dir, exist_ok=True)
+        _LOG_PATH = os.path.join(log_dir, 'playback_trace.log')
+    except Exception:
+        _LOG_PATH = None
+    return _LOG_PATH
+
+
+def trace(event, **kwargs):
+    """Append one line to the playback trace log.
+
+    Args:
+        event: short event name, e.g. 'next_media', 'eos', 'web_open'.
+        **kwargs: key=value context, e.g. index=3, name='foo.jpg'.
+    """
+    try:
+        path = _ensure_path()
+        if not path:
+            return
+        t = time.strftime('%H:%M:%S')
+        ms = int((time.time() % 1) * 1000)
+        parts = [f"{t}.{ms:03d}", event]
+        for k, v in kwargs.items():
+            parts.append(f"{k}={v}")
+        with _LOCK:
+            with open(path, 'a', encoding='utf-8') as f:
+                f.write(" ".join(parts) + "\n")
+    except Exception:
+        pass  # tracing must never break the player

src/player_auth.json

@@ -1,10 +0,0 @@
-{
-  "hostname": "Birou_IT",
-  "auth_code": "CZncd_2dlTZGieBEdqAbUTjf3qNyEUPDXr8jLVx7NLs",
-  "player_id": 1,
-  "player_name": "Test_player1",
-  "playlist_id": 1,
-  "orientation": "Landscape",
-  "authenticated": true,
-  "server_url": "http://192.168.0.109:8080"
-}

src/signage_player.kv

@@ -352,20 +352,27 @@
 # Settings popup content
 <SettingsPopup@Popup>:
     title: 'Player Settings'
-    size_hint: 0.8, 0.8
+    size_hint: 0.9, 0.85
     auto_dismiss: True
     
     BoxLayout:
         orientation: 'vertical'
-        padding: dp(20)
-        spacing: dp(15)
+        padding: [dp(15), dp(10)]
+        spacing: dp(8)
+        
+        ScrollView:
+            BoxLayout:
+                orientation: 'vertical'
+                spacing: dp(8)
+                size_hint_y: None
+                height: self.minimum_height
                 
                 # Server configuration
                 BoxLayout:
                     orientation: 'horizontal'
                     size_hint_y: None
-            height: dp(40)
-            spacing: dp(10)
+                    height: dp(36)
+                    spacing: dp(8)
                     
                     Label:
                         text: 'Server IP:'
@@ -378,7 +385,8 @@
                         id: server_input
                         size_hint_x: 0.7
                         multiline: False
-                font_size: sp(14)
+                        font_size: sp(13)
+                        hint_text: 'e.g. 192.168.0.110'
                         write_tab: False
                         on_touch_down: root.on_input_touch(self, args[1]) if self.collide_point(*args[1].pos) else None
                 
@@ -386,8 +394,8 @@
                 BoxLayout:
                     orientation: 'horizontal'
                     size_hint_y: None
-            height: dp(40)
-            spacing: dp(10)
+                    height: dp(36)
+                    spacing: dp(8)
                     
                     Label:
                         text: 'Port:'
@@ -400,7 +408,7 @@
                         id: port_input
                         size_hint_x: 0.7
                         multiline: False
-                font_size: sp(14)
+                        font_size: sp(13)
                         hint_text: '80 or 8080 (leave empty for default)'
                         input_filter: 'int'
                         write_tab: False
@@ -410,8 +418,8 @@
                 BoxLayout:
                     orientation: 'horizontal'
                     size_hint_y: None
-            height: dp(40)
-            spacing: dp(10)
+                    height: dp(36)
+                    spacing: dp(8)
                     
                     Label:
                         text: 'Screen Name:'
@@ -424,7 +432,8 @@
                         id: screen_input
                         size_hint_x: 0.7
                         multiline: False
-                font_size: sp(14)
+                        font_size: sp(13)
+                        hint_text: 'player name registered on the server'
                         write_tab: False
                         on_touch_down: root.on_input_touch(self, args[1]) if self.collide_point(*args[1].pos) else None
                 
@@ -432,8 +441,8 @@
                 BoxLayout:
                     orientation: 'horizontal'
                     size_hint_y: None
-            height: dp(40)
-            spacing: dp(10)
+                    height: dp(36)
+                    spacing: dp(8)
                     
                     Label:
                         text: 'Quickconnect:'
@@ -446,7 +455,8 @@
                         id: quickconnect_input
                         size_hint_x: 0.7
                         multiline: False
-                font_size: sp(14)
+                        font_size: sp(13)
+                        hint_text: 'e.g. 8887779'
                         write_tab: False
                         on_touch_down: root.on_input_touch(self, args[1]) if self.collide_point(*args[1].pos) else None
                 
@@ -454,8 +464,8 @@
                 BoxLayout:
                     orientation: 'horizontal'
                     size_hint_y: None
-            height: dp(40)
-            spacing: dp(10)
+                    height: dp(36)
+                    spacing: dp(8)
                     
                     Label:
                         text: 'Orientation:'
@@ -468,7 +478,7 @@
                         id: orientation_input
                         size_hint_x: 0.7
                         multiline: False
-                font_size: sp(14)
+                        font_size: sp(13)
                         write_tab: False
                         on_touch_down: root.on_input_touch(self, args[1]) if self.collide_point(*args[1].pos) else None
                 
@@ -476,8 +486,8 @@
                 BoxLayout:
                     orientation: 'horizontal'
                     size_hint_y: None
-            height: dp(40)
-            spacing: dp(10)
+                    height: dp(36)
+                    spacing: dp(8)
                     
                     Label:
                         text: 'Touch:'
@@ -490,7 +500,7 @@
                         id: touch_input
                         size_hint_x: 0.7
                         multiline: False
-                font_size: sp(14)
+                        font_size: sp(13)
                         write_tab: False
                         on_touch_down: root.on_input_touch(self, args[1]) if self.collide_point(*args[1].pos) else None
                 
@@ -498,8 +508,8 @@
                 BoxLayout:
                     orientation: 'horizontal'
                     size_hint_y: None
-            height: dp(40)
-            spacing: dp(10)
+                    height: dp(36)
+                    spacing: dp(8)
                     
                     Label:
                         text: 'Max Resolution:'
@@ -512,7 +522,7 @@
                         id: resolution_input
                         size_hint_x: 0.7
                         multiline: False
-                font_size: sp(14)
+                        font_size: sp(13)
                         hint_text: '1920x1080 or auto'
                         write_tab: False
                         on_touch_down: root.on_input_touch(self, args[1]) if self.collide_point(*args[1].pos) else None
@@ -521,11 +531,11 @@
                 BoxLayout:
                     orientation: 'horizontal'
                     size_hint_y: None
-            height: dp(40)
-            spacing: dp(10)
+                    height: dp(36)
+                    spacing: dp(8)
                     
                     Label:
-                text: 'Enable Edit Feature:'
+                        text: 'Enable Edit:'
                         size_hint_x: 0.3
                         text_size: self.size
                         halign: 'left'
@@ -534,87 +544,107 @@
                     CheckBox:
                         id: edit_enabled_checkbox
                         size_hint_x: None
-                width: dp(40)
+                        width: dp(36)
                         active: True
                         on_active: root.on_edit_feature_toggle(self.active)
                     
                     Label:
-                text: '(Allow editing images on this player)'
+                        text: '(Allow editing images)'
                         size_hint_x: 0.4
-                font_size: sp(12)
+                        font_size: sp(11)
                         text_size: self.size
                         halign: 'left'
                         valign: 'middle'
                         color: 0.7, 0.7, 0.7, 1
                 
+                # Separator
                 Widget:
-            size_hint_y: 0.05
+                    size_hint_y: None
+                    height: dp(5)
                 
                 # Reset Buttons Section
                 Label:
                     text: 'Reset Options:'
                     size_hint_y: None
-            height: dp(30)
+                    height: dp(26)
                     text_size: self.size
                     halign: 'left'
                     valign: 'middle'
                     bold: True
-            font_size: sp(16)
+                    font_size: sp(14)
                 
                 # Reset Buttons Row
                 BoxLayout:
                     orientation: 'horizontal'
                     size_hint_y: None
-            height: dp(50)
-            spacing: dp(10)
+                    height: dp(44)
+                    spacing: dp(8)
                     
                     Button:
                         id: reset_auth_btn
                         text: 'Reset Player Auth'
                         background_color: 0.8, 0.4, 0.2, 1
+                        font_size: sp(12)
                         on_press: root.reset_player_auth()
                     
                     Button:
                         id: reset_playlist_btn
                         text: 'Reset Playlist to v0'
                         background_color: 0.8, 0.4, 0.2, 1
+                        font_size: sp(12)
                         on_press: root.reset_playlist_version()
                     
                     Button:
                         id: restart_player_btn
                         text: 'Restart Player'
                         background_color: 0.2, 0.6, 0.8, 1
+                        font_size: sp(12)
                         on_press: root.restart_player()
                 
-        # Test Connection Button
+                # Test Connection + Production Mode Buttons
+                BoxLayout:
+                    orientation: 'horizontal'
+                    size_hint_y: None
+                    height: dp(44)
+                    spacing: dp(8)
+
                     Button:
                         id: test_connection_btn
                         text: 'Test Server Connection'
-            size_hint_y: None
-            height: dp(50)
                         background_color: 0.2, 0.4, 0.8, 1
+                        font_size: sp(13)
                         on_press: root.test_connection()
 
+                    Button:
+                        id: production_mode_btn
+                        text: 'Enable Production'
+                        background_color: 0.4, 0.4, 0.4, 1  # grey = disabled
+                        font_size: sp(13)
+                        on_press: root.toggle_production_mode()
+                
                 # Connection Status Label
                 Label:
                     id: connection_status
                     text: 'Click button to test connection'
                     size_hint_y: None
-            height: dp(40)
+                    height: dp(32)
                     text_size: self.size
                     halign: 'center'
                     valign: 'middle'
+                    font_size: sp(11)
                     color: 0.7, 0.7, 0.7, 1
                 
+                # Separator
                 Widget:
-            size_hint_y: 0.05
+                    size_hint_y: None
+                    height: dp(5)
                 
                 # Status information row
                 BoxLayout:
                     orientation: 'horizontal'
                     size_hint_y: None
-            height: dp(30)
-            spacing: dp(10)
+                    height: dp(26)
+                    spacing: dp(8)
                     
                     Label:
                         id: playlist_info
@@ -622,7 +652,7 @@
                         text_size: self.size
                         halign: 'center'
                         valign: 'middle'
-                font_size: sp(12)
+                        font_size: sp(11)
                     
                     Label:
                         id: media_count_info
@@ -630,7 +660,7 @@
                         text_size: self.size
                         halign: 'center'
                         valign: 'middle'
-                font_size: sp(12)
+                        font_size: sp(11)
                     
                     Label:
                         id: status_info
@@ -638,17 +668,14 @@
                         text_size: self.size
                         halign: 'center'
                         valign: 'middle'
-                font_size: sp(12)
+                        font_size: sp(11)
         
-        Widget:
-            size_hint_y: 0.05
-        
-        # Action buttons
+        # Action buttons (always visible, outside scroll)
         BoxLayout:
             orientation: 'horizontal'
             size_hint_y: None
-            height: dp(50)
-            spacing: dp(20)
+            height: dp(44)
+            spacing: dp(15)
             
             Button:
                 text: 'Save & Close'

src/video_safety.py

@@ -0,0 +1,184 @@
+"""video_safety.py — make Kivy's video teardown non-blocking.
+
+The bug this fixes
+------------------
+The player froze after ~30-45 minutes of looping, always at a *video* item.
+The trace stopped dead right after `video_loaded` with no `video_eos` and no
+`advance_after_video_eos`.
+
+Cause — a blocking ``join()`` that Kivy performs on the calling thread:
+
+1. At end of stream, ffpyplayer/``VideoFFPy`` fires its ``on_eos`` event.
+2. Kivy's ``Video`` widget binds its own handler **first** (in
+   ``kivy/uix/video.py``: ``self._video.bind(..., on_eos=self._on_eos)``).
+   That handler is::
+
+       def _on_eos(self, *largs):
+           if not self._video or self._video.eos != 'loop':
+               self.state = 'stop'      # <-- fires DURING the on_eos dispatch
+
+3. ``Video.state = 'stop'`` → ``on_state`` → ``VideoFFPy.stop()`` →
+   ``unload()``, which does ``self._thread.join()``
+   (``video_ffpyplayer.py``: ``# TODO: use callback, don't block here``).
+4. That join waits for the ffpyplayer decode thread, whose lifetime is variable
+   (the existing code comments note "0.4s up to 100s+"). When it does not
+   return, the SDL/Kivy main thread never returns either — the window stops
+pumping messages and the whole player appears hung.
+Why it only shows up after a while: our own EOS handler deliberately does not
+set ``state = 'stop'`` (that path is already handled off-thread), so the hang
+depends on Kivy's own handler firing first and on that particular video's
+decode thread being slow to exit. It is a race, so it looks random and only
+appears after many video cycles.
+
+The fix
+-------
+Bound the wait. ffpyplayer sets ``_ffplayer_need_quit = True`` and wakes its
+thread before joining, so the thread *is* asked to exit — we simply stop
+waiting indefinitely for it. ``suppress_kivy_video_blocking_unload()`` patches
+the join on the specific ``VideoFFPy`` thread object to a bounded timeout, so a
+wedged decode thread can no longer take the whole player down. The teardown
+still runs off the main thread (see ``_teardown_video_async`` in ``main.py``),
+so the normal case is unaffected.
+
+This is deliberately narrow: only Kivy's own internal video thread is patched,
+only its ``join`` timeout is bounded, and every failure path leaves Kivy
+untouched.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+
+#: How long a video's decode thread may take to exit before we give up on it.
+#: A healthy ffpyplayer thread exits in well under a second; this allows a lot
+#: of slack while still guaranteeing the UI thread is never parked forever.
+DEFAULT_JOIN_TIMEOUT = 5.0
+
+_patched_threads = 0
+_lock = threading.Lock()
+
+
+def _log(message):
+    try:
+        from kivy.logger import Logger
+
+        Logger.info(f'[VideoSafety] {message}')
+    except Exception:
+        print(f'[VideoSafety] {message}')
+
+
+def suppress_kivy_video_blocking_unload(timeout=DEFAULT_JOIN_TIMEOUT):
+    """Bound the join() Kivy's VideoFFPy.unload() performs on the caller.
+
+    Must be called *before* the video widget is constructed, because the
+    decode thread is created during ``play()``. Safe to call repeatedly.
+
+    Args:
+        timeout: maximum seconds to wait for the decode thread to exit.
+
+    Returns:
+        True when the guard was installed (or already present).
+    """
+    global _patched_threads
+
+    if timeout is None or float(timeout) <= 0:
+        return False
+
+    try:
+        # Importing this module has the side effect of selecting the
+        # ffpyplayer provider; if a different provider is active (or video
+        # support is missing) there is nothing to patch.
+        from kivy.core.video import Video as CoreVideo
+
+        if CoreVideo is None:
+            return False
+    except Exception as exc:
+        _log(f'video provider unavailable, nothing to patch ({exc})')
+        return False
+
+    try:
+        from kivy.core.video import Video
+    except Exception:
+        Video = None
+
+    if Video is None:
+        return False
+
+    # VideoFFPy resolves via the current provider. Import it directly so we
+    # patch the right class even if the provider changes later.
+    try:
+        from kivy.core.video import video_ffpyplayer as _vfp
+    except Exception as exc:
+        _log(f'ffpyplayer provider not active, nothing to patch ({exc})')
+        return False
+
+    provider = getattr(_vfp, 'VideoFFPy', None)
+    if provider is None:
+        return False
+
+    with _lock:
+        if getattr(provider, '_kiwy_bounded_join', False):
+            return True
+
+        original_play = provider.play
+        if getattr(provider, '_kiwy_original_play', None) is None:
+            provider._kiwy_original_play = original_play
+
+        def play(self, *args, **kwargs):
+            result = provider._kiwy_original_play(self, *args, **kwargs)
+            _bound_thread_join(self, timeout)
+            return result
+
+        provider.play = play
+        provider._kiwy_bounded_join = True
+        _patched_threads += 1
+
+    _log(f'Kivy video unload join() bounded to {float(timeout):.1f}s')
+    return True
+
+
+def _bound_thread_join(provider_instance, timeout):
+    """Replace the provider's internal thread join with a bounded one.
+
+    ffpyplayer has already been told to quit (``_ffplayer_need_quit = True``)
+    and its thread woken before ``unload()`` joins, so bounding the wait does
+    not leak work — it only stops an unresponsive decode thread from freezing
+    the whole application.
+    """
+    thread = getattr(provider_instance, '_thread', None)
+    if thread is None:
+        return
+    if getattr(thread, '_kiwy_bounded_join', False):
+        return
+
+    try:
+        real_join = thread.join
+    except Exception:
+        return
+
+    def bounded_join(join_timeout=None):
+        """Join with a hard upper bound; never block the caller forever."""
+        limit = float(timeout if join_timeout is None else min(join_timeout, timeout))
+        started = time.monotonic()
+        try:
+            real_join(timeout=limit)
+        except TypeError:
+            # Some Python builds dislike an explicit keyword here.
+            try:
+                real_join(limit)
+            except Exception:
+                pass
+        except Exception:
+            pass
+        if thread.is_alive():
+            _log(
+                f'video decode thread still alive {time.monotonic() - started:.1f}s '
+                'after being asked to quit - continuing without it'
+            )
+
+    try:
+        thread.join = bounded_join
+        thread._kiwy_bounded_join = True
+    except Exception as exc:
+        _log(f'could not bound video thread join ({exc})')

start.sh

@@ -242,9 +242,16 @@ while true; do
         source "$SCRIPT_DIR/.venv/bin/activate"
     fi
 
-    # Start the player
-    cd "$SCRIPT_DIR/src"
-    python3 main.py &
+    # Start the player.
+    #
+    # NOTE: the entry point is linux/run_linux.py, NOT src/main.py. Running
+    # main.py directly skips the Raspberry Pi platform patches (Wayland session
+    # environment, display keep-awake, Chromium kiosk adapter), which is why
+    # the player used to blank after 10 minutes and fail to show web links.
+    # Run from the project root so the data directory is the repo root and the
+    # relative config/media/playlists paths resolve as the app expects.
+    cd "$SCRIPT_DIR"
+    python3 linux/run_linux.py &
     PLAYER_PID=$!
     
     log_message "Player PID: $PLAYER_PID"

stop_player.sh

@@ -15,15 +15,17 @@ echo "Stopping watchdog..."
 pkill -f "bash.*start.sh"
 
 # Kill player
+# NOTE: match the linux/run_linux.py entry point, not "python3 main.py" — the
+# player is started as `python3 linux/run_linux.py` from the project root.
 echo "Stopping player..."
-pkill -f "python3 main.py"
+pkill -f "run_linux.py"
 
 # Give processes time to exit gracefully
 sleep 2
 
 # Force kill if still running
 pkill -9 -f "bash.*start.sh" 2>/dev/null
-pkill -9 -f "python3 main.py" 2>/dev/null
+pkill -9 -f "run_linux.py" 2>/dev/null
 
 # Clean up heartbeat and stop flag files
 rm -f "$SCRIPT_DIR/.player_heartbeat"

test_edited_media_upload.py

@@ -1,165 +0,0 @@
-#!/usr/bin/env python3
-"""
-Test script to diagnose edited media upload issues
-Run this to test if the server endpoint exists and works correctly
-"""
-
-import json
-import os
-import sys
-import requests
-from pathlib import Path
-
-# Add src to path
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'src'))
-
-def test_upload():
-    """Test the edited media upload functionality"""
-    
-    print("\n" + "="*60)
-    print("EDITED MEDIA UPLOAD DIAGNOSTICS")
-    print("="*60)
-    
-    # Get authentication
-    try:
-        from get_playlists_v2 import get_auth_instance
-        auth = get_auth_instance()
-        
-        if not auth or not auth.is_authenticated():
-            print("❌ ERROR: Not authenticated!")
-            print("   Please ensure player_auth.json exists and is valid")
-            return False
-        
-        server_url = auth.auth_data.get('server_url')
-        auth_code = auth.auth_data.get('auth_code')
-        
-        print(f"\n✓ Authentication successful")
-        print(f"  Server URL: {server_url}")
-        print(f"  Auth Code: {auth_code[:20]}..." if auth_code else "  Auth Code: None")
-        
-    except Exception as e:
-        print(f"❌ Authentication error: {e}")
-        return False
-    
-    # Check for edited media files
-    edited_media_dir = os.path.join(os.path.dirname(__file__), 'media', 'edited_media')
-    edited_files = list(Path(edited_media_dir).glob('*_e_v*.jpg'))
-    metadata_files = list(Path(edited_media_dir).glob('*_metadata.json'))
-    
-    print(f"\n✓ Edited Media Directory: {edited_media_dir}")
-    print(f"  Edited images: {len(edited_files)}")
-    print(f"  Metadata files: {len(metadata_files)}")
-    
-    if not edited_files:
-        print("\n⚠️  No edited images found!")
-        print("   Create an edit first, then run this test")
-        return False
-    
-    # Test with the first edited image
-    image_path = str(edited_files[0])
-    metadata_file = str(edited_files[0]).replace('.jpg', '_metadata.json')
-    
-    if not os.path.exists(metadata_file):
-        print(f"\n❌ Metadata file not found: {metadata_file}")
-        return False
-    
-    print(f"\nTesting upload with:")
-    print(f"  Image: {os.path.basename(image_path)}")
-    print(f"  Size: {os.path.getsize(image_path):,} bytes")
-    print(f"  Metadata: {os.path.basename(metadata_file)}")
-    
-    # Load and display metadata
-    with open(metadata_file, 'r') as f:
-        metadata = json.load(f)
-    
-    print(f"\nMetadata content:")
-    for key, value in metadata.items():
-        print(f"  {key}: {value}")
-    
-    # Add original_filename if not present
-    metadata['original_filename'] = os.path.basename(metadata['original_path'])
-    
-    # Prepare upload request
-    upload_url = f"{server_url}/api/player-edit-media"
-    headers = {'Authorization': f'Bearer {auth_code}'}
-    
-    print(f"\n{'='*60}")
-    print("TESTING UPLOAD...")
-    print(f"{'='*60}")
-    print(f"Endpoint: {upload_url}")
-    print(f"Headers: Authorization: Bearer {auth_code[:20]}...")
-    
-    try:
-        with open(image_path, 'rb') as img_file:
-            files = {
-                'image_file': (metadata['original_filename'], img_file, 'image/jpeg')
-            }
-            data = {
-                'metadata': json.dumps(metadata),
-                'original_file': metadata['original_filename']
-            }
-            
-            print(f"\nSending request (30s timeout, SSL verify=False)...")
-            response = requests.post(
-                upload_url,
-                headers=headers,
-                files=files,
-                data=data,
-                timeout=30,
-                verify=False
-            )
-        
-        print(f"\n✓ Response received!")
-        print(f"  Status Code: {response.status_code}")
-        print(f"  Headers: {dict(response.headers)}")
-        
-        if response.status_code == 200:
-            print(f"\n✅ SUCCESS! Server accepted the upload")
-            print(f"  Response: {response.json()}")
-            return True
-        elif response.status_code == 404:
-            print(f"\n❌ ENDPOINT NOT FOUND (404)")
-            print(f"  The server does NOT have /api/player-edit-media endpoint")
-            print(f"  Server may need to implement this feature")
-        elif response.status_code == 401:
-            print(f"\n❌ AUTHENTICATION FAILED (401)")
-            print(f"  Check your auth_code in player_auth.json")
-        else:
-            print(f"\n❌ REQUEST FAILED (Status: {response.status_code})")
-            print(f"  Response: {response.text}")
-        
-        return False
-        
-    except requests.exceptions.ConnectionError as e:
-        print(f"\n❌ CONNECTION ERROR")
-        print(f"  Cannot reach server at {server_url}")
-        print(f"  Error: {e}")
-        return False
-    except requests.exceptions.Timeout as e:
-        print(f"\n❌ TIMEOUT")
-        print(f"  Server did not respond within 30 seconds")
-        print(f"  Error: {e}")
-        return False
-    except requests.exceptions.SSLError as e:
-        print(f"\n❌ SSL ERROR")
-        print(f"  Error: {e}")
-        print(f"  Tip: Try adding verify=False to requests")
-        return False
-    except Exception as e:
-        print(f"\n❌ UNEXPECTED ERROR")
-        print(f"  Error: {e}")
-        import traceback
-        traceback.print_exc()
-        return False
-
-if __name__ == '__main__':
-    success = test_upload()
-    
-    print(f"\n{'='*60}")
-    if success:
-        print("✅ UPLOAD TEST PASSED - Server accepts edited media!")
-    else:
-        print("❌ UPLOAD TEST FAILED - See details above")
-    print(f"{'='*60}\n")
-    
-    sys.exit(0 if success else 1)

working_files/CARD_READER_AUTHENTICATION.md

@@ -1,182 +0,0 @@
-# USB Card Reader Authentication
-
-This document describes the USB card reader authentication feature for the Kiwy Signage Player.
-
-## Overview
-
-The player now supports user authentication via USB card readers when accessing the edit/drawing interface. When a user clicks the edit button (pencil icon), they must swipe their card to authenticate before being allowed to edit the image.
-
-## How It Works
-
-1. **Edit Button Click**: User clicks the pencil icon to edit the current image
-2. **Validation Checks**:
-   - Verify current media is an image (not video)
-   - Check if editing is allowed for this media (`edit_on_player` permission from server)
-3. **Card Reader Prompt**:
-   - Display "Please swipe your card..." message
-   - Wait for card swipe (5 second timeout)
-   - Read card data from USB card reader
-   - Store the card data (no validation required)
-4. **Open Edit Interface**: Edit interface opens with card data stored
-5. **Save & Upload**: When user saves the edited image:
-   - Card data is included in the metadata JSON
-   - Both image and metadata (with card data) are uploaded to server
-   - Server receives `user_card_data` field for tracking who edited the image
-
-## Card Reader Setup
-
-### Hardware Requirements
-- USB card reader (HID/keyboard emulation type)
-- Compatible cards (magnetic stripe or RFID depending on reader)
-
-### Software Requirements
-The player requires the `evdev` Python library to interface with USB input devices:
-
-```bash
-# Install via apt (recommended for Raspberry Pi)
-sudo apt-get install python3-evdev
-
-# Or via pip
-pip3 install evdev
-```
-
-### Fallback Mode
-If `evdev` is not available, the player will:
-- Log a warning message
-- Use a default card value (`DEFAULT_USER_12345`) for testing
-- This allows development and testing without hardware
-
-## Card Data Storage
-
-The card data is captured as a raw string and stored without validation or mapping:
-
-- **No preprocessing**: Card data is stored exactly as received from the reader
-- **Format**: Whatever the card reader sends (typically numeric or alphanumeric)
-- **Sent to server**: Raw card data is included in the `user_card_data` field of the metadata JSON
-- **Server-side processing**: The server can validate, map, or process the card data as needed
-
-### Metadata JSON Format
-When an image is saved, the metadata includes:
-```json
-{
-  "time_of_modification": "2025-12-08T10:30:00",
-  "original_name": "image.jpg",
-  "new_name": "image_e_v1.jpg",
-  "original_path": "/path/to/image.jpg",
-  "version": 1,
-  "user_card_data": "123456789"
-}
-```
-
-If no card is swiped (timeout), `user_card_data` will be `null`.
-
-## Testing the Card Reader
-
-A test utility is provided to verify card reader functionality:
-
-```bash
-cd /home/pi/Desktop/Kiwy-Signage/working_files
-python3 test_card_reader.py
-```
-
-The test tool will:
-1. List all available input devices
-2. Auto-detect the card reader (or let you select manually)
-3. Listen for card swipes and display the data received
-4. Show how the data will be processed
-
-### Test Output Example
-```
-✓ Card data received: '123456789'
-  Length: 9 characters
-  Processed ID: card_123456789
-```
-
-## Implementation Details
-
-### Main Components
-
-1. **CardReader Class** (`main.py`)
-   - Handles USB device detection
-   - Reads input events from card reader
-   - Provides async callback interface
-   - Includes timeout handling (5 seconds)
-
-2. **Card Read Flow** (`show_edit_interface()` method)
-   - Validates media type and permissions
-   - Initiates card read
-   - Stores raw card data
-   - Opens edit popup
-
-3. **Metadata Creation** (`_save_metadata()` method)
-   - Includes card data in metadata JSON
-   - No processing or validation of card data
-   - Sent to server as-is
-
-### Card Data Format
-
-Card readers typically send data as keyboard input:
-- Each character is sent as a key press event
-- Data ends with an ENTER key press
-- Reader format: `[CARD_DATA][ENTER]`
-
-The CardReader class:
-- Captures key press events
-- Builds the card data string character by character
-- Completes reading when ENTER is detected
-- Returns the complete card data to the callback
-
-### Security Considerations
-
-1. **Server-Side Validation**: Card validation should be implemented on the server
-2. **Timeout**: 5-second timeout prevents infinite waiting for card swipe
-3. **Logging**: All card reads are logged with the raw card data
-4. **Permissions**: Edit permission must be enabled on the server (`edit_on_player`)
-5. **Raw Data**: Card data is sent as-is; server is responsible for validation and authorization
-
-## Troubleshooting
-
-### Card Reader Not Detected
-- Check USB connection
-- Run `ls /dev/input/` to see available devices
-- Run the test script to verify detection
-- Check `evdev` is installed: `python3 -c "import evdev"`
-
-### Card Swipes Not Recognized
-- Verify card reader sends keyboard events
-- Test with the `test_card_reader.py` utility
-- Check card format is compatible with reader
-- Ensure card is swiped smoothly at proper speed
-
-### Card Data Not Captured
-- Check card data format in logs
-- Enable debug logging to see raw card data
-- Test in fallback mode (without evdev) to isolate hardware issues
-- Verify card swipe completes within 5-second timeout
-
-### Permission Denied Errors
-- User may need to be in the `input` group:
-  ```bash
-  sudo usermod -a -G input $USER
-  ```
-- Reboot after adding user to group
-
-## Future Enhancements
-
-Potential improvements for the card reader system:
-
-1. **Server Validation**: Server validates cards against database and returns authorization
-2. **Card Enrollment**: Server-side UI for registering new cards
-3. **Multiple Card Types**: Support for different card formats (barcode, RFID, magnetic)
-4. **Client-side Validation**: Add optional local card validation before opening edit
-5. **Audit Trail**: Server tracks all card usage with timestamps
-6. **RFID Support**: Test and optimize for RFID readers
-7. **Barcode Scanners**: Support USB barcode scanners as alternative
-8. **Retry Logic**: Allow re-swipe if card read fails
-
-## Related Files
-
-- `/src/main.py` - Main implementation (CardReader class, authentication flow)
-- `/src/edit_drowing.py` - Drawing/editing interface (uses authenticated user)
-- `/working_files/test_card_reader.py` - Card reader test utility
-- `/requirements.txt` - Dependencies (includes evdev)

working_files/CARD_READER_FIX.md

@@ -1,170 +0,0 @@
-# Card Reader Fix - Multi-USB Device Support
-
-## Problem Description
-
-When a USB touchscreen was connected to the Raspberry Pi, the card reader authentication was not working. The system reported "no authentication was received" even though the card reader was physically connected on a different USB port.
-
-### Root Cause
-
-The original `find_card_reader()` function used overly broad matching criteria:
-1. It would select the **first** device with "keyboard" in its name
-2. USB touchscreens often register as HID keyboard devices (for touch input)
-3. The touchscreen would be detected first, blocking the actual card reader
-4. No exclusion logic existed to filter out touch devices
-
-## Solution
-
-The fix implements a **priority-based device selection** with **exclusion filters**:
-
-### 1. Device Exclusion List
-Devices containing these keywords are now skipped:
-- `touch`, `touchscreen`
-- `mouse`, `mice`
-- `trackpad`, `touchpad`
-- `pen`, `stylus`
-- `video`, `button`, `lid`
-
-### 2. Three-Priority Device Search
-
-**Priority 1: Explicit Card Readers**
-- Devices with "card", "reader", "rfid", or "hid" in their name
-- Must have keyboard capabilities (EV_KEY)
-- Excludes any device matching exclusion keywords
-
-**Priority 2: USB Keyboards**
-- Devices with both "usb" AND "keyboard" in their name
-- Card readers typically appear as "USB Keyboard" or similar
-- Excludes touch devices and other non-card peripherals
-
-**Priority 3: Fallback to Any Keyboard**
-- Any keyboard device not in the exclusion list
-- Used only if no card reader or USB keyboard is found
-
-### 3. Enhanced Logging
-
-The system now logs:
-- All detected input devices at startup
-- Which devices are being skipped and why
-- Which device is ultimately selected as the card reader
-
-## Testing
-
-### Using the Test Script
-
-Run the enhanced test script to identify your card reader:
-
-```bash
-cd /home/pi/Desktop/Kiwy-Signage/working_files
-python3 test_card_reader.py
-```
-
-The script will:
-1. List all input devices with helpful indicators:
-   - `** LIKELY CARD READER **` - devices with "card" or "reader" in name
-   - `(Excluded: ...)` - devices that will be skipped
-   - `(USB Keyboard - could be card reader)` - potential card readers
-
-2. Auto-detect the card reader using the same logic as the main app
-
-3. Allow manual selection by device number if auto-detection is wrong
-
-### Example Output
-
-```
-=== Available Input Devices ===
-
-[0] /dev/input/event0
-    Name: USB Touchscreen Controller
-    Phys: usb-0000:01:00.0-1.1/input0
-    Type: Keyboard/HID Input Device
-    (Excluded: appears to be touch/mouse/other non-card device)
-
-[1] /dev/input/event1
-    Name: HID 08ff:0009
-    Phys: usb-0000:01:00.0-1.2/input0
-    Type: Keyboard/HID Input Device
-    ** LIKELY CARD READER **
-
-[2] /dev/input/event2
-    Name: Logitech USB Keyboard
-    Phys: usb-0000:01:00.0-1.3/input0
-    Type: Keyboard/HID Input Device
-    (USB Keyboard - could be card reader)
-```
-
-### Verifying the Fix
-
-1. **Check Logs**: When the main app starts, check the logs for device detection:
-   ```bash
-   tail -f /path/to/logfile
-   ```
-   
-   Look for messages like:
-   ```
-   CardReader: Scanning input devices...
-   CardReader: Skipping excluded device: USB Touchscreen Controller
-   CardReader: Found card reader: HID 08ff:0009 at /dev/input/event1
-   ```
-
-2. **Test Card Swipe**: 
-   - Start the signage player
-   - Click the edit button (pencil icon)
-   - Swipe a card
-   - Should successfully authenticate
-
-3. **Multiple USB Devices**: Test with various USB configurations:
-   - Touchscreen + card reader
-   - Mouse + keyboard + card reader
-   - Multiple USB hubs
-
-## Configuration
-
-### If Auto-Detection Fails
-
-If the automatic detection still selects the wrong device, you can:
-
-1. **Check device names**: Run `test_card_reader.py` to see all devices
-2. **Identify your card reader**: Note the exact name of your card reader
-3. **Add custom exclusions**: If needed, add more keywords to the exclusion list
-4. **Manual override**: Modify the priority logic to match your specific hardware
-
-### Permissions
-
-Ensure the user running the app has permission to access input devices:
-
-```bash
-# Add user to input group
-sudo usermod -a -G input $USER
-
-# Logout and login again for changes to take effect
-```
-
-## Files Modified
-
-1. **src/main.py**
-   - Updated `CardReader.find_card_reader()` method
-   - Added exclusion keyword list
-   - Implemented priority-based search
-   - Enhanced logging
-
-2. **working_files/test_card_reader.py**
-   - Updated `list_input_devices()` to show device classifications
-   - Updated `test_card_reader()` to use same logic as main app
-   - Added visual indicators for device types
-
-## Compatibility
-
-This fix is backward compatible:
-- Works with single-device setups (no touchscreen)
-- Works with multiple USB devices
-- Fallback behavior unchanged for systems without card readers
-- No changes to card data format or server communication
-
-## Future Enhancements
-
-Potential improvements for specific use cases:
-
-1. **Configuration file**: Allow specifying device path or name pattern
-2. **Device caching**: Remember the working device path to avoid re-scanning
-3. **Hot-plug support**: Detect when card reader is plugged in after app starts
-4. **Multi-reader support**: Support for multiple card readers simultaneously

working_files/DEBUGGING_MEDIA_SKIPS.md

@@ -1,211 +0,0 @@
-# Debugging Media File Skips - Guide
-
-## Summary
-Your playlist has been analyzed and all 3 media files are present and valid:
-- ✅ music.jpg (36,481 bytes) - IMAGE - 15s
-- ✅ 130414-746934884.mp4 (6,474,921 bytes) - VIDEO - 23s  
-- ✅ IMG_0386.jpeg (592,162 bytes) - IMAGE - 15s
-
-## Enhanced Logging Added
-The application has been updated with detailed logging to track:
-- When each media file starts playing
-- File path validation
-- File size and existence checks
-- Media type detection
-- Widget creation steps
-- Scheduling of next media
-- Any errors or skips
-
-## How to See Detailed Logs
-
-### Method 1: Run with log output
-```bash
-cd /home/pi/Desktop/Kiwy-Signage
-source .venv/bin/activate
-cd src
-python3 main.py 2>&1 | tee playback.log
-```
-
-### Method 2: Check Kivy logs location
-Kivy logs are typically stored in:
-- Linux: `~/.kivy/logs/`
-- Check with: `ls -lth ~/.kivy/logs/ | head`
-
-## Common Reasons Media Files Get Skipped
-
-### 1. **File Not Found** 
-**Symptom**: Log shows "❌ Media file not found"
-**Cause**: File doesn't exist at expected path
-**Solution**: Run diagnostic tool
-```bash
-python3 diagnose_playlist.py
-```
-
-### 2. **Unsupported File Type**
-**Symptom**: Log shows "❌ Unsupported media type"
-**Supported formats**:
-- Videos: .mp4, .avi, .mkv, .mov, .webm
-- Images: .jpg, .jpeg, .png, .bmp, .gif
-**Solution**: Convert files or check extension
-
-### 3. **Video Codec Issues**
-**Symptom**: Video file exists but doesn't play
-**Cause**: Video codec not supported by ffpyplayer
-**Check**: Look for error in logs about codec
-**Solution**: Re-encode video with H.264 codec:
-```bash
-ffmpeg -i input.mp4 -c:v libx264 -preset fast -crf 23 output.mp4
-```
-
-### 4. **Corrupted Media Files**
-**Symptom**: File exists but throws error when loading
-**Check**: Try playing file with external player
-```bash
-# For images
-feh media/music.jpg
-
-# For videos  
-vlc media/130414-746934884.mp4
-# or
-ffplay media/130414-746934884.mp4
-```
-
-### 5. **Memory/Performance Issues**
-**Symptom**: First few files play, then skipping increases
-**Cause**: Memory leak or performance degradation
-**Check**: Look for "consecutive_errors" in logs
-**Solution**: 
-- Reduce resolution setting in settings popup
-- Optimize video files (lower bitrate/resolution)
-
-### 6. **Timing Issues**
-**Symptom**: Files play too fast or skip immediately
-**Cause**: Duration set too low or scheduler issues
-**Check**: Verify durations in playlist.json
-**Current durations**: 15s (images), 23s (video)
-
-### 7. **Permission Issues**
-**Symptom**: "Permission denied" in logs
-**Check**: File permissions
-```bash
-ls -la media/
-```
-**Solution**: Fix permissions
-```bash
-chmod 644 media/*
-```
-
-## What to Look For in Logs
-
-### Successful Playback Pattern:
-```
-SignagePlayer: ===== Playing item 1/3 =====
-SignagePlayer: File: music.jpg
-SignagePlayer: Duration: 15s
-SignagePlayer: Full path: /path/to/media/music.jpg
-SignagePlayer: ✓ File exists (size: 36,481 bytes)
-SignagePlayer: Extension: .jpg
-SignagePlayer: Media type: IMAGE
-SignagePlayer: Creating AsyncImage widget...
-SignagePlayer: Adding image widget to content area...
-SignagePlayer: Scheduled next media in 15s
-SignagePlayer: ✓ Image displayed successfully
-SignagePlayer: ✓ Media started successfully (consecutive_errors reset to 0)
-```
-
-### Skip Pattern (File Not Found):
-```
-SignagePlayer: ===== Playing item 2/3 =====
-SignagePlayer: File: missing.mp4
-SignagePlayer: Full path: /path/to/media/missing.mp4
-SignagePlayer: ❌ Media file not found: /path/to/media/missing.mp4
-SignagePlayer: Skipping to next media...
-SignagePlayer: Transitioning to next media (was index 1)
-```
-
-### Video Loading Error:
-```
-SignagePlayer: Loading video file.mp4 for 23s
-SignagePlayer: Video provider: ffpyplayer
-[ERROR  ] [Video       ] Error reading video
-[ERROR  ] SignagePlayer: Error playing video: ...
-```
-
-## Testing Tools Provided
-
-### 1. Diagnostic Tool
-```bash
-python3 diagnose_playlist.py
-```
-Checks:
-- Playlist file exists and is valid
-- All media files exist
-- File types are supported
-- No case sensitivity issues
-
-### 2. Playback Simulation
-```bash
-python3 test_playback_logging.py
-```
-Simulates the playback sequence without running the GUI
-
-## Monitoring Live Playback
-
-To see live logs while the app is running:
-```bash
-# Terminal 1: Start the app
-./run_player.sh
-
-# Terminal 2: Monitor logs
-tail -f ~/.kivy/logs/kivy_*.txt
-```
-
-## Quick Fixes to Try
-
-### 1. Clear any stuck state
-```bash
-rm -f src/*.pyc
-rm -rf src/__pycache__
-```
-
-### 2. Test with simpler playlist
-Create `playlists/test_playlist_v9.json`:
-```json
-{
-  "playlist": [
-    {
-      "file_name": "music.jpg",
-      "url": "media/music.jpg",
-      "duration": 5
-    }
-  ],
-  "version": 9
-}
-```
-
-### 3. Check video compatibility
-```bash
-# Install ffmpeg tools if not present
-sudo apt-get install ffmpeg
-
-# Check video info
-ffprobe media/130414-746934884.mp4
-```
-
-## Getting Help
-
-When reporting issues, please provide:
-1. Output from `python3 diagnose_playlist.py`
-2. Last 100 lines of Kivy log file
-3. Any error messages from console
-4. What you observe (which files skip? pattern?)
-
-## Next Steps
-
-1. **Run the app** and observe the console output
-2. **Check logs** for error patterns
-3. **Run diagnostic** if files are skipping
-4. **Test individual files** with external players if needed
-5. **Re-encode videos** if codec issues found
-
-The enhanced logging will now tell you exactly why each file is being skipped!

working_files/IMPLEMENTATION_SUMMARY.md

@@ -1,263 +0,0 @@
-# ✅ Kiwy-Signage Authentication Implementation Complete
-
-## What Was Implemented
-
-The Kiwy-Signage player now supports **secure authentication** with DigiServer v2 using the flow:
-
-**hostname → password/quickconnect → get auth_code → use auth_code for API calls**
-
-## Files Created
-
-### 1. **Kiwy-Signage/src/player_auth.py**
-- Complete authentication module
-- Handles authentication, token storage, API calls
-- Methods:
-  - `authenticate()` - Initial authentication with server
-  - `verify_auth()` - Verify saved auth code
-  - `get_playlist()` - Fetch playlist using auth code
-  - `send_heartbeat()` - Send status updates
-  - `send_feedback()` - Send player feedback
-  - `clear_auth()` - Clear saved credentials
-
-### 2. **Kiwy-Signage/src/get_playlists_v2.py**
-- Updated playlist management
-- Uses new authentication system
-- Backward compatible with existing code
-- Functions:
-  - `ensure_authenticated()` - Auto-authenticate if needed
-  - `fetch_server_playlist()` - Get playlist via authenticated API
-  - `send_player_feedback()` - Send feedback with auth
-  - All existing functions updated to use auth
-
-### 3. **Kiwy-Signage/test_authentication.py**
-- Test script to verify authentication
-- Run before updating main.py
-- Tests:
-  - Server connectivity
-  - Authentication flow
-  - Playlist fetch
-  - Heartbeat sending
-
-### 4. **Kiwy-Signage/MIGRATION_GUIDE.md**
-- Complete migration instructions
-- Troubleshooting guide
-- Configuration examples
-- Rollback procedures
-
-### 5. **digiserver-v2/player_auth_module.py**
-- Standalone authentication module
-- Can be used in any Python project
-- Same functionality as Kiwy-Signage version
-
-### 6. **digiserver-v2/PLAYER_AUTH.md**
-- Complete API documentation
-- Authentication endpoint specs
-- Configuration file formats
-- Security considerations
-
-## Testing Steps
-
-### 1. Test Authentication (Recommended First)
-
-```bash
-cd /home/pi/Desktop/Kiwy-Signage
-python3 test_authentication.py
-```
-
-**Expected output:**
-```
-✅ Server is healthy (version: 2.0.0)
-🔐 Authenticating with server...
-   ✅ Authentication successful!
-   Player: Demo Player
-📋 Testing playlist fetch...
-   ✅ Playlist received!
-💓 Testing heartbeat...
-   ✅ Heartbeat sent successfully
-✅ All tests passed! Player is ready to use.
-```
-
-### 2. Update Main Player App
-
-In `Kiwy-Signage/src/main.py`, change:
-
-```python
-# OLD:
-from get_playlists import update_playlist_if_needed, ...
-
-# NEW:
-from get_playlists_v2 import update_playlist_if_needed, ...
-```
-
-### 3. Run Player
-
-```bash
-cd /home/pi/Desktop/Kiwy-Signage/src
-python3 main.py
-```
-
-## Configuration
-
-### No Changes Needed!
-
-Your existing `app_config.txt` works as-is:
-
-```json
-{
-  "server_ip": "192.168.1.100",
-  "port": "5000",
-  "screen_name": "player-001",
-  "quickconnect_key": "QUICK123",
-  ...
-}
-```
-
-### Authentication Storage
-
-Auto-created at `src/player_auth.json`:
-
-```json
-{
-  "hostname": "player-001",
-  "auth_code": "rrX4JtM99e4e6ni0VCsuIstjTVQQqILXeRmGu_Ek2Ks",
-  "player_id": 1,
-  "player_name": "Demo Player",
-  "group_id": 5,
-  "orientation": "Landscape",
-  "authenticated": true,
-  "server_url": "http://192.168.1.100:5000"
-}
-```
-
-## DigiServer v2 Setup
-
-### 1. Create Player
-
-Via Web UI (http://your-server:5000):
-1. Login as admin
-2. Go to Players → Add Player
-3. Fill in:
-   - **Name**: Display name
-   - **Hostname**: player-001 (must match `screen_name` in config)
-   - **Password**: (optional, use quickconnect instead)
-   - **Quick Connect Code**: QUICK123 (must match `quickconnect_key`)
-   - **Orientation**: Landscape/Portrait
-
-### 2. Test API Manually
-
-```bash
-# Test authentication
-curl -X POST http://your-server:5000/api/auth/player \
-  -H "Content-Type: application/json" \
-  -d '{
-    "hostname": "player-001",
-    "quickconnect_code": "QUICK123"
-  }'
-
-# Expected response:
-{
-  "success": true,
-  "player_id": 1,
-  "player_name": "Demo Player",
-  "auth_code": "rrX4JtM99e4e6ni0VCsuIstjTVQQqILXeRmGu_Ek2Ks",
-  ...
-}
-```
-
-## Security Features
-
-✅ **Auth Code Storage**: Saved locally, not transmitted after initial auth
-✅ **Bcrypt Hashing**: Passwords and quickconnect codes hashed in database
-✅ **Token-Based**: Auth codes are 32-byte URL-safe tokens
-✅ **Rate Limiting**: Authentication endpoint limited to 10 requests/minute
-✅ **Session Management**: Server tracks player sessions and status
-
-## Advantages Over Old System
-
-### Old System (v1)
-```
-Player → [hostname + quickconnect on EVERY request] → Server
-         ↓
-         Bcrypt verification on every API call (slow)
-```
-
-### New System (v2)
-```
-Player → [hostname + quickconnect ONCE] → Server
-         ↓
-         Returns auth_code
-         ↓
-Player → [auth_code for all subsequent requests] → Server
-         ↓
-         Fast token validation
-```
-
-**Benefits:**
-- 🚀 **10x faster API calls** (no bcrypt on every request)
-- 🔒 **More secure** (credentials only sent once)
-- 📊 **Better tracking** (server knows player sessions)
-- 🔄 **Easier management** (can revoke auth codes)
-
-## Troubleshooting
-
-### Authentication Fails
-
-**Check:**
-1. Player exists in DigiServer v2 with matching hostname
-2. Quickconnect code matches exactly (case-sensitive)
-3. Server is accessible: `curl http://server:5000/api/health`
-
-### Auth Code Expired
-
-**Solution:**
-```bash
-rm /home/pi/Desktop/Kiwy-Signage/src/player_auth.json
-# Restart player - will auto-authenticate
-```
-
-### Old get_playlists.py Issues
-
-**Keep both files:**
-- `get_playlists.py` - Original (for DigiServer v1)
-- `get_playlists_v2.py` - New (for DigiServer v2)
-
-Can switch between them by changing import in `main.py`.
-
-## Next Steps
-
-1. ✅ **Test authentication** with `test_authentication.py`
-2. ✅ **Update main.py** to use `get_playlists_v2`
-3. ✅ **Run player** and verify playlist loading
-4. ✅ **Monitor logs** for first 24 hours
-5. ✅ **Update other players** one at a time
-
-## Files Summary
-
-```
-Kiwy-Signage/
-├── src/
-│   ├── player_auth.py          # ✨ NEW: Authentication module
-│   ├── get_playlists_v2.py     # ✨ NEW: Updated playlist fetcher
-│   ├── get_playlists.py        # OLD: Keep for v1 compatibility
-│   ├── main.py                 # Update import to use v2
-│   └── player_auth.json        # ✨ AUTO-CREATED: Auth storage
-├── test_authentication.py      # ✨ NEW: Test script
-├── MIGRATION_GUIDE.md          # ✨ NEW: Migration docs
-└── resources/
-    └── app_config.txt          # Existing config (no changes needed)
-
-digiserver-v2/
-├── app/
-│   ├── models/player.py        # ✨ UPDATED: Added auth methods
-│   └── blueprints/api.py       # ✨ UPDATED: Added auth endpoints
-├── player_auth_module.py       # ✨ NEW: Standalone module
-├── player_config_template.ini  # ✨ NEW: Config template
-├── PLAYER_AUTH.md              # ✨ NEW: API documentation
-└── reinit_db.sh                # ✨ NEW: Database recreation script
-```
-
----
-
-## 🎉 Implementation Complete!
-
-The Kiwy-Signage player authentication system is now compatible with DigiServer v2 using secure token-based authentication. Test with `test_authentication.py` before deploying to production.

working_files/INVESTIGATION_RESULTS.md

@@ -1,182 +0,0 @@
-# Investigation Results: Media File Skipping
-
-## Diagnostic Summary
-✅ **All 3 media files are present and valid:**
-- music.jpg (36,481 bytes) - IMAGE
-- 130414-746934884.mp4 (6,474,921 bytes) - VIDEO (H.264, 1920x1080, compatible)
-- IMG_0386.jpeg (592,162 bytes) - IMAGE
-
-✅ **No file system issues found:**
-- All files exist
-- Correct permissions
-- No case sensitivity problems
-- Supported file types
-
-✅ **Video codec is compatible:**
-- H.264 codec (fully supported by ffpyplayer)
-- 1920x1080 @ 29.97fps
-- Reasonable bitrate (2.3 Mbps)
-
-## Potential Root Causes Identified
-
-### 1. **Video Widget Not Properly Stopping** (Most Likely)
-When transitioning from video to the next media, the video widget may not be properly stopped before removal. This could cause:
-- The video to continue playing in background
-- Race conditions with scheduling
-- Next media appearing to "skip"
-
-**Location**: `play_current_media()` line 417-420
-```python
-if self.current_widget:
-    self.ids.content_area.remove_widget(self.current_widget)
-    self.current_widget = None
-```
-
-**Fix**: Stop video before removing widget
-
-### 2. **Multiple Scheduled Events**
-The `Clock.schedule_once(self.next_media, duration)` could be called multiple times if widget loading triggers multiple events.
-
-**Location**: Lines 510, 548
-
-**Fix**: Add `Clock.unschedule()` before scheduling
-
-### 3. **Video Loading Callback Issues**
-The video `loaded` callback might not fire or might fire multiple times, causing state confusion.
-
-**Location**: `_on_video_loaded()` line 516
-
-### 4. **Pause State Not Properly Checked**
-If the player gets paused/unpaused during media transition, scheduling could get confused.
-
-**Location**: `next_media()` line 551
-
-## What Enhanced Logging Will Show
-
-With the new logging, you'll see patterns like:
-
-### If Videos Are Being Skipped:
-```
-===== Playing item 2/3 =====
-File: 130414-746934884.mp4
-Extension: .mp4
-Media type: VIDEO
-Loading video...
-Creating Video widget...
-[SHORT PAUSE OR ERROR]
-Transitioning to next media (was index 1)
-===== Playing item 3/3 =====
-```
-
-### If Duration Is Too Short:
-```
-Creating Video widget...
-Scheduled next media in 23s
-[Only 1-2 seconds pass]
-Transitioning to next media
-```
-
-## Recommended Fixes
-
-I've added comprehensive logging. Here are additional fixes to try:
-
-### Fix 1: Properly Stop Video Widget Before Removal
-Add this to `play_current_media()` before removing widget:
-
-```python
-# Remove previous media widget
-if self.current_widget:
-    # Stop video if it's playing
-    if isinstance(self.current_widget, Video):
-        self.current_widget.state = 'stop'
-        self.current_widget.unload()
-    self.ids.content_area.remove_widget(self.current_widget)
-    self.current_widget = None
-```
-
-### Fix 2: Ensure Scheduled Events Don't Overlap
-Modify scheduling in both `play_video()` and `play_image()`:
-
-```python
-# Unschedule any pending transitions before scheduling new one
-Clock.unschedule(self.next_media)
-Clock.schedule_once(self.next_media, duration)
-```
-
-### Fix 3: Add Video State Monitoring
-Track when video actually starts playing vs when widget is created.
-
-## How to Test
-
-### 1. Run with Enhanced Logging
-```bash
-cd /home/pi/Desktop/Kiwy-Signage
-source .venv/bin/activate
-cd src
-python3 main.py 2>&1 | tee ../playback_debug.log
-```
-
-Watch the console output. You should see:
-- Each media file being loaded
-- Timing information
-- Any errors or skips
-
-### 2. Check Timing
-If media skips, check the log for timing:
-- Does "Scheduled next media in Xs" appear?
-- How long until "Transitioning to next media" appears?
-- Is it immediate (< 1 second) = scheduling bug
-- Is it after full duration = normal operation
-
-### 3. Look for Error Patterns
-Search the log for:
-```bash
-grep "❌" playback_debug.log
-grep "Error" playback_debug.log
-grep "consecutive_errors" playback_debug.log
-```
-
-## Quick Test Scenario
-
-Create a test with just one file to isolate the issue:
-
-```json
-{
-  "playlist": [
-    {
-      "file_name": "music.jpg",
-      "url": "media/music.jpg",
-      "duration": 10
-    }
-  ],
-  "version": 99
-}
-```
-
-If this single image repeats correctly every 10s, the issue is with video playback or transitions.
-
-## What to Report
-
-When you run the app, please capture:
-
-1. **Console output** - especially the pattern around skipped files
-2. **Which files skip?** - Is it always videos? Always after videos?
-3. **Timing** - Do files play for full duration before skipping?
-4. **Pattern** - First loop OK then skips? Always skips certain file?
-
-## Tools Created
-
-1. **diagnose_playlist.py** - Check file system issues
-2. **test_playback_logging.py** - Simulate playback logic
-3. **check_video_codecs.py** - Verify video compatibility
-4. **Enhanced main.py** - Detailed logging throughout
-
-## Next Actions
-
-1. ✅ Run `diagnose_playlist.py` - **PASSED**
-2. ✅ Run `check_video_codecs.py` - **PASSED** 
-3. ⏳ Run app with logging and observe pattern
-4. ⏳ Apply video widget fixes if needed
-5. ⏳ Report findings for further diagnosis
-
-The enhanced logging will pinpoint exactly where and why files are being skipped!

working_files/MIGRATION_GUIDE.md

@@ -1,276 +0,0 @@
-# Kiwy-Signage Player Migration Guide
-## Updating to DigiServer v2 Authentication
-
-This guide explains how to update your Kiwy-Signage player to use the new secure authentication system with DigiServer v2.
-
-## What Changed?
-
-### Old System (v1)
-- Direct API calls with hostname + quickconnect code on every request
-- No persistent authentication
-- Credentials sent with every API call
-
-### New System (v2)
-- **Step 1**: Authenticate once with hostname + password/quickconnect
-- **Step 2**: Receive and save auth_code
-- **Step 3**: Use auth_code for all subsequent API calls
-- **Benefits**: More secure, faster, supports session management
-
-## Migration Steps
-
-### 1. Copy New Files
-
-Copy the authentication modules to your Kiwy-Signage project:
-
-```bash
-cd /home/pi/Desktop/Kiwy-Signage/src/
-
-# New files are already created:
-# - player_auth.py (authentication module)
-# - get_playlists_v2.py (updated playlist fetcher)
-```
-
-### 2. Update main.py Imports
-
-In `main.py`, replace the old import:
-
-```python
-# OLD:
-from get_playlists import (
-    update_playlist_if_needed,
-    send_playing_status_feedback,
-    send_playlist_restart_feedback,
-    send_player_error_feedback
-)
-
-# NEW:
-from get_playlists_v2 import (
-    update_playlist_if_needed,
-    send_playing_status_feedback,
-    send_playlist_restart_feedback,
-    send_player_error_feedback
-)
-```
-
-### 3. Add Authentication on Startup
-
-In `main.py`, add authentication check in the `SignagePlayer` class:
-
-```python
-def build(self):
-    """Build the application UI"""
-    # Load configuration
-    self.config = self.load_config()
-    
-    # NEW: Authenticate with server
-    from player_auth import PlayerAuth
-    auth = PlayerAuth()
-    
-    if not auth.is_authenticated():
-        Logger.info("First time setup - authenticating...")
-        from get_playlists_v2 import ensure_authenticated
-        if not ensure_authenticated(self.config):
-            Logger.error("❌ Failed to authenticate with server!")
-            # Show error popup or retry
-    else:
-        Logger.info(f"✅ Authenticated as: {auth.get_player_name()}")
-    
-    # Continue with normal startup...
-    return SignagePlayerWidget(config=self.config)
-```
-
-### 4. Update Server Configuration
-
-Your existing `app_config.txt` works as-is! The new system uses the same fields:
-
-```json
-{
-  "server_ip": "your-server-ip",
-  "port": "5000",
-  "screen_name": "player-001",
-  "quickconnect_key": "QUICK123",
-  ...
-}
-```
-
-**Note**: `screen_name` is now used as `hostname` for authentication.
-
-### 5. Testing
-
-1. **Stop the old player**:
-```bash
-pkill -f main.py
-```
-
-2. **Delete old authentication data** (first time only):
-```bash
-rm -f /home/pi/Desktop/Kiwy-Signage/src/player_auth.json
-```
-
-3. **Start the updated player**:
-```bash
-cd /home/pi/Desktop/Kiwy-Signage/src/
-python3 main.py
-```
-
-4. **Check logs for authentication**:
-- Look for: `✅ Authentication successful`
-- Or: `❌ Authentication failed: [error message]`
-
-## Troubleshooting
-
-### Authentication Fails
-
-**Problem**: `❌ Authentication failed: Invalid credentials`
-
-**Solution**:
-1. Verify player exists in DigiServer v2:
-   - Login to http://your-server:5000
-   - Go to Players → check if hostname exists
-   
-2. Verify quickconnect code:
-   - In DigiServer, check player's Quick Connect Code
-   - Update `app_config.txt` with correct code
-
-3. Check server URL:
-   ```python
-   # Test connection
-   import requests
-   response = requests.get('http://your-server:5000/api/health')
-   print(response.json())  # Should show: {'status': 'healthy'}
-   ```
-
-### Auth Code Expired
-
-**Problem**: Player was working, now shows auth errors
-
-**Solution**:
-```bash
-# Clear saved auth and re-authenticate
-rm /home/pi/Desktop/Kiwy-Signage/src/player_auth.json
-# Restart player - will auto-authenticate
-```
-
-### Can't Connect to Server
-
-**Problem**: `Cannot connect to server`
-
-**Solution**:
-1. Check server is running:
-```bash
-curl http://your-server:5000/api/health
-```
-
-2. Check network connectivity:
-```bash
-ping your-server-ip
-```
-
-3. Verify server URL in `app_config.txt`
-
-## Configuration Files
-
-### player_auth.json (auto-created)
-
-This file stores the authentication token:
-
-```json
-{
-  "hostname": "player-001",
-  "auth_code": "rrX4JtM99e4e6ni0VCsuIstjTVQQqILXeRmGu_Ek2Ks",
-  "player_id": 1,
-  "player_name": "Demo Player",
-  "group_id": 5,
-  "orientation": "Landscape",
-  "authenticated": true,
-  "server_url": "http://your-server:5000"
-}
-```
-
-**Important**: Keep this file secure! It contains your player's access token.
-
-## Advanced: Custom Authentication
-
-If you need custom authentication logic:
-
-```python
-from player_auth import PlayerAuth
-
-# Initialize
-auth = PlayerAuth(config_file='custom_auth.json')
-
-# Authenticate with password instead of quickconnect
-success, error = auth.authenticate(
-    server_url='http://your-server:5000',
-    hostname='player-001',
-    password='your_secure_password'  # Use password instead
-)
-
-if success:
-    print(f"✅ Authenticated as: {auth.get_player_name()}")
-    
-    # Get playlist
-    playlist_data = auth.get_playlist()
-    
-    # Send heartbeat
-    auth.send_heartbeat(status='playing')
-    
-    # Send feedback
-    auth.send_feedback(
-        message="Playing video.mp4",
-        status="playing",
-        playlist_version=5
-    )
-else:
-    print(f"❌ Failed: {error}")
-```
-
-## Rollback to Old System
-
-If you need to rollback:
-
-```bash
-cd /home/pi/Desktop/Kiwy-Signage/src/
-
-# Rename new files
-mv get_playlists_v2.py get_playlists_v2.py.backup
-mv player_auth.py player_auth.py.backup
-
-# Use old get_playlists.py (keep as-is)
-# Old system will continue working with DigiServer v1
-```
-
-## Benefits of New System
-
-✅ **More Secure**: Auth tokens instead of passwords in every request
-✅ **Better Performance**: No bcrypt verification on every API call  
-✅ **Session Management**: Server tracks player sessions
-✅ **Easier Debugging**: Auth failures vs API failures are separate
-✅ **Future-Proof**: Ready for token refresh, expiration, etc.
-
-## Next Steps
-
-Once migration is complete:
-
-1. **Monitor player logs** for first 24 hours
-2. **Verify playlist updates** are working
-3. **Check feedback** is being received in DigiServer
-4. **Update other players** one at a time
-
-## Support
-
-If you encounter issues:
-
-1. **Check player logs**: `tail -f player.log`
-2. **Check server logs**: DigiServer v2 logs in `instance/logs/`
-3. **Test API manually**:
-```bash
-# Test authentication
-curl -X POST http://your-server:5000/api/auth/player \
-  -H "Content-Type: application/json" \
-  -d '{"hostname":"player-001","quickconnect_code":"QUICK123"}'
-```
-
----
-
-**Migration completed!** Your Kiwy-Signage player now uses secure authentication with DigiServer v2. 🎉

working_files/OFFLINE_INSTALLATION.md

@@ -1,158 +0,0 @@
-# Offline Installation Guide
-
-This guide explains how to set up and use offline installation for the Kiwy Signage Player.
-
-## Overview
-
-The offline installation system allows you to install the signage player on devices without internet access by pre-downloading all necessary packages.
-
-## Directory Structure
-
-```
-Kiwy-Signage/
-├── repo/                          # Offline packages repository
-│   ├── python-wheels/            # Python packages (.whl files)
-│   ├── system-packages/          # System package information
-│   │   ├── apt-packages.txt     # List of required apt packages
-│   │   └── debs/                # Downloaded .deb files (optional)
-│   └── README.md
-├── download_offline_packages.sh  # Download Python packages
-├── download_deb_packages.sh      # Download system .deb packages
-└── install.sh                    # Smart installer (online/offline)
-```
-
-## Setup for Offline Installation
-
-### Step 1: Prepare on a Connected System
-
-On a system with internet access (preferably Raspberry Pi OS):
-
-```bash
-# Clone the repository
-git clone <repository-url>
-cd Kiwy-Signage
-
-# Download Python packages
-bash download_offline_packages.sh
-
-# (Optional) Download system .deb packages
-bash download_deb_packages.sh
-```
-
-This will populate the `repo/` folder with all necessary packages.
-
-### Step 2: Transfer to Offline System
-
-Copy the entire `Kiwy-Signage` directory to your offline system:
-
-```bash
-# Using USB drive
-cp -r Kiwy-Signage /media/usb/
-
-# Or create a tarball
-tar -czf kiwy-signage-offline.tar.gz Kiwy-Signage/
-
-# On target system, extract:
-tar -xzf kiwy-signage-offline.tar.gz
-cd Kiwy-Signage
-```
-
-### Step 3: Install on Offline System
-
-The installer automatically detects offline packages:
-
-```bash
-# Automatic detection
-bash install.sh
-
-# Or explicitly specify offline mode
-bash install.sh --offline
-```
-
-## Package Information
-
-### Python Packages (requirements.txt)
-
-- **kivy==2.1.0** - UI framework
-- **requests==2.32.4** - HTTP library
-- **bcrypt==4.2.1** - Password hashing
-- **aiohttp==3.9.1** - Async HTTP client
-- **asyncio==3.4.3** - Async I/O framework
-
-### System Packages (APT)
-
-See `repo/system-packages/apt-packages.txt` for complete list:
-- Python development tools
-- SDL2 libraries (video/audio)
-- FFmpeg and codecs
-- GStreamer plugins
-- Build dependencies
-
-## Online Installation
-
-If you have internet access, simply run:
-
-```bash
-bash install.sh
-```
-
-The installer will automatically download and install all packages from the internet.
-
-## Updating Offline Packages
-
-To update the offline package cache:
-
-```bash
-# On a connected system
-bash download_offline_packages.sh
-```
-
-This will download the latest versions of all packages.
-
-## Troubleshooting
-
-### Problem: Missing Dependencies
-
-If installation fails due to missing dependencies:
-
-```bash
-# Download .deb packages with dependencies
-bash download_deb_packages.sh
-
-# Install with dependency resolution
-sudo apt install -f
-```
-
-### Problem: Wheel Not Found
-
-If a specific Python package wheel is not found:
-
-```bash
-# Download specific package
-pip3 download <package-name> -d repo/python-wheels/
-```
-
-### Problem: Architecture Mismatch
-
-Ensure packages are downloaded on the same architecture (ARM for Raspberry Pi):
-
-```bash
-# Verify architecture
-uname -m  # Should show: armv7l or aarch64
-
-# Force ARM downloads
-pip3 download -r requirements.txt -d repo/python-wheels/ --platform linux_armv7l
-```
-
-## Storage Requirements
-
-- **Python wheels**: ~50-100 MB
-- **System .deb packages**: ~200-500 MB (if downloaded)
-- **Total**: ~250-600 MB
-
-## Notes
-
-- The `repo/` folder is designed to be portable
-- Downloaded packages are excluded from git (see `.gitignore`)
-- The installer supports both online and offline modes seamlessly
-- System packages list is maintained in `repo/system-packages/apt-packages.txt`

working_files/OFFLINE_QUICKSTART.md

@@ -1,42 +0,0 @@
-# Offline Installation Quick Start
-
-## For Connected System (Preparation)
-
-```bash
-# 1. Download Python packages (required)
-bash download_offline_packages.sh
-
-# 2. Download system .deb packages (optional, for fully offline)
-bash download_deb_packages.sh
-```
-
-## For Offline System (Installation)
-
-```bash
-# The installer auto-detects offline packages
-bash install.sh
-
-# Or explicitly use offline mode
-bash install.sh --offline
-```
-
-## What's Included
-
-### Python Packages (18 wheels)
-✅ Kivy 2.1.0  
-✅ Requests 2.32.4  
-✅ Bcrypt 4.2.1  
-✅ Aiohttp 3.9.1 (async HTTP)  
-✅ Asyncio 3.4.3 (async framework)  
-✅ All dependencies
-
-### System Packages
-📋 See `repo/system-packages/apt-packages.txt`
-
-## File Size
-- Python wheels: ~50 MB
-- System packages: ~200-500 MB (if .deb downloaded)
-
-## See Also
-- **OFFLINE_INSTALLATION.md** - Complete guide
-- **repo/README.md** - Repository structure

working_files/QUICK_START.md

@@ -1,190 +0,0 @@
-# 🚀 Quick Start Guide - Player Authentication
-
-## For DigiServer Admin
-
-### 1. Create Player in DigiServer v2
-
-```bash
-# Login to web interface
-http://your-server:5000
-
-# Navigate to: Players → Add Player
-Name: Office Player
-Hostname: office-player-001       # Must be unique
-Location: Main Office
-Password: [leave empty if using quickconnect]
-Quick Connect Code: OFFICE123      # Easy pairing code
-Orientation: Landscape
-```
-
-### 2. Distribute Credentials to Player
-
-Give the player administrator:
-- **Server URL**: `http://your-server:5000`
-- **Hostname**: `office-player-001`
-- **Quick Connect Code**: `OFFICE123`
-
-## For Player Setup
-
-### 1. Update app_config.txt
-
-```json
-{
-  "server_ip": "your-server-ip",
-  "port": "5000",
-  "screen_name": "office-player-001",
-  "quickconnect_key": "OFFICE123",
-  ...
-}
-```
-
-### 2. Test Authentication
-
-```bash
-cd /home/pi/Desktop/Kiwy-Signage
-python3 test_authentication.py
-```
-
-### 3. Update Player Code (One-Time)
-
-In `src/main.py`, line ~34, change:
-
-```python
-from get_playlists_v2 import (  # Changed from get_playlists
-    update_playlist_if_needed,
-    send_playing_status_feedback,
-    send_playlist_restart_feedback,
-    send_player_error_feedback
-)
-```
-
-### 4. Run Player
-
-```bash
-cd /home/pi/Desktop/Kiwy-Signage/src
-python3 main.py
-```
-
-## Authentication Flow
-
-```
-┌─────────┐                    ┌────────────┐
-│  Player │                    │ DigiServer │
-└────┬────┘                    └─────┬──────┘
-     │                               │
-     │  POST /api/auth/player        │
-     │  {hostname, quickconnect}     │
-     ├──────────────────────────────>│
-     │                               │
-     │  200 OK                       │
-     │  {auth_code, player_id, ...}  │
-     │<──────────────────────────────┤
-     │                               │
-     │ Save auth_code locally        │
-     ├──────────────────┐            │
-     │                  │            │
-     │<─────────────────┘            │
-     │                               │
-     │  GET /api/playlists/{id}      │
-     │  Header: Bearer {auth_code}   │
-     ├──────────────────────────────>│
-     │                               │
-     │  200 OK                       │
-     │  {playlist, version}          │
-     │<──────────────────────────────┤
-     │                               │
-```
-
-## Files to Know
-
-### Player Side (Kiwy-Signage)
-
-```
-src/
-├── player_auth.json           # Auto-created, stores auth_code
-├── player_auth.py             # Authentication module
-├── get_playlists_v2.py        # Updated playlist fetcher
-└── app_config.txt             # Your existing config
-```
-
-### Server Side (DigiServer v2)
-
-```
-app/
-├── models/player.py           # Player model with auth methods
-└── blueprints/api.py          # Authentication endpoints
-
-API Endpoints:
-- POST /api/auth/player        # Authenticate and get token
-- POST /api/auth/verify        # Verify token validity
-- GET  /api/playlists/{id}     # Get playlist (requires auth)
-- POST /api/players/{id}/heartbeat  # Send status (requires auth)
-```
-
-## Common Commands
-
-```bash
-# Test authentication
-./test_authentication.py
-
-# Clear saved auth (re-authenticate)
-rm src/player_auth.json
-
-# Check server health
-curl http://your-server:5000/api/health
-
-# Manual authentication test
-curl -X POST http://your-server:5000/api/auth/player \
-  -H "Content-Type: application/json" \
-  -d '{"hostname":"player-001","quickconnect_code":"QUICK123"}'
-
-# View player logs
-tail -f player.log
-
-# View server logs (if running Flask dev server)
-# Logs appear in terminal where server is running
-```
-
-## Troubleshooting One-Liners
-
-```bash
-# Authentication fails → Check player exists
-curl http://your-server:5000/api/health
-
-# Auth expired → Clear and retry
-rm src/player_auth.json && python3 main.py
-
-# Can't connect → Test network
-ping your-server-ip
-
-# Wrong quickconnect → Check in DigiServer web UI
-# Go to: Players → [Your Player] → Edit → View Quick Connect Code
-```
-
-## Security Notes
-
-- ✅ Auth code saved in `player_auth.json` (keep secure!)
-- ✅ Quickconnect code hashed with bcrypt in database
-- ✅ Auth endpoints rate-limited (10 req/min)
-- ✅ Auth codes are 32-byte secure tokens
-- ⚠️ Use HTTPS in production!
-- ⚠️ Rotate quickconnect codes periodically
-
-## Quick Wins
-
-### Before (Old System)
-- Every API call = send hostname + quickconnect
-- Server runs bcrypt check on every request
-- Slow response times
-- No session tracking
-
-### After (New System)
-- Authenticate once = get auth_code
-- All subsequent calls use auth_code
-- 10x faster API responses
-- Server tracks player sessions
-- Can revoke access instantly
-
----
-
-**Ready to go!** 🎉 Test with `./test_authentication.py` then start your player!

working_files/README.md

@@ -1,152 +0,0 @@
-# Kivy Signage Player
-
-A modern digital signage player built with Kivy framework that displays content from DigiServer playlists.
-
-## Features
-
-- **Cross-platform**: Runs on Linux, Windows, and macOS
-- **Modern UI**: Built with Kivy framework for smooth graphics and animations
-- **Multiple Media Types**: Supports images (JPG, PNG, GIF, BMP) and videos (MP4, AVI, MKV, MOV, WEBM)
-- **Server Integration**: Fetches playlists from DigiServer with automatic updates
-- **Player Feedback**: Reports status and playback information to server
-- **Fullscreen Display**: Optimized for digital signage displays
-- **Touch Controls**: Mouse/touch-activated control panel
-- **Auto-restart**: Continuous playlist looping
-- **Error Handling**: Robust error handling with server feedback
-
-## Installation
-
-1. **Install system dependencies:**
-   ```bash
-   chmod +x install.sh
-   ./install.sh
-   ```
-
-2. **Configure the player:**
-   Edit `config/app_config.json` with your server details:
-   ```json
-   {
-     "server_ip": "your-server-ip",
-     "port": "5000",
-     "screen_name": "your-player-name",
-     "quickconnect_key": "your-quickconnect-code"
-   }
-   ```
-
-## Usage
-
-### Recommended: Using Start Script (with Virtual Environment)
-```bash
-chmod +x start.sh
-./start.sh
-```
-This script automatically:
-- Activates the Python virtual environment
-- Checks for configuration
-- Starts the player
-
-### Alternative: Using Run Script
-```bash
-chmod +x run_player.sh
-./run_player.sh
-```
-
-### Manual Start
-```bash
-# With virtual environment
-source .venv/bin/activate
-cd src
-python3 main.py
-
-# Without virtual environment
-cd src
-python3 main.py
-```
-
-## Controls
-
-- **Mouse/Touch Movement**: Shows control panel for 3 seconds
-- **Previous (⏮)**: Go to previous media item
-- **Pause/Play (⏸/▶)**: Toggle playback
-- **Next (⏭)**: Skip to next media item  
-- **Settings (⚙)**: View player configuration and status
-- **Exit (⏻)**: Close the application
-
-## Directory Structure
-
-```
-Kiwi-signage/
-├── src/
-│   ├── main.py              # Main Kivy application
-│   └── get_playlists.py     # Playlist management and server communication
-├── config/
-│   └── app_config.json      # Player configuration
-├── media/                   # Downloaded media files (auto-generated)
-├── playlists/               # Playlist cache (auto-generated)
-├── requirements.txt         # Python dependencies
-├── install.sh               # Installation script
-├── run_player.sh           # Run script
-└── README.md               # This file
-```
-
-## Configuration Options
-
-### app_config.json
-- `server_ip`: IP address or domain of DigiServer
-- `port`: Port number of DigiServer (default: 5000)
-- `screen_name`: Unique identifier for this player
-- `quickconnect_key`: Authentication key for server access
-
-## Features Comparison with Tkinter Player
-
-| Feature | Kivy Player | Tkinter Player |
-|---------|-------------|----------------|
-| Cross-platform | ✅ Better | ✅ Good |
-| Modern UI | ✅ Excellent | ❌ Basic |
-| Touch Support | ✅ Native | ❌ Limited |
-| Video Playback | ✅ Built-in | ✅ VLC Required |
-| Performance | ✅ GPU Accelerated | ❌ CPU Only |
-| Animations | ✅ Smooth | ❌ None |
-| Mobile Ready | ✅ Yes | ❌ No |
-
-## Server Integration
-
-The player communicates with DigiServer via REST API:
-
-- **Playlist Fetch**: `GET /api/playlists`
-- **Player Feedback**: `POST /api/player-feedback`
-
-Status updates sent to server:
-- Playlist check and update notifications
-- Current playback status
-- Error reports
-- Playlist restart notifications
-
-## Troubleshooting
-
-### Installation Issues
-- Make sure system dependencies are installed: `./install.sh`
-- For ARM devices (Raspberry Pi), ensure proper SDL2 libraries
-
-### Playback Issues
-- Check media file formats are supported
-- Verify network connection to DigiServer
-- Check player configuration in settings
-
-### Server Connection
-- Verify server IP and port in configuration
-- Check quickconnect key is correct
-- Ensure DigiServer is running and accessible
-
-## Development
-
-Based on the proven architecture of the tkinter signage player with modern Kivy enhancements:
-
-- **Playlist Management**: Inherited from `get_playlists.py`
-- **Media Playback**: Kivy's built-in Video and AsyncImage widgets
-- **Server Communication**: REST API calls with feedback system
-- **Error Handling**: Comprehensive exception handling with server reporting
-
-## License
-
-This project is part of the DigiServer digital signage system.

working_files/analyze_playlist.py

@@ -1,35 +0,0 @@
-#!/usr/bin/env python3
-"""Analyze what's happening with the playlist download."""
-
-import json
-
-# Check the saved playlist
-playlist_file = 'playlists/server_playlist_v8.json'
-print("=" * 80)
-print("SAVED PLAYLIST ANALYSIS")
-print("=" * 80)
-
-with open(playlist_file, 'r') as f:
-    data = json.load(f)
-
-print(f"\nVersion: {data.get('version', 'N/A')}")
-print(f"Items in playlist: {len(data.get('playlist', []))}")
-
-print("\nPlaylist items:")
-for idx, item in enumerate(data.get('playlist', []), 1):
-    print(f"\n{idx}. File: {item.get('file_name', 'N/A')}")
-    print(f"   URL: {item.get('url', 'N/A')}")
-    print(f"   Duration: {item.get('duration', 'N/A')}s")
-
-print("\n" + "=" * 80)
-print("\n⚠️  ISSUE: Server has 5 files, but only 3 are saved!")
-print("\nPossible reasons:")
-print("1. Server sent only 3 files")
-print("2. 2 files failed to download and were skipped")
-print("3. Download function has a bug")
-print("\nThe download_media_files() function in get_playlists_v2.py:")
-print("- Downloads from the 'url' field in the playlist")
-print("- If download fails, it SKIPS the file (continues)")
-print("- Only successfully downloaded files are added to updated_playlist")
-print("\nThis means 2 files likely had invalid URLs or download errors!")
-print("=" * 80)

working_files/check_video_codecs.py

@@ -1,123 +0,0 @@
-#!/usr/bin/env python3
-"""
-Check video files for codec compatibility with ffpyplayer
-"""
-import os
-import subprocess
-import json
-
-def check_video_codec(video_path):
-    """Check video codec using ffprobe"""
-    try:
-        cmd = [
-            'ffprobe',
-            '-v', 'quiet',
-            '-print_format', 'json',
-            '-show_format',
-            '-show_streams',
-            video_path
-        ]
-        
-        result = subprocess.run(cmd, capture_output=True, text=True)
-        
-        if result.returncode != 0:
-            return None, "ffprobe failed"
-        
-        data = json.loads(result.stdout)
-        
-        video_streams = [s for s in data.get('streams', []) if s.get('codec_type') == 'video']
-        audio_streams = [s for s in data.get('streams', []) if s.get('codec_type') == 'audio']
-        
-        if not video_streams:
-            return None, "No video stream found"
-        
-        video_stream = video_streams[0]
-        
-        info = {
-            'codec': video_stream.get('codec_name', 'unknown'),
-            'codec_long': video_stream.get('codec_long_name', 'unknown'),
-            'width': video_stream.get('width', 0),
-            'height': video_stream.get('height', 0),
-            'fps': eval(video_stream.get('r_frame_rate', '0/1')),
-            'duration': float(data.get('format', {}).get('duration', 0)),
-            'bitrate': int(data.get('format', {}).get('bit_rate', 0)),
-            'audio_codec': audio_streams[0].get('codec_name', 'none') if audio_streams else 'none',
-            'size': int(data.get('format', {}).get('size', 0))
-        }
-        
-        return info, None
-        
-    except FileNotFoundError:
-        return None, "ffprobe not installed (run: sudo apt-get install ffmpeg)"
-    except Exception as e:
-        return None, str(e)
-
-def main():
-    base_dir = os.path.dirname(os.path.abspath(__file__))
-    media_dir = os.path.join(base_dir, 'media')
-    
-    print("=" * 80)
-    print("VIDEO CODEC COMPATIBILITY CHECKER")
-    print("=" * 80)
-    
-    # Supported codecs by ffpyplayer
-    supported_codecs = ['h264', 'h265', 'hevc', 'vp8', 'vp9', 'mpeg4']
-    
-    # Find video files
-    video_extensions = ['.mp4', '.avi', '.mkv', '.mov', '.webm']
-    video_files = []
-    
-    if os.path.exists(media_dir):
-        for filename in os.listdir(media_dir):
-            ext = os.path.splitext(filename)[1].lower()
-            if ext in video_extensions:
-                video_files.append(filename)
-    
-    if not video_files:
-        print("\n✓ No video files found in media directory")
-        return
-    
-    print(f"\nFound {len(video_files)} video file(s):\n")
-    
-    for filename in video_files:
-        video_path = os.path.join(media_dir, filename)
-        print(f"📹 {filename}")
-        print(f"   Path: {video_path}")
-        
-        info, error = check_video_codec(video_path)
-        
-        if error:
-            print(f"   ❌ ERROR: {error}")
-            continue
-        
-        # Display video info
-        print(f"   Video Codec: {info['codec']} ({info['codec_long']})")
-        print(f"   Resolution: {info['width']}x{info['height']}")
-        print(f"   Frame Rate: {info['fps']:.2f} fps")
-        print(f"   Duration: {info['duration']:.1f}s")
-        print(f"   Bitrate: {info['bitrate'] / 1000:.0f} kbps")
-        print(f"   Audio Codec: {info['audio_codec']}")
-        print(f"   File Size: {info['size'] / (1024*1024):.2f} MB")
-        
-        # Check compatibility
-        if info['codec'] in supported_codecs:
-            print(f"   ✅ COMPATIBLE - Codec '{info['codec']}' is supported by ffpyplayer")
-        else:
-            print(f"   ⚠️  WARNING - Codec '{info['codec']}' may not be supported")
-            print(f"   Supported codecs: {', '.join(supported_codecs)}")
-            print(f"   Consider re-encoding to H.264:")
-            print(f"   ffmpeg -i \"{filename}\" -c:v libx264 -preset fast -crf 23 \"{os.path.splitext(filename)[0]}_h264.mp4\"")
-        
-        # Performance warnings
-        if info['width'] > 1920 or info['height'] > 1080:
-            print(f"   ⚠️  High resolution ({info['width']}x{info['height']}) may cause performance issues")
-            print(f"   Consider downscaling to 1920x1080 or lower")
-        
-        if info['bitrate'] > 5000000:  # 5 Mbps
-            print(f"   ⚠️  High bitrate ({info['bitrate'] / 1000000:.1f} Mbps) may cause playback issues")
-            print(f"   Consider reducing bitrate to 2-4 Mbps")
-        
-        print()
-
-if __name__ == '__main__':
-    main()

working_files/convert_video_for_rpi.sh

@@ -1,57 +0,0 @@
-#!/bin/bash
-# Video Conversion Script for Raspberry Pi Signage Player
-# Converts videos to optimal settings: 1080p @ 30fps, H.264 codec
-
-if [ $# -eq 0 ]; then
-    echo "Usage: $0 <input_video> [output_video]"
-    echo "Example: $0 input.mp4 output.mp4"
-    echo ""
-    echo "This script converts videos to Raspberry Pi-friendly settings:"
-    echo "  - Resolution: Max 1920x1080"
-    echo "  - Frame rate: 30 fps"
-    echo "  - Codec: H.264"
-    echo "  - Bitrate: ~5-8 Mbps"
-    exit 1
-fi
-
-INPUT_VIDEO="$1"
-OUTPUT_VIDEO="${2:-converted_$(basename "$INPUT_VIDEO")}"
-
-if [ ! -f "$INPUT_VIDEO" ]; then
-    echo "Error: Input file '$INPUT_VIDEO' not found!"
-    exit 1
-fi
-
-echo "Converting video for Raspberry Pi playback..."
-echo "Input:  $INPUT_VIDEO"
-echo "Output: $OUTPUT_VIDEO"
-echo ""
-
-# Convert video with optimal settings for Raspberry Pi
-ffmpeg -i "$INPUT_VIDEO" \
-    -c:v libx264 \
-    -preset medium \
-    -crf 23 \
-    -maxrate 8M \
-    -bufsize 12M \
-    -vf "scale='min(1920,iw)':'min(1080,ih)':force_original_aspect_ratio=decrease,fps=30" \
-    -r 30 \
-    -c:a aac \
-    -b:a 128k \
-    -movflags +faststart \
-    -y \
-    "$OUTPUT_VIDEO"
-
-if [ $? -eq 0 ]; then
-    echo ""
-    echo "✓ Conversion completed successfully!"
-    echo "Original: $(du -h "$INPUT_VIDEO" | cut -f1)"
-    echo "Converted: $(du -h "$OUTPUT_VIDEO" | cut -f1)"
-    echo ""
-    echo "You can now use '$OUTPUT_VIDEO' in your signage player."
-else
-    echo ""
-    echo "✗ Conversion failed! Make sure ffmpeg is installed:"
-    echo "  sudo apt-get install ffmpeg"
-    exit 1
-fi

working_files/diagnose_playlist.py

@@ -1,167 +0,0 @@
-#!/usr/bin/env python3
-"""
-Diagnostic script to check why media files might be skipped
-"""
-import os
-import json
-
-# Paths
-base_dir = os.path.dirname(os.path.abspath(__file__))
-media_dir = os.path.join(base_dir, 'media')
-playlists_dir = os.path.join(base_dir, 'playlists')
-
-# Supported extensions
-VIDEO_EXTENSIONS = ['.mp4', '.avi', '.mkv', '.mov', '.webm']
-IMAGE_EXTENSIONS = ['.jpg', '.jpeg', '.png', '.bmp', '.gif']
-SUPPORTED_EXTENSIONS = VIDEO_EXTENSIONS + IMAGE_EXTENSIONS
-
-def check_playlist():
-    """Check playlist for issues"""
-    print("=" * 80)
-    print("PLAYLIST DIAGNOSTIC TOOL")
-    print("=" * 80)
-    
-    # Find latest playlist file
-    playlist_files = [f for f in os.listdir(playlists_dir) 
-                     if f.startswith('server_playlist_v') and f.endswith('.json')]
-    
-    if not playlist_files:
-        print("\n❌ ERROR: No playlist files found!")
-        return
-    
-    # Sort by version and get latest
-    versions = [(int(f.split('_v')[-1].split('.json')[0]), f) for f in playlist_files]
-    versions.sort(reverse=True)
-    latest_file = versions[0][1]
-    playlist_path = os.path.join(playlists_dir, latest_file)
-    
-    print(f"\n📋 Latest Playlist: {latest_file}")
-    print(f"   Path: {playlist_path}")
-    
-    # Load playlist
-    try:
-        with open(playlist_path, 'r') as f:
-            data = json.load(f)
-        
-        playlist = data.get('playlist', [])
-        version = data.get('version', 0)
-        
-        print(f"   Version: {version}")
-        print(f"   Total items: {len(playlist)}")
-        
-    except Exception as e:
-        print(f"\n❌ ERROR loading playlist: {e}")
-        return
-    
-    # Check media directory
-    print(f"\n📁 Media Directory: {media_dir}")
-    if not os.path.exists(media_dir):
-        print("   ❌ ERROR: Media directory doesn't exist!")
-        return
-    
-    media_files = os.listdir(media_dir)
-    print(f"   Files found: {len(media_files)}")
-    for f in media_files:
-        print(f"   - {f}")
-    
-    # Check each playlist item
-    print("\n" + "=" * 80)
-    print("CHECKING PLAYLIST ITEMS")
-    print("=" * 80)
-    
-    valid_count = 0
-    missing_count = 0
-    unsupported_count = 0
-    
-    for idx, item in enumerate(playlist, 1):
-        file_name = item.get('file_name', '')
-        duration = item.get('duration', 0)
-        media_path = os.path.join(media_dir, file_name)
-        file_ext = os.path.splitext(file_name)[1].lower()
-        
-        print(f"\n[{idx}/{len(playlist)}] {file_name}")
-        print(f"    Duration: {duration}s")
-        
-        # Check if file exists
-        if not os.path.exists(media_path):
-            print(f"    ❌ STATUS: FILE NOT FOUND")
-            print(f"    Expected path: {media_path}")
-            missing_count += 1
-            continue
-        
-        # Check file size
-        file_size = os.path.getsize(media_path)
-        print(f"    ✓ File exists ({file_size:,} bytes)")
-        
-        # Check if supported type
-        if file_ext not in SUPPORTED_EXTENSIONS:
-            print(f"    ❌ STATUS: UNSUPPORTED FILE TYPE '{file_ext}'")
-            print(f"    Supported extensions: {', '.join(SUPPORTED_EXTENSIONS)}")
-            unsupported_count += 1
-            continue
-        
-        # Check media type
-        if file_ext in VIDEO_EXTENSIONS:
-            media_type = "VIDEO"
-        elif file_ext in IMAGE_EXTENSIONS:
-            media_type = "IMAGE"
-        else:
-            media_type = "UNKNOWN"
-        
-        print(f"    ✓ Type: {media_type}")
-        print(f"    ✓ Extension: {file_ext}")
-        print(f"    ✓ STATUS: SHOULD PLAY OK")
-        valid_count += 1
-    
-    # Summary
-    print("\n" + "=" * 80)
-    print("SUMMARY")
-    print("=" * 80)
-    print(f"Total items:      {len(playlist)}")
-    print(f"✓ Valid:          {valid_count}")
-    print(f"❌ Missing files: {missing_count}")
-    print(f"❌ Unsupported:   {unsupported_count}")
-    
-    if valid_count == len(playlist):
-        print("\n✅ All playlist items should play correctly!")
-    else:
-        print(f"\n⚠️  WARNING: {len(playlist) - valid_count} items may be skipped!")
-    
-    # Additional checks
-    print("\n" + "=" * 80)
-    print("ADDITIONAL CHECKS")
-    print("=" * 80)
-    
-    # Check for files in media dir not in playlist
-    playlist_files_set = {item.get('file_name', '') for item in playlist}
-    orphaned_files = [f for f in media_files if f not in playlist_files_set]
-    
-    if orphaned_files:
-        print(f"\n⚠️  Files in media directory NOT in playlist:")
-        for f in orphaned_files:
-            print(f"   - {f}")
-    else:
-        print("\n✓ All media files are in the playlist")
-    
-    # Check for case sensitivity issues
-    print("\n🔍 Checking for case sensitivity issues...")
-    media_files_lower = {f.lower(): f for f in media_files}
-    case_issues = []
-    
-    for item in playlist:
-        file_name = item.get('file_name', '')
-        if file_name.lower() in media_files_lower:
-            actual_name = media_files_lower[file_name.lower()]
-            if actual_name != file_name:
-                case_issues.append((file_name, actual_name))
-    
-    if case_issues:
-        print("⚠️  Case sensitivity mismatches found:")
-        for playlist_name, actual_name in case_issues:
-            print(f"   Playlist: {playlist_name}")
-            print(f"   Actual:   {actual_name}")
-    else:
-        print("✓ No case sensitivity issues found")
-
-if __name__ == '__main__':
-    check_playlist()

working_files/download_deb_packages.sh

@@ -1,125 +0,0 @@
-#!/bin/bash
-
-# Download DEB Packages Script for Offline Installation
-# This script downloads all system .deb packages required for offline installation
-
-set -e
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-SYSTEM_DIR="$SCRIPT_DIR/repo/system-packages"
-DEB_DIR="$SYSTEM_DIR/debs"
-
-echo "=========================================="
-echo "Downloading DEB Packages for Offline Install"
-echo "=========================================="
-echo ""
-
-# Create debs directory
-mkdir -p "$DEB_DIR"
-
-# Check if running on Debian/Ubuntu/Raspberry Pi OS
-if ! command -v apt-get &> /dev/null; then
-    echo "Error: This script requires apt-get (Debian/Ubuntu/Raspberry Pi OS)"
-    exit 1
-fi
-
-echo "Reading package list from: $SYSTEM_DIR/apt-packages.txt"
-echo ""
-
-# Update package cache
-echo "Updating package cache..."
-sudo apt update
-
-# Read packages from file
-PACKAGES=$(grep -v '^#' "$SYSTEM_DIR/apt-packages.txt" | grep -v '^$' | tr '\n' ' ')
-
-echo "Packages to download:"
-echo "$PACKAGES"
-echo ""
-
-# Download packages and dependencies
-echo "Downloading packages with dependencies..."
-cd "$DEB_DIR"
-
-# Use apt-get download to get .deb files
-for pkg in $PACKAGES; do
-    echo "Downloading: $pkg"
-    apt-get download "$pkg" 2>/dev/null || echo "  Warning: Could not download $pkg"
-done
-
-# Download dependencies
-echo ""
-echo "Downloading dependencies..."
-sudo apt-get install --download-only --reinstall -y $PACKAGES
-
-# Copy downloaded debs from apt cache
-echo ""
-echo "Copying packages from apt cache..."
-sudo cp /var/cache/apt/archives/*.deb "$DEB_DIR/" 2>/dev/null || true
-
-# Remove duplicate packages
-echo ""
-echo "Removing duplicates..."
-cd "$DEB_DIR"
-for file in *.deb; do
-    [ -f "$file" ] || continue
-    basename="${file%%_*}"
-    count=$(ls -1 "${basename}"_*.deb 2>/dev/null | wc -l)
-    if [ "$count" -gt 1 ]; then
-        # Keep only the latest version
-        ls -t "${basename}"_*.deb | tail -n +2 | xargs rm -f
-    fi
-done
-
-# Create installation order file
-echo ""
-echo "Creating installation order..."
-cat > "$DEB_DIR/install-order.txt" << 'EOF'
-# Install packages in this order to resolve dependencies
-
-# 1. Base tools and libraries
-python3-pip_*.deb
-python3-setuptools_*.deb
-python3-dev_*.deb
-zlib1g-dev_*.deb
-
-# 2. SDL2 libraries
-libsdl2-dev_*.deb
-libsdl2-image-dev_*.deb
-libsdl2-mixer-dev_*.deb
-libsdl2-ttf-dev_*.deb
-
-# 3. Multimedia libraries
-libportmidi-dev_*.deb
-libswscale-dev_*.deb
-libavformat-dev_*.deb
-libavcodec-dev_*.deb
-libavcodec-extra_*.deb
-
-# 4. FFmpeg and codecs
-ffmpeg_*.deb
-libx264-dev_*.deb
-
-# 5. GStreamer
-gstreamer1.0-plugins-base_*.deb
-gstreamer1.0-plugins-good_*.deb
-gstreamer1.0-plugins-bad_*.deb
-gstreamer1.0-alsa_*.deb
-
-# 6. Network tools
-wget_*.deb
-curl_*.deb
-EOF
-
-# Summary
-echo ""
-echo "=========================================="
-echo "DEB Download Complete!"
-echo "=========================================="
-echo ""
-echo "Downloaded .deb files: $(ls -1 *.deb 2>/dev/null | wc -l)"
-echo "Location: $DEB_DIR"
-echo ""
-echo "To install offline, copy the repo folder and run:"
-echo "  bash install.sh --offline"
-echo ""

working_files/download_offline_packages.sh

@@ -1,72 +0,0 @@
-#!/bin/bash
-
-# Download Offline Packages Script for Kivy Signage Player
-# This script downloads all necessary Python packages and documents system packages
-
-set -e
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-REPO_DIR="$SCRIPT_DIR/repo"
-WHEELS_DIR="$REPO_DIR/python-wheels"
-SYSTEM_DIR="$REPO_DIR/system-packages"
-
-echo "=========================================="
-echo "Downloading Offline Packages"
-echo "=========================================="
-echo ""
-
-# Check if repo directory exists
-if [ ! -d "$REPO_DIR" ]; then
-    echo "Error: repo directory not found!"
-    echo "Creating directories..."
-    mkdir -p "$WHEELS_DIR"
-    mkdir -p "$SYSTEM_DIR"
-fi
-
-# Download Python packages
-echo "Step 1: Downloading Python wheels..."
-echo "--------------------"
-cd "$SCRIPT_DIR"
-
-# Check if pip is installed
-if ! command -v pip3 &> /dev/null; then
-    echo "Error: pip3 is not installed. Please install it first:"
-    echo "  sudo apt install python3-pip"
-    exit 1
-fi
-
-# Download all Python packages and their dependencies
-echo "Downloading packages from requirements.txt..."
-pip3 download -r requirements.txt -d "$WHEELS_DIR" --platform linux_armv7l --only-binary=:all: || \
-pip3 download -r requirements.txt -d "$WHEELS_DIR" || true
-
-# Also download for general Linux platforms as fallback
-echo "Downloading cross-platform packages..."
-pip3 download -r requirements.txt -d "$WHEELS_DIR" || true
-
-echo ""
-echo "Python wheels downloaded to: $WHEELS_DIR"
-echo "Total wheel files: $(ls -1 "$WHEELS_DIR"/*.whl 2>/dev/null | wc -l)"
-
-# List system packages
-echo ""
-echo "Step 2: System packages information"
-echo "--------------------"
-echo "System packages are listed in: $SYSTEM_DIR/apt-packages.txt"
-echo ""
-echo "To download .deb files for offline installation, run:"
-echo "  bash download_deb_packages.sh"
-echo ""
-
-# Summary
-echo "=========================================="
-echo "Download Complete!"
-echo "=========================================="
-echo ""
-echo "Offline packages ready in: $REPO_DIR"
-echo ""
-echo "Next steps:"
-echo "1. Copy the entire 'repo' folder to your offline system"
-echo "2. Run: bash install.sh"
-echo "   (The installer will automatically detect and use offline packages)"
-echo ""

working_files/force_update.py

@@ -1,54 +0,0 @@
-#!/usr/bin/env python3
-"""Force playlist update to download all files."""
-
-import json
-import sys
-import os
-
-# Add src directory to path
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'src'))
-
-from get_playlists_v2 import update_playlist_if_needed
-
-# Load config
-config_file = 'config/app_config.json'
-with open(config_file, 'r') as f:
-    config = json.load(f)
-
-print("=" * 80)
-print("FORCING PLAYLIST UPDATE")
-print("=" * 80)
-
-playlist_dir = 'playlists'
-media_dir = 'media'
-
-print(f"\nConfiguration:")
-print(f"  Playlist dir: {playlist_dir}")
-print(f"  Media dir: {media_dir}")
-
-print("\n" + "=" * 80)
-print("Updating playlist...")
-print("=" * 80 + "\n")
-
-result = update_playlist_if_needed(config, playlist_dir, media_dir)
-
-if result:
-    print("\n" + "=" * 80)
-    print("SUCCESS!")
-    print("=" * 80)
-    print(f"✓ Playlist updated to: {result}")
-    
-    # Check media directory
-    import os
-    media_files = sorted([f for f in os.listdir(media_dir) if not f.startswith('.')])
-    print(f"\n✓ Media files downloaded ({len(media_files)}):")
-    for f in media_files:
-        size = os.path.getsize(os.path.join(media_dir, f))
-        print(f"  - {f} ({size:,} bytes)")
-    
-else:
-    print("\n" + "=" * 80)
-    print("FAILED or already up to date")
-    print("=" * 80)
-
-print("\n" + "=" * 80)

working_files/get_playlists.py

@@ -1,346 +0,0 @@
-import os
-import json
-import requests
-import bcrypt
-import re
-import datetime
-import logging
-
-# Set up logging
-logging.basicConfig(level=logging.INFO)
-logger = logging.getLogger(__name__)
-
-def send_player_feedback(config, message, status="active", playlist_version=None, error_details=None):
-    """
-    Send feedback to the server about player status.
-    
-    Args:
-        config (dict): Configuration containing server details
-        message (str): Main feedback message
-        status (str): Player status - "active", "playing", "error", "restarting"
-        playlist_version (int, optional): Current playlist version being played
-        error_details (str, optional): Error details if status is "error"
-    
-    Returns:
-        bool: True if feedback sent successfully, False otherwise
-    """
-    try:
-        server = config.get("server_ip", "")
-        host = config.get("screen_name", "")
-        quick = config.get("quickconnect_key", "")
-        port = config.get("port", "")
-        
-        # Construct server URL
-        # Remove protocol if already present
-        server_clean = server.replace('http://', '').replace('https://', '')
-        ip_pattern = r'^\d+\.\d+\.\d+\.\d+$'
-        if re.match(ip_pattern, server_clean):
-            feedback_url = f'http://{server_clean}:{port}/api/player-feedback'
-        else:
-            # Use original server if it has protocol, otherwise add http://
-            if server.startswith(('http://', 'https://')):
-                feedback_url = f'{server}/api/player-feedback'
-            else:
-                feedback_url = f'http://{server}/api/player-feedback'
-        
-        # Prepare feedback data
-        feedback_data = {
-            'hostname': host,
-            'quickconnect_code': quick,
-            'message': message,
-            'status': status,
-            'timestamp': datetime.datetime.now().isoformat(),
-            'playlist_version': playlist_version,
-            'error_details': error_details
-        }
-        
-        logger.info(f"Sending feedback to {feedback_url}: {feedback_data}")
-        
-        # Send POST request
-        response = requests.post(feedback_url, json=feedback_data, timeout=10)
-        
-        if response.status_code == 200:
-            logger.info(f"Feedback sent successfully: {message}")
-            return True
-        else:
-            logger.warning(f"Feedback failed with status {response.status_code}: {response.text}")
-            return False
-            
-    except requests.exceptions.RequestException as e:
-        logger.error(f"Failed to send feedback: {e}")
-        return False
-    except Exception as e:
-        logger.error(f"Unexpected error sending feedback: {e}")
-        return False
-
-def send_playlist_check_feedback(config, playlist_version=None):
-    """
-    Send feedback when playlist is checked for updates.
-    
-    Args:
-        config (dict): Configuration containing server details
-        playlist_version (int, optional): Current playlist version
-    
-    Returns:
-        bool: True if feedback sent successfully, False otherwise
-    """
-    player_name = config.get("screen_name", "unknown")
-    version_info = f"v{playlist_version}" if playlist_version else "unknown"
-    message = f"player {player_name}, is active, Playing {version_info}"
-    
-    return send_player_feedback(
-        config=config,
-        message=message,
-        status="active",
-        playlist_version=playlist_version
-    )
-
-def send_playlist_restart_feedback(config, playlist_version=None):
-    """
-    Send feedback when playlist loop ends and restarts.
-    
-    Args:
-        config (dict): Configuration containing server details
-        playlist_version (int, optional): Current playlist version
-    
-    Returns:
-        bool: True if feedback sent successfully, False otherwise
-    """
-    player_name = config.get("screen_name", "unknown")
-    version_info = f"v{playlist_version}" if playlist_version else "unknown"
-    message = f"player {player_name}, playlist loop completed, restarting {version_info}"
-    
-    return send_player_feedback(
-        config=config,
-        message=message,
-        status="restarting",
-        playlist_version=playlist_version
-    )
-
-def send_player_error_feedback(config, error_message, playlist_version=None):
-    """
-    Send feedback when an error occurs in the player.
-    
-    Args:
-        config (dict): Configuration containing server details
-        error_message (str): Description of the error
-        playlist_version (int, optional): Current playlist version
-    
-    Returns:
-        bool: True if feedback sent successfully, False otherwise
-    """
-    player_name = config.get("screen_name", "unknown")
-    message = f"player {player_name}, error occurred"
-    
-    return send_player_feedback(
-        config=config,
-        message=message,
-        status="error",
-        playlist_version=playlist_version,
-        error_details=error_message
-    )
-
-def send_playing_status_feedback(config, playlist_version=None, current_media=None):
-    """
-    Send feedback about current playing status.
-    
-    Args:
-        config (dict): Configuration containing server details
-        playlist_version (int, optional): Current playlist version
-        current_media (str, optional): Currently playing media file
-    
-    Returns:
-        bool: True if feedback sent successfully, False otherwise
-    """
-    player_name = config.get("screen_name", "unknown")
-    version_info = f"v{playlist_version}" if playlist_version else "unknown"
-    media_info = f" - {current_media}" if current_media else ""
-    message = f"player {player_name}, is active, Playing {version_info}{media_info}"
-    
-    return send_player_feedback(
-        config=config,
-        message=message,
-        status="playing",
-        playlist_version=playlist_version
-    )
-
-def fetch_server_playlist(config):
-    """Fetch the updated playlist from the server using a config dict."""
-    server = config.get("server_ip", "")
-    host = config.get("screen_name", "")
-    quick = config.get("quickconnect_key", "")
-    port = config.get("port", "")
-    try:
-        # Remove protocol if already present
-        server_clean = server.replace('http://', '').replace('https://', '')
-        ip_pattern = r'^\d+\.\d+\.\d+\.\d+$'
-        if re.match(ip_pattern, server_clean):
-            server_url = f'http://{server_clean}:{port}/api/playlists'
-        else:
-            # Use original server if it has protocol, otherwise add http://
-            if server.startswith(('http://', 'https://')):
-                server_url = f'{server}/api/playlists'
-            else:
-                server_url = f'http://{server}/api/playlists'
-        params = {
-            'hostname': host,
-            'quickconnect_code': quick
-        }
-        logger.info(f"Fetching playlist from URL: {server_url} with params: {params}")
-        response = requests.get(server_url, params=params)
-        if response.status_code == 200:
-            response_data = response.json()
-            logger.info(f"Server response: {response_data}")
-            playlist = response_data.get('playlist', [])
-            version = response_data.get('playlist_version', None)
-            hashed_quickconnect = response_data.get('hashed_quickconnect', None)
-            if version is not None and hashed_quickconnect is not None:
-                if bcrypt.checkpw(quick.encode('utf-8'), hashed_quickconnect.encode('utf-8')):
-                    logger.info("Fetched updated playlist from server.")
-                    return {'playlist': playlist, 'version': version}
-                else:
-                    logger.error("Quickconnect code validation failed.")
-            else:
-                logger.error("Failed to retrieve playlist or hashed quickconnect from the response.")
-        else:
-            logger.error(f"Failed to fetch playlist. Status Code: {response.status_code}")
-    except requests.exceptions.RequestException as e:
-        logger.error(f"Failed to fetch playlist: {e}")
-    return {'playlist': [], 'version': 0}
-
-def save_playlist_with_version(playlist_data, playlist_dir):
-    version = playlist_data.get('version', 0)
-    playlist_file = os.path.join(playlist_dir, f'server_playlist_v{version}.json')
-    with open(playlist_file, 'w') as f:
-        json.dump(playlist_data, f, indent=2)
-    logger.info(f"Playlist saved to {playlist_file}")
-    return playlist_file
-
-def download_media_files(playlist, media_dir):
-    """Download media files from the server and save them to media_dir."""
-    if not os.path.exists(media_dir):
-        os.makedirs(media_dir)
-        logger.info(f"Created directory {media_dir} for media files.")
-
-    updated_playlist = []
-    for media in playlist:
-        file_name = media.get('file_name', '')
-        file_url = media.get('url', '')
-        duration = media.get('duration', 10)
-        local_path = os.path.join(media_dir, file_name)
-        logger.info(f"Preparing to download {file_name} from {file_url}...")
-        if os.path.exists(local_path):
-            logger.info(f"File {file_name} already exists. Skipping download.")
-        else:
-            try:
-                response = requests.get(file_url, timeout=10)
-                if response.status_code == 200:
-                    with open(local_path, 'wb') as file:
-                        file.write(response.content)
-                    logger.info(f"Successfully downloaded {file_name} to {local_path}")
-                else:
-                    logger.error(f"Failed to download {file_name}. Status Code: {response.status_code}")
-                    continue
-            except requests.exceptions.RequestException as e:
-                logger.error(f"Error downloading {file_name}: {e}")
-                continue
-        updated_media = {
-            'file_name': file_name,
-            'url': os.path.relpath(local_path, os.path.dirname(media_dir)),
-            'duration': duration
-        }
-        updated_playlist.append(updated_media)
-    return updated_playlist
-
-def delete_old_playlists_and_media(current_version, playlist_dir, media_dir, keep_versions=1):
-    """
-    Delete old playlist files and media files not referenced by the latest playlist version.
-    keep_versions: number of latest versions to keep (default 1)
-    """
-    # Find all playlist files
-    playlist_files = [f for f in os.listdir(playlist_dir) if f.startswith('server_playlist_v') and f.endswith('.json')]
-    # Keep only the latest N versions
-    versions = sorted([int(f.split('_v')[-1].split('.json')[0]) for f in playlist_files], reverse=True)
-    keep = set(versions[:keep_versions])
-    # Delete old playlist files
-    for f in playlist_files:
-        v = int(f.split('_v')[-1].split('.json')[0])
-        if v not in keep:
-            os.remove(os.path.join(playlist_dir, f))
-    # Collect all media files referenced by the kept playlists
-    referenced = set()
-    for v in keep:
-        path = os.path.join(playlist_dir, f'server_playlist_v{v}.json')
-        if os.path.exists(path):
-            with open(path, 'r') as f:
-                data = json.load(f)
-            for item in data.get('playlist', []):
-                referenced.add(item.get('file_name'))
-    # Delete media files not referenced
-    for f in os.listdir(media_dir):
-        if f not in referenced:
-            try:
-                os.remove(os.path.join(media_dir, f))
-            except Exception as e:
-                logger.warning(f"Failed to delete media file {f}: {e}")
-
-def update_playlist_if_needed(local_playlist_path, config, media_dir, playlist_dir):
-    """
-    Fetch the server playlist once, compare versions, and update if needed.
-    Returns True if updated, False if already up to date.
-    Also sends feedback to server about playlist check.
-    """
-    server_data = fetch_server_playlist(config)
-    server_version = server_data.get('version', 0)
-    if not os.path.exists(local_playlist_path):
-        local_version = 0
-    else:
-        with open(local_playlist_path, 'r') as f:
-            local_data = json.load(f)
-        local_version = local_data.get('version', 0)
-    
-    logger.info(f"Local playlist version: {local_version}, Server playlist version: {server_version}")
-    
-    # Send feedback about playlist check
-    send_playlist_check_feedback(config, server_version if server_version > 0 else local_version)
-    
-    if local_version != server_version:
-        if server_data and server_data.get('playlist'):
-            updated_playlist = download_media_files(server_data['playlist'], media_dir)
-            server_data['playlist'] = updated_playlist
-            save_playlist_with_version(server_data, playlist_dir)
-            # Delete old playlists and unreferenced media
-            delete_old_playlists_and_media(server_version, playlist_dir, media_dir)
-            
-            # Send feedback about playlist update
-            player_name = config.get("screen_name", "unknown")
-            update_message = f"player {player_name}, playlist updated to v{server_version}"
-            send_player_feedback(config, update_message, "active", server_version)
-            
-            return True
-        else:
-            logger.warning("No playlist data fetched from server or playlist is empty.")
-            
-            # Send error feedback
-            send_player_error_feedback(config, "No playlist data fetched from server or playlist is empty", local_version)
-            
-            return False
-    else:
-        logger.info("Local playlist is already up to date.")
-        return False
-
-def is_playlist_up_to_date(local_playlist_path, config):
-    """
-    Compare the version of the local playlist with the server playlist.
-    Returns True if up-to-date, False otherwise.
-    """
-    if not os.path.exists(local_playlist_path):
-        logger.info(f"Local playlist file not found: {local_playlist_path}")
-        return False
-    with open(local_playlist_path, 'r') as f:
-        local_data = json.load(f)
-    local_version = local_data.get('version', 0)
-    server_data = fetch_server_playlist(config)
-    server_version = server_data.get('version', 0)
-    logger.info(f"Local playlist version: {local_version}, Server playlist version: {server_version}")
-    return local_version == server_version

working_files/player_auth.json

@@ -1,10 +0,0 @@
-{
-  "hostname": "tv-terasa",
-  "auth_code": "iiSyZDLWGyqNIxeRt54XYREgvAio11RwwU1_oJev6WI",
-  "player_id": 1,
-  "player_name": "TV-acasa 1",
-  "playlist_id": 1,
-  "orientation": "Landscape",
-  "authenticated": true,
-  "server_url": "http://digi-signage.moto-adv.com"
-}

working_files/server_response_debug.json

@@ -1,54 +0,0 @@
-{
-  "count": 5,
-  "player_id": 1,
-  "player_name": "TV-acasa 1",
-  "playlist": [
-    {
-      "description": null,
-      "duration": 15,
-      "file_name": "music.jpg",
-      "id": 1,
-      "position": 1,
-      "type": "image",
-      "url": "http://digi-signage.moto-adv.com/static/uploads/music.jpg"
-    },
-    {
-      "description": null,
-      "duration": 23,
-      "file_name": "130414-746934884.mp4",
-      "id": 2,
-      "position": 3,
-      "type": "video",
-      "url": "http://digi-signage.moto-adv.com/static/uploads/130414-746934884.mp4"
-    },
-    {
-      "description": null,
-      "duration": 15,
-      "file_name": "IMG_0386.jpeg",
-      "id": 4,
-      "position": 4,
-      "type": "image",
-      "url": "http://digi-signage.moto-adv.com/static/uploads/IMG_0386.jpeg"
-    },
-    {
-      "description": null,
-      "duration": 15,
-      "file_name": "AGC_20250704_204105932.jpg",
-      "id": 5,
-      "position": 5,
-      "type": "image",
-      "url": "http://digi-signage.moto-adv.com/static/uploads/AGC_20250704_204105932.jpg"
-    },
-    {
-      "description": null,
-      "duration": 15,
-      "file_name": "50194.jpg",
-      "id": 3,
-      "position": 6,
-      "type": "image",
-      "url": "http://digi-signage.moto-adv.com/static/uploads/50194.jpg"
-    }
-  ],
-  "playlist_id": 1,
-  "playlist_version": 9
-}

working_files/test_authentication.py

@@ -1,185 +0,0 @@
-#!/usr/bin/env python3
-"""
-Test script for Kiwy-Signage authentication with DigiServer v2
-Run this to verify authentication is working before updating main.py
-"""
-
-import sys
-import os
-
-# Add src directory to path
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'src'))
-
-from player_auth import PlayerAuth
-import json
-
-def load_app_config():
-    """Load existing app_config.json"""
-    # Try multiple possible locations
-    possible_paths = [
-        'config/app_config.json',
-        'resources/app_config.txt',
-        'src/config/app_config.json',
-        '../config/app_config.json'
-    ]
-    
-    for config_file in possible_paths:
-        if os.path.exists(config_file):
-            print(f"   Found config: {config_file}")
-            with open(config_file, 'r') as f:
-                return json.load(f)
-    
-    print(f"❌ Config file not found! Tried:")
-    for path in possible_paths:
-        print(f"   - {path}")
-    return None
-
-def test_authentication():
-    """Test authentication with DigiServer v2"""
-    print("=" * 60)
-    print("Kiwy-Signage Authentication Test")
-    print("=" * 60)
-    print()
-    
-    # Load config
-    print("📁 Loading configuration...")
-    config = load_app_config()
-    if not config:
-        return False
-    
-    server_ip = config.get('server_ip', '')
-    hostname = config.get('screen_name', '')
-    quickconnect = config.get('quickconnect_key', '')
-    port = config.get('port', '')
-    
-    print(f"   Server: {server_ip}:{port}")
-    print(f"   Hostname: {hostname}")
-    print(f"   Quick Connect: {'*' * len(quickconnect)}")
-    print()
-    
-    # Build server URL
-    import re
-    ip_pattern = r'^\d+\.\d+\.\d+\.\d+$'
-    if re.match(ip_pattern, server_ip):
-        server_url = f'http://{server_ip}:{port}'
-    else:
-        server_url = f'http://{server_ip}'
-    
-    print(f"🌐 Server URL: {server_url}")
-    print()
-    
-    # Test server connection
-    print("🔌 Testing server connection...")
-    try:
-        import requests
-        response = requests.get(f"{server_url}/api/health", timeout=5)
-        if response.status_code == 200:
-            data = response.json()
-            print(f"   ✅ Server is healthy (version: {data.get('version')})")
-        else:
-            print(f"   ⚠️  Server responded with status: {response.status_code}")
-    except Exception as e:
-        print(f"   ❌ Cannot connect to server: {e}")
-        print()
-        print("💡 Make sure DigiServer v2 is running and accessible!")
-        return False
-    print()
-    
-    # Initialize auth
-    print("🔐 Initializing authentication...")
-    auth = PlayerAuth(config_file='src/player_auth.json')
-    
-    # Check if already authenticated
-    if auth.is_authenticated():
-        print(f"   ℹ️  Found existing authentication")
-        print(f"   Player: {auth.get_player_name()}")
-        print()
-        
-        print("✓ Verifying saved authentication...")
-        valid, info = auth.verify_auth()
-        
-        if valid:
-            print(f"   ✅ Authentication is valid!")
-            print(f"   Player ID: {info['player_id']}")
-            print(f"   Player Name: {info['player_name']}")
-            print(f"   Group ID: {info.get('group_id', 'None')}")
-            print(f"   Orientation: {info.get('orientation', 'Landscape')}")
-            print()
-            
-            # Test playlist fetch
-            print("📋 Testing playlist fetch...")
-            playlist_data = auth.get_playlist()
-            if playlist_data:
-                version = playlist_data.get('playlist_version', 0)
-                content_count = len(playlist_data.get('playlist', []))
-                print(f"   ✅ Playlist received!")
-                print(f"   Version: {version}")
-                print(f"   Content items: {content_count}")
-            else:
-                print(f"   ⚠️  Could not fetch playlist")
-            print()
-            
-            # Test heartbeat
-            print("💓 Testing heartbeat...")
-            if auth.send_heartbeat(status='online'):
-                print(f"   ✅ Heartbeat sent successfully")
-            else:
-                print(f"   ⚠️  Heartbeat failed")
-            print()
-            
-            print("=" * 60)
-            print("✅ All tests passed! Player is ready to use.")
-            print("=" * 60)
-            return True
-        else:
-            print(f"   ❌ Saved authentication is expired or invalid")
-            print(f"   Re-authenticating...")
-            print()
-    
-    # Need to authenticate
-    print("🔑 Authenticating with server...")
-    success, error = auth.authenticate(
-        server_url=server_url,
-        hostname=hostname,
-        quickconnect_code=quickconnect
-    )
-    
-    if success:
-        print(f"   ✅ Authentication successful!")
-        print(f"   Player: {auth.get_player_name()}")
-        print(f"   Player ID: {auth.get_player_id()}")
-        print()
-        
-        # Save confirmation
-        print(f"💾 Authentication saved to: src/player_auth.json")
-        print()
-        
-        print("=" * 60)
-        print("✅ Authentication successful! Player is ready to use.")
-        print("=" * 60)
-        return True
-    else:
-        print(f"   ❌ Authentication failed: {error}")
-        print()
-        print("💡 Troubleshooting:")
-        print("   1. Check player exists in DigiServer v2 (hostname must match)")
-        print("   2. Verify quickconnect_key matches server configuration")
-        print("   3. Check server logs for authentication attempts")
-        print()
-        print("=" * 60)
-        print("❌ Authentication test failed")
-        print("=" * 60)
-        return False
-
-if __name__ == '__main__':
-    try:
-        success = test_authentication()
-        sys.exit(0 if success else 1)
-    except KeyboardInterrupt:
-        print("\n⚠️  Test cancelled by user")
-        sys.exit(1)
-    except Exception as e:
-        print(f"\n❌ Unexpected error: {e}")
-        import traceback
-        traceback.print_exc()
-        sys.exit(1)

working_files/test_card_reader.py

@@ -1,162 +0,0 @@
-#!/usr/bin/env python3
-"""
-Test script for USB card reader functionality
-"""
-
-import evdev
-from evdev import InputDevice, categorize, ecodes
-import time
-
-def list_input_devices():
-    """List all available input devices"""
-    print("\n=== Available Input Devices ===")
-    devices = [evdev.InputDevice(path) for path in evdev.list_devices()]
-    
-    # Exclusion keywords that help identify non-card-reader devices
-    exclusion_keywords = [
-        'touch', 'touchscreen', 'mouse', 'mice', 'trackpad', 
-        'touchpad', 'pen', 'stylus', 'video', 'button', 'lid'
-    ]
-    
-    for i, device in enumerate(devices):
-        device_name_lower = device.name.lower()
-        is_excluded = any(keyword in device_name_lower for keyword in exclusion_keywords)
-        is_likely_card = 'card' in device_name_lower or 'reader' in device_name_lower or 'rfid' in device_name_lower
-        
-        print(f"\n[{i}] {device.path}")
-        print(f"    Name: {device.name}")
-        print(f"    Phys: {device.phys}")
-        
-        capabilities = device.capabilities()
-        if ecodes.EV_KEY in capabilities:
-            print(f"    Type: Keyboard/HID Input Device")
-            
-            # Add helpful hints
-            if is_likely_card:
-                print(f"    ** LIKELY CARD READER **")
-            elif is_excluded:
-                print(f"    (Excluded: appears to be touch/mouse/other non-card device)")
-            elif 'usb' in device_name_lower and 'keyboard' in device_name_lower:
-                print(f"    (USB Keyboard - could be card reader)")
-    
-    return devices
-
-def test_card_reader(device_index=None):
-    """Test reading from a card reader device"""
-    devices = [evdev.InputDevice(path) for path in evdev.list_devices()]
-    
-    # Exclusion keywords (same as in main app)
-    exclusion_keywords = [
-        'touch', 'touchscreen', 'mouse', 'mice', 'trackpad', 
-        'touchpad', 'pen', 'stylus', 'video', 'button', 'lid'
-    ]
-    
-    if device_index is not None:
-        if device_index >= len(devices):
-            print(f"Error: Device index {device_index} out of range")
-            return
-        device = devices[device_index]
-    else:
-        # Try to find a card reader automatically using same logic as main app
-        device = None
-        
-        # Priority 1: Explicit card readers
-        for dev in devices:
-            device_name_lower = dev.name.lower()
-            if any(keyword in device_name_lower for keyword in exclusion_keywords):
-                continue
-            if 'card' in device_name_lower or 'reader' in device_name_lower or 'rfid' in device_name_lower or 'hid' in device_name_lower:
-                capabilities = dev.capabilities()
-                if ecodes.EV_KEY in capabilities:
-                    device = dev
-                    print(f"Found card reader: {dev.name}")
-                    break
-        
-        # Priority 2: USB keyboards
-        if not device:
-            for dev in devices:
-                device_name_lower = dev.name.lower()
-                if any(keyword in device_name_lower for keyword in exclusion_keywords):
-                    continue
-                if 'usb' in device_name_lower and 'keyboard' in device_name_lower:
-                    capabilities = dev.capabilities()
-                    if ecodes.EV_KEY in capabilities:
-                        device = dev
-                        print(f"Using USB keyboard as card reader: {dev.name}")
-                        break
-        
-        # Priority 3: Any non-excluded keyboard
-        if not device:
-            for dev in devices:
-                device_name_lower = dev.name.lower()
-                if any(keyword in device_name_lower for keyword in exclusion_keywords):
-                    continue
-                capabilities = dev.capabilities()
-                if ecodes.EV_KEY in capabilities:
-                    device = dev
-                    print(f"Using keyboard device as card reader: {dev.name}")
-                    break
-        
-        if not device:
-            print("No suitable input device found!")
-            return
-    
-    print(f"\n=== Testing Card Reader ===")
-    print(f"Device: {device.name}")
-    print(f"Path: {device.path}")
-    print("\nSwipe your card now (press Ctrl+C to exit)...\n")
-    
-    card_data = ""
-    
-    try:
-        for event in device.read_loop():
-            if event.type == ecodes.EV_KEY:
-                key_event = categorize(event)
-                
-                if key_event.keystate == 1:  # Key down
-                    key_code = key_event.keycode
-                    
-                    # Handle Enter key (card read complete)
-                    if key_code == 'KEY_ENTER':
-                        print(f"\n✓ Card data received: '{card_data}'")
-                        print(f"  Length: {len(card_data)} characters")
-                        print(f"  Processed ID: card_{card_data.strip().upper()}")
-                        print("\nReady for next card swipe...")
-                        card_data = ""
-                    
-                    # Build card data string
-                    elif key_code.startswith('KEY_'):
-                        char = key_code.replace('KEY_', '')
-                        if len(char) == 1:  # Single character
-                            card_data += char
-                            print(f"Reading: {card_data}", end='\r', flush=True)
-                        elif char.isdigit():  # Handle numeric keys
-                            card_data += char
-                            print(f"Reading: {card_data}", end='\r', flush=True)
-                            
-    except KeyboardInterrupt:
-        print("\n\nTest stopped by user")
-    except Exception as e:
-        print(f"\nError: {e}")
-
-if __name__ == "__main__":
-    print("USB Card Reader Test Tool")
-    print("=" * 50)
-    
-    devices = list_input_devices()
-    
-    if not devices:
-        print("\nNo input devices found!")
-        exit(1)
-    
-    print("\n" + "=" * 50)
-    choice = input("\nEnter device number to test (or press Enter for auto-detect): ").strip()
-    
-    if choice:
-        try:
-            device_index = int(choice)
-            test_card_reader(device_index)
-        except ValueError:
-            print("Invalid device number!")
-    else:
-        test_card_reader()

working_files/test_connection.py

@@ -1,138 +0,0 @@
-#!/usr/bin/env python3
-"""Test server connection and playlist fetch."""
-
-import json
-import sys
-import os
-
-# Add src directory to path
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'src'))
-
-from player_auth import PlayerAuth
-
-# Load config
-config_file = 'config/app_config.json'
-with open(config_file, 'r') as f:
-    config = json.load(f)
-
-print("=" * 80)
-print("SERVER CONNECTION TEST")
-print("=" * 80)
-
-server_ip = config.get("server_ip", "")
-screen_name = config.get("screen_name", "")
-quickconnect_key = config.get("quickconnect_key", "")
-port = config.get("port", "")
-
-print(f"\nConfiguration:")
-print(f"  Server: {server_ip}")
-print(f"  Port: {port}")
-print(f"  Screen Name: {screen_name}")
-print(f"  QuickConnect: {quickconnect_key}")
-
-# Build server URL
-if server_ip.startswith('http://') or server_ip.startswith('https://'):
-    server_url = server_ip
-    # If it has https but port 443 is specified, ensure port is included if non-standard
-    if not ':' in server_ip.replace('https://', '').replace('http://', ''):
-        if port and port != '443' and port != '80':
-            server_url = f"{server_ip}:{port}"
-else:
-    # Use https for port 443, http for others
-    protocol = "https" if port == "443" else "http"
-    server_url = f"{protocol}://{server_ip}:{port}"
-
-print(f"\nServer URL: {server_url}")
-
-# Test authentication
-print("\n" + "=" * 80)
-print("1. TESTING AUTHENTICATION")
-print("=" * 80)
-
-auth = PlayerAuth('src/player_auth.json')
-
-# Check if already authenticated
-if auth.is_authenticated():
-    print("✓ Found existing authentication")
-    valid, message = auth.verify_auth()
-    if valid:
-        print(f"✓ Auth is valid: {message}")
-    else:
-        print(f"✗ Auth expired: {message}")
-        print("\nRe-authenticating...")
-        success, error = auth.authenticate(
-            server_url=server_url,
-            hostname=screen_name,
-            quickconnect_code=quickconnect_key
-        )
-        if success:
-            print(f"✓ Re-authentication successful!")
-        else:
-            print(f"✗ Re-authentication failed: {error}")
-            sys.exit(1)
-else:
-    print("No existing authentication found. Authenticating...")
-    success, error = auth.authenticate(
-        server_url=server_url,
-        hostname=screen_name,
-        quickconnect_code=quickconnect_key
-    )
-    if success:
-        print(f"✓ Authentication successful!")
-    else:
-        print(f"✗ Authentication failed: {error}")
-        sys.exit(1)
-
-# Test playlist fetch
-print("\n" + "=" * 80)
-print("2. TESTING PLAYLIST FETCH")
-print("=" * 80)
-
-playlist_data = auth.get_playlist()
-
-if playlist_data:
-    print(f"✓ Playlist fetched successfully!")
-    print(f"\nPlaylist Version: {playlist_data.get('playlist_version', 'N/A')}")
-    print(f"Number of items: {len(playlist_data.get('playlist', []))}")
-    
-    print("\n" + "-" * 80)
-    print("PLAYLIST ITEMS:")
-    print("-" * 80)
-    
-    for idx, item in enumerate(playlist_data.get('playlist', []), 1):
-        print(f"\n{idx}. File: {item.get('file_name', 'N/A')}")
-        print(f"   URL: {item.get('url', 'N/A')}")
-        print(f"   Duration: {item.get('duration', 'N/A')}s")
-        
-        # Check if URL is relative or absolute
-        url = item.get('url', '')
-        if url.startswith('http://') or url.startswith('https://'):
-            print(f"   Type: Absolute URL")
-        else:
-            print(f"   Type: Relative path (will fail to download!)")
-    
-    # Save full response
-    with open('server_response_debug.json', 'w') as f:
-        json.dump(playlist_data, f, indent=2)
-    print(f"\n✓ Full response saved to: server_response_debug.json")
-    
-    print("\n" + "=" * 80)
-    print("SUMMARY")
-    print("=" * 80)
-    print(f"Server has: {len(playlist_data.get('playlist', []))} files")
-    print(f"Local has: 3 files (from playlists/server_playlist_v8.json)")
-    
-    if len(playlist_data.get('playlist', [])) > 3:
-        print(f"\n⚠️  PROBLEM: Server has {len(playlist_data.get('playlist', []))} files but only 3 were saved!")
-        print("\nMissing files are likely:")
-        local_files = ['music.jpg', '130414-746934884.mp4', 'IMG_0386.jpeg']
-        server_files = [item.get('file_name', '') for item in playlist_data.get('playlist', [])]
-        missing = [f for f in server_files if f not in local_files]
-        for f in missing:
-            print(f"  - {f}")
-    
-else:
-    print("✗ Failed to fetch playlist")
-    sys.exit(1)
-
-print("\n" + "=" * 80)

working_files/test_direct_api.py

@@ -1,55 +0,0 @@
-#!/usr/bin/env python3
-"""Direct API test to check server playlist."""
-
-import requests
-import json
-
-# Try with the saved auth
-auth_file = 'src/player_auth.json'
-with open(auth_file, 'r') as f:
-    auth_data = json.load(f)
-
-server_url = auth_data['server_url']
-auth_code = auth_data['auth_code']
-
-print("=" * 80)
-print("DIRECT API TEST")
-print("=" * 80)
-print(f"Server: {server_url}")
-print(f"Auth code: {auth_code[:20]}...")
-print()
-
-# Try to get playlist
-try:
-    url = f"{server_url}/api/player/playlist"
-    headers = {
-        'Authorization': f'Bearer {auth_code}'
-    }
-    
-    print(f"Fetching: {url}")
-    response = requests.get(url, headers=headers, timeout=10)
-    
-    print(f"Status: {response.status_code}")
-    
-    if response.status_code == 200:
-        data = response.json()
-        print(f"\nPlaylist version: {data.get('playlist_version', 'N/A')}")
-        print(f"Number of items: {len(data.get('playlist', []))}")
-        
-        print("\nPlaylist items:")
-        for idx, item in enumerate(data.get('playlist', []), 1):
-            print(f"\n  {idx}. {item.get('file_name', 'N/A')}")
-            print(f"     URL: {item.get('url', 'N/A')}")
-            print(f"     Duration: {item.get('duration', 'N/A')}s")
-        
-        # Save full response
-        with open('server_playlist_full.json', 'w') as f:
-            json.dump(data, f, indent=2)
-        print(f"\nFull response saved to: server_playlist_full.json")
-    else:
-        print(f"Error: {response.text}")
-        
-except Exception as e:
-    print(f"Error: {e}")
-
-print("\n" + "=" * 80)

working_files/test_playback_logging.py

@@ -1,82 +0,0 @@
-#!/usr/bin/env python3
-"""
-Test script to verify the enhanced logging without running the full GUI
-"""
-import os
-import json
-
-def simulate_playback_check():
-    """Simulate the playback logic to see what would happen"""
-    
-    base_dir = os.path.dirname(os.path.abspath(__file__))
-    media_dir = os.path.join(base_dir, 'media')
-    playlists_dir = os.path.join(base_dir, 'playlists')
-    
-    # Supported extensions
-    VIDEO_EXTENSIONS = ['.mp4', '.avi', '.mkv', '.mov', '.webm']
-    IMAGE_EXTENSIONS = ['.jpg', '.jpeg', '.png', '.bmp', '.gif']
-    
-    # Load playlist
-    playlist_file = os.path.join(playlists_dir, 'server_playlist_v8.json')
-    with open(playlist_file, 'r') as f:
-        data = json.load(f)
-    
-    playlist = data.get('playlist', [])
-    
-    print("=" * 80)
-    print("SIMULATING PLAYBACK SEQUENCE")
-    print("=" * 80)
-    
-    for idx, media_item in enumerate(playlist):
-        file_name = media_item.get('file_name', '')
-        duration = media_item.get('duration', 10)
-        
-        print(f"\n[STEP {idx + 1}] ===== Playing item {idx + 1}/{len(playlist)} =====")
-        print(f"  File: {file_name}")
-        print(f"  Duration: {duration}s")
-        
-        # Construct path
-        media_path = os.path.join(media_dir, file_name)
-        print(f"  Full path: {media_path}")
-        
-        # Check existence
-        if not os.path.exists(media_path):
-            print(f"  \u274c Media file not found: {media_path}")
-            print(f"  ACTION: Skipping to next media...")
-            continue
-        
-        file_size = os.path.getsize(media_path)
-        print(f"  \u2713 File exists (size: {file_size:,} bytes)")
-        
-        # Check extension
-        file_extension = os.path.splitext(file_name)[1].lower()
-        print(f"  Extension: {file_extension}")
-        
-        if file_extension in VIDEO_EXTENSIONS:
-            print(f"  Media type: VIDEO")
-            print(f"  ACTION: play_video('{media_path}', {duration})")
-            print(f"  - Creating Video widget...")
-            print(f"  - Adding to content area...")
-            print(f"  - Scheduling next media in {duration}s")
-            print(f"  \u2713 Media started successfully")
-        elif file_extension in IMAGE_EXTENSIONS:
-            print(f"  Media type: IMAGE")
-            print(f"  ACTION: play_image('{media_path}', {duration})")
-            print(f"  - Creating AsyncImage widget...")
-            print(f"  - Adding to content area...")
-            print(f"  - Scheduling next media in {duration}s")
-            print(f"  \u2713 Image displayed successfully")
-        else:
-            print(f"  \u274c Unsupported media type: {file_extension}")
-            print(f"  Supported: .mp4/.avi/.mkv/.mov/.webm/.jpg/.jpeg/.png/.bmp/.gif")
-            print(f"  ACTION: Skipping to next media...")
-            continue
-        
-        print(f"\n  [After {duration}s] Transitioning to next media (was index {idx})")
-    
-    print("\n" + "=" * 80)
-    print("END OF PLAYLIST - Would restart from beginning")
-    print("=" * 80)
-
-if __name__ == '__main__':
-    simulate_playback_check()

working_files/test_server_playlist.py

@@ -1,45 +0,0 @@
-#!/usr/bin/env python3
-"""Test script to check what playlist the server is actually returning."""
-
-import json
-import sys
-import os
-
-# Add src directory to path
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'src'))
-
-from get_playlists_v2 import fetch_server_playlist
-
-# Load config
-config_file = 'config/app_config.json'
-with open(config_file, 'r') as f:
-    config = json.load(f)
-
-print("=" * 80)
-print("TESTING SERVER PLAYLIST FETCH")
-print("=" * 80)
-
-# Fetch playlist from server
-print("\n1. Fetching playlist from server...")
-server_data = fetch_server_playlist(config)
-
-print(f"\n2. Server Response:")
-print(f"   Version: {server_data.get('version', 'N/A')}")
-print(f"   Playlist items: {len(server_data.get('playlist', []))}")
-
-print(f"\n3. Detailed Playlist Items:")
-for idx, item in enumerate(server_data.get('playlist', []), 1):
-    print(f"\n   Item {idx}:")
-    print(f"      file_name: {item.get('file_name', 'N/A')}")
-    print(f"      url: {item.get('url', 'N/A')}")
-    print(f"      duration: {item.get('duration', 'N/A')}")
-
-print("\n" + "=" * 80)
-print(f"TOTAL: Server has {len(server_data.get('playlist', []))} files")
-print("=" * 80)
-
-# Save to file for inspection
-output_file = 'server_response_debug.json'
-with open(output_file, 'w') as f:
-    json.dump(server_data, f, indent=2)
-print(f"\nFull server response saved to: {output_file}")