Youtube AS3 Wrapper – Documentation
The IYoutube Interface
This actually represents the playground for Youtube AS3 Wrapper: all the methods needed to handle youtube videos are methods of this interface.
So let’s go through each of the methods.
EventDispatcher related:
Use addEventListener to listen to the events dispatched by IYoutube:
YoutubeEvent.PLAYER_READY: dispatched when the player is loaded and ready to receive method calls
YoutubeEvent.PlAYER_ERROR: dispatched when the player receives an error
Possible error codes: 100 – video not found; 101, 150 – video not available in user area or cannot be played in chromeless player
YoutubeEvent.PlAYER_STATE_CHANGE: dispatched when the player has changed state
Always check if the player is ready to receive function call (after a YoutubeEvent.PLAYER_READY event the player is ready) before calling any function (exception functions are those described above and: destroy(), reload() and destroyAndReload() which will be discussed later).
Use isPlayerReady() to check if the player is ready:
* check to see if player is ready; always check if it's ready before calling any method
* @return Boolean true if player is ready, false otherwise
*/
function isPlayerReady():Boolean;
Loading videos methods:
* loads a video
* @param id String youtube id or youtube url
* @param startSeconds Number seconds from where to start the video
*/
function loadVideo(id:String, startSeconds:Number = 0):void;
/**
* cue a video
* @param id String youtube id or youtube url
* @param startSeconds Number seconds from where to start the video
*/
function cueVideo(id:String, startSeconds:Number = 0):void;
Use loadVideo when you want the playback to start as soon as the video is loaded. If loadVideo is used, there’s no need to call playVideo method, as playback starts automatically.
Use cueVideo when you don’t want the playback to start automatically. When this method is used, the player sends a Cue Video state (5) when the video is ready to play. Then playVideo method can be called.
On both methods, information about the video is available only after the playback has started ( a Playing state is entered (1)).
Video playback control:
* Play or resume a paused video
*/
function playVideo():void;
/**
* Pauses a playing video
*/
function pauseVideo():void;
/**
* Stops the current video; after this method is called, the clip cannot be played anymore; the video must be loaded again
*/
function stopVideo():void;
If stopVideo method is called, the clip that was playing cannot be played again. In order to do that, that video must be reloaded, using one of the loading methods described above.
To clear the remnant picture of a stopped video (stopped by using stopVideo()):
* Clears a remnant video after stopVideo() was called
*/
function clearVideo():void;
/**
* A merge between stopVideo() and clearVideo(); should be used instead of calling stopVideo() then clearVideo()
*/
function stopAndClearVideo() : void;
Use clearVideo to clear a video from display. However, instead of calling stopVideo() and then clearVideo(), call only stopAndClearVideo(). This is a better way because it uses only one LocalConnection call, instead of 2 (1 for stopVideo and 1 for clearVideo).
To resize the video:
Always use this method instead of setting width and height parameters on IYoutube object directly. By using this method, the youtube logo will keep it’s current size, otherwise scaling will occur both on the video picture and the logo (which is unwanted).
Methods to check if the player has any errors. However remember that when an error occurs, a YoutubeEvent.PLAYER_ERROR event is dispatched.
After an YoutubeEvent.PLAYER_ERROR event is dispatched, getPlayerError() returns the current error. Also playerHasError will return true.
The error is cleared when a new video is loaded or cued, or the current video is stopped or cleared.
Audio control functions:
* Mute the video
*/
function mute():void;
/**
* Unmute the video
*/
function unmute():void;
/**
* @return Boolean true if the video is muted false otherwise
*/
function isMute():Boolean;
/**
* Set the volume of the video
* @param volume Number the volume to be set [0-100]
*/
function setVolume(volume:Number):void;
/**
* Return the current volume of the video
* @return Number volume [0-100]
*/
function getVolume():Number;
The volume is a Number between 0 and 100.
Details about loading:
* Returns the current bytes loaded
* @return Number the current bytes loaded
*/
function getVideoBytesLoaded():Number;
/**
* Return the total bytes of the video, or a negative number until the total bytes of the video is known
* @return Number the total video bytes
*/
function getVideoBytesTotal():Number;
Notice that getVideoBytesTotal will return a negative Number until the details about the current video are loaded (which happens when a Playing (1) state is entered). So you should always check to see if the returned Number is greater than 0 before using it in calculations.
Also getVideoBytesLoaded returns 0 until any bytes are downloaded.
Details about playback and video length in seconds:
Both values are in seconds. Notice that getDuration will return a negative Number until the duration of the clip is found (after a Playing (1) state is entered). getCurrentTime will return 0 until the playback head changes. You should always check to see if getDuration returns a Number greater than 0 before using it.
Method to change the playhead:
Method to determine the current playing state the player is in. Should be used when a YoutubeEvent.PLAYER_STATE_CHANGE event occurs:
* Returns the players state
* @return int returns the current player stat
*/
function getPlayerState():int;
This method returns the current state that player has: -1=Video is Unstarted, 0=Video has Ended, 1=Video is Playing, 2=Video is Paused, 3=Buffering Video, 5=Video is Cued (received when cueVideo method is used to load a video; after this event is received, playVideo method can be used to start playback).
Use this method to know the current state of the player.
Link and embed code of current video:
Note that the url and the embed code are those related to Youtube site, and not related to the current player!
The next method, recently introduced by youtube api, returns the bytes where the video has started playing (if appropriate):
* Return the current bytes the video has started from
* @return uint video start bytes
*/
function getVideoStartBytes() : uint;
And saved the best for the last. This methods help destroying and reloading the player without the need to reload the entire wrapper.
* Destroy the player; no other action, other than reload() can occur on the player after this call
*/
function destroy() : void;
/**
* Reloads the player; YoutubeEvent.PLAYER_READY event will be dispatched when the player is loaded and ready to receive action
*/
function reload() : void;
/**
* A merge of destroy() and reload(); it should be used instead of calling destroy() and then reload()
*/
function destroyAndReload() : void;
As you can see there are these three methods: destroy, reload and destroyAndReload.
If you need to call destroy, then reload, use destroyAndReload instead.
You might be wondering why would you ever need to destroy and reload the player, and you’re right. In most of the cases you won’t need to destroy and reload it. However in Internet Explorer, after a few, or after every clip, has played, on another clip volume and mute will not work anymore. So when this happens, you can call destroyAndReload(), wait for Youtube.PLAYER_READY event, and then you’re good to play another clip, with volume and mute, and everything else supported. Note that this only happens in Internet Explorer, so before destroying and reloading the player check what browser is the embedding the player.
This method is used in the test harness player v1.0, so you can download the sources of the test harness player v1.0 (v1.1 uses the new Youtube AS3 Wrapper) and look through the code for more details on this is use.
The YoutubeEvent class
The only important here are these 3 constants:
Use these constants when you add event listeners to the IYoutube object.
Example:
....
ytPlayer.addEventListener(YoutubeEvent.PLAYER_READY, onYTPlayerReady);
function onYTPlayerReady(event : YoutubeEvent) : void {
// code here
}
