Skip to navigation

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.

Stack(
children: [
FastPixVideoSurface(controller: controller),
MyControls(controller: controller),
],
)

Everything those controls need is on the controller.

// Transport
await controller.togglePlayPause();
await controller.seekForward(); // 10s by default
await controller.seekBackward(const Duration(seconds: 30));
await controller.setPlaybackRate(1.5);
controller.supportedPlaybackRates;
// A single stream to build the whole bar from
StreamBuilder<FastPixPlaybackState>(
stream: controller.playbackStateStream,
initialData: controller.playbackState,
builder: (context, snapshot) {
final state = snapshot.data!;
// position, duration, bufferedPosition, isPlaying, isBuffering, playbackRate
return MySeekBar(state: state);
},
);
// Scrubbing, so the bar does not fight the position updates mid-drag
controller.beginScrub();
controller.updateScrub(position);
await controller.endScrub(position);
controller.cancelScrub(); // drag abandoned: no seek
// Tracks and quality
controller.getQualityLevels();
await controller.setQualityLevel(level);
await controller.setQualityAuto();
controller.getAudioTracks();
await controller.setAudioTrack(audioTrack);
controller.getSubtitleTracks();
await controller.setSubtitleTrack(subtitleTrack);
await controller.disableSubtitles();
// Fullscreen and cast
controller.toggleFullscreen();
await controller.toggleCast();

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:

FastPixVideoSurface(
controller: controller,
errorBuilder: (context, error) => MyFailurePanel(
message: error.message,
code: error.code,
isDrm: error is FastPixPlayerDrmErrorEvent,
),
)

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