YouTube JavaScript Player API Reference

This document provides reference information for the YouTube JavaScript player API.

Overview

The JavaScript API allows users to control the YouTube chromeless or embedded video players via JavaScript. Calls can be made to play, pause, seek to a certain time in a video, set the volume, mute the player, and other useful functions.

Requirements

The end user must have Flash Player 10.1 or higher installed to view everything correctly. Because of this requirement, we suggest using SWFObject to embed the SWF and detect the user's Flash Player version.

In addition, any HTML page that contains the YouTube player must implement a JavaScript function named onYouTubePlayerReady. The API will call this function when the player is fully loaded and the API is ready to receive calls. See the Event Handlers section for more details.

Embedded players must have a viewport that is at least 200px by 200px. If the player displays controls, it must be large enough to fully display the controls without shrinking the viewport below the minimum size. We recommend 16:9 players be at least 480 pixels wide and 270 pixels tall.

Getting Started

Note: To test any of these calls, you must have your file running on a webserver, as the Flash player restricts calls between local files and the internet.

You can enable the JavaScript API handlers for chromeless and embedded players. To enable the JavaScript API for a player, add the URL parameter enablejsapi=1 to the player's URL.

Enabling the JavaScript API for a chromeless player

If your application is using a chromeless player, use the following URL to load the player in your application and enable JavaScript API handlers in the player. You can then build your own custom player controls using JavaScript:
```
http://www.youtube.com/apiplayer?enablejsapi=1&version;=3
```
Enabling the JavaScript API for an embedded player

Use the following URL to load an embedded video player. In the URL, replace the string VIDEO_ID with the 11-character YouTube video ID that identifies the video that the player will show.
```
http://www.youtube.com/v/VIDEO_ID?version=3&enablejsapi=1
```

When the player is ready, the API will call the onYouTubePlayerReady callback function. You can use the optional playerapiid parameter to the player URL to pass a value, such as the player ID, back to the callback function.

http://www.youtube.com/v/VIDEO_ID?enablejsapi=1&version=3&playerapiid=ytplayer

Once the player SWF is loaded, you can use the queueing functions – cueVideoById(), loadVideoById(), cueVideoByUrl(), loadVideoByUrl(), cuePlaylist(), or loadPlaylist() – to load a particular YouTube video or playlist.

The Player API demo lets you compare the chromeless and embedded video players, and the examples below provide more detailed information about how to embed a YouTube player SWF into your page. You can also customize your users' experience by using player parameters to control various types of player behavior.

Operations

In order to call the player API methods, you must first get a reference to the player object you wish to control. If you are using SWFObject to embed the player SWF, you can obtain the reference to the player object by calling getElementById() on the <object> or <embed> tag that contains the player SWF.

Functions

The following subsections list the functions that the player API supports.

This function indicates whether a playlist's videos should be shuffled so that they play back in an order different from the one that the playlist creator designated. If you shuffle a playlist after it has already started playing, the list will be reordered while the video that is playing continues to play. The next video that plays will then be selected based on the reordered list.

This setting will not persist if you load or cue a different playlist, which means that if you load a playlist, call the setShuffle function, and then load a second playlist, the second playlist will not be shuffled.

The required shufflePlaylist parameter indicates whether YouTube should shuffle the playlist.

If the parameter value is true, then YouTube will shuffle the playlist order. If you instruct the function to shuffle a playlist that has already been shuffled, YouTube will shuffle the order again.

If the parameter value is false, then YouTube will change the playlist order back to its original order.

Playback status

player.getVideoLoadedFraction():Float: Returns a number between 0 and 1 that specifies the percentage of the video that the player shows as buffered. This method returns a more reliable number than the now-deprecated getVideoBytesLoaded and getVideoBytesTotal methods.

player.getPlayerState():Number

Returns the state of the player. Possible values are:

-1 – unstarted
0 – ended
1 – playing
2 – paused
3 – buffering
5 – video cued

player.getCurrentTime():Number: Returns the elapsed time in seconds since the video started playing.

player.getVideoStartBytes():Number: Deprecated as of October 31, 2012. Returns the number of bytes the video file started loading from. (This method now always returns a value of 0.) Example scenario: the user seeks ahead to a point that hasn't loaded yet, and the player makes a new request to play a segment of the video that hasn't loaded yet.

player.getVideoBytesLoaded():Number: Deprecated as of July 18, 2012. Instead, use the getVideoLoadedFraction method to determine the percentage of the video that has buffered.

Returns the number of bytes loaded for the current video.

