Player

The player subsystem supports local files and direct media URLs through media_kit, while YouTube watch pages run in flutter_inappwebview.

flowchart LR
  Request[Player launch request] --> Controller[PlayerController]
  Controller --> Local[MediaKitPlayerEngine]
  Controller --> YouTube[YouTube WebView engine]
  Local --> Host[Permanent PlayerSurfaceHost]
  YouTube --> Host
  Host --> Target[Registered viewport target]

Loading

Engine ownership

Only MediaKitPlayerEngine and PlayerController may own a media_kit Player. Feature widgets must not instantiate players or build native video/WebView surfaces independently.

YouTube playback

YouTube uses a separate WebView engine. Google sign-in navigation inside the player WebView is blocked, and playback state is reconciled from authoritative WebView events.

Global controls

GlobalTransportBar appears when a playback session exists and provides transport, subtitle, and desktop keyboard actions. Transcript cues can seek playback and define echo-practice windows. The permanent surface host parks video while root-level overlays are shown.

See ADR-0003, ADR-0015, and ADR-0057.