Skip to content

Screens and Casting

Michael Riddle edited this page Aug 20, 2026 · 5 revisions

Screens and Casting

Screen app (KHost.Screen2)

A Photino desktop app that plays the host's HLS stream in a native <video> element (the platform web view's built-in HLS support). It decodes nothing from the library itself. Double-click toggles full screen; Escape exits it.

The player page (screen-ui/index.html and player.js) is compiled into the executable as an embedded resource and handed to the web view as a string via Photino's LoadRawString, with the script inlined at startup — the screen has no page files on disk and serves nothing. Page edits therefore need a rebuild to take effect.

  • Launched from the host's Screens dialog (LocalScreenProvider), which injects the host's live address as --server-uri; it can also be run by hand (see Configuration for the flags).
  • A screen the host launched is closed when the host shuts down. One started by hand, or running on another machine, is left alone and falls back to its lost-host behaviour.
  • Logs to logs/ beside the screen executable, one file per screen id per day; files older than 7 days are pruned at startup.
  • Lost host: the connection auto-reconnects; if the host is still gone after a 5-second grace period the screen pauses and shows a "Lost the host" overlay rather than playing on where nobody can stop it.

IPC protocol (KHost.IPC.SignalR)

The host maps ScreenHub at /ipc/screen (AddSignalRIPCServer() + MapIPCServer()); the screen connects via ScreenClient. Commands are [JsonPolymorphic] on ScreenCommandBase — adding a command requires a [JsonDerivedType] attribute on the base.

Command Purpose
LoadMediaCommand Point the screen at the host's HLS StreamUrl; StreamStartOffset maps stream zero to song position.
PlayCommand / PauseCommand Start/resume, pause.
StopCommand Stop with optional FadeDuration (default 5 s).
SeekCommand Absolute song position.
SetVolumeCommand Set volume.
SetTimelineCommand The shared-clock primitive: Position anchored to AnchorUtc (host clock), IsPlaying, IsPrimary. Sent only to sync-capable screens.
SetVideoCommand Blank/unblank the picture while the screen stays on the timeline (audio-only routing).

Pitch shifting is not a screen command: the host applies it when ffmpeg builds the stream, so a transposed song is a new stream rather than a message to the screens.

Screens register with their capabilities (supportsSync, supportsAudio, supportsVideo) and report ScreenPlaybackState back (~every 250 ms and after each command). EchoClock() provides NTP-style clock-offset estimation (best of 5 round trips, resynced every 5 minutes). StreamUrlRewriter rewrites loopback stream URLs to the address each screen actually connected on, so multi-NIC hosts hand back reachable URLs.

A screen reports StreamUrl — the stream it was pointed at, never a local path, since it opens nothing itself. The song title shown in the Screens dialog comes from the host, which is the side that knows which performance it loaded.

Shared timeline

  • Roles. ScreenCoordinationService elects an audio screen (preferring one that supports both audio and sync) and derives the primary screen from it. The primary is the reference clock; correcting a screen means seeking it, and seeking the audible one is a glitch, so audio and primary are normally the same screen.
  • Scheduled start. PlaybackService anchors the timeline at UtcNow + SyncStartLead (default 400 ms) when starting playback, giving every screen one common future instant to start on.
  • Follower correction. Non-primary screens compute the expected stream position from SetTimelineCommand plus their measured clock offset and correct by seeking only — never by adjusting playbackRate, which would pitch-shift. A seek happens only after drift exceeds 0.15 s for 3 consecutive 200 ms samples, to avoid rebuffering on noise. The primary is never corrected.
  • Host position. The host trusts position reports only from the current primary and interpolates between them; re-anchoring is rate-limited to once per second. With no sync-capable screen connected, the Cast receiver's (arrival-timestamped, less accurate) status is used as a fallback clock.
  • Late joiners reuse the existing transcode session and are seeked to the current position; if playing, the timeline is re-published to the whole group.

The Screens dialog shows live drift per screen and provides per-screen audio/video toggles.

Chromecast (KHost.Cast)

CastService (the sole ICastService implementation, built on Sharpcaster) drives a receiver over CASTV2 using Google's stock Default Media Receiver app (CC1AD845) — no custom receiver app is deployed.

  • Discovery sweeps the network, so it is off at startup and runs only while the Screens dialog has it enabled.
  • One receiver at a time — connecting a new device disconnects the current one.
  • A receiver is deliberately not a screen: it never holds the primary role or receives SetTimelineCommand; PlaybackService mirrors load/play/pause/stop/seek to it when connected. Loopback stream URLs are rewritten to the host's LAN address before being handed over.
  • Transport failures are logged and swallowed — a television switched off mid-song must not fail the performance.

Clone this wiki locally