508 lines
14 KiB
Markdown
508 lines
14 KiB
Markdown
|
# video.js Playlist API
|
||
|
|
|
||
|
|
## Playlist Item Object
|
||
|
|
|
||
|
|
A playlist is an array of playlist items. A playlist item is an object with the following properties:
|
||
|
|
|
||
|
|
| Property | Type | Optional | Description |
|
||
|
|
| ------------ | ------ | -------- | -------------------------------------------------- |
|
||
|
|
| `sources` | Array | | An array of sources that video.js understands. |
|
||
|
|
| `poster` | String | ✓ | A poster image to display for these sources. |
|
||
|
|
| `textTracks` | Array | ✓ | An array of text tracks that Video.js understands. |
|
||
|
|
|
||
|
|
## Methods
|
||
|
|
### `player.playlist([Array newList], [Number newIndex]) -> Array`
|
||
|
|
|
||
|
|
Get or set the current playlist for a player.
|
||
|
|
|
||
|
|
If called without arguments, it is a getter. With an argument, it is a setter.
|
||
|
|
|
||
|
|
```js
|
||
|
|
player.playlist([{
|
||
|
|
sources: [{
|
||
|
|
src: 'http://media.w3.org/2010/05/sintel/trailer.mp4',
|
||
|
|
type: 'video/mp4'
|
||
|
|
}],
|
||
|
|
poster: 'http://media.w3.org/2010/05/sintel/poster.png'
|
||
|
|
}, {
|
||
|
|
sources: [{
|
||
|
|
src: 'http://media.w3.org/2010/05/bunny/trailer.mp4',
|
||
|
|
type: 'video/mp4'
|
||
|
|
}],
|
||
|
|
poster: 'http://media.w3.org/2010/05/bunny/poster.png'
|
||
|
|
}, {
|
||
|
|
sources: [{
|
||
|
|
src: 'http://vjs.zencdn.net/v/oceans.mp4',
|
||
|
|
type: 'video/mp4'
|
||
|
|
}],
|
||
|
|
poster: 'http://www.videojs.com/img/poster.jpg'
|
||
|
|
}, {
|
||
|
|
sources: [{
|
||
|
|
src: 'http://media.w3.org/2010/05/bunny/movie.mp4',
|
||
|
|
type: 'video/mp4'
|
||
|
|
}],
|
||
|
|
poster: 'http://media.w3.org/2010/05/bunny/poster.png'
|
||
|
|
}, {
|
||
|
|
sources: [{
|
||
|
|
src: 'http://media.w3.org/2010/05/video/movie_300.mp4',
|
||
|
|
type: 'video/mp4'
|
||
|
|
}],
|
||
|
|
poster: 'http://media.w3.org/2010/05/video/poster.png'
|
||
|
|
}]);
|
||
|
|
// [{ ... }, ... ]
|
||
|
|
|
||
|
|
player.playlist([{
|
||
|
|
sources: [{
|
||
|
|
src: 'http://media.w3.org/2010/05/video/movie_300.mp4',
|
||
|
|
type: 'video/mp4'
|
||
|
|
}],
|
||
|
|
poster: 'http://media.w3.org/2010/05/video/poster.png'
|
||
|
|
}]);
|
||
|
|
// [{ ... }]
|
||
|
|
```
|
||
|
|
|
||
|
|
If a setter, a second argument sets the video to be loaded. If omitted, the
|
||
|
|
first video is loaded. If `-1`, no video is loaded.
|
||
|
|
|
||
|
|
```js
|
||
|
|
player.playlist([{
|
||
|
|
sources: [{
|
||
|
|
src: 'http://media.w3.org/2010/05/sintel/trailer.mp4',
|
||
|
|
type: 'video/mp4'
|
||
|
|
}],
|
||
|
|
poster: 'http://media.w3.org/2010/05/sintel/poster.png'
|
||
|
|
}, {
|
||
|
|
sources: [{
|
||
|
|
src: 'http://media.w3.org/2010/05/bunny/trailer.mp4',
|
||
|
|
type: 'video/mp4'
|
||
|
|
}],
|
||
|
|
poster: 'http://media.w3.org/2010/05/bunny/poster.png'
|
||
|
|
}], 1);
|
||
|
|
// [{ ... }]
|
||
|
|
```
|
||
|
|
|
||
|
|
#### `player.playlist.currentItem([Number index]) -> Number`
|
||
|
|
|
||
|
|
Get or set the current item index.
|
||
|
|
|
||
|
|
If called without arguments, it is a getter. With an argument, it is a setter.
|
||
|
|
|
||
|
|
If the player is currently playing a non-playlist video, it will return `-1`.
|
||
|
|
|
||
|
|
```js
|
||
|
|
var samplePlaylist = [{
|
||
|
|
sources: [{
|
||
|
|
src: 'http://media.w3.org/2010/05/sintel/trailer.mp4',
|
||
|
|
type: 'video/mp4'
|
||
|
|
}],
|
||
|
|
poster: 'http://media.w3.org/2010/05/sintel/poster.png'
|
||
|
|
}, {
|
||
|
|
sources: [{
|
||
|
|
src: 'http://media.w3.org/2010/05/bunny/trailer.mp4',
|
||
|
|
type: 'video/mp4'
|
||
|
|
}],
|
||
|
|
poster: 'http://media.w3.org/2010/05/bunny/poster.png'
|
||
|
|
}];
|
||
|
|
|
||
|
|
player.playlist(samplePlaylist);
|
||
|
|
|
||
|
|
player.currentItem();
|
||
|
|
// 0
|
||
|
|
|
||
|
|
player.currentItem(2);
|
||
|
|
// 2
|
||
|
|
|
||
|
|
player.src('http://example.com/video.mp4');
|
||
|
|
player.playlist.currentItem();
|
||
|
|
// -1
|
||
|
|
```
|
||
|
|
|
||
|
|
#### `player.playlist.contains(String|Object|Array value) -> Boolean`
|
||
|
|
|
||
|
|
Determine whether a string, source object, or playlist item is contained within a playlist.
|
||
|
|
|
||
|
|
Assuming the playlist used above, consider the following example:
|
||
|
|
|
||
|
|
```js
|
||
|
|
player.playlist.contains('http://media.w3.org/2010/05/sintel/trailer.mp4');
|
||
|
|
// true
|
||
|
|
|
||
|
|
player.playlist.contains([{
|
||
|
|
src: 'http://media.w3.org/2010/05/sintel/poster.png',
|
||
|
|
type: 'image/png'
|
||
|
|
}]);
|
||
|
|
// false
|
||
|
|
|
||
|
|
player.playlist.contains({
|
||
|
|
sources: [{
|
||
|
|
src: 'http://media.w3.org/2010/05/sintel/trailer.mp4',
|
||
|
|
type: 'video/mp4'
|
||
|
|
}]
|
||
|
|
});
|
||
|
|
// true
|
||
|
|
```
|
||
|
|
|
||
|
|
#### `player.playlist.indexOf(String|Object|Array value) -> Number`
|
||
|
|
|
||
|
|
Get the index of a string, source object, or playlist item in the playlist. If not found, returns `-1`.
|
||
|
|
|
||
|
|
Assuming the playlist used above, consider the following example:
|
||
|
|
|
||
|
|
```js
|
||
|
|
player.playlist.indexOf('http://media.w3.org/2010/05/bunny/trailer.mp4');
|
||
|
|
// 1
|
||
|
|
|
||
|
|
player.playlist.contains([{
|
||
|
|
src: 'http://media.w3.org/2010/05/bunny/movie.mp4',
|
||
|
|
type: 'video/mp4'
|
||
|
|
}]);
|
||
|
|
// 3
|
||
|
|
|
||
|
|
player.playlist.contains({
|
||
|
|
sources: [{
|
||
|
|
src: 'http://media.w3.org/2010/05/video/movie_300.mp4',
|
||
|
|
type: 'video/mp4'
|
||
|
|
}]
|
||
|
|
});
|
||
|
|
// 4
|
||
|
|
```
|
||
|
|
|
||
|
|
#### `player.playlist.currentIndex() -> Number`
|
||
|
|
|
||
|
|
Get the index of the current item in the playlist. This is identical to calling `currentItem()` with no arguments.
|
||
|
|
|
||
|
|
```js
|
||
|
|
var samplePlaylist = [{
|
||
|
|
sources: [{
|
||
|
|
src: 'http://media.w3.org/2010/05/sintel/trailer.mp4',
|
||
|
|
type: 'video/mp4'
|
||
|
|
}],
|
||
|
|
poster: 'http://media.w3.org/2010/05/sintel/poster.png'
|
||
|
|
}, {
|
||
|
|
sources: [{
|
||
|
|
src: 'http://media.w3.org/2010/05/bunny/trailer.mp4',
|
||
|
|
type: 'video/mp4'
|
||
|
|
}],
|
||
|
|
poster: 'http://media.w3.org/2010/05/bunny/poster.png'
|
||
|
|
}];
|
||
|
|
|
||
|
|
player.currentIndex();
|
||
|
|
// 0
|
||
|
|
```
|
||
|
|
|
||
|
|
#### `player.playlist.nextIndex() -> Number`
|
||
|
|
|
||
|
|
Get the index of the next item in the playlist.
|
||
|
|
|
||
|
|
If the player is on the last item, returns the last item's index. However, if the playlist repeats and is on the last item, returns `0`.
|
||
|
|
|
||
|
|
If the player is currently playing a non-playlist video, it will return `-1`.
|
||
|
|
|
||
|
|
```js
|
||
|
|
var samplePlaylist = [{
|
||
|
|
sources: [{
|
||
|
|
src: 'http://media.w3.org/2010/05/sintel/trailer.mp4',
|
||
|
|
type: 'video/mp4'
|
||
|
|
}],
|
||
|
|
poster: 'http://media.w3.org/2010/05/sintel/poster.png'
|
||
|
|
}, {
|
||
|
|
sources: [{
|
||
|
|
src: 'http://media.w3.org/2010/05/bunny/trailer.mp4',
|
||
|
|
type: 'video/mp4'
|
||
|
|
}],
|
||
|
|
poster: 'http://media.w3.org/2010/05/bunny/poster.png'
|
||
|
|
}];
|
||
|
|
|
||
|
|
player.playlist(samplePlaylist);
|
||
|
|
|
||
|
|
player.nextIndex();
|
||
|
|
// 1
|
||
|
|
|
||
|
|
player.next();
|
||
|
|
player.nextIndex();
|
||
|
|
// 1
|
||
|
|
|
||
|
|
player.repeat(true);
|
||
|
|
player.nextIndex();
|
||
|
|
// 0
|
||
|
|
|
||
|
|
player.src('http://example.com/video.mp4');
|
||
|
|
player.playlist.nextIndex();
|
||
|
|
// -1
|
||
|
|
```
|
||
|
|
|
||
|
|
#### `player.playlist.previousIndex() -> Number`
|
||
|
|
|
||
|
|
Get the index of the previous item in the playlist.
|
||
|
|
|
||
|
|
If the player is on the first item, returns `0`. However, if the playlist repeats and is on the first item, returns the last item's index.
|
||
|
|
|
||
|
|
If the player is currently playing a non-playlist video, it will return `-1`.
|
||
|
|
|
||
|
|
```js
|
||
|
|
var samplePlaylist = [{
|
||
|
|
sources: [{
|
||
|
|
src: 'http://media.w3.org/2010/05/sintel/trailer.mp4',
|
||
|
|
type: 'video/mp4'
|
||
|
|
}],
|
||
|
|
poster: 'http://media.w3.org/2010/05/sintel/poster.png'
|
||
|
|
}, {
|
||
|
|
sources: [{
|
||
|
|
src: 'http://media.w3.org/2010/05/bunny/trailer.mp4',
|
||
|
|
type: 'video/mp4'
|
||
|
|
}],
|
||
|
|
poster: 'http://media.w3.org/2010/05/bunny/poster.png'
|
||
|
|
}];
|
||
|
|
|
||
|
|
player.playlist(samplePlaylist, 1);
|
||
|
|
|
||
|
|
player.previousIndex();
|
||
|
|
// 0
|
||
|
|
|
||
|
|
player.previous();
|
||
|
|
player.previousIndex();
|
||
|
|
// 0
|
||
|
|
|
||
|
|
player.repeat(true);
|
||
|
|
player.previousIndex();
|
||
|
|
// 1
|
||
|
|
|
||
|
|
player.src('http://example.com/video.mp4');
|
||
|
|
player.playlist.previousIndex();
|
||
|
|
// -1
|
||
|
|
```
|
||
|
|
|
||
|
|
#### `player.playlist.lastIndex() -> Number`
|
||
|
|
|
||
|
|
Get the index of the last item in the playlist.
|
||
|
|
|
||
|
|
```js
|
||
|
|
var samplePlaylist = [{
|
||
|
|
sources: [{
|
||
|
|
src: 'http://media.w3.org/2010/05/sintel/trailer.mp4',
|
||
|
|
type: 'video/mp4'
|
||
|
|
}],
|
||
|
|
poster: 'http://media.w3.org/2010/05/sintel/poster.png'
|
||
|
|
}, {
|
||
|
|
sources: [{
|
||
|
|
src: 'http://media.w3.org/2010/05/bunny/trailer.mp4',
|
||
|
|
type: 'video/mp4'
|
||
|
|
}],
|
||
|
|
poster: 'http://media.w3.org/2010/05/bunny/poster.png'
|
||
|
|
}];
|
||
|
|
|
||
|
|
player.lastIndex();
|
||
|
|
// 1
|
||
|
|
```
|
||
|
|
|
||
|
|
#### `player.playlist.first() -> Object|undefined`
|
||
|
|
|
||
|
|
Play the first item in the playlist.
|
||
|
|
|
||
|
|
Returns the activated playlist item unless the playlist is empty (in which case, returns `undefined`).
|
||
|
|
|
||
|
|
```js
|
||
|
|
player.playlist.first();
|
||
|
|
// { ... }
|
||
|
|
|
||
|
|
player.playlist([]);
|
||
|
|
player.playlist.first();
|
||
|
|
// undefined
|
||
|
|
```
|
||
|
|
|
||
|
|
#### `player.playlist.last() -> Object|undefined`
|
||
|
|
|
||
|
|
Play the last item in the playlist.
|
||
|
|
|
||
|
|
Returns the activated playlist item unless the playlist is empty (in which case, returns `undefined`).
|
||
|
|
|
||
|
|
```js
|
||
|
|
player.playlist.last();
|
||
|
|
// { ... }
|
||
|
|
|
||
|
|
player.playlist([]);
|
||
|
|
player.playlist.last();
|
||
|
|
// undefined
|
||
|
|
```
|
||
|
|
|
||
|
|
#### `player.playlist.next() -> Object`
|
||
|
|
|
||
|
|
Advance to the next item in the playlist.
|
||
|
|
|
||
|
|
Returns the activated playlist item unless the playlist is at the end (in which case, returns `undefined`).
|
||
|
|
|
||
|
|
```js
|
||
|
|
player.playlist.next();
|
||
|
|
// { ... }
|
||
|
|
|
||
|
|
player.playlist.last();
|
||
|
|
player.playlist.next();
|
||
|
|
// undefined
|
||
|
|
```
|
||
|
|
|
||
|
|
#### `player.playlist.previous() -> Object`
|
||
|
|
|
||
|
|
Go back to the previous item in the playlist.
|
||
|
|
|
||
|
|
Returns the activated playlist item unless the playlist is at the beginning (in which case, returns `undefined`).
|
||
|
|
|
||
|
|
```js
|
||
|
|
player.playlist.next();
|
||
|
|
// { ... }
|
||
|
|
|
||
|
|
player.playlist.previous();
|
||
|
|
// { ... }
|
||
|
|
|
||
|
|
player.playlist.first();
|
||
|
|
// { ... }
|
||
|
|
|
||
|
|
player.playlist.previous();
|
||
|
|
// undefined
|
||
|
|
```
|
||
|
|
|
||
|
|
#### `player.playlist.autoadvance([Number delay]) -> undefined`
|
||
|
|
|
||
|
|
Sets up playlist auto-advance behavior.
|
||
|
|
|
||
|
|
Once invoked, at the end of each video in the playlist, the plugin will wait `delay` seconds before proceeding automatically to the next video.
|
||
|
|
|
||
|
|
Any value which is not a positive, finite integer, will be treated as a request to cancel and reset the auto-advance behavior.
|
||
|
|
|
||
|
|
If you change auto-advance during a delay, the auto-advance will be canceled and it will not advance the next video, but it will use the new timeout value for the following videos.
|
||
|
|
|
||
|
|
```js
|
||
|
|
// no wait before loading in the next item
|
||
|
|
player.playlist.autoadvance(0);
|
||
|
|
|
||
|
|
// wait 5 seconds before loading in the next item
|
||
|
|
player.playlist.autoadvance(5);
|
||
|
|
|
||
|
|
// reset and cancel the auto-advance
|
||
|
|
player.playlist.autoadvance();
|
||
|
|
```
|
||
|
|
|
||
|
|
#### `player.playlist.repeat([Boolean val]) -> Boolean`
|
||
|
|
|
||
|
|
Enable or disable repeat by passing true or false as the argument.
|
||
|
|
|
||
|
|
When repeat is enabled, the "next" video after the final video in the playlist is the first video in the playlist. This affects the behavior of calling `next()`, of autoadvance, and so on.
|
||
|
|
|
||
|
|
This method returns the current value. Call with no argument to use as a getter.
|
||
|
|
|
||
|
|
Examples:
|
||
|
|
|
||
|
|
```js
|
||
|
|
|
||
|
|
player.playlist.repeat(true);
|
||
|
|
|
||
|
|
player.playlist.repeat();
|
||
|
|
// true
|
||
|
|
|
||
|
|
player.playlist.repeat(false);
|
||
|
|
player.playlist.repeat();
|
||
|
|
// false
|
||
|
|
|
||
|
|
```
|
||
|
|
|
||
|
|
#### `player.playlist.sort([Function compare]) -> undefined`
|
||
|
|
|
||
|
|
Sort the playlist in a manner identical to [`Array#sort`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort).
|
||
|
|
|
||
|
|
Fires the `playlistsorted` event after sorting.
|
||
|
|
|
||
|
|
#### `player.playlist.reverse() -> undefined`
|
||
|
|
|
||
|
|
Reverse the playlist in a manner identical to [`Array#reverse`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reverse).
|
||
|
|
|
||
|
|
Fires the `playlistsorted` event after reversing.
|
||
|
|
|
||
|
|
#### `player.playlist.shuffle() -> undefined`
|
||
|
|
|
||
|
|
Shuffles/randomizes the order of playlist items in a manner identical to [`lodash.shuffle`](https://lodash.com/docs/4.17.4#shuffle).
|
||
|
|
|
||
|
|
Fires the `playlistsorted` event after shuffling.
|
||
|
|
|
||
|
|
## Events
|
||
|
|
|
||
|
|
### `duringplaylistchange`
|
||
|
|
|
||
|
|
This event is fired _after_ the contents of the playlist are changed when calling `playlist()`, but _before_ the current playlist item is changed. The event object has several special properties:
|
||
|
|
|
||
|
|
- `nextIndex`: The index from the next playlist that will be played first.
|
||
|
|
- `nextPlaylist`: A shallow clone of the next playlist.
|
||
|
|
- `previousIndex`: The index from the previous playlist (will always match the current index when this event triggers, but is provided for completeness).
|
||
|
|
- `previousPlaylist`: A shallow clone of the previous playlist.
|
||
|
|
|
||
|
|
**NOTE**: This event fires every time `player.playlist()` is called - including the first time.
|
||
|
|
|
||
|
|
#### Caveats
|
||
|
|
|
||
|
|
During the firing of this event, the playlist is considered to be in a **changing state**, which has the following effects:
|
||
|
|
|
||
|
|
- Calling the main playlist method (i.e. `player.playlist([...])`) will throw an error.
|
||
|
|
- Playlist navigation methods - `first`, `last`, `next`, and `previous` - are rendered inoperable.
|
||
|
|
- The `currentItem()` method only acts as a getter.
|
||
|
|
- While the sorting methods - `sort`, `reverse`, and `shuffle` - will continue to work, they do not fire the `playlistsorted` event.
|
||
|
|
|
||
|
|
#### Why have this event?
|
||
|
|
|
||
|
|
This event provides an opportunity to intercept the playlist setting process before a new source is set on the player and before the `playlistchange` event fires, while providing a consistent playlist API.
|
||
|
|
|
||
|
|
One use-case might be shuffling a playlist that has just come from a server, but before its initial source is loaded into the player or the playlist UI is updated:
|
||
|
|
|
||
|
|
```js
|
||
|
|
player.on('duringplaylistchange', function() {
|
||
|
|
|
||
|
|
// Remember, this will not trigger a "playlistsorted" event!
|
||
|
|
player.playlist.shuffle();
|
||
|
|
});
|
||
|
|
|
||
|
|
player.on('playlistchange', function() {
|
||
|
|
videojs.log('The playlist was shuffled, so the UI can be updated.');
|
||
|
|
});
|
||
|
|
```
|
||
|
|
|
||
|
|
### `playlistchange`
|
||
|
|
|
||
|
|
This event is fired _asynchronously_ whenever the contents of the playlist are changed (i.e., when `player.playlist()` is called with an argument) - except the first time.
|
||
|
|
|
||
|
|
It is fired asynchronously to let the browser start loading the first video in the new playlist.
|
||
|
|
|
||
|
|
```js
|
||
|
|
player.on('playlistchange', function() {
|
||
|
|
player.playlist();
|
||
|
|
});
|
||
|
|
|
||
|
|
player.playlist([]);
|
||
|
|
// [ ... ]
|
||
|
|
|
||
|
|
player.playlist([]);
|
||
|
|
// [ ... ]
|
||
|
|
```
|
||
|
|
|
||
|
|
#### Backward Compatibility
|
||
|
|
|
||
|
|
This event _does not fire_ the first time `player.playlist()` is called. If you want it to fire on the first call to `player.playlist()`, you can call it without an argument before calling it with one:
|
||
|
|
|
||
|
|
```js
|
||
|
|
// This will fire no events.
|
||
|
|
player.playlist();
|
||
|
|
|
||
|
|
// This will fire both "duringplaylistchange" and "playlistchange"
|
||
|
|
player.playlist([...]);
|
||
|
|
```
|
||
|
|
|
||
|
|
This behavior will be removed in v5.0.0 and the event will fire in all cases.
|
||
|
|
|
||
|
|
### `beforeplaylistitem`
|
||
|
|
|
||
|
|
This event is fired before switching to a new content source within a playlist (i.e., when any of `currentItem()`, `first()`, or `last()` is called, but before the player's state has been changed).
|
||
|
|
|
||
|
|
### `playlistitem`
|
||
|
|
|
||
|
|
This event is fired when switching to a new content source within a playlist (i.e., when any of `currentItem()`, `first()`, or `last()` is called; after the player's state has been changed, but before playback has been resumed).
|
||
|
|
|
||
|
|
### `playlistsorted`
|
||
|
|
|
||
|
|
This event is fired when any method is called that changes the order of playlist items - `sort()`, `reverse()`, or `shuffle()`.
|