Printable versionThis document provides reference information for the YouTube ActionScript 3.0 (AS3) player API.
Note: This documentation was updated in October 2009 to explain how to use AS3 rather than ActionScript 2.0 (AS2).
The AS3 API allows users to control the YouTube video players by loading the player into a Flash application and making calls via ActionScript to the player's public API. 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. The ActionScript API is automatically activated when the player is loaded into another SWF.
The end user must have Flash Player 9 or higher installed to view everything correctly.
Use the following URL to load the chromeless player into your application and build your own custom controls in Flash:
http://www.youtube.com/apiplayer?version=3
Once the chromeless player SWF has been loaded, you can use cueVideoById(), loadVideoById(), cueVideoByUrl() or loadVideoByUrl() to load a particular YouTube video.
See the examples below for more detailed information about how to embed a YouTube player SWF into your Flash file.
The AS3 API is very similar to the JavaScript API, with some small changes to how the player is initialized and some additional functions. For examples of how to initialize and make calls to the player via ActionScript, see the examples below.
Queueing functions
player.cueVideoById(videoId:String, startSeconds:Number, suggestedQuality:String):VoidplayVideo() or seekTo() is called.
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.startSeconds parameter accepts a float/integer and specifies the time from which the video should start playing when playVideo() is called. If you specify a startSeconds value and then call seekTo(), then the player plays from the time specified in the seekTo() call. When the video is cued and ready to play, the player will broadcast a video cued event (5).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.loadVideoById(videoId:String, startSeconds:Number, suggestedQuality:String):VoidvideoId 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.startSeconds parameter accepts a float/integer. If it is specified, then the video will start from the closest keyframe to the specified time.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.cueVideoByUrl(mediaContentUrl:String, startSeconds:Number):VoidplayVideo() or seekTo() is called.
mediaContentUrl must be a fully qualified YouTube player URL in the format http://www.youtube.com/v/VIDEO_ID. 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.startSeconds accepts a float/integer and specifies the time from which the video should start playing when playVideo() is called. If you specify startSeconds and then call seekTo(), then the player plays from the time specified in the seekTo() call. When the video is cued and ready to play, the player will broadcast a video cued event (5).player.loadVideoByUrl(mediaContentUrl:String, startSeconds:Number):VoidmediaContentUrl must be a fully qualified YouTube player URL in the format http://www.youtube.com/v/VIDEO_ID. 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.startSeconds accepts a float/integer and specifies the time from which the video should start playing. If startSeconds (number can be a float) is specified, the video will start from the closest keyframe to the specified time.Playback controls and player settings
Playing a video
player.playVideo():Voidplayer.pauseVideo():Voidplayer.stopVideo():Voidplayer.seekTo(seconds:Number, allowSeekAhead:Boolean):VoidseekTo() function will look for the closest keyframe before the seconds specified. This means that sometimes the play head may seek to just before the requested time, usually no more than ~2 seconds.allowSeekAhead parameter determines whether or not the player will make a new request to the server if seconds is beyond the currently loaded video data.player.clearVideo():VoidstopVideo(). Note that this function has been deprecated in the ActionScript 3.0 Player API.Changing the player volume
player.mute():Voidplayer.unMute():Voidplayer.isMuted():Booleanplayer.setVolume(volume:Number):Voidplayer.getVolume():NumbergetVolume() will return the volume even if the player is muted.Setting the player size
player.setSize(width:Number, height:Number):VoidPlayback status
player.getVideoBytesLoaded():Numberplayer.getVideoBytesTotal():Numberplayer.getVideoStartBytes():Numberplayer.getPlayerState():Numberplayer.getCurrentTime():NumberPlayback quality
player.getPlaybackQuality():Stringundefined if there is no current video. Possible return values are hd720, large, medium and small.player.setPlaybackQuality(suggestedQuality:String):VoidonPlaybackQualityChange event will fire, and your code should respond to the event rather than the fact that it called the setPlaybackQuality function.suggestedQuality parameter value can be small, medium, large, hd720 or default. Setting the parameter value to default instructs YouTube to select the most appropriate playback quality, which will vary for different users, videos, systems and other playback conditions.medium quality video will actually look better than a large quality video. The following list shows recommended playback quality levels for different player sizes:small: Player resolution less than 640px by 360px.medium: Minimum player resolution of 640px by 360px.large: Minimum player resolution of 854px by 480px.hd720: Minimum player resolution of 1280px by 720px.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.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).suggestedQuality to a value that is not a recognized quality level is equivalent to setting suggestedQuality to default.player.getAvailableQualityLevels():Arrayhd720, large, medium and small. This function returns an empty array if there is no current video.Retrieving video information
player.getDuration():NumbergetDuration() will return 0 until the video's metadata is loaded, which normally happens just after the video starts playing.player.getVideoUrl():Stringplayer.getVideoEmbedCode():StringAdding an event listener
player.addEventListener(event:String, listener:Function):Voidevent. The Events section below identifies the different events that the player might fire. The listener is a reference to the function that will execute when the specified event fires.The ActionScript specific API calls are listed below:
player.destroy():Voidplayer.destroy() to unload a YouTube player. This function will
close the NetStream object and stop additional videos from downloading after
the player has been unloaded. If your code contains additional references to
the player SWF, you also need to destroy those references separately when you
unload the player.onReadyonStateChangeonPlaybackQualityChangesetPlaybackQuality(suggestedQuality) function, this event will fire if the playback quality actually changes. Your code 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.onError100, 101, and 150. The 100 error code is broadcast when the video requested is not found. This occurs when a video has been removed (for any reason), or it has been marked as private. The 101 error code is broadcast when the video requested does not allow playback in the embedded players. The error code 150 is the same as 101, it's just 101 in disguise!The AS3 API uses a different initialization sequence than the AS2 player. Whereas the AS2 player uses the isPlayerLoaded() function to determine when the player is loaded, initialized and ready to receive API calls, the AS3 player uses a more robust event system. The sample code below demonstrates how to load and initialize the AS3 API player:
// This will hold the API player instance once it is initialized.
var player:Object;
var loader:Loader = new Loader();
loader.contentLoaderInfo.addEventListener(Event.INIT, onLoaderInit);
loader.load(new URLRequest("http://www.youtube.com/apiplayer?version=3"));
function onLoaderInit(event:Event):void {
addChild(loader);
loader.content.addEventListener("onReady", onPlayerReady);
loader.content.addEventListener("onError", onPlayerError);
loader.content.addEventListener("onStateChange", onPlayerStateChange);
loader.content.addEventListener("onPlaybackQualityChange",
onVideoPlaybackQualityChange);
}
function onPlayerReady(event:Event):void {
// Event.data contains the event parameter, which is the Player API ID
trace("player ready:", Object(event).data);
// Once this event has been dispatched by the player, we can use
// cueVideoById, loadVideoById, cueVideoByUrl and loadVideoByUrl
// to load a particular YouTube video.
player = loader.content;
// Set appropriate player dimensions for your application
player.setSize(480, 360);
}
function onPlayerError(event:Event):void {
// Event.data contains the event parameter, which is the error code
trace("player error:", Object(event).data);
}
function onPlayerStateChange(event:Event):void {
// Event.data contains the event parameter, which is the new player state
trace("player state:", Object(event).data);
}
function onVideoPlaybackQualityChange(event:Event):void {
// Event.data contains the event parameter, which is the new video quality
trace("video quality:", Object(event).data);
}
The sample code below demonstrates how YouTube determines the status of its quality toggle button, which lets users select a different playback quality based on available quality levels for a video.
var qualityLevels:Array = getAvailableQualityLevels()
// qualityLevels may be undefined if the API function does not exist,
// in which case this conditional is false
if (qualityLevels.length > 1) {
var highestQuality:String = qualityLevels[0]
if (highestQuality begins with "hd") {
// Brand quality toggle button as HD.
} else {
// Brand quality toggle button as HQ.
// The highest available quality is shown, but it is not HD video.
}
var quality:String = getPlaybackQuality();
if (quality == 'small' || quality == 'medium') {
// The user is not watching the highest quality available
// can can toggle to a higher quality.
} else {
// The user is watching the highest quality available
// and can toggle to a lower quality.
}
} else {
// Hide the toggle button because there is no current video or
// there is only one quality available.
}
Standalone sample code illustrating basic ActionScript 3.0 Player API usage is available as part of the gdata-samples Google Code project. After checking out the code from the source code repository, you'll find the sample in the ytplayer/actionscript3/com/google/youtube/example/ directory. The code uses the Flex UI libraries, and can be built with the open source Flex SDK.