Skip to navigation

Manage a playlist

One controller plays a whole list. setPlaylist takes the ordered sources and loads the one at startIndex. Every later item replaces the playing source in place, so there is no second controller and no re-mount.

await controller.setPlaylist(
[
FastPixPlayerDataSource.hls(playbackId: 'first-playback-id', title: 'Episode 1'),
FastPixPlayerDataSource.hls(playbackId: 'second-playback-id', title: 'Episode 2'),
FastPixPlayerDataSource.hls(playbackId: 'third-playback-id', title: 'Episode 3'),
],
configuration: configuration,
);
controller.autoPlayNext = true;
controller.repeatMode = FastPixPlaylistRepeatMode.all;

The same list can arrive as JSON, a top-level array of objects where playbackId is required, every other field is optional, and unknown keys are ignored.

await controller.setPlaylistFromJson(response.body, configuration: configuration);

An empty list, an entry with no playback ID, unparseable JSON, or a start index outside the list is rejected with a FastPixPlaylistException that names what is wrong and where. A rejected playlist leaves existing playback and playlist state untouched.


final moved = await controller.next(); // false at the last item
await controller.previous();
await controller.jumpTo(4);
controller.currentPlaylistIndex; // -1 when nothing in the list is active
controller.currentPlaylistItem;
controller.playlistCount;
controller.canGoNext;
controller.canGoPrevious;

Navigation returns whether the position moved rather than throwing at the boundaries, so a button can drive it directly. A refused move emits nothing and does not interrupt what is playing.

repeatMode decides what a finished item leads to: off stops at the last item and emits playlistEnded, one replays the active item without changing the index, and all wraps from the last item back to the first. The SDK suppresses automatic advance while a Cast session is connected, because the local player is not the surface being watched, but explicit navigation still works.


Play a single source without a playlist

loadPlaybackId swaps the playing source on the same controller. When the source is one of the playlist’s items, the active index moves to it and navigation continues from there. When it is not, the source plays and the playlist reports no active position until the next navigation or playlist.

await controller.loadPlaybackId(
FastPixPlayerDataSource.hls(playbackId: 'another-playback-id'),
);

Preload windowing

With a playlist set, the SDK warms the items around the active one after each load, interleaved outward from the current index and preferring the item ahead at equal distance. preloadRadius is the depth on each side. Set it to 0 to declare nothing and drive preloading yourself.

controller.preloadRadius = 2; // default

Watch the playlist

playlistStateStream publishes a snapshot on every active-item change, which is what the built-in queue panel uses.

StreamBuilder<FastPixPlaylistState>(
stream: controller.playlistStateStream,
initialData: controller.playlistState,
builder: (context, snapshot) {
final state = snapshot.data!;
return Text(state.position); // "2 of 3"
},
);

The event bus carries the same updates as discrete events: playlistChanged, playlistItemChanged (with the index it left, the index it moved to, the playback ID, and why), and playlistEnded. Every ordinary playback event also carries playbackId and, when a playlist is set, playlistIndex in its data map.


Show the queue panel

FastPixPlaylistPanel(
controller: controller,
onDismiss: () => setState(() => _panelOpen = false),
title: 'Up next',
)

The panel draws itself from the controller alone, so there is no second ordered list to keep in step with what is playing. The built-in skin opens it from the control bar. showPlaylistPanel and showPlaylistControls on FastPixPlayerControlsConfiguration turn the panel and the previous and next arrows off.


What’s next