> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://fastpix.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://fastpix.com/docs/_mcp/server.

# Build a custom UI

> Render only the video with FastPixVideoSurface and build your own controls on the FastPix Flutter Player controller: transport, scrubbing, tracks, and quality.

`FastPixVideoSurface` renders the video and nothing else. Stack your own controls over it, and the built-in skin is never involved.

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

Everything those controls need is on the controller.

```dart
// 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:

```dart
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

* [Add seek preview thumbnails](/docs/flutter-player/seek-preview-thumbnails) to show a frame as the viewer scrubs your custom seek bar.
* [Show subtitles](/docs/flutter-player/show-subtitles) for subtitle auto-detection and the `showSubtitles` default.