Kiwy-Signage/windows/development-track.md

🧪 Development Track — Kiwy Signage Player (Windows Edition)

This file tracks every change, bug fix, tested solution, build info, and pending issues for the Windows port. Read this FIRST before starting any debugging or coding session.

---

📅 Current Session — 2026-07-24

Field	Value
Branch	Windows-Player
Python	3.12.9 — C:\Users\Dell-PC\AppData\Local\Programs\Python\Python312\python.exe
Venv	windows\venv312\ (pre-built, all deps installed)
Kivy	2.3.1
PyInstaller	6.21.0
Last .exe build	2026-07-24 13:47 — windows\dist\KiwySignagePlayer\KiwySignagePlayer.exe (96 MB)
Build command	Set-Location windows; venv312\Scripts\python.exe -m PyInstaller build.spec --clean --noconfirm

⚠️ Python Version Constraints

• Python 3.12.9 — ✅ Confirmed working. Has pre-built Kivy 2.3.1 wheels.
• Python 3.13 — ❌ Kivy wheels NOT available for Windows.
• Python 3.14 — ❌ Tested 2026-07-24. kivy_deps.sdl2_dev~=0.8.0 has no cp314 wheel. → Solution: removed Python 3.14 from system, keeping only 3.12.9.

---

🐛 Bug Tracker

[BUG-001] RecursionError: play_current_media ↔ restart_playlist

• Status: ✅ Fixed 2026-07-24
• Symptom: Pressing "Restart Player" in settings with empty playlist causes infinite recursion: play_current_media → restart_playlist → play_current_media → ...
• Fix: Added empty-playlist guard in both play_current_media() and restart_playlist() → they return early instead of calling each other.
• Files: src/main.py — lines ~1304 and ~2073
• Test: Verified no Python syntax errors via ast.parse.

[BUG-002] Settings fields cut off on small screens

• Status: ✅ Fixed 2026-07-24
• Symptom: "Screen Name", "Quickconnect" and other fields at the top of the settings popup are invisible on smaller resolutions because content overflows the popup.
• Fix: Wrapped settings content in a ScrollView. Moved "Save & Close" / "Cancel" buttons outside the scroll (always visible). Reduced row heights.
• Files: src/signage_player.kv — <SettingsPopup@Popup> block

[BUG-003] Chromium not fullscreen on Windows

• Status: ✅ Fixed 2026-07-24
• Symptom: Web links open in a small window instead of fullscreen.
• Fix: Changed launch args from --kiosk to --start-maximized --app=URL
  • explicit --window-size=WxH. --kiosk uses Wayland exclusive-fullscreen protocol which doesn't work on Windows.
• Tested rejected solutions:
  • ❌ --kiosk alone → small window, no fullscreen
  • ❌ --start-fullscreen alone → not reliable
  • ✅ --start-maximized --app=URL --window-size=... → works
• Files: windows/run_win.py — _windows_play_weblink()

[BUG-004] Desktop flash when switching between Chromium and Kivy

• Status: ✅ Fixed 2026-07-24
• Symptom: When Chrome closes, the desktop is briefly visible before Kivy reappears. Also when Chrome opens, there's a flash.
• Fix: Added _Win32Overlay class — a fullscreen black Win32 window that covers the screen during transitions. Shown BEFORE closing Chrome / opening Chrome, hidden AFTER Kivy is ready.
• Tested rejected solutions:
  • ❌ Window.raise_window() alone → still shows flash
  • ✅ Win32 black overlay → smooth masking
• Files: windows/run_win.py — _Win32Overlay class

[BUG-005] Chrome processes linger after closing weblink

• Status: ✅ Fixed 2026-07-24
• Symptom: After a weblink item ends, Chrome child processes (GPU, renderer) remain running → blank windows accumulate.
• Fix: Use taskkill /F /T /PID <pid> to kill the entire process tree.
• Tested rejected solutions:
  • ❌ proc.terminate() → leaves children running
  • ❌ proc.kill() → same problem
  • ✅ taskkill /F /T → kills everything
• Files: windows/run_win.py — _windows_kill_process_tree()

[BUG-006] Video plays in background behind Chromium

• Status: 🟡 Known, needs investigation
• Symptom: When transitioning from a weblink back to a video, the video starts playing while Chromium is still visible (audio plays, video is behind Chrome window).
• Possible causes:
  1. _kill_weblink_after_frame delay is too short — Kivy renders the video before Chrome is killed
  2. Window.raise_window() is not working reliably on Windows to bring Kivy to front
  3. Chrome's --kiosk / --start-maximized keeps it on top
  4. The content_area.opacity manipulation happens too early/late
• Current approach: _windows_kill_weblink_after_frame() shows overlay, kills Chrome tree, raises Kivy, hides overlay.
• Next thing to test: Use user32.SetForegroundWindow(KivyHwnd) instead of Window.raise_window(). Get Kivy's HWND via Window.get_window_info().

---

🧪 Tested & Rejected Solutions Log

Keep a record of approaches that were tried and didn't work, so we don't waste time re-testing them.

Date	What was tested	Result	Reason it failed
2026-07-24	Python 3.14 with Kivy	❌	kivy_deps.sdl2_dev~=0.8.0 has no cp314 wheel
2026-07-24	--kiosk Chrome flag on Windows	❌	Not fullscreen, Wayland exclusive-fullscreen not available
2026-07-24	--start-fullscreen alone	❌	Inconsistent, sometimes not full
2026-07-24	proc.terminate() for Chrome	❌	Leaves child processes running
2026-07-24	proc.kill() for Chrome	❌	Same as terminate — children survive
2026-07-24	Window.raise_window() for transition	❌	Brief desktop flash visible

---

📁 Data Directory Behaviour

When the .exe runs:

1. Runtime hook (pyi_runtime_hook.py) sets KIWY_DATA_DIR = exe_dir
2. run_win.py patches SignagePlayer.__init__ to use KIWY_DATA_DIR
3. Local folders created next to the .exe:

   KiwySignagePlayer.exe
   config/
     app_config.json
     resources/  (icons, intro video)
     certs/      (SSL certificates)
   media/
     edited_media/
   playlists/
   logs/
   .kivy/        (Kivy home)
   .player_heartbeat
   

---

🔧 Build Cheatsheet

# Build the .exe (from project root or windows/)
Set-Location windows
& .\venv312\Scripts\python.exe -m PyInstaller build.spec --clean --noconfirm

# Run in dev mode (no build needed)
& .\venv312\Scripts\python.exe run_win.py

# Test imports only
& .\venv312\Scripts\python.exe test_import_fix.py

---

📝 Notes for the Next Session

• Investigate [BUG-006] — video playing behind Chromium
• Test if SetForegroundWindow works better than Window.raise_window()
• Consider adding a startup .bat file that users can double-click
• Check if the intro video plays correctly on Windows
• Test card reader fallback behaviour (evdev not available)