player.getVideoBytesTotal():Number: Deprecated as of July 18, 2012. Instead, use the getVideoLoadedFraction method to determine the percentage of the video that has buffered.

Returns the size in bytes of the currently loaded/playing video or an approximation of the video's size.

Specifically, this function will approximate the total size of the video when the value of player.getVideoStartBytes() is greater than zero. The function needs to approximate the video's size because the video's actual size is only communicated to the player when the video starts from the beginning.

Playback quality

player.getPlaybackQuality():String: This function retrieves the actual video quality of the current video. Possible return values are highres, hd1080, hd720, large, medium and small. It will also return undefined if there is no current video.

player.setPlaybackQuality(suggestedQuality:String):Void

This function sets the suggested video quality for the current video. The function causes the video to reload at its current position in the new quality. If the playback quality does change, it will only change for the video being played. Calling this function does not guarantee that the playback quality will actually change. However, if the playback quality does change, the onPlaybackQualityChange event will fire, and your code should respond to the event rather than the fact that it called the setPlaybackQuality function.

The suggestedQuality parameter value can be small, medium, large, hd720, hd1080, highres or default. We recommend that you set the parameter value to default, which instructs YouTube to select the most appropriate playback quality, which will vary for different users, videos, systems and other playback conditions.

When you suggest a playback quality for a video, the suggested quality will only be in effect for that video. You should select a playback quality that corresponds to the size of your video player. For example, if your page displays a 1280px by 720px video player, a hd720 quality video will actually look better than an hd1080 quality video. We recommend calling the getAvailableQualityLevels() function to determine which quality levels are available for a video.

The list below shows the playback quality levels that correspond to different standard player sizes. We recommend that you set the height of your video player to one of the values listed below and that you size your player to use 16:9 aspect ratio. As stated above, even if you choose a standard player size, we also recommend that you set the suggestedQuality parameter value to default to enable YouTube to select the most appropriate playback quality.

Quality level small: Player height is 240px, and player dimensions are at least 320px by 240px for 4:3 aspect ratio.
Quality level medium: Player height is 360px, and player dimensions are 640px by 360px (for 16:9 aspect ratio) or 480px by 360px (for 4:3 aspect ratio).
Quality level large: Player height is 480px, and player dimensions are 853px by 480px (for 16:9 aspect ratio) or 640px by 480px (for 4:3 aspect ratio).
Quality level hd720: Player height is 720px, and player dimensions are 1280px by 720px (for 16:9 aspect ratio) or 960px by 720px (for 4:3 aspect ratio).
Quality level hd1080: Player height is 1080px, and player dimensions are 1920px by 1080px (for 16:9 aspect ratio) or 1440px by 1080px (for 4:3 aspect ratio).
Quality level highres: Player height is greater than 1080px, which means that the player's aspect ratio is greater than 1920px by 1080px.
Quality level default: YouTube selects the appropriate playback quality. This setting effectively reverts the quality level to the default state and nullifies any previous efforts to set playback quality using the cueVideoById, loadVideoById or setPlaybackQuality functions.

If you call the setPlaybackQuality function with a suggestedQuality level that is not available for the video, then the quality will be set to the next lowest level that is available. For example, if you request a quality level of large, and that is unavailable, then the playback quality will be set to medium (as long as that quality level is available).

In addition, setting suggestedQuality to a value that is not a recognized quality level is equivalent to setting suggestedQuality to default.

player.getAvailableQualityLevels():Array: This function returns the set of quality formats in which the current video is available. You could use this function to determine whether the video is available in a higher quality than the user is viewing, and your player could display a button or other element to let the user adjust the quality.

The function returns an array of strings ordered from highest to lowest quality. Possible array element values are highres, hd1080, hd720, large, medium and small. This function returns an empty array if there is no current video.

Your client should not automatically switch to use the highest (or lowest) quality video or to any unknown format name. YouTube could expand the list of quality levels to include formats that may not be appropriate in your player context. Similarly, YouTube could remove quality options that would be detrimental to the user experience. By ensuring that your client only switches to known, available formats, you can ensure that your client's performance will not be affected by either the introduction of new quality levels or the removal of quality levels that are not appropriate for your player context.

Retrieving video information

player.getDuration():Number: Returns the duration in seconds of the currently playing video. Note that getDuration() will return 0 until the video's metadata is loaded, which normally happens just after the video starts playing.

If the currently playing video is a live event, the getDuration() function will return the elapsed time since the live video stream began. Specifically, this is the amount of time that the video has streamed without being reset or interrupted. In addition, this duration is commonly longer than the actual event time since streaming may begin before the event's start time.

