> 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.

# Manage a playlist

> Play a list of videos on one FastPix Flutter Player controller. Set the playlist, navigate between items, and show the built-in queue panel.

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.

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

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

\


## Navigate the playlist

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

```dart
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](/docs/flutter-player/preload-and-precache-videos) yourself.

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

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

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

* [Preload and precache videos](/docs/flutter-player/preload-and-precache-videos) to warm the items around the active one.
* [Prerender the next video](/docs/flutter-player/prerender-the-next-video) for a flash-free transition to the next item.