Viddler

The Viddler Chromeless Player is a Flash API built in AS3. This API allows Flash developers to build their own Player Skins for use on Viddler’s platform.

Loading Chromeless Player

The end-point for the Chromeless Player is

http://www.viddler.com/chromeless/

Demo & Player Skin

We’ve set up a demo to show you how some of this stuff works. We also have an open source player skin that you can see an example of.

Interface

The following functions are used to control the player interface.

Including the JavaScript Viddler Library (JS implementation only)

<script src="http://cdn.static.viddler.com/js/vapi.js" type="text/javascript"></script>

Getting the player object (JavaScript)

function getPlayer(player_id)
{
    return Viddler(player_id);
}

Loading video

The Chromeless Player allows for videos to be queued up and then played or loaded directly into the player. Here are the functions that facilitate queuing and loading.

cueVideoByKey

ActionScript and JavaScript:

function cueVideoByKey(videoKey:String,
    startSeconds:Number = 0,
    suggestedQuality:String = null,
    secretCode:String = null):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.

cueVideoById

ActionScript and JavaScript:

function cueVideoById(videoKey:String,
    startSeconds:Number = 0,
    suggestedQuality:String = null,
    secretCode:String = null):void;

Alias for cueVideoByKey.

cueVideoByUsernameAndVideoNumber

ActionScript and JavaScript:

function cueVideoByUsernameAndVideoNumber(
    username:String,
    videoNumber:Number,
    startSeconds:Number = 0,
    suggestedQuality:String = null,
    secretCode:String = null):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.

loadVideoByKey

ActionScript and JavaScript:

function loadVideoByKey(videoKey:String,
    startSeconds:Number = 0,
    suggestedQuality:String = null,
    secretCode:String = null):void;

Loads and plays the specified video.

loadVideoById

ActionScript and JavaScript:

function loadVideoById(videoKey:String,
    startSeconds:Number = 0,
    suggestedQuality:String = null,
    secretCode:String = null):void;

Alias for loadVideoByKey.

loadVideoByUsernameAndVideoNumber

ActionScript and JavaScript:

function loadVideoByUsernameAndVideoNumber(username:String,
    videoNumber:Number,
    startSeconds:Number = 0,
    suggestedQuality:String = null,
    secretCode:String = null):void;

Loads and plays the specified video.

Video Playback Controls

The following functions are used to control video playback.

playVideo

ActionScript and JavaScript:

function playVideo():void;

Plays the currently cued/loaded video.

pauseVideo

ActionScript and JavaScript:

function pauseVideo():void;

Pauses the currently playing video.

stopVideo

ActionScript and JavaScript:

function stopVideo():void;

Stops the current video. This function also cancels the loading of the video.

seekTo

ActionScript and JavaScript:

function seekTo(seconds:Number,
    allowSeekAhead:Boolean = true):void;

Seeks to the specified time of the video in seconds. The seekTo() 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.

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

Volume controls

Changing the player volume.

mute

ActionScript and JavaScript:

function mute():void;

Mutes the player.

unMute

ActionScript and JavaScript:

function unMute():void;

Unmutes the player.

isMuted

ActionScript:

function isMuted():Boolean;

JavaScript:

function isMuted(callbackName:String = null):Boolean;

Returns true if the player is muted, false if not.

setVolume

ActionScript and JavaScript:

function setVolume(volume:Number):void;

Sets the volume. Accepts an integer between 0 and 100.

getVolume

ActionScript:

function getVolume():Number;

JavaScript:

function getVolume(callbackName:String = null):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 dimensions

Setting the player size.

setSize

ActionScript and JavaScript:

function setSize(width:Number, height:Number):void;

Sets the size in pixels of the player.

Playback status

Playback status.

getVideoBytesLoaded

ActionScript:

function getVideoBytesLoaded():Number;

JavaScript:

function getVideoBytesLoaded(callbackName:String = null):Number;

Returns the number of bytes loaded for the current video.

getVideoSecondsLoaded

ActionScript:

function getVideoSecondsLoaded():Number;

JavaScript:

function getVideoSecondsLoaded(callbackName:String = null):Number;

Returns the number of seconds loaded for current video.

