States

Some behaviours are easier to reason about by observing the coarse-grained states that sit on top of the raw events. Vesper SDK exposes two primary state callbacks:

  • onPlayerStateChanged(old:new:) via DorisPlayerOutputProtocol
  • viewDidChangeState(old:new:) via DorisViewOutputProtocol

Use them alongside the event stream to drive overlays, analytics, and custom logic if needed.

Player states (DorisPlayerState)

Each state is mutually exclusive and describes the lifecycle of the underlying AVPlayer. Transitions are triggered automatically by the SDK.

State Meaning
initialization Player stack is being instantiated and configured.
loading A source is resolving and AVPlayer is preparing media.
loaded AVPlayerItem finished loading and is ready to start.
buffering Playback auto-paused because more data is required.
playing Content (or an ad) is rendering frames.
paused Playback is paused by UI or your code.
waitingForNetwork AVFoundation waits for connectivity before resuming.
failed Player hit an unrecoverable error (see DorisPlayerEvent.playerItemFailed).

View states (DorisViewState)

Available when using the default UI through viewDidChangeState(old:new:). It reflects what the SDK UI is currently showing.

State Meaning
initialLoading Waiting for the first playable frame; loader visible.
contentWatching Minimal chrome while content plays.
controls Transport controls are visible after a tap/remote event.
info Metadata/info sheet is shown.
tracksSelection Track picker is open.
episodesSelection Episodes/playlist sheet is open.
seeking User initiated a standard seek gesture.
fastSeeking Long-press/rapid seek mode is active.
progressiveSeeking Progressive/VoiceOver incremental seek is active.
delayedLoad Waiting for stream availability (e.g. SSAI transition).
restart Restart overlay is shown after playback completion.
error Error overlay is visible.
externalOverlay Casting/AirPlay or other overlay is covering the UI.
none Neutral fallback when no other UI mode is active.