Build a custom UI
FastPixVideoSurface renders the video and nothing else. Stack your own controls over it, and the built-in skin is never involved.
Everything those controls need is on the controller.
Call cancelScrub() when the seek bar goes away mid-drag. Entering fullscreen or PiP rebuilds the controls, and Flutter disposes the old slider without calling its end callback, so endScrub never arrives. Without it, the scrub target stands in for the playhead until the next drag. It seeks nowhere, emits no scrubEnded, and returns whether a scrub was in progress.
Quality selection is a ceiling rather than an exact selection on both platforms: the player still adapts below the level you set.
Populate menus from manifest events
Track lists arrive with the manifest, not at initialization. Listen for qualityLevelsReady, audioTracksReady, and subtitleTracksReady to populate menus when there is something to put in them, and for qualityLevelChanged, audioTrackChanged, subtitleChanged, playbackRateChanged, scrubStarted, and scrubEnded to follow the state.
Failures from these calls do not throw. They arrive on the playback error channel the app already listens to, carrying a FastPixCustomUIErrorCode: trackUnavailable, trackSwitchFailed, qualitySelectionUnsupported, playbackRateUnsupported, castUnavailable, playerNotReady, pipUnsupported, or pipFailed.
Draw your own failure UI
FastPixVideoSurface draws no failure panel of its own. A playback failure is reported on the error event and on controller.lastError, and the surface keeps drawing what it was drawing. What the viewer sees about the failure is yours to draw, over the surface or through errorBuilder, which replaces the surface once playback has failed:
Only failures that actually stopped playback reach errorBuilder. The FastPixCustomUIErrorCode failures above share the same error channel but never replace the surface, because playback did not stop. The test for it is controller.lastError, which those failures deliberately do not set.
The platform players report every load failure as the same opaque string, Source error. To find the real cause, call controller.diagnosePlayback() from your own failure UI. It re-requests the manifest and, for a protected source, the license and certificate endpoints, separating a bad playback ID (manifest 404) from an expired playback token (403) from a rejected license (401 or 403). The surface’s diagnoseErrors parameter has no effect and is kept only so existing code still compiles.
What’s next
- Add seek preview thumbnails to show a frame as the viewer scrubs your custom seek bar.
- Show subtitles for subtitle auto-detection and the
showSubtitlesdefault.