getVideoBytesTotal

ActionScript:

function getVideoBytesTotal():Number;

JavaScript:

function getVideoBytesTotal(callbackName:String = null):Number;

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

getVideoStartBytes

ActionScript:

function getVideoStartBytes():Number;

JavaScript:

function getVideoStartBytes(callbackName:String = null):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.

getVideoStartSeconds

ActionScript:

function getVideoStartSeconds():Number;

JavaScript:

function getVideoStartSeconds(callbackName:String = null):Number;

Returns the number of seconds 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.

getCurrentTime

ActionScript:

function getCurrentTime():Number;

JavaScript:

function getCurrentTime(callbackName:String = null):Number;

Returns the elapsed time in seconds since the video started playing.

getPlayerState

ActionScript:

function getPlayerState():Number;

JavaScript:

function getPlayerState(callbackName:String = null):Number;

Returns the state of the player. Possible values are unstarted (-1), ended (0), playing (1), paused (2), buffering (3), video cued (5).

Playback quality

Retrieve info about available quality levels and current quality, and change current quality.

getPlaybackQuality

ActionScript:

function getPlaybackQuality():String;

JavaScript:

function getPlaybackQuality(callbackName:String = null):String;

This function retrieves the actual video quality of the current video. It returns null if there is no current video. Possible return values are hd720, high, normal.

setPlaybackQuality

ActionScript and JavaScript:

