Reference: VideoPlayerConfig
VideoPlayerConfig<T> extends the kit’s BasePlayerConfig (baseUrl, auth, playlist, storage, platform, and the rest, shared with the music player). This page covers only the fields video adds. One inherited field is worth flagging here even though video didn’t add it: controls renders the native <video controls> bar, and loading DesktopUiPlugin or TvKeyHandlerPlugin alongside controls: true doubles the UI, pick one.
| Field | Type | Default | Notes |
|---|
muted | boolean | — | Seeded onto the backend before any play() call, satisfies the browser’s autoplay-with-sound policy. Call unmute() after a user gesture. |
autoPlay | boolean | — | Whether the item setup() already primed also starts playing once ready() resolves. Every non-empty playlist primes a start item either way, see below. |
playbackRates | number[] | — | Available speeds, read by playbackRates() and the speed key bindings. |
preload | HtmlPreloadMode | — | 'auto' / 'metadata' / 'none', maps directly to the <video> element’s preload attribute. |
disableMediaControls | boolean | false | Gates only the hardware MediaX key bindings, see Plugin: Key Handler. |
disableControls | boolean | false | Short-circuits KeyHandlerPlugin’s addDefaults() entirely. |
| Field | Type | Default | Notes |
|---|
stretching | Stretching | 'uniform' | Initial aspectRatio() value. |
theaterDefault | boolean | — | Starts in theater mode once setup() resolves. |
baseImageUrl | string | — | Prefix for relative image/poster/thumbnail paths, useful for a TMDB-style relative path catalogue. Absolute URLs pass through unchanged. |
| Field | Type | Default | Notes |
|---|
backendFactory | VideoBackendFactory | resolves Html5VideoBackend | Overrides backend resolution. See Adapter: Video Backend. |
| Field | Type | Default | Notes |
|---|
defaultSubtitleLanguage | string | — | Auto-selects a matching subtitle track once tracks are available. Exact tag first, then prefix match ('en' matches 'en-US'). |
defaultAudioLanguage | string | — | Same matching rule, for audio tracks. |
defaultQuality | 'auto' | number | 'auto' | Applied once, after the first manifest parse. Interactive changes afterward persist across item transitions. |
| Field | Type | Default | Notes |
|---|
autoAdvance | boolean | true | Calls next() automatically when the current item ends. Set false when an external orchestrator (Cast sync, a WebSocket-driven session) drives next() itself, to avoid duplicate advances. |
playlist | T[] | string | — | Same field as BasePlayerConfig, retyped here from BasePlaylistItem[] to T[] (T defaults to VideoPlaylistItem) — the wire-format normalizer (file, tracks[], {time, date} progress) applies to every item, canonical items pass through unchanged. |
Video’s setup() wrapper injects three defaults BasePlayerConfig alone doesn’t set, all overridable by passing your own value explicitly:
| Field | Default for video | Notes |
|---|
crossfadeEnabled | false | A hard cut between items, unlike music’s true. Preloading still happens, preloadLeadSeconds (kit default 10) is unaffected. |
transitionStrategy | GaplessTransitionStrategy | Matches the hard-cut default above. |
preloadStrategy | VideoPreloadStrategy | Prefetches the next item’s video assets (HLS manifest, poster, sprite VTT, subtitle and chapter sidecars, ASS fonts) so the next item starts instantly on the hard cut. Extends the kit’s DefaultPreloadStrategy. |
Every setup() call with a non-empty playlist primes a start item once ready() resolves, reading each item’s progress field (WatchProgress) to pick it: most recently watched wins, over 90% watched rolls forward to the next item, otherwise resumes at the saved time (passed as startAt, so the backend fetches from the offset directly). This runs regardless of autoPlay, a player without it still mounts paused on the right item and the right position instead of blank. autoPlay: true decides the one thing this selection doesn’t do on its own: whether that primed item also starts playing. See Recipe: Persistence & Resume for the full pattern, including saving progress in the first place.