player.getVideoUrl():String: Returns the YouTube.com URL for the currently loaded/playing video.

player.getVideoEmbedCode():String: Returns the embed code for the currently loaded/playing video.

Retrieving playlist information

player.getPlaylist():Array: This function returns an array of the video IDs in the playlist as they are currently ordered. By default, this function will return video IDs in the order designated by the playlist owner. However, if you have called the setShuffle function to shuffle the playlist order, then the getPlaylist() function's return value will reflect the shuffled order.

player.getPlaylistIndex():Number

This function returns the index of the playlist video that is currently playing.

If you have not shuffled the playlist, the return value will identify the position where the playlist creator placed the video. The return value uses a zero-based index, so a value of 0 identifies the first video in the playlist.
If you have shuffled the playlist, the return value will identify the video's order within the shuffled playlist.

Adding or removing an event listener

player.addEventListener(event:String, listener:String):Void: Adds a listener function for the specified event. The Events section below identifies the different events that the player might fire. The listener is a string that specifies the function that will execute when the specified event fires.

player.removeEventListener(event:String, listener:String):Void: Removes a listener function for the specified event. The listener is a string that identifies the function that will no longer execute when the specified event fires.

Events

onStateChange

This event fires whenever the player's state changes. The value that the API passes to your event listener function will specify an integer that corresponds to the new player state. Possible values are:

-1 (unstarted)
0 (ended)
1 (playing)
2 (paused)
3 (buffering)
5 (video cued).

When the player first loads a video, it will broadcast an unstarted (-1) event. When a video is cued and ready to play, the player will broadcast a video cued (5) event. In your code, you can specify the integer values or you can use one of the following namespaced variables:

YT.PlayerState.ENDED
YT.PlayerState.PLAYING
YT.PlayerState.PAUSED
YT.PlayerState.BUFFERING
YT.PlayerState.CUED

onPlaybackQualityChange

This event fires whenever the video playback quality changes. For example, if you call the setPlaybackQuality(suggestedQuality) function, this event will fire if the playback quality actually changes. Your application should respond to the event and should not assume that the quality will automatically change when the setPlaybackQuality(suggestedQuality) function is called. Similarly, your code should not assume that playback quality will only change as a result of an explicit call to setPlaybackQuality or any other function that allows you to set a suggested playback quality.

The value that the API passes to the event listener function will be a string that identifies the new playback quality. Possible values are:

small
medium
large
hd720
hd1080
highres

onPlaybackRateChange: This event fires whenever the video playback rate changes. For example, if you call the setPlaybackRate(suggestedRate) function, this event will fire if the playback rate actually changes. Your application should respond to the event and should not assume that the playback rate will automatically change when the setPlaybackRate(suggestedRate) function is called. Similarly, your code should not assume that the video playback rate will only change as a result of an explicit call to setPlaybackRate.

The value that the API passes to the event listener function will be a number that identifies the new playback rate. The getAvailablePlaybackRates method returns a list of the valid playback rates for the currently cued or playing video.

Note: Even though the AS3 player supports this event, variable speeds are currently only supported in the HTML5 player.

onError

This event fires if an error occurs in the player. The value that the API passes to the event listener function will be an integer that identifies the type of error that occurred. Possible values are:

2 – The request contains an invalid parameter value. For example, this error occurs if you specify a video ID that does not have 11 characters, or if the video ID contains invalid characters, such as exclamation points or asterisks.
100 – The video requested was not found. This error occurs when a video has been removed (for any reason) or has been marked as private.
101 – The owner of the requested video does not allow it to be played in embedded players.
150 – This error is the same as 101. It's just a 101 error in disguise!

onApiChange

This event is fired to indicate that the player has loaded (or unloaded) a module with exposed API methods. Your application can listen for this event and then poll the player to determine which options are exposed for the recently loaded module. Your application can then retrieve or update the existing settings for those options.

The following command retrieves an array of module names for which you can set player options:

player.getOptions();

Currently, the only module that you can set options for is the cc module, which handles closed captioning in the player. Upon receiving an onApiChange event, your application can use the following command to determine which options can be set for the cc module:

player.getOptions('cc');

By polling the player with this command, you can confirm that the options you want to access are, indeed, accessible. The following commands retrieve and update module options:

Retrieving an option:
player.getOption(module, option);

Setting an option
player.setOption(module, option, value);

The table below lists the options that the API supports:

