From 7efc0233271014cb2bf142dd2f17867bfbfbf483 Mon Sep 17 00:00:00 2001 From: ske087 Date: Fri, 24 Jul 2026 13:52:28 +0300 Subject: [PATCH] =?UTF-8?q?Add=20development-track.md=20=E2=80=94=20sessio?= =?UTF-8?q?n=20log,=20bug=20tracker,=20rejected=20solutions,=20build=20inf?= =?UTF-8?q?o?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- windows/development-track.md | 163 +++++++++++++++++++++++++++++++++++ 1 file changed, 163 insertions(+) create mode 100644 windows/development-track.md diff --git a/windows/development-track.md b/windows/development-track.md new file mode 100644 index 0000000..5f3c2d0 --- /dev/null +++ b/windows/development-track.md @@ -0,0 +1,163 @@ +# ๐Ÿงช 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` โ€” `` 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 ` 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 + +```powershell +# 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)