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

# Add a playlist

> Queue multiple videos in the FastPix Web Player, navigate between them programmatically or with the default panel, and build your own playlist UI.

Queue multiple videos in the FastPix Web Player and move between them, either with the built-in panel or your own controls. Each item is a playback ID with optional metadata and tokens, so a playlist can mix public and protected videos.

\


## Before you begin

Make sure you have the following:

* The FastPix Web Player added to your page. See [Install the FastPix web player](/docs/web-player/install-the-fastpix-web-player).
* A playback ID for each video you want to queue. For protected videos, have the playback token (and a DRM token for DRM-protected videos) ready.

\


## Add a playlist

Pass an array of items to `addPlaylist()`. Each item needs a `playbackId`, and can carry a `title` and `thumbnail` for the panel, plus a `token` or `drmToken` for protected videos.

```html
<fastpix-player id="player" aspect-ratio="16/9"></fastpix-player>
<script>
  const playlist = [
    { playbackId: 'playback-id-1', title: 'Intro', thumbnail: 'https://example.com/thumb-1.jpg' },
    { playbackId: 'playback-id-2', title: 'Deep Dive', thumbnail: 'https://example.com/thumb-2.jpg', token: 'playback-token' },
    { playbackId: 'playback-id-3', title: 'Wrap-up', thumbnail: 'https://example.com/thumb-3.jpg', drmToken: 'drm-token' },
  ];

  const player = document.getElementById('player');
  player.addPlaylist(playlist);
</script>
```

The player loads the first item and shows the built-in playlist panel, from which a viewer can pick any item.

\


## Start from a specific item

To open the playlist on a specific video rather than the first, set `default-playback-id` on the element to that item's playback ID.

```html
<fastpix-player id="player" default-playback-id="7f847ed3-6688-482b-8043-67a35325fb00"></fastpix-player>
```

\


## Move between items

Call `next()` and `previous()` to navigate the queue from your own controls.

```javascript
player.next();
player.previous();
```

\


## Replace the current source

To play a different video without changing the queue, call `loadByPlaybackId()`. Pass options for a protected video or a custom domain, and set `emitPlaybackChange` to `true` to fire the `playbackidchange` event for the new source.

```javascript
player.loadByPlaybackId('PLAYBACK_ID', {
  token: 'optional-token',
  drmToken: 'optional-drm-token',
  customDomain: 'stream.fastpix.app',
  emitPlaybackChange: true,
});
```

\


## React to the current item

The player fires `playbackidchange` whenever the active item changes, with the new playback ID and its position in the queue.

```javascript
player.addEventListener('playbackidchange', (e) => {
  const { playbackId, currentIndex, totalItems } = e.detail || {};
  console.log('Now playing', playbackId, currentIndex, '/', totalItems);
});
```

\


## Build a custom playlist panel

To replace the built-in panel with your own, add `hide-default-playlist-panel` to the element and provide your UI in the `playlist-panel` slot. The player fires `playlisttoggle` when the panel should open or close, so you can show and hide your UI in step with the player.

```html
<fastpix-player id="player" hide-default-playlist-panel>
  <div slot="playlist-panel" id="myPlaylistPanel">Your custom UI here</div>
</fastpix-player>
<script>
  const player = document.getElementById('player');
  const panel = document.getElementById('myPlaylistPanel');

  player.addEventListener('playlisttoggle', (e) => {
    if ((e.detail?.hasPlaylist ?? false) === false) return;
    panel.style.display = e.detail.open ? 'block' : 'none';
  });
</script>
```

\


## Reference

**Playlist item fields**

| Field        | Description                                  |
| ------------ | -------------------------------------------- |
| `playbackId` | The playback ID of the video. Required.      |
| `title`      | A title shown in the playlist panel.         |
| `thumbnail`  | A thumbnail image URL shown in the panel.    |
| `token`      | Playback token for a signed (private) video. |
| `drmToken`   | DRM token for a DRM-protected video.         |

**Methods**

| Method                          | Description                                                                                                                      |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `addPlaylist(items)`            | Load an array of playlist items and show the panel.                                                                              |
| `next()`                        | Play the next item in the queue.                                                                                                 |
| `previous()`                    | Play the previous item in the queue.                                                                                             |
| `loadByPlaybackId(id, options)` | Replace the current source without changing the queue. Options: `token`, `drmToken`, `customDomain`, `emitPlaybackChange`.       |
| `destroy()`                     | Lightweight teardown before switching sources. Not needed for standard playlist navigation, which the player handles internally. |

**Attributes**

| Attribute                     | Description                                                                      |
| ----------------------------- | -------------------------------------------------------------------------------- |
| `default-playback-id`         | The playback ID to open the playlist on, instead of the first item.              |
| `hide-default-playlist-panel` | Hide the built-in panel so you can supply your own in the `playlist-panel` slot. |

**Events**

| Event              | `event.detail`                                                      |
| ------------------ | ------------------------------------------------------------------- |
| `playbackidchange` | `{ playbackId, currentIndex, totalItems }` for the new active item. |
| `playlisttoggle`   | `{ hasPlaylist, open }` when the panel should open or close.        |

\


## What's next

* [Play a DRM-protected video](/docs/web-player/play-drm-protected-content) to queue protected items with a `drmToken`.
* [Listen to player events](/docs/web-player/listen-to-player-events) for the full set of events the player fires.