Playlist JavaScript Public API Documentation v1.0.1

This document describes the API provided by the JavaScript file playlist.js. For a tutorial, see How To Embed The Playlist In Your Web Page.

This documentation is for the old API which is no longer supported. If you're going to start a new web page, please reference the new Snip API. This page is provided for those who are still on the original API implementation.

Variables

PlaylistObject

The Playlist is implemented via a JavaScript prototype ("class"), PlaylistObject. This is described in detail below.

PlaylistVersion

A string that encodes the full current version of the player.

PlaylistVersionAPI

A string that stores the API version of the player (no micro version, in "major.minor" format).

PlaylistObject - Constructors

`new PlaylistObject(Object player)`

Parameter Name	Parameter Type	Description
`player`	`Object`	YouTube embedded flash player instance

The PlaylistObject prototype can be created once the YouTube embedded Flash player executes the onYouTubePlayerReady function:

function onYouTubePlayerReady() {
    var ytplayer = document.getElementById("myytplayer");
    playlist = new PlaylistObject(ytplayer);
}

PlaylistObject - Fields

Field Name	Field Type	Read Only?	Description
`size`	`int`	Yes	Total number of videos currently loaded into the playlist.
`player`	`Object`	Yes	The YouTube embedded Flash player, as passed into the constructor.
`callback`	`function`	No	The `callback` function allows for the embedding web page to discover when different events occur within the playlist instance. See the event reference for details into the usage of this function.
`autostart`	`boolean`	No	`true` (default value) means that next videos in the playlist will automatically start after the previous one completes. This does not apply to the invocation of `ready()`.
`allowResize`	`boolean`	No	`true` means that the video structure can specify the `width` and `height` of the video player when that video is played. The default value, `false`, means that the video player will ignore the video size setting per video file. Note that if a video does not specify a video size while `allowResize = true`, then it will use the video size of the previously played video.
`maxSeekAttempts`	`boolean`	No	The maximum number of attempts to seek a video to the start position. If the number of attempts exceeds this value, then the video is assumed to not be capable of seeking correctly, and the video playback will fail.

PlaylistObject - Methods

`add(Object video)`

Parameter	Type	Description
`video`	`Object`	A non-null object/dictionary. See below for details on this object.

Adds a single video to the end of the playlist. The "video" here is described by the parameter object, which can have any attributes the user may need to support the website. For use with the Playlist API, it must provide the vId attribute. The following attributes are recognized and reserved for the Playlist API:

Key	Value Type	Description
`vId`	`string`	YouTube video ID of the video to show
`start`	`float`	offset (in seconds) from the start of the video, for where the video should begin playing. If not specified, this defaults to 0.
`end`	`float`	offset (in seconds) from the start of the video, for where the video should stop playing. Any value less than the `start` value means the video will play to the end. If not specified, this defaults to -1.
`width`	`float`	sets the width of the video player when the video is played; only used if the allowResize field is set to `true`, and the `height` attribute of the video is set.
`height`	`float`	sets the height of the video player when the video is played; only used if the allowResize field is set to `true`, and the `width` attribute of the video is set.
`quality`	`string`	if set to "hq" or "hd", the video player will attempt to load the video as either high-quality or high-definition, respecitively. If not set or any other value, then the video will load at the default resolution.

This call does not affect the state of the video player.

`addAll(Object[] videoArray)`

Parameter	Type	Description
`videoArray`	`Object[]`	A non-null array of object/dictionary objects. See `add(Object)` for details on these objects.

Adds all the video objects in the videoArray to the end of the playlist, in order.

This call does not affect the state of the video player.

`insert(int indx, Object video)`

Parameter	Type	Description
`indx`	`int`	index in the playlist to place the video. To insert a video at the beginning of the playlist, use index `0`.
`video`	`Object`	A non-null object/dictionary. See `add(Object)` for details on these objects.

Adds the video object into the playlist at the specified location. All videos in the playlist will move up. If there is an already playing video, the playlist will compensate such that the next video will be after the currently playing video.

This call does not affect the state of the video player.

`remove(int indx)`

Parameter	Type	Description
`indx`	`int`	index of the video in the playlist to remove. To remove the first video in the playlist, use index `0`.

Removes the video at the given index from the playlist. If the index is before the currently playing video, then the state will be correctly compensated. If the currently playing video is removed, then certain queries into the state of the playlist will return inaccurate information - getCurrentVideo() will return the video before the current one.

This call does not affect the state of the video player.

`clear()`

Removes all videos from the playlist.

This call does not affect the state of the video player.

`ready()`

Prepares the Playlist instance for playback in the video player. The video player will be queued with the first video, which means there must be at least one video in the playlist. This must be done before the playlist can be used, generally in the same method that creates and loads the playlist with videos.

`getCurrentVideo()`

Returns: object/dictionary of the video

