Kiwy-Signage/.github/instructions/kiwy-build-and-development.instructions.md

description, name

description	name
Use when building, compiling, packaging or releasing the Kiwy Signage Player: PyInstaller build, .exe generation, build.spec, hiddenimports, code signing, Smart App Control, Windows development, Raspberry Pi deployment, or adding new modules under src/. Covers the exact build commands, environment constraints, bundling rules and verification steps.	Kiwy Build & Development

Kiwy Signage Player — Build & Development

Cross-platform Kivy digital signage player.

• Raspberry Pi / Linux — src/main.py is the entry point (root install.sh, start.sh).
• Windows — windows/run_win.py is the entry point; it sets Windows env vars, imports main.py, then monkey-patches platform differences. Packaged to .exe with PyInstaller.

Ground Rules

• Keep src/main.py cross-platform. Windows-specific behaviour belongs in windows/run_win.py (see _patch_main()), Pi-specific behaviour in main.py guarded by capability checks. Do not add Windows-only imports to main.py.
• Rebuild is mandatory. The .exe bundles src/, so Python edits are invisible until you rebuild. There is no hot reload in the packaged app.
• dist/ is a runtime folder, not just build output. It holds config/, media/, playlists/, logs/, .kiosk-profile/ and .player_heartbeat. Never wipe dist/ blindly; a --clean rebuild preserves it, but a manual delete destroys player state.

Environment

Item	Value
Interpreter	Python 3.12.9 (64-bit) — project venv at windows\venv
Kivy	2.3.1
PyInstaller	6.21.0
Linux target	Python 3.13 (repo/python-wheels/, repo/system-packages/)

• 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 (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

From windows\:

venv\Scripts\python.exe -m PyInstaller build.spec --clean --noconfirm

Or the full one-click path (creates venv, installs deps, builds, then signs):

build_win.bat

Output (folder mode, via COLLECT):

windows\dist\KiwySignagePlayer\KiwySignagePlayer.exe   <- the real build output

Deployment hazard: windows\dist\KiwySignagePlayer.exe (one level up) is a stale leftover from an older single-file build of the same name. It is not refreshed by the current spec, so deploying it ships old code. Always take the executable from the KiwySignagePlayer\ subfolder, and delete the stray copy if it reappears.

build.spec facts

• Entry point run_win.py; pathex=[BUILD_DIR, SRC_DIR] so src/ modules resolve.
• runtime_hooks=[pyi_runtime_hook.py] — sets per-monitor DPI awareness before SDL/Kivy initialise. Keep DPI work here; it must run before any window is created.
• datas += Tree(src) bundles all of src/. console=True so startup errors and the Kivy log remain visible — do not flip this to False without a reason.
• hiddenimports must list modules that PyInstaller's static analysis cannot see: lazily imported ones (cef_browser is imported inside a function) or dynamic imports (getattr, importlib). Top-level imports such as weblink_session are found automatically via pathex, but listing them is harmless insurance. When you add a module under src/ that is imported lazily or by string, add it to hiddenimports or the packaged exe will fail at runtime with ModuleNotFoundError.
• 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, UMCI enforced) with no "Run anyway" bypass — an unsigned exe is blocked at kernel level.

• A self-signed certificate does NOT satisfy Smart App Control. A cert from a reputable public CA is required. create_self_signed_cert.ps1 is dev-only.
• Provide a cert as KIWY_SIGN_PFX (+ optional KIWY_SIGN_PFX_PASSWORD) or drop kiwy_signing.pfx in windows\; build_win.bat then signs via sign_exe.ps1 (signtool with RFC3161 timestamp when available).
• See documentation/CODE_SIGNING_SMART_APP_CONTROL.md.

Verify Before Committing

Fast syntax gate (no build, seconds):

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 hold locks; if the build fails, check for stray msedge.exe / chrome.exe before retrying.

Because .exe is a reserved Windows device name as well as a real file, use Test-Path -LiteralPath when probing for the executable, otherwise the path silently resolves to the console device.

Development run — use this on a SAC-locked host, since the unsigned exe cannot launch:

cd windows
venv\Scripts\activate
python run_win.py

Diagnose playback transitions via the trace log (logs\playback_trace.log), written by src/playback_trace.py.

Release Checklist

1. Bump PLAYER_VERSION in src/main.py and filevers/prodvers/FileVersion/ ProductVersion in windows\version_info.txt; keep them in sync.
2. Rebuild (build_win.bat).
3. Confirm the exe is signed (Get-AuthenticodeSignature); unsigned builds are blocked on production hosts.
4. Smoke-test a mixed playlist: image → video → weblink → image, verifying durations, audio (audio: off / muted), and a clean exit/restart.

Commit Hygiene

• Never commit windows\build\ or windows\dist\ (git-ignored). Tracked build output such as windows\archive_list.txt and windows\build_last.txt is the exception, not the rule.
• Do not commit player_auth.json or src/player_auth.json — they contain live credentials (auth_code, player_id, server_url). These are currently tracked; treat any future change to them as a deliberate, reviewed decision.
• Do not commit config\app_config.json values that are host-specific without checking whether they belong in the repo default.