Kiwy-Signage/windows/README_WINDOWS_BUILD.md

Kiwy Signage Player - Windows Edition

Build and run the Kiwy digital signage player on Windows as a standalone .exe.

📋 Requirements Analysis

The original app was built for Raspberry Pi (Linux), using these technologies:

Component	Original (RPi/Linux)	Windows Equivalent
GUI	Kivy 2.3+	Kivy 2.3+ (works cross-platform)
Video	ffpyplayer	ffpyplayer (needs FFmpeg DLLs)
Card Reader	evdev (Linux input)	✅ Raw Input API + LL-hook fallback
Screen Keep-Awake	xset, xdotool, Wayland	SetThreadExecutionState (Win32 API)
Weblink	chromium-browser (kiosk)	Chrome/Edge (--kiosk mode)
Audio	ALSA/PulseAudio	DirectSound
Window Backend	SDL2 (Wayland/X11)	SDL2 (Windows native)
OpenGL	Desktop GL	ANGLE (DirectX wrapper)

What works on Windows

• ✅ Media playback (images, videos via ffpyplayer)
• ✅ Playlist sync from DigiServer (HTTP/HTTPS)
• ✅ Touch & mouse controls
• ✅ Settings popup
• ✅ Image editing/annotation
• ✅ Password-protected exit
• ✅ Web links (opens in Chrome/Edge kiosk)
• ✅ Network monitoring
• ✅ Auto-update playlist
• ✅ Card reader authentication (Raw Input API — see below)

What is disabled on Windows

• ❌ HDMI power management (tvservice is RPi-specific)
• ❌ WiFi restart (uses Linux nmcli)

🚀 Quick Start (Development)

Prerequisites

1. Python 3.12+ (64-bit) — python.org
   • ⚠️ Python 3.13+ is NOT supported — Kivy 2.3.1 does not have pre-built wheels for it
   • ⚠️ Python 3.14 is NOT supported — no Kivy wheels available
   • ✅ Python 3.12.9 is the recommended version (confirmed working)
2. FFmpeg — for video codec support
   • Download from ffmpeg.org
   • Add bin\ folder to your PATH
3. Visual C++ Redistributable — latest

Install & Run

cd windows

REM Create virtual environment with Python 3.12
py -3.12 -m venv venv
:: OR specify full path:
:: "C:\Users\Dell-PC\AppData\Local\Programs\Python\Python312\python.exe" -m venv venv

venv\Scripts\activate

REM Install dependencies
pip install -r requirements_win.txt

REM Run in development mode
python run_win.py

📦 Building the .exe

One-Command Build

cd windows
build_win.bat

Manual Build

cd windows
venv\Scripts\activate
pip install -r requirements_win.txt
pyinstaller build.spec --clean --noconfirm

Output

windows\dist\KiwySignagePlayer\
    ├── KiwySignagePlayer.exe     # Main executable
    ├── config/                    # Config files (auto-copied)
    ├── resources/                 # Icons, intro video
    └── ... (supporting DLLs)

For a single-file .exe, edit build.spec — uncomment the exe_onefile section and comment out the coll = COLLECT(...) section.

🌐 Web Links (embedded WebView2)

Web links render with WebView2, embedded as a child window inside the Kivy window. Because it is not a separate browser process, it cannot open behind the player, cannot be handed off to an existing browser and exit, and never leaves leaked msedge.exe/chrome.exe processes behind.

WebView2 has two parts, and they are handled differently:

Part	What it is	How it ships
SDK	Microsoft.Web.WebView2.Core.dll + WebView2Loader.dll — the API surface	Bundled in the exe (windows\webview2_sdk\, ~860 KB)
Runtime	msedgewebview2.exe — the actual Chromium engine	Microsoft's evergreen component. Ships with Windows 11 and nearly all Windows 10 machines. Installed automatically on first start if missing.

Automatic Runtime installation

On start-up the player checks for the Runtime (registry pv value under the Edge Update client GUID, with a live SDK probe as fallback). If it is absent it runs the installer silently:

MicrosoftEdgeWebview2Setup.exe /silent /install

Deliberately not elevated — an unelevated run performs a per-user install, so no UAC dialog ever appears on the signage display.

Installers are looked up in this order, so you can drop a replacement next to the .exe without rebuilding:

1. KIWY_WEBVIEW2_INSTALLER environment variable
2. <exe dir>\webview2_runtime\
3. <exe dir>\ (next to the executable)
4. bundled copy inside the exe

Installer	Size	Bundled?	Use when
MicrosoftEdgeWebview2Setup.exe	~1.7 MB	✅ yes	Machine has internet (downloads the Runtime)
MicrosoftEdgeWebView2RuntimeInstallerX64.exe	~203 MB	⬜ opt-in	Machine is offline

To bundle the offline installer (adds ~200 MB to the exe):

cd windows
.\webview2_runtime\download_runtime_installers.ps1 -Offline
venv\Scripts\python.exe -m PyInstaller build.spec --clean --noconfirm

Re-download the installers at any time (they are Microsoft-signed; the script verifies the signature):

.\webview2_runtime\download_runtime_installers.ps1

