Repository navigation
Screens and Casting
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.
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.
-
Roles.
ScreenCoordinationServiceelects 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.
PlaybackServiceanchors the timeline atUtcNow + 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
SetTimelineCommandplus their measured clock offset and correct by seeking only — never by adjustingplaybackRate, 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.
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;PlaybackServicemirrors 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.
KHost
Architecture
- Architecture
- Projects
- Screens and Casting
- Break Music and Ads
- Messaging
- Data and Persistence
- Plugins
Contributing