ske087/Kiwy-Signage
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix video hang and silent-video crash; add 24/7 watchdog

Browse Source 
Two independent failures were killing long unattended runs.

1. HANG at the end of a video (Windows AppHangB1)

The player froze after ~30-45 minutes of looping, always at a video item. The
playback trace stopped dead right after "video_loaded" with no "video_eos" and
no "advance_after_video_eos", and Windows logged AppHangB1 rather than a crash.

Cause, all inside Kivy and verified against the installed source:

  1. ffpyplayer fires on_eos.
  2. Kivy's Video widget binds its OWN handler first (kivy/uix/video.py
     _do_video_load), and that handler sets state = 'stop' DURING the event
     dispatch.
  3. state = 'stop' -> VideoFFPy.stop() -> unload(), which calls
     self._thread.join() with no timeout (the source even carries the comment
     "TODO: use callback, don't block here").
  4. When that decode thread is slow to exit, the Kivy/SDL main thread never
     returns, so the window stops pumping messages.

It is a race, which is why it looked random and only appeared after many videos.

src/video_safety.py bounds that join. ffpyplayer has already been told to quit
and its thread woken before the join, so limiting the wait does not leak work;
it only stops an unresponsive thread from taking the whole player down. The
guard is installed before the Video widget is constructed, because the decode
thread is created during play().

The intro video had the same hazard on the main thread (state='stop' followed by
unload() inside the state callback) and is now torn down on a worker thread like
playlist videos.

2. CRASH in SDL2_mixer.dll (0xc0000005) on a video with no audio stream

Triggered when a silent 4K clip entered the playlist while the item was marked
audio: on. ffpyplayer initialises SDL2_mixer from the FIRST audio file it opens
and reuses those parameters, so a file with no audio stream (rate/channels 0)
makes SDL2_mixer dereference garbage. Muting via volume=0.0 does NOT avoid it -
the audio stream itself must be disabled.

play_video now probes the file with ffprobe and forces mute when it has no audio
track, so such a file can never reach ffpyplayer with sound enabled. The probe
fails safe (assumes audio present) if ffprobe is unavailable.

3. 24/7 supervision (solution A + C)

windows/watchdog.ps1 + start_player_watchdog.bat restart the player when it
crashes (process gone) or hangs (process alive but .player_heartbeat stale),
with a crash-loop breaker that backs off when it cannot stay up. This is the
Windows counterpart of the proven Linux start.sh watchdog.

The exit-screen password remains the only supported way to stop the player. On
success it writes .player_stop_requested next to the .exe and the watchdog
stands down instead of restarting. The flag is SESSION SCOPED: the watchdog
clears it on every start, so launching again begins a new session and there is
no file to delete by hand. Clearing on start also means a power cut cannot leave
the player permanently off.

Deliberately NOT done: a Windows service. A service runs in session 0 with no
desktop, so the player could not render to the screen at all. A login-triggered
startup entry is the correct Windows analogue of the Pi's systemd unit.

Important detail: the packaged player is TWO processes (PyInstaller bootloader
parent plus the child that owns the SDL window), so any kill uses taskkill /T or
the visible window survives and the next launch collides with it.

Verified in the packaged exe over a 7-hour run: 170 playlist restarts, 1365
items, 171 web links launched/visible/ended with zero failures, and no crashes,
no hangs and no leaked browser processes.

