This document describes the API provided by the JavaScript file
playlist-helper.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.
Required Files
playlist-helper.js requires 2 external JavaScript source files in order to work correctly.
These are the playlist.js and swfobject.js files:
<script
src="http://swfobject.googlecode.com/svn/tags/rc3/swfobject/src/swfobject.js"
type="text/javascript"></script>
<script
src="http://ytsnip.sf.net/playlist.js"
type="text/javascript"></script>
In addition to these, playlist-helper.js requires 2 external JavaScript source files in order to
properly handle the downloading of remote playlists. They are not needed unless your web page supports this
functionality. You can insert the following header-level tags to include them:
<script
src="http://groboclown.net/yt_playlist/async.js"
type="text/javascript"></script>
<script
src="http://www.json.org/json2.js"
type="text/javascript"></script>
Global Functions
onYouTubePlayerReady()
The required function for interacting with the YouTube player. Provided here to make embedding the playlist easier.
PlaylistHelper - Fields
| Field Name | Field Type | Read Only? | Description |
PlaylistHelper.version | string | Yes | String specifying the version of the file currently loaded. |
PlaylistHelper.userTimerCallback | function | No | The userTimerCallback function allows for the embedding web page to hook into the
timer events generated by the PlaylistHelper. The function takes no arguments,
and is called after the PlaylistHelper has completed its actions. |
PlaylistHelper.userErrorCallback | function | No | The userErrorCallback function allows for the embedding web page to react to
different error conditions from the playlist and player. The function takes a single argument, which is
a description of the error message. |
PlaylistHelper.allowResize | boolean | No | This value is passed to all instantiated
PlaylistObject
objects. See that documentation for details. |
PlaylistHelper.playerWidth | int | No | The base width of the video player. This can be later altered by changing the player width value. |
PlaylistHelper.playerHeight | int | No | The base height of the video player. This can be later altered by changing the player height value. |
PlaylistHelper - Functions
PlaylistHelper.addPlayer(string divId)
| Parameter | Type | Description |
|---|---|---|
divId | string | A non-null div tag ID attribute value for where to place the
new player. |
Returns: a new PHO instance if the divId has not been added, or the existing PHO instance if the divId has already been added.
Allocates a YouTube player and playlist for the web page, but does not
embed it in the page. A call to PHO.createPlayer()
must be made in order to create the player itself.
PlaylistHelper.getPlayer(string divId)
| Parameter | Type | Description |
|---|---|---|
divId | string | div tag ID attribute value for the added player. |
Returns: the PHO instance for the
div tag with the given ID, or null if it was not created.
Returns the PHO instance created with a call to
PlaylistHelper.addPlayer(string)
or
PlaylistHelper.createPlayer(string)
or
null if it could not be found.
PlaylistHelper.createPlayer(string divId)
This function is deprecated, and will be removed from the 1.0 version. Please
use PHO.createPlayer()
instead.
| Parameter | Type | Description |
|---|---|---|
divId | string | div tag ID attribute value for the added player. |
Returns: the constructed PHO instance
Convenience function that wraps a call to
PlaylistHelper.addPlayer(string)
followed by PHO.createPlayer()
. This returns the
created PHO instance.
PlaylistHelper.createPlayers()
This function is deprecated, and will be removed from the 1.0 version. Please
use PHO.createPlayer()
instead.
Creates the embedded YouTube player into the web page, and begins the process
of initializing the players and a
PlaylistObject
instance, for each added-but-not-created player from calls to
PlaylistHelper.addPlayer(string)
.
PlaylistHelper.addVideos(Object p, Object[] videoList)
This function is deprecated, and will be removed from the 1.0 version. Please
use PHO.createPlayer()
instead.
| Parameter | Type | Description |
|---|---|---|
p | Object | the PHO instance |
videoList | Object[] | array of videos to load |
Appends a list of videos to the playlist, similar to addAll(Object[] videoArray).
The main difference is that, if the playlist hasn't been created yet, then the added videos will
be appended to the pending object's initialVideos list. Thus, this method is a safe way to
add videos to a playlist, regardless of its current state.
PlaylistHelper.loadPlaylistJSon(Object p, string url, function callback)
This function is deprecated, and will be removed from the 1.0 version. Please
use PHO.loadRemotePlaylistJSon()
instead.
| Parameter | Type | Description |
|---|---|---|
p | Object | the PHO instance |
url | string | Fully-specified URL from which to load the JSon playlist. |
callback | function | Function to invoke when the playlist has completed loading. It takes a single argument - a boolean. |
Appends the playlist of the passed-in player p with the videos specified in the JSON formatted file
at the given URL. The format for the JSON file is specified here.
After loading the playlist, the callback will be invoked, with a true argument for success, or
false if it failed to load for some reason.
PlaylistHelper.loadPlaylistXML(Object p, string url, function callback)
This function is deprecated, and will be removed from the 1.0 version. Please
use PHO.loadRemotePlaylistXML()
instead.
| Parameter | Type | Description |
|---|---|---|
p | Object | the PHO instance |
url | string | Fully-specified URL from which to load the JSon playlist. |
callback | function | Function to invoke when the playlist has completed loading. It takes a single argument - a boolean. |
Appends the playlist of the passed-in player p with the videos specified in the XML formatted file
at the given URL. The format for the XML file is specified here.
After loading the playlist, the callback will be invoked, with a true argument for success, or
false if it failed to load for some reason.
PHO Class
The PHO class is returned by
PlaylistHelper.addPlayer([divId, string])
and by
PlaylistHelper.createPlayer([divId, string])
.
It allows convienience methods for accessing both the instantiated YouTube
player functions and the playlist.js methods.
PHO - Fields
| Field Name | Field Type | Read Only? | Description |
divId | string | Yes | The div ID that contains the player. |
player | Object | Yes | The YouTube player object. Will be null until initialized. |
playlist | Object | Yes | The PlaylistObject
instance for the associated player. Will be null until initialized. |
width | int | No | Initial width of the player. Defaults to
PlaylistHelper.playerWidth.
Once the playlist is initialzed, this field will not be used. |
height | int | No | Initial height of the player. Defaults to
PlaylistHelper.playerHeight.
Once the playlist is initialzed, this field will not be used. |
initialVideos | Array(Video Object) | No | Array of the videos to load initially into the playlist, once the playlist
is created. See
PlaylistObject.addAll(Object[])
for a description of the value this can be assigned to. This defaults to
null. Once the playlist is initialzed, this field will not be
used. |
autostart | boolean | No | The value to use in the created playlist object's
autostart
field value. Defaults to false.
Once the playlist is initialzed, this field will not be used. |
allowResize | boolean | No | The value to use in the created playlist object's
allowResize
field value. Defaults to PlaylistHelper.allowResize.
Once the playlist is initialzed, this field will not be used. |
callback | function | No | The playlist object's callback
field value. Defaults to null.
Once the playlist is initialzed, this field will not be used. |
title | string | No | The title for the playlist. |
PHO - Methods
PHO.create()
This function is deprecated, and will be removed from the 1.0 version. Please
use PHO.embed()
instead.
Embeds the YouTube video into the div tag (passed in at object
creation time). This starts the initialization process for the PHO instance.
PHO.embed()
Embeds the YouTube video into the div tag (passed in at object
creation time). This starts the initialization process for the PHO instance.
PHO.addVideos(Object[] videoList)
| Parameter | Type | Description |
|---|---|---|
videoList | Object[] | Array of videos to load |
Appends a list of videos to the playlist, similar to
addAll(Object[]).
The main difference is that, if the playlist hasn't been created yet, then the
added videos will be appended to the pending object's initialVideos
list. Thus, this method is a safe way to add videos to a playlist, regardless
of its current state.
PHO.addVideo(Object video)
| Parameter | Type | Description |
|---|---|---|
video | Object | video description |
Appends a single video description to the playlist.
PHO.insertVideoAt(int index, Object video)
| Parameter | Type | Description |
|---|---|---|
index | int | index in the playlist to insert the video |
video | Object | video description |
Inserts the video to the given index in the playlist. If index
is outside the bounds of the playlist (less than 0 or greater than the current
length), it will be changed to the boundary. A null video
will be safely ignored.
PHO.removeVideoAt(int index)
| Parameter | Type | Description |
|---|---|---|
index | int | index in the playlist to remove |
Removes the video at the given index. If the index is out of bounds, the removal will be ignored.
PHO.removeAllVideos()
Removes all videos in the playlist.
PHO.setNextVideoIndex(int index)
| Parameter | Type | Description |
|---|---|---|
index | int | video index |
Sets the next video index to play. Only usable if the playlist has been embedded and initialized. If the index is out of range to the current video list, the index will be bounded - if the index is less than zero, the first video in the list to be played next, and above the list size the playlist will end when the current one finishes.
PHO.loadRemotePlaylistJSon(string url, function callback)
| Parameter | Type | Description |
|---|---|---|
url | string | Fully-specified URL from which to load the playlist. |
callback | function | Function to invoke when the playlist has completed loading. It takes a
single argument - a boolean. |
Appends the playlist with the videos specified in the JSON formatted file
at the given URL. The format for the JSON file is specified
here.
After loading the playlist, the callback will be invoked, with a
true argument for success, or
false if it failed to load for some reason.
PHO.loadRemotePlaylistXML(string url, function callback)
| Parameter | Type | Description |
|---|---|---|
url | string | Fully-specified URL from which to load the playlist. |
callback | function | Function to invoke when the playlist has completed loading. It takes a
single argument - a boolean. |
Appends the playlist with the videos specified in the XML formatted file
at the given URL. The format for the XML file is specified
here.
After loading the playlist, the callback will be invoked, with a
true argument for success, or
false if it failed to load for some reason.
PHO.getState()
Returns: an object/dictionary that contains information describing the playlist helper's state
If the instance has been embedded and initialized, then this will return the
same value as
PlaylistObject.getState().
If not, then the returned object will have these settings:
- ready: false
- player: "not playing"
- playlist: "not initialized"
In both situations, if the YouTube player instance has not been embedded, then
the player value will be set to
"not initialized"
PHO.getVideos()
Returns: copy of the current video playlist
If the instance has been initialized, then this returns the same value as
PlaylistObject.getVideos().
Otherwise, it returns a copy of the initialVideos
field. It will never return null.
PHO.play()
Plays the currently loaded video if the player is initialized and a video is loaded, otherwise does nothing.
PHO.pause()
Pauses the currently playing video if the player is initialized and a video is loaded, otherwise does nothing.
PHO.nextVideo(boolean autostart)
| Parameter | Type | Description |
|---|---|---|
autostart | boolean | true if the next video should start playing upon being loaded, otherwise the video will not start when loaded |
Loads the next video, and plays it after being loaded if the argument is provided and true.
PHO.prevVideo(boolean autostart)
| Parameter | Type | Description |
|---|---|---|
autostart | boolean | true if the previous video should start playing upon being loaded, otherwise the video will not start when loaded |
Loads the previous video, and plays it after being loaded if the argument is provided and true.
PHO.loadPlaylistJSon(string text)
| Parameter | Type | Description |
|---|---|---|
text | string | text version of the JSON-formatted video list |
Loads the video list with the videos provided in the JSON-formatted string argument. The format for the JSON text is specified here.
PHO.loadPlaylistXML(string text)
| Parameter | Type | Description |
|---|---|---|
text | string | text version of the XML-formatted video list |
Loads the video list with the videos provided in the XML-formatted string argument. The format for the JSON text is specified here.
PHO.getCurrentVideo()
Returns: the current video object, or null if none is active.
Retrieve the currently loaded video object, as passed into the playlist. If
no video is loaded, or if the instance is not initialized, null.
PHO.getCurrentVideoIndex()
Returns: -1 if at the beginning of the playlist, size if at the end of the playlist, or the actual index.
Returns -1 if at the beginning of the playlist, size if at the end of the playlist, or the actual index.
PHO.getCurrentVideoInfo()
Returns: copy of the current video object, along with additional information, or null if nothing is playing
Returns a copy of the currently playing video object, augmented with additional information on its playing state. The expected fields will include:
| Parameter | Type | Description |
|---|---|---|
vId | string | YouTube video ID |
start | float | seconds from start of video |
end | float | seconds into the video to stop, or -1 for end |
bytesTotal | int | total byte size of the video |
bytesLoaded | int | number of bytes loaded into the player so far |
absDuration | float | total time for the video, in seconds |
absCurrentTime | float | current position from the start of the video, in seconds |
duration | float | total time that the playlist will play the video, in seconds |
currentTime | float | current position from the playlist start time of the video, in seconds |
index | int | current video index |
quality | string | 'std' for normal video format, 'hq' for high quality, and 'hd' for high definition |
width | int | player current width |
height | int | player current height |
If the video object included custom fields, they will be added to this list.
PHO.absSeekTo(float seconds, boolean autostart)
| Parameter | Type | Description |
|---|---|---|
seconds | float | position, in seconds, to seek to |
autostart | boolean | true if the video should start playing after seeking, otherwise the video will not start after seeking |
Seek to a position in the video relative to the start of the video. If the seconds argument is after the end of the video (either absolute, or the end parameter of the current video), then the player will advance to the next video in the playlist.
PHO.relSeekTo(float seconds, boolean autostart)
| Parameter | Type | Description |
|---|---|---|
seconds | float | position, in seconds, to seek to |
autostart | boolean | true if the video should start playing after seeking, otherwise the video will not start after seeking |
Seek to a position in the video relative to the video's start parameter (or 0 if not specified). If the seconds argument is after the end of the video (either absolute, or the end parameter of the current video), then the player will advance to the next video in the playlist.
