Wiki Navigation

JW Player for Flash - API calls

The 4.0 version of the player for Flash supports a more flexible javascript API than the 3.x, since it is now possible to assign distinct javascript functions as listeners to the player. Also, the javascript API will work out-of-the-box. No enablejs=true function is needed anymore. Through the playerReady() call, instantiated players will report themselves to javascript.

Referencing the player.

Please note that the player will NOT be available the instant your HML page is loaded and the first javascript is executed. The SWF file (40k) has to be loaded and instantiated first! You can catch this issue by defining a simple global javascript function. It is called playerReady(obj) and every player that's succesfully instantiated will call it. The 'obj' object will contain the id, version and client of the player, so you immediately know what player it is an where to subscribe to. Use the id variable to get a reference to the player itself. Example:

var player;

function playerReady(obj) {
	var id = obj['id'];
	var version = obj['version'];
	var client = obj['client'];
	alert('the videoplayer '+id+' has been instantiated');
	player = document.getElementById(id);
};

If you are not interested in calling the player when the page is loading, you won't need this function. You can then simply use the ID of the embed/object tag that embeds the player to get a reference. A simple getElementById() function will do the trick, so it can be called. This function needs the ID of the object/embed tag as a reference. So for example with this embed tag:

<embed id="myplayer" name="myplayer" src="/upload/player.swf" width="400" height="200" />

You can get a pointer to the player with this line of code:

var player = document.getElementById('myplayer');

Note you must add both the id and name attributes in the <embed> in order to get back an ID in all browsers.

Config and playlist requests.

There's three types of calls javascript can make to the player. The first ones are calls for the config and playlist arrays:

player.getConfig();
player.getPlaylist();

getConfig() returns an object with key:value pairs of all config variables. So if, for example, you want to know the value of the autostart variable of the player, you can request it like this:

alert(player.getConfig().autostart);

getPlaylist() returns an array of all playlist-items with their properties. If, for example, you want to know the title of the second video in your playlist, you can request it like this:

alert(player.getPlaylist()[1].title);

A list of all the config variables can be found at this page. A playlist item can contain all items from the file properties section of this page.

Event sending

Of course it is also possible to send events from javascript to the player. Javascript can send all events the View of the MVC supports (e.g. STOP and VOLUME). Some events need a value (like VOLUME) and some don't (like STOP):

player.sendEvent('LINK',number);
player.sendEvent('LOAD',object);
player.sendEvent('MUTE',boolean);
player.sendEvent('NEXT',null);
player.sendEvent('ITEM',number);
player.sendEvent('PLAY',boolean);
player.sendEvent('PREV',null);
player.sendEvent('QUALITY',boolean);
player.sendEvent('SEEK',number);
player.sendEvent('STOP',null);
player.sendEvent('VOLUME',number);

A simple example is the sending of a play event:

player.sendEvent("PLAY");

The most complex example is the sending of a LOAD event. When sending a LOAD, the value of the function can be either a URL (to a video or playlist), an object (with a file, title, type, etc. key/value pair) or a complete array with playlist objects. In case of the latter two, always make sure you add the type key/value, or the player doesn't know which API to use! The type can be video, image, sound, youtube and camera. Examples:

var url ="http://www.myserver.com/myvideo.flv";
player.sendEvent("LOAD",url);

var obj = {file:"http://www.myserver.com/myvideo.flv",title:"My Cool Video"};
player.sendEvent("LOAD",obj);

var obj2 = {type:"video",file:"http://www.myserver.com/othervideo.flv",title:"Someone else's Cool Video"};
var lst = Array(obj,obj2);
player.sendEvent("LOAD",lst);

See the player setup PDF file for an overview of all events the view supports.

Listener assignments.

Last, javascript can assign listener functions to any event the Model, View and Controller forward. Whenever the event is fired, the function gets called, with a key:value populated object as parameters. The values in this object depend on the type of event, but three values are always sent: client (type and version of the flash plugin), id (ID of the player in the HTML DOM) and version (exact player version). Here's a list of all events you can listen to, plus the values they return:

Note that you must string representations of a function for the addListener function parameter!

1. player.addControllerListener(EVENT,function):

The ERROR event returns {message,id,client,version}.
The ITEM event returns {index,id,client,version}.
The MUTE event returns {state,id,client,version}.
The PLAY event returns {state,id,client,version}.
The PLAYLIST event returns {playlist,id,client,version}.
The QUALITY event returns {state,id,client,version}.
The RESIZE event returns {fullscreen,height,width,id,client,version}.
The SEEK event returns {position,id,client,version}.
The STOP event returns {id,client,version}.
The VOLUME event returns {percentage,id,client,version}.

2. player.addModelListener(EVENT,function):

The BUFFER event returns {percentage,id,client,version}.
The ERROR event returns {message,id,client,version}.
The LOADED event returns {loaded,total,offset,id,client,version}.
The META event returns {variable1,variable2,variable3,...,id,client,version}.
The STATE event returns {newstate,oldstate,id,client,version}.
The TIME event returns {position,duration,id,client,version}.

3. player.addViewListener(EVENT,function):

The LINK event returns {index,id,client,version}.
The LOAD event returns {object,id,client,version}.
The MUTE event returns {state,id,client,version}.
The NEXT event returns {id,client,version}.
The ITEM event returns {index,id,client,version}.
The PLAY event returns {state,id,client,version}.
The PREV event returns {id,client,version}.
The QUALITY event returns {state,id,client,version}.
The RESIZE event returns {height,width,id,client,version}.
The SEEK event returns {position,id,client,version}.
The STOP event returns {id,client,version}.
The VOLUME event returns {position,id,client,version}.

Note that a couple of events (ITEM, VOLUME, MUTE) are present in both the View and the Controller. Typically, the View broadcasts the raw user input (e.g. PLAY-null or Volume-115) and immediately thereafter the Controller broadcasts the validated value (e.g. PLAY-true or Volume-100).

Once again, here's an example.

function muteTracker(obj) { alert('the new mute state is: '+obj.state); };
player.addControllerListener("MUTE","muteTracker");

Please see the player setup PDF for an overview of all events the player is releasing.

Download in other formats:

Plain Text