Kiwy-Signage/PLAYER_WEBLINK_INTEGRATION.md

Web Link Playlist Items — Player Integration Guide

This document describes how the Kiwy-Signage player (https://gitea.moto-adv.com/ske087/Kiwy-Signage.git) supports the weblink playlist item type (display a live web page / URL instead of an uploaded media file).

Status: implemented. The player supports weblink items on both Raspberry Pi (chromium subprocess) and Windows (embedded CEF with a Chrome/Edge subprocess fallback). Sections 1–4 describe the original design plan; section 6 documents the shipped architecture and the interaction model.

---

1. Background — how items flow

DigiServer API  ──JSON──▶  player sync (get_playlists_v2.py)  ──▶  playlist.json  ──▶  main.py renders
   /api/playlists           downloads files to media/                                  by item type

Each playlist item the server returns currently looks like:

{
  "id": 42,
  "file_name": "promo.jpg",
  "type": "image",
  "duration": 10,
  "position": 1,
  "url": "https://server/digiserver/static/uploads/promo.jpg",
  "edit_on_player": false
}

The player:

1. Syncs (src/get_playlists_v2.py → download_media_files()): downloads url into the local media/ directory, then rewrites each item keeping only file_name, url (now a local relative path), duration, edit_on_player. Note: the type field is currently discarded here.
2. Renders (src/main.py → play_current_media()): opens the local file and chooses a Kivy widget purely by file extension (.mp4/.avi/... → Video, .jpg/.png/... → AsyncImage). Unknown extensions are skipped as "unsupported".

A web link breaks all three assumptions: there is no file to download, no extension to switch on, and no widget that renders a web page.

---

2. New server contract (what DigiServer will send)

A web-link playlist item will look like this:

{
  "id": 91,
  "file_name": "weblink-3f9c1a2b",
  "type": "weblink",
  "duration": 30,
  "position": 4,
  "url": "https://example.com/dashboard",
  "edit_on_player": false
}

Key differences vs. a file item:

Field	File item	Web-link item
type	image / video	weblink
url	Path to a file on the server	The web page to display (the link)
file_name	Real filename on disk	Synthetic id (weblink-<uuid>), no file exists

The player must branch on type == "weblink" and treat url as the page to open — never try to download it as a file.

---

3. Required player changes

3.1 Sync step — src/get_playlists_v2.py

Function: download_media_files(playlist, media_dir, ...)

1. Skip download for web links. At the top of the per-item loop, detect media.get('type') == 'weblink' and do not call session.get() / write any file for it.
2. Preserve type and the original url. The updated_media dict that is appended to updated_playlist currently drops type and rewrites url to a local path. It must now carry type through, and for web links keep url as the original web address (do not convert to a local relative path).

Suggested shape of the per-item logic:

item_type = media.get('type', '')

if item_type == 'weblink':
    # No file to download — pass the web link through unchanged.
    updated_playlist.append({
        'file_name': media.get('file_name', ''),
        'type': 'weblink',
        'url': media.get('url', ''),          # the actual web page
        'duration': media.get('duration', 10),
        'edit_on_player': False,
    })
    continue

# ... existing download logic for file items ...
updated_playlist.append({
    'file_name': file_name,
    'type': item_type,                        # <-- now preserved
    'url': os.path.relpath(local_path, os.path.dirname(media_dir)),
    'duration': duration,
    'edit_on_player': media.get('edit_on_player', False),
})

3. delete_unused_media() walks media/ using file_name. Web links have no file, so they simply won't match anything on disk — no change strictly required, but make sure a missing local file for a weblink item does not trigger a re-download or an error elsewhere.

3.2 Render step — src/main.py

Function: play_current_media(self, force_reload=False)

The current logic builds media_path = os.path.join(self.media_dir, file_name) and then does os.stat(media_path) — which will fail for a web link (no file). Add a web-link branch before the file-existence check:

media_item = self.playlist[self.current_index]
file_name = media_item.get('file_name', '')
duration = media_item.get('duration', 10)

# NEW: handle web links before any file/path handling
if media_item.get('type') == 'weblink':
    self.play_weblink(media_item.get('url', ''), duration)
    return

# ... existing file existence check + extension branching ...

Then add a new method play_weblink(self, url, duration):

• Validate the scheme is http/https (reject anything else, e.g. file://).
• Open the page for duration seconds, then advance with self.next_media().
• Wrap in try/except; on failure increment self.consecutive_errors and call self.next_media(), matching the existing error-handling pattern.
• Make sure the previous widget (self.current_widget) is removed/stopped just like the image/video paths do.

Rendering approach (pick one)

Kivy has no production-grade embedded web view, especially on Raspberry Pi. Recommended options, in order of robustness:

1. Chromium kiosk overlay (recommended). Launch Chromium over the Kivy window for the item's duration, then close it and return to Kivy:

   import subprocess, shutil
   from urllib.parse import urlparse
   from kivy.clock import Clock
   
   def play_weblink(self, url, duration):
       scheme = urlparse(url).scheme.lower()
       if scheme not in ('http', 'https'):
           Logger.warning(f"SignagePlayer: Refusing non-http(s) weblink: {url}")
           self.next_media()
           return
       try:
           browser = shutil.which('chromium-browser') or shutil.which('chromium')
           self._weblink_proc = subprocess.Popen([
               browser,
               '--kiosk', '--app=' + url,
               '--noerrdialogs', '--disable-infobars',
               '--incognito', '--no-first-run',
               '--check-for-update-interval=31536000',
           ])
           Clock.schedule_once(lambda dt: self._close_weblink_and_next(), duration)
       except Exception as e:
           Logger.error(f"SignagePlayer: Error opening weblink: {e}")
           self.consecutive_errors += 1
           self.next_media()
   
   def _close_weblink_and_next(self):
       proc = getattr(self, '_weblink_proc', None)
       if proc and proc.poll() is None:
           proc.terminate()
           try:
               proc.wait(timeout=5)
           except Exception:
               proc.kill()
       self._weblink_proc = None
       self.next_media()
   

   Requirements / notes:

   • Install Chromium on the player image (chromium-browser on Raspberry Pi OS).
   • Ensure Chromium gets window focus over Kivy and is fully killed before the next item, including on pause/stop/restart paths and on app shutdown (on_stop) so no stray browser window is left behind.
   • On Wayland/X11 the player already sets SDL_VIDEODRIVER; verify Chromium launches on the same display/session.

2. Embedded web view widget (kivy_garden.webview, WebKit/GTK, or WebView2). Cleaner UX (stays inside the Kivy widget tree) but fragile and poorly supported on Pi/Wayland — only pursue if option 1 is unacceptable.

3. Server-side screenshot fallback (no player change). If embedding a live browser is not desirable, DigiServer can periodically screenshot the URL and store it as a normal image item; the player then needs no changes. This loses live/animated content. Documented here for completeness only.

---

4. Checklist for the player update

• get_playlists_v2.py: skip download when type == 'weblink'.
• get_playlists_v2.py: preserve type in the rewritten playlist items (fixes the current loss of type).
• get_playlists_v2.py: keep the original web url for weblink items.
• main.py play_current_media(): branch to play_weblink() before the os.stat() file check.
• main.py: implement play_weblink(url, duration) (Chromium kiosk).
• main.py: validate scheme is http/https; reject others.
• Kill/cleanup the browser process on next item, pause, stop, restart, and on_stop.
• Install Chromium on the player image / document it in the player README.
• Test: mixed playlist (image → video → weblink → image) cycles correctly and respects per-item duration.

---

5. Security notes

• Only allow http/https schemes on both server and player; never open file://, chrome://, etc.
• The server validates and stores the URL when the operator adds it; the player should still re-validate the scheme before launching the browser (defence in depth).
• Consider running Chromium with --incognito (no persistent cookies/cache) as shown above.

---

6. Shipped architecture (src/weblink_session.py)

The player-side implementation lives in one module, so launch, verification, timing and teardown have a single owner instead of being duplicated per platform:

Piece	Responsibility
WeblinkSession	Owns one weblink item: validate → launch → verify → watch → teardown. Generation-tokened so stale callbacks are ignored, and atexit-safe.
WeblinkAdapter	The only platform-specific part: launch / wait for the window / is it alive / tear it down / pre-warm.
ChromiumSubprocessAdapter	Default engine (Raspberry Pi chromium, Windows chrome.exe/msedge.exe).
InteractionWatcher	Decides when the item is finished (see the interaction model below).
WebInputSources	Reads /dev/input/event* (Linux) and does a pointer-position tap (Windows, needed for embedded CEF).

Platform wrappers inject their engines through SignagePlayer.weblink_adapter_factory:

• Raspberry Pi / Linux — built-in Chromium subprocess adapter.
• Windows (windows/run_win.py) — embedded CEF first (cef_browser.py, renders inside the Kivy window: no z-order fights, no subprocess), then the Chrome/Edge subprocess adapter as fallback.

6.1 Interaction model — web links are not passive media

duration on a weblink is not a hard cut-off. The player advances only when both conditions are true:

1. the configured duration has elapsed; and
2. the viewer has not interacted with the page for interaction_postpone seconds (default 10 s), measured from the most recent interaction.

Consequences:

• A viewer who taps, scrolls or navigates the page during the final seconds of the slot keeps the page on screen — the advance is pushed 10 s past that touch, and every further touch pushes it again. The link is never pulled out from under someone who is using it.
• An untouched page still advances on schedule, exactly like a media item.
• A multi-event burst (a drag, a page transition) counts as one interaction but the countdown is measured from the last event of that burst, so an item can never be cut off mid-gesture.
• max_dwell (duration × max_dwell_factor, at least min_max_dwell) is an absolute backstop so a wedged browser or a jammed touchscreen cannot park the playlist forever.

Pause/play does not apply to web links. A web link is an interactive surface, so toggle_pause() is a no-op while one is on screen — the interaction watcher owns its lifecycle. The pause button continues to work normally for images and videos.

6.2 Verified start-up

Launching a browser is not the same as displaying a page. The session therefore does not report success immediately after spawning the process (that used to reset the error counter and leave a black screen for the whole duration). The watcher thread — never the Kivy main thread — waits for the browser window to appear, and if it never does the item is reported as failed and skipped.

6.3 Configuration

All timings are tunable in config/app_config.json under weblink:

"weblink": {
  "engine": "auto",
  "interaction_postpone": 10,
  "interaction_debounce": 0.5,
  "interaction_grace": 5.0,
  "max_dwell_factor": 6.0,
  "min_max_dwell": 300,
  "launch_timeout": 15,
  "prewarm": true
}

Key	Meaning
engine	Preferred engine (auto, cef, subprocess).
interaction_postpone	Seconds the advance is postponed, measured from each interaction (default 10).
interaction_debounce	Logging/trace throttle for continuous drags (default 0.5).
interaction_grace	Settle window after the last raw event still counted as interacting (default 5).
max_dwell_factor	Hard ceiling = duration × factor.
min_max_dwell	Floor for that hard ceiling, in seconds.
launch_timeout	How long to wait for the browser window to appear.
prewarm	Pre-warm the next weblink (disabled on Windows).

6.4 Diagnostics

The watcher traces structured events through playback_trace.py: weblink_launch, weblink_visible, weblink_interaction, weblink_end (with reason viewer_idle, browser_exited or max_dwell), weblink_not_visible and weblink_failed.