# Playlist plugin

The Playlist plugin adds support for player playlists. With playlists, you can organize related videos into a cohesive sequence, making it easier to manage large amounts of content. Users can quickly navigate through videos in a structured way without having to search for individual items. Overall, this user experience can provide a sense of continuity.

To see the Playlist plugin in action, view this demo of a playlist with selection controls. You can also add a standard playlist without selection controls.

Info
This documentation applies to Wowza Flowplayer Native v3.x. In previous releases, playlists were not implemented with a source loader but with a special initialization.

## Before you start

Before you use this plugin with the standalone player, we recommend the following steps:

* Read about [embedding the core player](/docs/wowza-flowplayer/player/embed/embed-with-standalone/) in your site by adding the minimum CSS and JavaScript player components.
* Make sure you have a player token. For more, see [Token configuration](/docs/wowza-flowplayer/player/configure/#token-configuration). Tokens aren't needed for local development.
* The instructions on this page generally assume you're using the Wowza Flowplayer CDN to embed the player in your site. If you're using npm, see our [npm instructions](/docs/wowza-flowplayer/player/embed/embed-with-standalone/#use-npm) or our [TypeScript guide](/docs/wowza-flowplayer/guides/add-the-player-using-typescript/).


## Install the plugin

To install the Playlist plugin, load it next to the core player:


```html
<!-- Load standard player skin -->
<link rel="stylesheet" href="https://cdn.flowplayer.com/releases/native/3/stable/style/flowplayer.css">
<!-- Load player script -->
<script src="//cdn.flowplayer.com/releases/native/3/stable/flowplayer.min.js"></script>

<!-- Load plugin -->
<script src="//cdn.flowplayer.com/releases/native/3/stable/plugins/playlist.min.js"></script>
<!-- Add optional plugins -->
<script src="https://cdn.flowplayer.com/releases/native/3/stable/plugins/hls.min.js"></script>
<script src="//cdn.flowplayer.com/releases/native/3/stable/plugins/ovp.min.js"></script>
```


```js
// Import player library and basic CSS for player
import flowplayer from "@flowplayer/player";
import "@flowplayer/player/flowplayer.css";

// Import playlist plugin and optional plugins
import Playlist from "@flowplayer/player/plugins/playlist";
import HLS from "@flowplayer/player/plugins/hls";
import OVP from "@flowplayer/player/plugins/ovp";
```

## Add HTML elements

Add the HTML components to render the player elements on your page:


```html
<div id="player"></div>
<div id="fp-playlist-controls"></div>
```

To position the playlist to the right or left of the player, use these CSS helper classes instead:


```html
<div class="fp-playlist-layout right">
  <div id="player"></div>
  <div id="fp-playlist-controls"></div>
</div>
```

## Configure the plugin

The plugin can be set up at the top-level configuration under the `playlist` namespace. Playlist elements are configured as an `items` array in the configuration root `src` object, with the special `type: "flowplayer/playlist` source type. This is similar to how standard [video sources](/docs/wowza-flowplayer/player/configure#video-source) are configured.

| Property | Example | Description |
|  --- | --- | --- |
| `advance` *boolean* | `true` or `false` | Determines if the player should auto-advance to the next clip. Default value is `true`. |
| `delay` *integer* | `0` | Defines the time in seconds between clips. If larger than zero, a contain screen displays between clips. Default value is `5`. |
| `loop` *boolean* | `true` or `false` | Determines if the playlist should loop and restart from the beginning after the last clip. Default value is `false`. |
| `controls` *string* | `#fp-playlist-controls` | Adds a string selector that defines where to optionally insert the visual playlist queue controller. If left blank, no playlist queue is created. The corresponding `<div>` element can be placed anywhere on the page. |
| `playlist_title` *string* | `My playlist` | Defines the title of the playlist and displays it at the top of the playlist controller. The default value is `Playlist`. |
| `skip_controls` *boolean* | `true` or `false` | Displays playlist skip controls in the player control bar if `delay` is set to greater than 0. Default value is `true`. |
| `shuffle` *boolean* | `true` or `false` | Randomizes the playback value when set to `true`. Default value is `false`. |
| `start_index` *number* | `1` | Specifies the index from which the playlist will start playing. Default value is `0`. Available with v3.2.1 and later. |


### Add a standard playlist

The following example configures the player using a standard playlist without selection controls. Three different playlist items are included.


```javascript
const player = flowplayer('#player', { 
  src: {
        type: "flowplayer/playlist",
        items: [{ 
          src: "https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ForBiggerBlazes.mp4",
          title: "For Bigger Blazes",
          description: "HBO GO now works with Chromecast, the easiest way to enjoy online video on your TV.",
          poster: "https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/images/ForBiggerBlazes.jpg"
        },
        { 
          src: "https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ForBiggerEscapes.mp4",
          title: "For Bigger Escapes",
          description: "Introducing Chromecast. The easiest way to enjoy online video and music on your TV—for when Batman's escapes aren't quite big enough.",
          poster: "https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/images/ForBiggerEscapes.jpg"
        },
        { 
          src: "https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ForBiggerJoyrides.mp4",
          title: "For Bigger Joyrides",
          description: "Introducing Chromecast. The easiest way to enjoy online video and music on your TV.",
          poster: "https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/images/ForBiggerJoyrides.jpg"
        }
      ]},
  playlist: {
    advance: true, // Auto-advance playlist
    delay: 10, // 15 seconds between clips
    skip_controls: true
  },
  token: "[your-player-token]"
})
```

### Add a playlist controller

If you use the `controls` configuration option, the corresponding `<div>` tag with the same name shows a visual playlist queue control element with name, description (if configured in the player), and thumbnail for each item in the playlist queue.

For a full demo where the playlist controller appears to the right of the player, see this example.

## Listen to plugin events

This section describes the events you can capture to control and manage the playlist that's used with your player instance. To understand even handling differences between CDN or npm implementations, see [Plugin events](/docs/wowza-flowplayer/plugins/about-plugins/#plugin-events).

| CDN event | npm event | Description |
|  --- | --- | --- |
| `flowplayer.playlist.events.PLAYLIST_READY` | `Playlist.events.PLAYLIST_READY` | Fires when the playlist is updated. Gets the updated video queue as parameter `queue`. |
| `flowplayer.playlist.events.PLAYLIST_NEXT` | `Playlist.events.PLAYLIST_NEXT` | Fires when the playlist advances. You can get the index for the next video in the playlist with the `next_index` property. |
| `flowplayer.playlist.events.PLAYLIST_ENDED` | `Playlist.events.PLAYLIST_ENDED` | Fires when the playlist is finished. |


#### Example

In this example, we capture when the viewer advances to the next video in the playlist and output the `next_index` value to the console. A message is also added to the console when the entire playlist ends.


```js
player.on(flowplayer.playlist.events.PLAYLIST_NEXT, (event) => {
  console.log(event.detail.next_index);
});

player.on(flowplayer.playlist.events.PLAYLIST_ENDED, (event) => {
  console.log("Playlist finished.");
});
```


```js
player.on(Playlist.events.PLAYLIST_NEXT, (event) => {
  console.log(event.detail.next_index);
});

player.on(Playlist.events.PLAYLIST_ENDED, (event) => {
  console.log("Playlist finished.");
});
```

## Manage the plugin

You can use the properties and methods described in this section to interact with our API and manage the Playlist plugin and video playback.
The Playlist API lives under the `playlist` namespace in the Player API.

### Properties

These properties can be used to retrieve information about the current state of the plugin and to modify the plugin's behavior.

| Property | Description |
|  --- | --- |
| `queue` | Holds the state of the playlist and exposes the current playlist queue, including its `idx`, `members`, `last_index` properties.`idx` defines the index of the video currently playing.`members` defines the videos in the playlist queue.`last_idx` specifies the last possible index to play. |


### Methods

These methods allow you to work with the plugin and perform specific actions to control the plugin's behavior.

| Method | Description |
|  --- | --- |
| `play(idx)` | Plays the video at index `idx`. |
| `next()` | Plays the next video. |
| `prev()` | Plays the previous video. |
| `push(...members: Config[])` | Pushes a new video to the queue. Accepts either a player configuration object or an array of player configurations. |
| `remove(idx: number)` | Remove video at index `idx`. |
| `clear()` | Clear whole queue. |