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 NameParameter TypeDescription
playerObjectYouTube 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 NameField TypeRead Only?Description
sizeintYes Total number of videos currently loaded into the playlist.
playerObjectYes The YouTube embedded Flash player, as passed into the constructor.
callbackfunctionNo 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.
autostartbooleanNo 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().
allowResizebooleanNo 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.
maxSeekAttemptsbooleanNo 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)

ParameterTypeDescription
videoObject 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:

KeyValue TypeDescription
vIdstring YouTube video ID of the video to show
startfloat offset (in seconds) from the start of the video, for where the video should begin playing. If not specified, this defaults to 0.
endfloat 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.
widthfloat 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.
heightfloat 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.
qualitystring 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)

ParameterTypeDescription
videoArrayObject[] 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)

ParameterTypeDescription
indxint index in the playlist to place the video. To insert a video at the beginning of the playlist, use index 0.
videoObject 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)

ParameterTypeDescription
indxint 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)

ParameterTypeDescription
indxint 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)

ParameterTypeDescription
immediatePlaybackboolean 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:

KeyValue TypeDescription
readyboolean true if the player is initialized and ready to be used, or false if the YouTube player has not completed loading.
playerstring 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
playliststring 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)

ParameterTypeDescription
newstateint 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:

The following table describes the attributes associated with each event.

EventAttributeTypeDescription
(All)statusstring the event code ("NEXT", "LOADING", "START PLAYBACK", "WAITING FOR USER", "FINISHED", or "ERROR")
(All)playlistPlaylistObject the playlist instance that generated the event.
NEXT, LOADING, START PLAYBACK, WAITING FOR USERindexint the index in the playlist for the video under consideration.
NEXT, LOADING, START PLAYBACK, WAITING FOR USERvideodictionary 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 USERautostartboolean true if the loaded video was/will be played immediately after loading, otherwise false.
ERRORerridint error code for the kind of error. This allows for easier machine handling of different error conditions.
ERRORmsgidint an integer representing the message, for easier computer parsing of the error.
ERRORmsgstring 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.

CategoryError IDMessage IDDescription
Internal Error11Invalid state transition
Internal Error23Invalid state
Usage34Video object is null
Video Format45Video does not support seek operation