Add development-track.md — session log, bug tracker, rejected solutions, build info

2026-07-24 13:52:28 +03:00
parent 6abde5a767
commit 7efc023327
1 changed files with 163 additions and 0 deletions
@@ -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` — `<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
+
+```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)