This document provides reference information for the YouTube ActionScript 2.0 player API.

Contents

Overview

The ActionScript 2.0 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.

Requirements

The end user must have Flash Player 8 or higher installed to view everything correctly.

Getting Started

To add the embedded player for a specific video into your Flash file, you will be loading the following SWF into a MovieClip:

http://www.youtube.com/v/VIDEO_ID

Alternatively, you may wish to load the chromeless player into your MovieClip if you are building your own custom controls in Flash:

http://www.youtube.com/apiplayer

Once the chromeless player SWF has been loaded, you can use cueVideoById() or loadVideoById() 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.

Operations

The ActionScript 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.

Functions

player.playVideo():Void

Plays the currently cued/loaded video.

player.pauseVideo():Void

Pauses the currently playing video.

player.stopVideo():Void

Stops the current video. This function also closes the NetStream object and cancels the loading of the video. Once stopVideo() is called, a video cannot be resumed without reloading the player or loading a new video (chromeless player only). When calling stopVideo(), the player broadcasts an end event (0).

player.clearVideo():Void

Clears the video display. This function is useful if you want to clear the video remnant after calling stopVideo().

player.getVideoBytesLoaded():Number

Returns the number of bytes loaded for the current video.

player.getVideoBytesTotal():Number

Returns the size in bytes of the currently loaded/playing video.

player.getVideoStartBytes():Number

Returns the number of bytes the video file started loading from. 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.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):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.

player.seekTo(seconds, allowSeekAhead):Void

Seeks to the specified time of the video in seconds. The allowSeekAhead determines whether or not the player will make a new request to the server if seconds is beyond the currently loaded video data. Note that seekTo() 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.

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.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.

player.addEventListener(event:String, listener):Void

Adds a listener function for the specified event. The listener is a string of a function name if you are using the JavaScript API and is a reference to a function if you are using the ActionScript API.

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.loadVideoById(videoId:String, startSeconds:Number):Void

Load and plays the specified video. If startSeconds (number can be a float) is specified, the video will start from the closest keyframe to the specified time.

player.cueVideoById(videoId:String, startSeconds:Number):Void

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. 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(), the startSeconds is value is ignored and 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.setSize(width:Number, height:Number):Void

Sets the size in pixels of the player. This method should be used instead of setting the width and height properties of the MovieClip. Note that this method does not constrain the proportions of the video player, so you will need to maintain a 4:3 aspect ratio. The default size of the chromeless SWF when loaded into another SWF is 320px by 240px and the default size of the embedded player SWF is 480px by 385px.

Special Functions

The ActionScript specific API calls are listed below:

player.isPlayerLoaded():Boolean

Returns true when the player SWF is loaded, initialized, and ready to receive API calls. It will return false or could be undefined before the player is completely loaded and initialized.

player.destroy():Void

Destroys the player instance. This method should be called before unloading the player SWF from your parent SWF.

Events

onStateChange

This event is fired whenever the player's state changes. Possible values are unstarted (-1), ended (0), playing (1), paused (2), buffering (3), video cued (5). When the SWF is first loaded it will broadcast an unstarted (-1) event. When the video is cued and ready to play it will broadcast a video cued event (5).

onError

This event is fired when an error in the player occurs. The possible error codes are 100, 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!

Examples

Loading the player SWF

Because of the architecture of the player SWF, using ActionScript's built in MovieClipLoader will not give you accurate information. To detect when the player SWF is ready to receive API calls, you should call player.isPlayerLoaded(), which will return true when the player is completely loaded and initialized.

At this point, you may subscribe to events and make any other API calls to the player.

In this example, we wait for the player SWF to load using MovieClipLoader's onLoadInit event, and then start an interval to check for when the player SWF is initialized.

Using the player SWF in Adobe Flash

This is the easiest way to get started if you have Adobe Flash installed. Just open the FLA and publish the SWF. The code can be seen in the "Actions - Frame" tab.

Using the player SWF using MTASC

If you don't have Flash installed you can compile a simple AS2 file that includes the player. This can then be compiled with an ActionScript compiler like MTASC.

To compile the above AS2 source file into a SWF, use the following MTASC command:

path/to/mtasc -swf ytdemo.swf -main -header 800:600:20 YTDemo.as

Once the player is loaded and ready, all API calls can be made in the same way as the JavaScript API.

Working with AS3

Currently, all of the Player API SWFs are only available in AS2. To use Player API in AS3, you must wrap the API SWF in an AS2 wrapper that provides an interface to AS3 using LocalConnection or ExternalInterface.

TubeLoc: A LocalConnection Wrapper

TubeLoc is an ActionScript 3 library that serves as an adapter to the YouTube ActionScript 2 Player API. Easily add YouTube video functionality to your ActionScript 3 or Flex app with either the full-chrome or the chromeless YouTube players.

Additional AS3 Resources

There are other resources which you may find useful in your quest to get AS3 working correctly with YouTube.

• Wrapper using External Interface
• Data API wrapper for AS3

Caveats

When unloading a YouTube player, you should always call destroy() first. This will close the NetStream object and stop the video from continuing to download even after the player has been unloaded. It will also remove references to the player SWF so if you load a new player SWF into your application, the new SWF can load and initialize properly.

You should only call destroy() on the player. There is no need to call removeMovieClip().

Back to top