Module	Option	Description
cc	fontSize	This option adjusts the font size of the captions displayed in the player. Valid values are `-1`, `0`, `1`, `2`, and `3`. The default size is `0`, and the smallest size is `-1`. Setting this option to an integer below `-1` will cause the smallest caption size to display, while setting this option to an integer above `3` will cause the largest caption size to display.
cc	reload	This option reloads the closed caption data for the video that is playing. The value will be `null` if you retrieve the option's value. Set the value to `true` to reload the closed caption data.

Event Handlers

Your HTML pages that display the chromeless player must implement a callback function named onYouTubePlayerReady. The API will call this function when the player is fully loaded and the API is ready to receive calls.

onYouTubePlayerReady(playerid): Called when the player is fully loaded and the API is ready to receive calls. If a playerapiid is passed into the player via URL arguments, then it will be passed to this function.

Examples

Embedding the YouTube player using SWFObject

We recommend using SWFObject to embed any players that will be accessed using the JavaScript API. This will allow you to detect the end user's Flash Player version (the JavaScript API requires Flash Player 8 or higher), and also will get rid of the 'Click to activate this control' box when using Internet Explorer to view the player. To enabled the API in the SWF, you must pass in the parameter enablejsapi=1.

See below for an example of using the script to embed a YouTube player with the JavaScript API enabled, and with a playerapiid of ytplayer.

  <script type="text/javascript" src="swfobject.js"></script>    
  <div id="ytapiplayer">
    You need Flash player 8+ and JavaScript enabled to view this video.
  </div>

  <script type="text/javascript">

    var params = { allowScriptAccess: "always" };
    var atts = { id: "myytplayer" };
    swfobject.embedSWF("http://www.youtube.com/v/VIDEO_ID?enablejsapi=1&playerapiid=ytplayer&version=3",
                       "ytapiplayer", "425", "356", "8", null, null, params, atts);

  </script>

The allowScriptAccess parameter in the code is needed to allow the player SWF to call functions on the containing HTML page, since the player is hosted on a different domain from the HTML page.

The only attribute we're passing in is the id of the embed object — in this case, myytplayer. This id is what we'll use to get a reference to the player using getElementById().

swfobject.embedSWF will load the player from YouTube and embed it onto your page.

swfobject.embedSWF(swfUrlStr, replaceElemIdStr, widthStr, heightStr, swfVersionStr, xiSwfUrlStr, flashvarsObj, parObj, attObj)

swfUrlStr - This is the URL of the SWF. Note that we have appended the enablejsapi and playerapiid parameters to the normal YouTube SWF URL to enable JavaScript API calls.
replaceElemIdStr - This is the HTML DIV id to replace with the embed content. In the example above, it is ytapiplayer.
widthStr - Width of the player.
heightStr - Height of the player.
swfVersionStr - The minimum required version for the user to see the content. In this case, version 8 or above is needed. If the user does not have 8 or above, they will see the default line of text in the HTML DIV.
xiSwfUrlStr - (Optional) Specifies the URL of your express install SWF. Not used in this example.
flashVarsObj - (Optional) Specifies your FlashVars in name:value pairs. Not used in this example.
parObj - (Optional) The parameters for the embed object. In this case, we've set allowScriptAccess.
AttObj - (Optional) The attributes for the embed object. In this case, we've set the id to myytplayer.

See the SWFObject documentation for further explanation.

Getting the Player Reference

Once the player is ready, it will call onYouTubePlayerReady.

To get the reference to the player, use getElementById(). Once you have the object, you can start making calls to the API.

    function onYouTubePlayerReady(playerId) {
      ytplayer = document.getElementById("myytplayer");
    }

Issuing Calls

You can now call functions using the player reference. For example, if you wanted to play the video when a user clicked a link, it would look like this:

function play() {
  if (ytplayer) {
    ytplayer.playVideo();
  }
}

<a href="javascript:void(0);" onclick="play();">Play</a>

Or simply,

<a href="javascript:ytplayer.playVideo()">Play</a>

Subscribing to Events

Subscribe to events by adding an event listener to the player reference. For example, to get notified when the player's state changes, add an event listener for onStateChange and include a callback function.

function onYouTubePlayerReady(playerId) {
  ytplayer = document.getElementById("myytplayer");
  ytplayer.addEventListener("onStateChange", "onytplayerStateChange");
}

function onytplayerStateChange(newState) {
   alert("Player's new state: " + newState);
}

Live Demo

You can use the YouTube Player Demo to test the features of the JavaScript API with either the embedded or chromeless player.

Revision history

This section lists YouTube JavaScript Player API changes and documentation updates. Subscribe to this changelog.