Contents
- Overview
- Requirements
- Getting started
- Loading a video player
- Operations
- Functions
- Queueing functions
- Playback controls and player settings
- Playback status
- Playback quality
- Retrieving video information
- Retrieving playlist information
- Adding an event listener
- Events
- Mobile Considerations
- Examples
- Revision history
Overview
The IFrame player API lets you embed a YouTube video player on your website and control the player using JavaScript. Unlike the
Flash and
JavaScript player APIs, which both involve embedding a Flash object on your web page, the IFrame API posts content to an
<iframe> tag on your page. This approach provides more flexibility than the previously available APIs since it allows YouTube to serve an HTML5 player rather than a Flash player for mobile devices that do not support Flash.
Using the API's JavaScript functions, you can queue videos for playback; play, pause, or stop those videos; adjust the player volume; or retrieve information about the video being played. You can also add event listeners that will execute in response to certain player events, such as a player state change or a video playback quality change.
This guide explains how to use the IFrame API. It identifies the different types of events that the API can send and explains how to write event listeners to respond to those events. It also details the different JavaScript functions that you can call to control the video player as well as the player parameters you can use to further customize the player.
Requirements
The end user must be using a browser that supports the HTML5 postMessage feature. Most modern browsers support postMessage, though Internet Explorer 7 does not support it.
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.
Any web page that uses the IFrame API must also implement the following JavaScript function:
onYouTubeIframeAPIReady – The API will call this function when the page has finished downloading the JavaScript for the player API, which enables you to then use the API on your page. Thus, this function might create the player objects that you want to display when the page loads.
Getting started
The sample HTML page below creates an embedded player that will load a video, play it for six seconds, and then stop the playback. The numbered comments in the HTML are explained in the list below the example.
<!DOCTYPE html>
<html>
<body>
<div id="player"></div>
<script>
var tag = document.createElement('script');
tag.src = "https://www.youtube.com/iframe_api";
var firstScriptTag = document.getElementsByTagName('script')[0];
firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);
var player;
function onYouTubeIframeAPIReady() {
player = new YT.Player('player', {
height: '390',
width: '640',
videoId: 'M7lc1UVf-VE',
events: {
'onReady': onPlayerReady,
'onStateChange': onPlayerStateChange
}
});
}
function onPlayerReady(event) {
event.target.playVideo();
}
var done = false;
function onPlayerStateChange(event) {
if (event.data == YT.PlayerState.PLAYING && !done) {
setTimeout(stopVideo, 6000);
done = true;
}
}
function stopVideo() {
player.stopVideo();
}
</script>
</body>
</html>
The following list provides more details about the sample above:
The
<div> tag in this section identifies the location on the page where the IFrame API will place the video player. The constructor for the player object, which is described in the
Loading a video player section, identifies the
<div> tag by its
id to ensure that the API places the
<iframe> in the proper location. Specifically, the IFrame API will replace the
<div> tag with the
<iframe> tag.
As an alternative, you could also put the
<iframe> element directly on the page. The
Loading a video player section explains how to do so.
The code in this section loads the IFrame Player API JavaScript code. The example uses DOM modification to download the API code to ensure that the code is retrieved asynchronously. (The
<script> tag's
async attribute, which also enables asynchronous downloads, is not yet supported in all modern browsers as discussed in this
Stack Overflow answer.
The onYouTubeIframeAPIReady function will execute as soon as the player API code downloads. This portion of the code defines a global variable,player, which refers to the video player you are embedding, and the function then constructs the video player object.
The onPlayerReady function will execute when the onReady event fires. In this example, the function indicates that when the video player is ready, it should begin to play.
The API will call the onPlayerStateChange function when the player's state changes, which may indicate that the player is playing, paused, finished, and so forth. The function indicates that when the player state is 1 (playing), the player should play for six seconds and then call the stopVideofunction to stop the video.
Loading a video player
After the API's JavaScript code loads, the API will call the onYouTubeIframeAPIReady function, at which point you can construct a YT.Player object to insert a video player on your page. The HTML excerpt below shows the onYouTubeIframeAPIReady function from the example above:
var player;
function onYouTubeIframeAPIReady() {
player = new YT.Player('player', {
height: '390',
width: '640',
videoId: 'M7lc1UVf-VE',
events: {
'onReady': onPlayerReady,
'onStateChange': onPlayerStateChange
}
});
}
The constructor for the video player specifies the following parameters:
The first parameter specifies either the DOM element or the id of the HTML element where the API will insert the <iframe> tag containing the player.
The IFrame API will replace the specified element with the <iframe> element containing the player. This could affect the layout of your page if the element being replaced has a different display style than the inserted <iframe> element. By default, an <iframe> displays as an inline-blockelement.
- The second parameter is an object that specifies player options. The object contains the following properties:
width (number) – The width of the video player. The default value is 640.height (number) – The height of the video player. The default value is 390.videoId (string) – The YouTube video ID that identifies the video that the player will load.playerVars (object) – The object's properties identify player parameters that can be used to customize the player.events (object) – The object's properties identify the events that the API fires and the functions (event listeners) that the API will call when those events occur. In the example, the constructor indicates that the onPlayerReady function will execute when the onReady event fires and that theonPlayerStateChange function will execute when the onStateChange event fires.
As mentioned in the
Getting started section, instead of writing an empty
<div> element on your page, which the player API's JavaScript code will then replace with an
<iframe> element, you could create the
<iframe> tag yourself.
<iframe id="player" type="text/html" width="640" height="390"
src="http://www.youtube.com/embed/M7lc1UVf-VE?enablejsapi=1&origin=http://example.com"
frameborder="0"></iframe>
If you do write the <iframe> tag, then when you construct the YT.Player object, you do not need to specify values for the width and height, which are specified as attributes of the <iframe> tag, or the videoId and player parameters, which are are specified in the src URL. As an extra security measure, you should also include the origin parameter to the URL, specifying the URL scheme (http:// or https://) and full domain of your host page as the parameter value. While origin is optional, including it protects against malicious third-party JavaScript being injected into your page and hijacking control of your YouTube player.
The
Examples section shows a few more examples for constructing video player objects.
Operations
To call the player API methods, you must first get a reference to the player object you wish to control. You obtain the reference by creating a
YT.Player object as discussed in the
Getting started and
Loading a video player sections of this document.
Functions
The following subsections list the functions that the player API supports.
Queueing functions
Queueing functions allow you to load and play a video, a playlist, or another list of videos. If you are using the object syntax, described below, to call these functions, you can also queue or load a list of search results or a user's list of uploaded videos.
The API supports two different syntaxes for calling the queueing functions.
The argument syntax requires function arguments to be listed in a prescribed order.
The object syntax lets you pass an object as a single parameter and to define object properties for the function arguments that you wish to set. In addition, the API may support additional functionality that the argument syntax does not support.
For example, the
loadVideoById function can be called in either of the following ways. Note that the object syntax supports the
endSeconds property, which the argument syntax does not support.
Argument syntax
loadVideoById("bHQqvYy5KYo", 5, "large")
Object syntax
loadVideoById({'videoId': 'bHQqvYy5KYo', 'startSeconds': 5, 'endSeconds': 60, 'suggestedQuality': 'large'});
The different queueing functions for
videos and
playlists are described below.
Queueing functions for videos
cueVideoById
Argument syntax
player.cueVideoById(videoId:String, startSeconds:Number, suggestedQuality:String):Void
Object syntax
player.cueVideoById({videoId:String, startSeconds:Number, endSeconds:Number, suggestedQuality:String}):Void
This function loads the specified video's thumbnail and prepares the player to play the video. The player does not request the FLV until
playVideo()or
seekTo() is called.
- The required
videoId parameter specifies the YouTube Video ID of the video to be played. In YouTube Data API video feeds, the<yt:videoid> tag specifies the ID.
- The optional
startSeconds parameter accepts a float/integer and specifies the time from which the video should start playing whenplayVideo() is called. If you specify a startSeconds value and then call seekTo(), then the player plays from the time specified in theseekTo() call. When the video is cued and ready to play, the player will broadcast a video cued event (5).
- The optional
endSeconds parameter, which is only supported in object syntax, accepts a float/integer and specifies the time when the video should stop playing when playVideo() is called. If you specify an endSeconds value and then call seekTo(), the endSeconds value will no longer be in effect.
- The optional
suggestedQuality parameter specifies the suggested playback quality for the video. Please see the definition of thesetPlaybackQuality function for more information about playback quality.
loadVideoById
Argument syntax
player.loadVideoById(videoId:String, startSeconds:Number, suggestedQuality:String):Void
Object syntax
player.loadVideoById({videoId:String, startSeconds:Number, endSeconds:Number, suggestedQuality:String}):Void
This function loads and plays the specified video.
- The required
videoId parameter specifies the YouTube Video ID of the video to be played. In YouTube Data API video feeds, the<yt:videoid> tag specifies the ID.
- The optional
startSeconds parameter accepts a float/integer. If it is specified, then the video will start from the closest keyframe to the specified time.
- The optional
endSeconds parameter accepts a float/integer. If it is specified, then the video will stop playing at the specified time.
- The optional
suggestedQuality parameter specifies the suggested playback quality for the video. Please see the definition of thesetPlaybackQuality function for more information about playback quality.
cueVideoByUrl
Argument syntax
player.cueVideoByUrl(mediaContentUrl:String, startSeconds:Number, suggestedQuality:String):Void
Object syntax
player.cueVideoByUrl({mediaContentUrl:String, startSeconds:Number, endSeconds:Number, suggestedQuality:String}):Void
This function loads the specified video's thumbnail and prepares the player to play the video. The player does not request the FLV until
playVideo()or
seekTo() is called.
- The required
mediaContentUrl parameter specifies a fully qualified YouTube player URL in the formathttp://www.youtube.com/v/VIDEO_ID?version=3. In YouTube Data API video feeds, the <media:content> tag's url attribute contains a fully qualified player URL when the tag's format attribute has a value of 5.
- The optional
startSeconds parameter accepts a float/integer and specifies the time from which the video should start playing whenplayVideo() is called. If you specify startSeconds and then call seekTo(), then the player plays from the time specified in theseekTo() call. When the video is cued and ready to play, the player will broadcast a video cued event (5).
- The optional
endSeconds parameter, which is only supported in object syntax, accepts a float/integer and specifies the time when the video should stop playing when playVideo() is called. If you specify an endSeconds value and then call seekTo(), the endSeconds value will no longer be in effect.
- The optional
suggestedQuality parameter specifies the suggested playback quality for the video. Please see the definition of thesetPlaybackQuality function for more information about playback quality.
loadVideoByUrl
Argument syntax
player.loadVideoByUrl(mediaContentUrl:String, startSeconds:Number, suggestedQuality:String):Void
Object syntax
player.loadVideoByUrl({mediaContentUrl:String, startSeconds:Number, endSeconds:Number, suggestedQuality:String}):Void
This function loads and plays the specified video.
- The required
mediaContentUrl parameter specifies a fully qualified YouTube player URL in the formathttp://www.youtube.com/v/VIDEO_ID?version=3. In YouTube Data API video feeds, the url attribute of the <media:content> tag contains a fully qualified player URL when the tag's format attribute has a value of 5.
- The optional
startSeconds parameter accepts a float/integer and specifies the time from which the video should start playing. IfstartSeconds (number can be a float) is specified, the video will start from the closest keyframe to the specified time.
- The optional
endSeconds parameter, which is only supported in object syntax, accepts a float/integer and specifies the time when the video should stop playing.
- The optional
suggestedQuality parameter specifies the suggested playback quality for the video. Please see the definition of thesetPlaybackQuality function for more information about playback quality.
Queueing functions for lists
The cuePlaylist and loadPlaylist functions allow you to load and play a playlist or list of videos. If you are using the object syntax to call these functions, you can also queue (or load) a list of search results or a user's list of uploaded videos.
Since the functions work differently depending on whether they are called using the argument syntax or the object syntax, both calling methods are documented below.
Argument syntax
player.cuePlaylist(playlist:String|Array, index:Number, startSeconds:Number, suggestedQuality:String):Void- Queues the specified playlist. When the playlist is cued and ready to play, the player will broadcast a video cued event (
5).
The required
playlist parameter specifies an array of YouTube video IDs. In YouTube Data API feeds, the
<yt:videoid> tag specifies a video ID.
The optional index parameter specifies the index of the first video in the playlist that will play. The parameter uses a zero-based index, and the default parameter value is 0, so the default behavior is to load and play the first video in the playlist.
The optional
startSeconds parameter accepts a float/integer and specifies the time from which the first video in the playlist should start playing when the
playVideo() function is called. If you specify a
startSeconds value and then call
seekTo(), then the player plays from the time specified in the
seekTo() call. If you cue a playlist and then call the
playVideoAt() function, the player will start playing at the beginning of the specified video.
The optional
suggestedQuality parameter specifies the suggested playback quality for the video. Please see the definition of the
setPlaybackQuality function for more information about playback quality.
player.loadPlaylist(playlist:String|Array, index:Number, startSeconds:Number, suggestedQuality:String):Void- This function loads the specified playlist and plays it.
The required
playlist parameter specifies an array of YouTube video IDs. In YouTube Data API feeds, the
<yt:videoid> tag specifies a video ID.
The optional index parameter specifies the index of the first video in the playlist that will play. The parameter uses a zero-based index, and the default parameter value is 0, so the default behavior is to load and play the first video in the playlist.
The optional startSeconds parameter accepts a float/integer and specifies the time from which the first video in the playlist should start playing.
The optional
suggestedQuality parameter specifies the suggested playback quality for the video. Please see the definition of the
setPlaybackQuality function for more information about playback quality.
Object syntax
player.cuePlaylist({listType:String,
list:String,
index:Number,
startSeconds:Number,
suggestedQuality:String}):Void- Queues the specified list of videos. The list can be a playlist, a search results feed, or a user's uploaded videos feed. When the list is cued and ready to play, the player will broadcast a video cued event (
5).
The optional listType property specifies the type of results feed that you are retrieving. Valid values are playlist, search, anduser_uploads. The default value is playlist.
The required list property contains a key that identifies the particular list of videos that YouTube should return.
- If the
listType property value is playlist, then the list property specifies the playlist ID or an array of video IDs. In YouTube Data API feeds, the <yt:playlistid> tag specifies a playlist ID, and the <yt:videoid> tag specifies a video ID.
- If the
listType property value is search, then the list property specifies the search query.
- If the
listType property value is user_uploads, then the list property identifies the user whose uploaded videos will be returned.
The optional index property specifies the index of the first video in the list that will play. The parameter uses a zero-based index, and the default parameter value is 0, so the default behavior is to load and play the first video in the list.
The optional
startSeconds property accepts a float/integer and specifies the time from which the first video in the list should start playing when the
playVideo() function is called. If you specify a
startSeconds value and then call
seekTo(), then the player plays from the time specified in the
seekTo() call. If you cue a list and then call the
playVideoAt() function, the player will start playing at the beginning of the specified video.
The optional
suggestedQuality property specifies the suggested playback quality for the list's videos. Please see the definition of the
setPlaybackQuality function for more information about playback quality.
player.loadPlaylist({list:String,
listType:String,
index:Number,
startSeconds:Number,
suggestedQuality:String}):Void- This function loads the specified list and plays it. The list can be a playlist, a search results feed, or a user's uploaded videos feed.
The optional listType property specifies the type of results feed that you are retrieving. Valid values are playlist, search, anduser_uploads. The default value is playlist.
The required list property contains a key that identifies the particular list of videos that YouTube should return.
- If the
listType property value is playlist, then the list property specifies a playlist ID or an array of video IDs. In YouTube Data API feeds, the <yt:playlistid> tag specifies a playlist ID, and the <yt:videoid> tag specifies a video ID.
- If the
listType property value is search, then the list property specifies the search query.
- If the
listType property value is user_uploads, then the list property identifies the user whose uploaded videos will be returned.
The optional index property specifies the index of the first video in the list that will play. The parameter uses a zero-based index, and the default parameter value is 0, so the default behavior is to load and play the first video in the list.
The optional startSeconds property accepts a float/integer and specifies the time from which the first video in the list should start playing.
The optional
suggestedQuality property specifies the suggested playback quality for the list's videos. Please see the definition of the
setPlaybackQuality function for more information about playback quality.
Playback controls and player settings
Playing a video
player.playVideo():Void- Plays the currently cued/loaded video. The final player state after this function executes will be
playing (1).
Note: A playback only counts toward a video's official view count if it is initiated via a native play button in the player.
player.pauseVideo():Void- Pauses the currently playing video. The final player state after this function executes will be
paused (2) unless the player is in the ended (0) state when the function is called, in which case the player state will not change.
player.stopVideo():Void- Stops and cancels loading of the current video. This function should be reserved for rare situations when you know that the user will not be watching additional video in the player. If your intent is to pause the video, you should just call the pauseVideo function. If you want to change the video that the player is playing, you can call one of the queueing functions without calling
stopVideo first.
Important: Unlike the pauseVideo function, which leaves the player in the paused (2) state, the stopVideo function could put the player into any not-playing state, including ended (0), paused (2), video cued (5) or unstarted (-1).
player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void- Seeks to a specified time in the video. If the player is paused when the function is called, it will remain paused. If the function is called from another state (
playing, video cued, etc.), the player will play the video.
The seconds parameter identifies the time to which the player should advance.
The player will advance to the closest keyframe before that time unless the player has already downloaded the portion of the video to which the user is seeking. In that case, the player will advance to the closest keyframe before or after the specified time as dictated by the
seek()method of the Flash player's
NetStream object. (See
Adobe's documentation for more information.)
The allowSeekAhead parameter determines whether the player will make a new request to the server if the seconds parameter specifies a time outside of the currently buffered video data.
We recommend that you set this parameter to false while the user drags the mouse along a video progress bar and then set it to true when the user releases the mouse. This approach lets a user scroll to different points of a video without requesting new video streams by scrolling past unbuffered points in the video. When the user releases the mouse button, the player advances to the desired point in the video and requests a new video stream if necessary.
player.clearVideo():Void- Clears the video display. This function is useful if you want to clear the video remnant after calling
stopVideo(). Note that this function has been deprecated in the ActionScript 3.0 Player API.
Playing a video in a playlist
player.nextVideo():Void- This function loads and plays the next video in the playlist.
player.previousVideo():Void- This function loads and plays the previous video in the playlist.
If
player.previousVideo() is called while the first video in the playlist is being watched, and the playlist is set to play continuously (
loop), then the player will load and play the last video in the list.
If player.previousVideo() is called while the first video in the playlist is being watched, and the playlist is not set to play continuously, then the player will restart the first playlist video from the beginning.
player.playVideoAt(index:Number):Void- This function loads and plays the specified video in the playlist.
The required
index parameter specifies the index of the video that you want to play in the playlist. The parameter uses a zero-based index, so a value of
0 identifies the first video in the list. If you have
shuffled the playlist, this function will play the video at the specified position in the shuffled playlist.
Changing the player volume
player.mute():Void- Mutes the player.
player.unMute():Void- Unmutes the player.
player.isMuted():Boolean- Returns true if the player is muted, false if not.
player.setVolume(volume:Number):Void- Sets the volume. Accepts an integer between 0 and 100.
player.getVolume():Number- Returns the player's current volume, an integer between 0 and 100. Note that
getVolume() will return the volume even if the player is muted.
Setting the player size
player.setSize(width:Number, height:Number):Object- Sets the size in pixels of the
<iframe> that contains the player.
Setting the playback rate
player.getPlaybackRate():Number- This function retrieves the playback rate of the currently playing video. The default playback rate is
1, which indicates that the video is playing at normal speed. Playback rates may include values like 0.25, 0.5, 1, 1.5, and 2.
player.setPlaybackRate(suggestedRate:Number):Void- This function sets the suggested playback rate for the current video. If the playback rate changes, it will only change for the video that is already cued or being played. If you set the playback rate for a cued video, that rate will still be in effect when the
playVideo function is called or the user initiates playback directly through the player controls. In addition, calling functions to cue or load videos or playlists (cueVideoById, loadVideoById, etc.) will reset the playback rate to 1.
Calling this function does not guarantee that the playback rate will actually change. However, if the playback rate does change, theonPlaybackRateChange event will fire, and your code should respond to the event rather than the fact that it called the setPlaybackRate function.
The getAvailablePlaybackRates method will return the possible playback rates for the currently playing video. However, if you set thesuggestedRate parameter to a non-supported integer or float value, the player will round that value down to the nearest supported value in the direction of 1.
Note: Even though the AS3 player supports playback rate controls, variable speeds are currently only supported in the HTML5 player.
player.getAvailablePlaybackRates():Array- This function returns the set of playback rates in which the current video is available. The default value is
1, which indicates that the video is playing in normal speed.
The function returns an array of numbers ordered from slowest to fastest playback speed. Even if the player does not support variable playback speeds, the array should always contain at least one value (1).
Setting playback behavior for playlists
player.setLoop(loopPlaylists:Boolean):Void
This function indicates whether the video player should continuously play a playlist or if it should stop playing after the last video in the playlist ends. The default behavior is that playlists do not loop.
This setting will persist even if you load or cue a different playlist, which means that if you load a playlist, call the setLoop function with a value oftrue, and then load a second playlist, the second playlist will also loop.
player.setShuffle(shufflePlaylist:Boolean):Void
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.
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 unstarted (-1), ended (0), playing (1), paused (2), buffering (3), video cued (5).
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.
This method returns a value between 0 and 1000 that approximates the amount of the video that has been loaded. You could calculate the fraction of the video that has been loaded by dividing the getVideoBytesLoaded value by the getVideoBytesTotal value.
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.
This method always returns a value of 1000. You could calculate the fraction of the video that has been loaded by dividing the getVideoBytesLoadedvalue by the getVideoBytesTotal value.
Playback quality
player.getPlaybackQuality():String- This function retrieves the actual video quality of the current video. It returns
undefined if there is no current video. Possible return values are highres,hd1080, hd720, large, medium and small.
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.
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.
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 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.
Accessing and modifying DOM nodes
player.getIframe():Object- This method returns the DOM node for the embedded
<iframe>.
player.destroy():Void- Removes the
<iframe> containing the player.
Events
The API fires events to notify your application of changes to the embedded player. As noted in the previous section, you can subscribe to events by adding an event listener when
constructing the YT.Player object, and you can also use the
addEventListener function.
The API will pass an event object as the sole argument to each of those functions. The event object has the following properties:
- The event's
target identifies the video player that corresponds to the event.
- The event's
data specifies a value relevant to the event. Note that the onReady event does not specify a data property.
The following list defines the events that the API fires:
onReady- This event fires whenever a player has finished loading and is ready to begin receiving API calls. Your application should implement this function if you want to automatically execute certain operations, such as playing the video or displaying information about the video, as soon as the player is ready.
The example below shows a sample function for handling this event. The event object that the API passes to the function has a target property, which identifies the player The function retrieves the embed code for the currently loaded video, starts to play the video, and displays the embed code in the page element that has an id value of embed-code.function onPlayerReady(event) {
var embedCode = event.target.getVideoEmbedCode();
event.target.playVideo();
if (document.getElementById('embed-code')) {
document.getElementById('embed-code').innerHTML = embedCode;
}
}
onStateChange- This event fires whenever the player's state changes. The
data property of the event object 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.ENDEDYT.PlayerState.PLAYINGYT.PlayerState.PAUSEDYT.PlayerState.BUFFERINGYT.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 data property value of the event object that the API passes to the event listener function will be a string that identifies the new playback quality. Possible values are:
smallmediumlargehd720hd1080highres
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 data property value of the event object that the API passes to the event listener function will be a number that identifies the new playback rate. ThegetAvailablePlaybackRates 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 API will pass an
event object to the event listener function. That object's data property will specify 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.5 – The requested content cannot be played in an HTML5 player or another error related to the HTML5 player has occurred.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 onApiChangeevent, 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 -1will 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. |
Mobile Considerations
Autoplay and Scripted Playback
The HTML5
<video> element, in certain mobile browsers (such as Chrome and Safari), only allows playback to take place if it's initiated by a user interaction (such as tapping on the player). Here's an excerpt from
Apple's documentation:
"Warning: To prevent unsolicited downloads over cellular networks at the user’s expense, embedded media cannot be played automatically in Safari on iOS — the user always initiates playback."
Due to this restriction, functions and parameters such as autoplay, playVideo(), loadVideoById() won't work in all mobile environments.
Examples
Creating YT.Player objects
Example 1: Loud playback
This example creates a 1280px by 720px video player. The event listener for the
onReady event then calls the
setVolume function to adjust the volume to the highest setting.
function onYouTubeIframeAPIReady() {
var player;
player = new YT.Player('player', {
width: 1280,
height: 720,
videoId: 'M7lc1UVf-VE',
events: {
'onReady': onPlayerReady,
'onPlaybackQualityChange': onPlayerPlaybackQualityChange,
'onStateChange': onPlayerStateChange,
'onError': onPlayerError
}
});
}
function onPlayerReady(event) {
event.target.setVolume(100);
event.target.playVideo();
}
Example 2: This example sets player parameters to automatically play the video when it loads and to hide the video player's controls. It also adds event listeners for all of the events that the API broadcasts.
function onYouTubeIframeAPIReady() {
var player;
player = new YT.Player('player', {
videoId: 'M7lc1UVf-VE',
playerVars: { 'autoplay': 1, 'controls': 0 },
events: {
'onReady': onPlayerReady,
'onPlaybackQualityChange': onPlayerPlaybackQualityChange,
'onStateChange': onPlayerStateChange,
'onError': onPlayerError
}
});
}
Revision history
March 25, 2014
This update contains the following changes:
The
Requirements section has been updated to note that embedded players must have a viewport that is at least 200px by 200px. If a 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.
July 23, 2013
This update contains the following changes:
The
Overview now includes a video of a 2011 Google I/O presentation that discusses the iframe player.
October 31, 2012
This update contains the following changes:
The
Queueing functions section has been updated to explain that you can use either argument syntax or object syntax to call all of those functions. Note that the API may support additional functionality in object syntax that the argument syntax does not support.
When called using object syntax, each of the
video queueing functions supports an
endSeconds property, which accepts a float/integer and specifies the time when the video should stop playing when
playVideo() is called.
The
getVideoStartBytes method has been deprecated. The method now always returns a value of
0.
August 22, 2012
This update contains the following changes:
The example in the
Loading a video player section that demonstrates how to manually create the
<iframe> tag has been updated to include a closing
</iframe> tag since the
onYouTubeIframeAPIReady function is only called if the closing
</iframe> element is present.
August 6, 2012
This update contains the following changes:
July 19, 2012
This update contains the following changes:
-
The
onError event may now return an error code of
5, which indicates that the requested content cannot be played in an HTML5 player or another error related to the HTML5 player has occurred.
The
Requirements section has been updated to indicate that any web page using the IFrame API must also implement the
onYouTubeIframeAPIReady function. Previously, the section indicated that the required function was named
onYouTubePlayerAPIReady. Code samples throughout the document have also been updated to use the new name.
Note: To ensure that this change does not break existing implementations, both names will work. If, for some reason, your page has anonYouTubeIframeAPIReady function and an onYouTubePlayerAPIReady function, both functions will be called, and theonYouTubeIframeAPIReady function will be called first.
The code sample in the
Getting started section has been updated to reflect that the URL for the IFrame Player API code has changed to
http://www.youtube.com/iframe_api. To ensure that this change does not affect existing implementations, the old URL (
http://www.youtube.com/player_api) will continue to work.
July 16, 2012
This update contains the following changes:
The
Operations section now explains that the API supports the
setSize() and
destroy() methods. The
setSize() method sets the size in pixels of the
<iframe> that contains the player and the
destroy() method removes the
<iframe>.
June 6, 2012
This update contains the following changes:
We have removed the experimental status from the IFrame Player API.
The
Loading a video player section has been updated to point out that when inserting the
<iframe> element that will contain the YouTube player, the IFrame API replaces the element specified in the constructor for the YouTube player. This documentation change does not reflect a change in the API and is intended solely to clarify existing behavior.
In addition, that section now notes that the insertion of the <iframe> element could affect the layout of your page if the element being replaced has a different display style than the inserted <iframe> element. By default, an <iframe> displays as an inline-block element.
March 30, 2012
This update contains the following changes:
The
Operations section has been updated to explain that the IFrame API supports a new method,
getIframe(), which returns the DOM node for the IFrame embed.
March 26, 2012
This update contains the following changes:
The
Requirements section has been updated to note the minimum player size.
![[Note]](https://lh3.googleusercontent.com/blogger_img_proxy/AEn0k_uFrvWaVatUu7pXO7ogpgHWTZVt9odC0nXFpTo_IxstLT6bbNZT-2rKeyTvfQpNueAgs2uOocPrAXF07S5COzy3kic1MlJYAXRFzoBFBFwpzOm_DCdQuXUqiThp3SXkQKE0Rw=s0-d)
![[Note]](https://lh3.googleusercontent.com/blogger_img_proxy/AEn0k_s8b84y1gsAlaZBpMH8cd9uy_9KpYxHCcjigWJoNo2XPickWr0dbMZXYN_iaPuYlL44e9W70rhNJMAtsxHV-SgYcQ1sOFzpjrbE7BUqBM7TdvVtBKlmYcaDcgW_0j01YAcZ=s0-d)