Returns the video object added to the playlist, which is currently loaded in the video player. If nothing is showing in the video player (either the ready() method hasn't been called, or the playlist has finished), then this returns null.

`getCurrentVideoIndex()`

Returns: int

Returns the index in the playlist of the currently playing video. If the ready() method hasn't been called, then this returns -1. If it returns size, then the playlist has finished. The first video has an index of 0.

`hasMore()`

Returns: boolean

Returns true if there are more videos in the playlist that can be played, or false if there are not. This is independent of the initialization status of the associated player.

`setNextVideo(int indx)`

Parameter	Type	Description
`indx`	`int`	index of the video in the playlist to play next. To set the next video to the first video, use an index of `0`.

Sets the next video to play in the playlist by index. The next call to loadNextVideo(boolean) will load this video.

If the index is less than or equal to 0, then the next video will be at the beginning of the playlist. If the index is greater or equal to the size of the playlist, then there will be no more videos played.

This call does not affect the state of the video player.

`loadNextVideo(boolean immediatePlayback)`

Parameter	Type	Description
`immediatePlayback`	`boolean`	`true` if the video should play as soon as it loads, otherwise `false`.

Returns: boolean - true if there was another video to load, or false if the playlist ended.

Advances the video player to the next video in the playlist. If the parameter is true, then the video will also start playing as soon as it finishes loading.

Under normal operation, this method is called automatically when a video finishes playing.

`getVideos()`

Returns: a copy of the list of video objects.

Retrieves a copy of the list of video objects in the playlist. The video objects themselves will be the live objects used by the playlist, but altering the list itself will do nothing to the playlist state.

`getState()`

Returns: an object reporting the current state of the player

Summarizes the current state of the player. The object returned will have the following attributes:

Key	Value Type	Description
`ready`	`boolean`	`true` if the player is initialized and ready to be used, or `false` if the YouTube player has not completed loading.
`player`	`string`	An English-readable string that describes the current state of the player. It can be one of the following values: not playing the player is not playing a video (stopped) playing the player is playing a video paused the player is paused in the middle of playing a video buffering the player loading a video
`playlist`	`string`	An English-readable string that describes the current state of the playlist object. It can be one of the following values: not initialized the playlist has not been initialized yet, and cannot be used. has more the playlist has more videos pending to play end of list the playlist has reached the end of its list of videos to play

`onStateChange(int newstate)`

Parameter	Type	Description
`newstate`	`int`	input parameter to the `onStateChange` listener (YouTube player-specific state value)

Handles management of internal settings and the video player. It must be invoked by user code when the registered onStateChange event callback on the video player is invoked.

`onTimer()`

Handles management of internal settings and the video player. It must be invoked by user code when the interval timer thread is invoked.

PlaylistObject - Events

The PlaylistObject can inform the embedding web page when certain events occur during playback. It does this by calling to the callback field of the instance. This must be a function (and not a string).

The function is in the form:

function myCallback(obj) { ...

The event is passed in the obj parameter, which is a dictionary containing the event's properties. There are different event types generated by the playlist, each represented by the "status" string attribute in the obj parameter:

Playlist_NEXT - a request was made to the player to start loading the next video in the playlist. String value: NEXT
Playlist_LOADING - the player has begun loading the next video in the playlist. String value: LOADING
Playlist_START_PLAYBACK - the player has started automatic playback of the next video in the playlist. Note that if the user manually must start the playback, then this event is never called, and instead calls WAITING FOR USER. String value: START PLAYBACK
Playlist_WAITING_FOR_USER - the player has completed loading and seeking the video, and is waiting for the user to manually start the video. String value: WAITING FOR USER
Playlist_FINISHED - the playlist has become empty. String value: FINISHED
Playlist_ERROR - an unexpected error occurred. String value: ERROR

The following table describes the attributes associated with each event.

Event	Attribute	Type	Description
(All)	`status`	`string`	the event code ("NEXT", "LOADING", "START PLAYBACK", "WAITING FOR USER", "FINISHED", or "ERROR")
(All)	`playlist`	`PlaylistObject`	the playlist instance that generated the event.
NEXT, LOADING, START PLAYBACK, WAITING FOR USER	`index`	`int`	the index in the playlist for the video under consideration.
NEXT, LOADING, START PLAYBACK, WAITING FOR USER	`video`	`dictionary`	the video object under consideration. This is the same instance as was added to the player, and so will have all the user-specific data associated with it.
NEXT, LOADING, START PLAYBACK, WAITING FOR USER	`autostart`	`boolean`	`true` if the loaded video was/will be played immediately after loading, otherwise `false`.
ERROR	`errid`	`int`	error code for the kind of error. This allows for easier machine handling of different error conditions.
ERROR	`msgid`	`int`	an integer representing the message, for easier computer parsing of the error.
ERROR	`msg`	`string`	a human-readable error message describing what went wrong.

In the case of an ERROR, these are the different error IDs and message IDs the playlist can generate. In each situation, the playlist will be in a state similar to when the video is loaded, waiting for the user to start it.

Category	Error ID	Message ID	Description
Internal Error	1	1	Invalid state transition
Internal Error	2	3	Invalid state
Usage	3	4	Video object is null
Video Format	4	5	Video does not support seek operation