If WebView2 is unavailable

Web links fall back to the Chrome/Edge subprocess engine (see src/weblink_session.py). That engine still works, but reintroduces the old drawbacks — a separate browser window, possible background/z-order behaviour, and browser processes to clean up.

Troubleshooting

Problem	Solution
Web links show a black/blank page	Check logs\ for [WebView2] lines. Confirm the Runtime version is reported.
Runtime install did not happen	A failed attempt is not retried for 6 hours (marker: logs\.webview2_install_attempt). Delete that file to retry immediately.
Need it working offline	Bundle the standalone installer (see above).

⚙️ Configuration

No configuration ships with the exe. On a machine that has never been set up, config\app_config.json is absent, so after the splash video the player shows a "Player is not configured" notice, waits 5 seconds and then opens the Settings screen automatically. Enter the server details and playback starts right away — no restart required.

On a machine that already has a valid config\app_config.json, the first-run flow is skipped entirely and the cached playlist plays immediately.

1. Config is created next to the executable (not in %APPDATA%)
   • The .exe creates: config/, media/, playlists/, logs/ locally
   • This allows you to copy the entire dist\KiwySignagePlayer\ folder anywhere and it works
2. The player is considered configured once server_ip, screen_name and quickconnect_key all hold real values. Placeholder values (localhost, kivy-player, 1234567, 127.0.0.1) count as unconfigured.
3. Edit config\app_config.json (next to the .exe) to set your server:

{
  "server_ip": "192.168.0.109",
  "port": "8080",
  "screen_name": "Birou_IT",
  "quickconnect_key": "8887779",
  "orientation": "Landscape",
  "touch": "True",
  "max_resolution": "1920x1080",
  "edit_feature_enabled": true,
  "use_https": false,
  "verify_ssl": false
}

💳 Card Reader (Windows Edition)

The card reader now works on Windows via the Raw Input API (with a low-level keyboard-hook fallback). It replaces the Linux-only evdev implementation automatically when run_win.py starts.

• Detection mirrors the Linux logic:
  1. A device named with card / reader / rfid
  2. A USB HID keyboard (non-PS/2) — most card readers enumerate this way
  3. Any remaining keyboard (excluding touchscreens/mice)
• Only keystrokes from the selected device are captured, so the operator's real keyboard cannot pollute card data.
• Card data ends on Enter (same as Linux).

Card reader config (optional)

Add any of these to config\app_config.json next to the .exe:

{
  "card_reader_mode": "auto",      // "auto" | "raw" | "hook"
  "card_reader_device": "",        // e.g. "VID_08FF" to force a specific device
  "card_reader_timeout": 5         // seconds
}

• card_reader_mode: auto (default, tries Raw Input then falls back), raw (force Raw Input), or hook (force the low-level keyboard hook).
• card_reader_device: optional substring of the device name to pin the reader (e.g. VID_08FF, HID#VID_08FF). Run the manual test below to see the exact device names on your host.
• card_reader_timeout: how long the swipe popup waits (default 5 s).

Manual card reader test (no GUI)

cd windows
venv\Scripts\activate
python win_card_reader.py

Swipe a card within 10 seconds — the tool prints the captured data, then exits. The detected devices are listed in the console/log.

🧪 Testing

cd windows
venv\Scripts\activate
python run_win.py

🔧 Troubleshooting

Problem	Solution
"ffpyplayer not found"	Install: pip install ffpyplayer
"No video" / black screen	Install FFmpeg and add to PATH. Try KIVY_GL_BACKEND=angle_sdl2 or KIVY_GL_BACKEND=gl
Kivy window doesn't open	Run from command prompt to see error messages. Ensure GPU drivers are up to date.
Weblinks not opening	Install Google Chrome or Microsoft Edge
Can't connect to server	Check firewall. Try use_https: false and verify_ssl: false for testing
Antivirus flags .exe	Add the output folder to antivirus exclusions. This is a false positive common with PyInstaller.

📁 Project Structure (Build)

Kiwy-Signage/
├── windows/
│   ├── run_win.py              # Windows entry point (patches platform differences)
│   ├── build.spec              # PyInstaller configuration
│   ├── build_win.bat           # One-click build script
│   ├── pyi_runtime_hook.py     # PyInstaller runtime hook
│   ├── requirements_win.txt    # Windows Python dependencies
│   └── README_WINDOWS_BUILD.md # This file
├── src/
│   ├── main.py                 # Main application (original)
│   ├── get_playlists_v2.py     # Playlist sync
│   ├── player_auth.py          # Authentication
│   ├── ssl_utils.py            # SSL/HTTPS
│   ├── keyboard_widget.py      # On-screen keyboard
│   ├── network_monitor.py      # Network monitoring
│   ├── edit_popup.py           # Image editing
│   └── signage_player.kv       # Kivy UI layout
├── config/
│   ├── app_config.json         # Player configuration
│   └── resources/              # Icons, images, intro video
├── media/                      # Downloaded media (created at runtime)
├── playlists/                  # Playlist files (created at runtime)
└── logs/                       # Log files (created at runtime)