function 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. If the playback quality does change, it will only change for the video being played. At that time, 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 normal, high, hd720 or default. Setting the parameter value to default instructs Viddler to select the most appropriate playback quality, which will vary for different users, videos, systems and other playback conditions.

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 high, and that is unavailable, then the playback quality will be set to normal (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.

getAvailableQualityLevels

ActionScript:

function getAvailableQualityLevels():Array;

JavaScript:

function getAvailableQualityLevels(callbackName:String = null):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 hd720, high, normal. 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. Viddler could expand the list of quality levels to include formats that may not be appropriate in your player context. Similarly, Viddler 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.

Video data

Retrieve data about the video that is currently loaded in the player.

getVideoKey

ActionScript:

function getVideoKey():String;

JavaScript:

function getVideoKey(callbackName:String = null):String;

Returns key of the currently playing video Note that getVideoKey() will return null until the video’s info is loaded, which normally happens just after cueVideoBy* or loadVideoBy* call. Player state PLAYER_STATE_VIDEO_CUED indicates that video’s info is loaded.

getDuration

ActionScript:

function getDuration():Number;

JavaScript:

function getDuration(callbackName:String = null):Number;

Returns the duration in seconds of the currently playing video. Note that getDuration() will return 0 until the video’s info is loaded, which normally happens just after cueVideoBy* or loadVideoBy* call. Player state PLAYER_STATE_VIDEO_CUED indicates that video’s info is loaded.

getVideoUrl

ActionScript:

function getVideoUrl(offset:Number = 0):String;

JavaScript:

function getVideoUrl(offset:Number = 0,
    callbackName:String = null):String;

Returns the Viddler.com URL or permalink for the currently loaded/playing video. Note that getVideoUrl() will return null until the video’s info is loaded, which normally happens just after cueVideoBy* or loadVideoBy* call. Player state PLAYER_STATE_VIDEO_CUED indicates that video’s info is loaded.

getVideoEmbedCode

ActionScript:

function getVideoEmbedCode(playerUrl:String = null,
    offset:Number = 0,
    width:Number = 0,
    height:Number = 0,
    controlPanelHeight:Number = 0):String;

JavaScript:

function getVideoEmbedCode(playerUrl:String = null,
    offset:Number = 0,
    width:Number = 0,
    height:Number = 0,
    controlPanelHeight:Number = 0,
    callbackName:String = null):String;

Returns the embed code for the currently loaded/playing video. Note that getVideoEmbedCode() will return null until the video’s info is loaded, which normally happens just after cueVideoBy* or loadVideoBy* call. Player state PLAYER_STATE_VIDEO_CUED indicates that video’s info is loaded.

getVideoTitle

ActionScript:

function getVideoTitle():String;

JavaScript:

function getVideoTitle(callbackName:String = null):String;

Returns title. Note that getVideoTitle() will return null until the video’s info is loaded, which normally happens just after cueVideoBy* or loadVideoBy* call. Player state PLAYER_STATE_VIDEO_CUED indicates that video’s info is loaded.

getAuthorName

ActionScript:

function getAuthorName():String;

JavaScript:

function getAuthorName(callbackName:String = null):String;

Returns video’s author’s name. Note that getAuthorName() will return null until the video’s info is loaded, which normally happens just after cueVideoBy* or loadVideoBy* call. Player state PLAYER_STATE_VIDEO_CUED indicates that video’s info is loaded.

getAuthorAvatarUrl

ActionScript:

function getAuthorAvatarUrl():String;

JavaScript:

function getAuthorAvatarUrl(callbackName:String = null):String;

Returns video’s author’s avatar’s url. Note that getAuthorAvatarUrl() will return null until the video’s info is loaded, which normally happens just after cueVideoBy* or loadVideoBy* call. Player state PLAYER_STATE_VIDEO_CUED indicates that video’s info is loaded.

getViewsCount

ActionScript:

function getViewsCount():Number;

JavaScript:

function getViewsCount(callbackName:String = null):Number;

Returns number of views for current video. Note that getViewsCount() will always return -1 until the video’s info is loaded, which normally happens just after cueVideoBy* or loadVideoBy* call. Player state PLAYER_STATE_VIDEO_CUED indicates that video’s info is loaded.

getCommentsCount

ActionScript:

function getCommentsCount():Number;

JavaScript:

function getCommentsCount(callbackName:String = null):Number;

Returns number of comments for current video. Note that getCommentsCount() will always return -1 until the video’s info is loaded, which normally happens just after cueVideoBy* or loadVideoBy* call. Player state PLAYER_STATE_VIDEO_CUED indicates that video’s info is loaded.

getFavoritesCount

ActionScript:

function getFavoritesCount():Number;

JavaScript:

function getFavoritesCount(callbackName:String = null):Number;

Returns number of users that favorited this video. Note that getFavoritesCount() will always return -1 until the video’s info is loaded, which normally happens just after cueVideoBy* or loadVideoBy* call. Player state PLAYER_STATE_VIDEO_CUED indicates that video’s info is loaded.

Comments

You can manipulate video comments using those methods.

CommentInfo

Data object representing comment. Properties in ActionScript and JavaScript:

public var dateAdded:Date; // date the comment was added
public var id:Number; // comment id
public var test:String; // comment content
public var videoId:Number; // id of video that this comment belongs to
public var posterId:Number; // id of comment author
public var posterImage:String; // url to avatar of comment author
public var posterName:String; // name of comment author
public var startTime:Number; // comment timepoint
public var rating:Number; // current comment rating
public var ratedAs:Number; // if -1 current user rated this comment negatively, if 1 current user rated this comment positively, if 0 current user didn't rate this comment
public var replyToId:number; // id of comment that this comment is a reply to
public var videoReply:Boolean; // true if this comment is video comment
public var videoUrl:String; // url to flv file of the video comment
public var moderationStatus:Number; // moderations status (-1 refused, 0 pending review, 1 approved, 2 denied)

getComments

ActionScript:

function getComments():Array;

JavaScript:

function getComments(callbackName:String = null):Array;

Returns comments of current video. This method returns array of CommentInfo objects.

saveComment

ActionScript and JavaScript:

function saveComment(text:String, 
    startTime:Number, 
    replyToId:Number = 0,
    username:String = null):void;

Saves comment as current user. This function will send request to viddler’s servers to save comment and upon receiving response it will dispatch event: onSaveCommentResult. text is the comment’s content. startTime is the comment’s timepoint in seconds (float). replyToId is the parent comment’s id (this is passed to function when we want to indicate that this comment is a response). username is user’s name used only when player is in anonymous commenting mode.

deleteComment

ActionScript and JavaScript:

function deleteComment(id:Number):void;

Delete comment. id is comment’s id. This function will send request to viddler’s server to delete comment and upon receiving response it will dispatch event: onDeleteCommentResult.

rateComment

ActionScript and JavaScript:

function rateComment(id:Number, rating:Number):void;

Rates comment. id is comment’s id. rating is user’s rating of current comment: -1 negative, 0 neutral, 1 positive. This function will send request to viddler’s server to rate comment and it will dispatch event: onRateCommentResult on completion.

Event Listeners

You can add an event listener to watch for certain actions in the player.

addEventListener

ActionScript:

function addEventListener(type:String,
    listener:Function,
    useCapture:Boolean=false,
    priority:int=0,
    useWeakReference:Boolean=false):void;

Adds a listener function for the specified event. The Events section 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.

JavaScript:

function addEventListener(type:String,
    listenerName:String):void

Adds a listener function for the specified event. The Events section identifies the different events that the player might fire. The listenerName is a name off the function that will execute when the specified event fires.

Events

onReady

This event is fired when the player is loaded and initialized, meaning it is ready to receive API calls.

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

onPlaybackQualityChange

This event is fired whenever the video playback quality changes. For example, if you call the setPlaybackQuality 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 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 event broadcasts is the new playback quality. Possible values are “normal”, “high” and “hd720″.

onError

This event is fired when an error in the player occurs. The possible error codes are 100 and 111. 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 never existed in the first place. Verbose meaning of 100 error is ‘not found’. The 111 error code is broadcast when the video requested is marked as private or is not available to current user. Verbose meaning of 111 error is ‘forbidden’.

onBrandingUpdate

This event is fired when new branding info is loaded. Data contains new BrandingInfo object. If data is null, skin should use default branding.

onSecurityUpdate

This event is fired when security is updated after loading new video info or updating old one. Data property contains SecurityManagerInterface instance.

onSaveCommentResult

This event is fired when saveComment function is called. Data contains new CommentInfo object if saving was successful or null if player wasn’t able to save the comment.

onRateCommentResult

This event is fired when rateComment function is called. Data contains result: 0 success, 1 error.

onDeleteCommentResult

This event is fired when deleteComment function is called. Data contains result: 0 success, 1 error.

Examples

Loading the player

Here is an example of how to load the player in AS3.

package {
	import flash.display.Loader;
	import flash.display.Sprite;
	import flash.events.Event;
	import flash.net.URLRequest;
	import flash.system.Security;
 
	public class LoadExample extends Sprite {
 
		// This loader will be used to load chromeless player
		private var loader:Loader;
 
		// This will hold chromeless player instance
		private var player:Object;
 
		public function LoadExample() {
			loader = new Loader();
			loader.contentLoaderInfo.addEventListener(Event.INIT, onLoaderInit);
			loader.load(new URLRequest("http://www.viddler.com/chromeless/"));
		}
 
		private function onLoaderInit(event:Event):void {
			addChild(loader);
			Security.allowDomain(loader.contentLoaderInfo.url);
			loader.content.addEventListener(ChromelessPlayerConstants.EVENT_READY, onPlayerReady);
			loader.content.addEventListener(ChromelessPlayerConstants.EVENT_ERROR, onPlayerError);
			loader.content.addEventListener(ChromelessPlayerConstants.EVENT_STATE_CHANGE, onPlayerStateChange);
			loader.content.addEventListener(ChromelessPlayerConstants.EVENT_PLAYBACK_QUALITY_CHANGE, onPlayerPlaybackQualityChange);
		}
 
		private function onPlayerReady(event:Event):void {
			trace('player ready:', Object(event).data);
			player = loader.content;
			player.setSize(480, 360);
		}
 
		private function onPlayerError(event:Event):void {
			trace('player error:', Object(event).data);
		}
 
		private function onPlayerStateChange(event:Event):void {
			trace('player state:', Object(event).data);
		}
 
		private function onPlayerPlaybackQualityChange(event:Event):void {
			trace('video quality:', Object(event).data);
		}
	}
}

Example skin

You can download a example skin here. The source is also available on Github.

(The following links need to be depreciated when everything is on GitHub.)
Example skin can be seen here: http://developers.viddler.com/files/chromeless/ExampleSkin.swf
Source: http://developers.viddler.com/files/chromeless/ExampleSkin.as