Tests: windows/test_video_hang.py and windows/test_watchdog.py. The hang test
deliberately holds the heartbeat open with an exclusive Windows lock (share mode
0) so the player's own write fails - backdating the file's mtime does NOT
simulate a hang, because the healthy player rewrites it immediately and the test
would then pass for the wrong reason.
This commit is contained in:
ske087
2026-09-13 10:14:42 +03:00
parent 9f5409685d
commit d8c6ab0bc5
8 changed files with 1851 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/instructions/kiwy-build-and-development.instructions.md
+138 -5
View File
@@ -33,10 +33,19 @@ Cross-platform Kivy digital signage player.
- **Python 3.13+/3.14 is NOT supported for the Windows build** — Kivy 2.3.1 has no wheels
for them.
- `cefpython3` is **not installed** in the project venv. The embedded-CEF web-link engine is
therefore unavailable and web links fall back to the Chrome/Edge subprocess adapter.
Installing `cefpython3` (uncomment it in `windows/requirements_win.txt`) restores the
CEF engine.
- `cefpython3` is **not installed** in the project venv (its wheels stop at Python 3.9).
The embedded-CEF engine in `windows/cef_browser.py` is therefore dormant on this
build — do not rely on it.
- **Web links use embedded WebView2** (`windows/webview2_browser.py`), driven through
`pythonnet` (installed). Two extra things ship with the exe:
- `windows/webview2_sdk/` — ~860 KB of SDK DLLs (`Microsoft.Web.WebView2.Core.dll`,
`WebView2Loader.dll`). **Tracked in git on purpose**: without them WebView2
silently downgrades to the Chrome/Edge subprocess engine.
- `windows/webview2_runtime/MicrosoftEdgeWebview2Setup.exe` — ~1.7 MB bootstrapper,
used to install the Runtime on a machine that lacks it. The ~203 MB offline
standalone installer is **git-ignored**; fetch it with
`windows/webview2_runtime/download_runtime_installers.ps1 -Offline` when you need
to deploy to machines with no internet (it makes the exe ~305 MB).
## Build
@@ -79,6 +88,118 @@ current spec, so deploying it ships old code. Always take the executable from th
- `excluded_imports` drops Linux-only packages (`evdev`, `gi`, GStreamer) and the
non-matching `cefpython3` `.pyd` variants.
## First-run setup (no bundled credentials)
`config/app_config.json` is **deliberately NOT bundled** into the exe, and
`player_auth.json` is excluded from `Tree(src)`. Shipping either one planted the
build machine's `server_ip` / `screen_name` / `auth_code` into every install, so
a fresh machine silently connected to the wrong server (or played a stale
playlist) instead of asking.
What happens on a machine with no usable config:
1. The splash video (`config/resources/intro1.mp4`) plays.
2. A notice appears: *"Player is not configured"*.
3. After `SETUP_NOTICE_SECONDS` (**5 s**, `src/main.py`) the Settings screen
opens automatically.
4. Saving valid values writes `config/app_config.json` next to the **.exe** and
playback starts immediately — no restart needed.
On a machine that **is** configured, the notice and Settings are skipped and the
cached playlist plays straight away.
Key functions in `src/main.py`:
| Name | Role |
|------|------|
| `config_is_configured(config)` | Single source of truth. Missing file, empty/unparseable JSON, missing keys and leftover placeholders (`localhost`, `kivy-player`, `1234567`, `127.0.0.1`) all count as **unconfigured**. |
| `DEFAULT_CONFIG` | Blank-credential starting point, so a fresh install can never look configured. |
| `SignagePlayer.on_intro_finished()` | The one decision point after the splash: setup vs. playback. Both intro paths (video end and "no intro file") go through it. |
| `show_setup_required_notice()` | Shows the notice, then opens Settings after 5 s. |
| `on_first_run_config_saved()` | Re-syncs and starts playback. |
`config_is_configured()` is covered by `windows/test_first_run_setup.py` — run it
after touching that logic.
> When adding a new **required** config key, add it to `CONFIG_REQUIRED_KEYS`
> (and to `CONFIG_PLACEHOLDER_VALUES` if it has a placeholder default), or the
> first-run flow will not ask for it.
## 24/7 Supervision (Windows)
A signage player must survive crashes and hangs unattended. On **Linux/Pi** this is
`start.sh` (systemd or `./start.sh`). On **Windows** it is `windows/watchdog.ps1`,
launched by `windows/start_player_watchdog.bat`.
It restarts the player when it:
- **crashed** — the process disappeared; or
- **hung** — the process is alive but `.player_heartbeat` has gone stale
(the player rewrites it every 10 s; the watchdog treats >60 s as hung). A frozen
player is otherwise indistinguishable from a working one.
It also backs off if the player cannot stay up (crash-loop breaker:
`CrashLoopMaxFailures` failures in `CrashLoopWindowMin` minutes without ever
becoming healthy → `CrashLoopBackoffMin` minutes of quiet).
### The stop flag is SESSION-SCOPED
The only supported way to stop the player is the **exit-screen password**. On
success the player writes `.player_stop_requested` next to its `.exe`, and the
watchdog then **stands down instead of restarting**.
The flag is cleared **every time the watchdog starts**, which is what makes it
session-scoped: the password exit ends the *current* session, and the next launch
begins a new one. There is no file to delete by hand.
> **Ordering matters:** the flag is the operationally-correct choice over a
> "remember the last exit" setting, because a reboot must come back up playing.
> Clearing on start also means a power cut cannot leave the player permanently off.
### Two failure modes that must not be confused
| Situation | Correct reaction |
|---|---|
| Was healthy, then heartbeat went stale | **Restart promptly** (this is a hang) |
| Running but never became healthy (slow start, bad install, the **first-run setup screen**) | **Be patient**, then restart after `2 × StartupGraceSec` |
Never kill a player that has not yet been healthy — it may be an operator entering
server settings on the first-run setup screen.
### Important Windows-specific facts
- The packaged player is **TWO processes** (PyInstaller bootloader parent + the
child that owns the SDL window). Any kill must use `taskkill /T` or the visible
window survives and the next launch collides with it.
- The watchdog can only *restart* an install that already has a working config.
It cannot help before the player has first run.
- Hiding the console window (`console=False`) is **not** done: the console is the
only way to see a start-up failure, and the build instructions warn against
flipping it without reason.
- **No Windows service.** A service runs in session 0 with no desktop, so the
player could not render to the screen. A login-triggered task is the correct
Windows counterpart to the Pi's systemd unit — that is what
`start_player_watchdog.bat` is for (add it to the Startup folder for autostart).
### Verify the watchdog
```
cd windows
venv\Scripts\python.exe test_watchdog.py # crash + hang + stop-flag + new-session
```
Check state at any time (read-only):
```
powershell -NoProfile -ExecutionPolicy Bypass -File windows\watchdog.ps1 -Status
```
> When testing a hang, do **not** just backdate the heartbeat file's mtime — the
> healthy player rewrites it immediately, so nothing is actually stale and the
> test passes for the wrong reason. Hold the file open with an exclusive Windows
> lock (share mode 0) so the player's own write fails; that reproduces a genuine
> stale heartbeat while the process stays alive.
## Code Signing (production constraint)
Production PCs run with **Smart App Control enforced** (`VerifiedAndReputablePolicyState=1`,
@@ -96,9 +217,21 @@ UMCI enforced) with **no "Run anyway" bypass** — an unsigned exe is blocked at
Fast syntax gate (no build, seconds):
```
python -m py_compile src/main.py src/weblink_session.py windows/run_win.py
python -m py_compile src/main.py src/weblink_session.py windows/run_win.py windows/webview2_browser.py windows/webview2_runtime.py
```
Web-link engine checks (no build, no player):
```
cd windows
venv\Scripts\python.exe test_webview2_embed.py # embeds WebView2 in a bare Win32 window
venv\Scripts\python.exe test_webview2_runtime.py # Runtime detection + installer discovery
```
Rebuild warning: the bundled offline installer makes the exe ~305 MB. If you do not
need offline machines, delete
`windows/webview2_runtime/MicrosoftEdgeWebView2RuntimeInstallerX64.exe` before building.
**Close the running player before rebuilding.** A running
`dist\KiwySignagePlayer\KiwySignagePlayer.exe` locks the output and the build fails with
"Access is denied". Chrome/Edge kiosk processes left over from web-link playback can also