JW Player for Flash

  1. Overview
  2. All Flashvars
  3. Supported Formats
  4. Crossdomain Security
     
  5. API Calls
  6. Events Overview
     
  7. Skinning in Flash CS3
  8. All Skin Elements
     
  9. Building Plugins
  10. Compiling Plugins

JW Player: API Calls

The 4.0 version of the player for Flash supports an extremely flexible API, both externally (for javascript) and internally (for plugins, that can be built in actionscript). It is possible to read the config/playlist variables of the player, send events to the player and assign functions as listeners. Plugins can also access specific calls/variables of one another. A small initialization routine is needed to connect your apps to the player.

Initialization

Javascript

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) {
	alert('the videoplayer '+obj['id']+' has been instantiated');
	player = document.getElementById(obj['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.

Plugins

All plugins have to define a function called initializePlugin(view). This function will be called by the player when it is initialized. A reference to the View is passed to this function, so the plugin can instantly read the config/playlist, send events and assign listeners. 

public class MyPlugin extends Sprite implements PluginInterface {
	private var view:AbstractView;

	public function initializePlugin(vw:AbstractView):void {	
		view = vw;
	};
}

You need to include the com.jeroenwijering.events package in your plugin project in order to be able to strong-type your code and avoid compilation errors.

Reading variables

There's three variable calls you can make through the API:

  • getConfig returns an object with all the variables (FlashVars) loaded into the player.
  • getPlaylist returns an array with all the entries in a playlist. For a single file, the list will indeed have just one entry. Every entry in the playlist is an object too, with a file, type, duration etc. property.
  • getPluginConfig(name) returns an object with all the flashvars of a certain plugin (for example the included controlbar or the externally loaded yousearch). Additionally, every plugin will have an x, y, width,height and visible variable that contains its positioning.

Javascript

If, for example, you want to know the value of the autostart variable of the player, you can request it like this: 

var start = 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: 

var title = player.getPlaylist()[1].title;

Plugins

The same call for plugins in actionscript looks like this: 

var start = view.getconfig()['autostart'];
var title = view.getPlaylist()[1]['title'];

Sending events

Of course it is also possible to send events to the player. This is done through a sendEvent() call. You can send all events defined by the View (e.g. STOP or VOLUME). Some of the event need a parameter and some don't. An overview of all events can be found on this page. Here's also a single sheet overview of all events.

Javascript

An example is the sending of a play event: 

player.sendEvent("PLAY","true");

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

Plugins

For plugins, events are again sent through the View. Also, there is the possiblity of strong typing the events through the included events package: 

view.sendEvent(ViewEvent.PLAY);
view.sendEvent(ViewEvent.LOAD,'http://www.mysite.com/mycoolvideo.mp4');

Setting listeners

Each language can assign listener functions to any event the Model, View or Controller fires. 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. An overview of all events can be found on this page.

It is recommended to not listen to events of the View, but only to the corresponding event of the Controller. The Controller generally checks the event of the View and fires a corrected version itself.

The 4.4 player introduced the possibility to also remove the listeners.

Javascript

Listeners can be set through three different functions:

  • player.addControllerListener(EVENT,myFunction);
  • player.addModelListener(EVENT,myFunction);
  • player.addViewListener(EVENT,myFunction);

Once again, here's an example. Note that you must string representations of a function for the function parameter! 

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

Removal of listeners works just the same (4.4+ compatible): 

player.removeControllerListener("MUTE","muteTracker");

Plugins

Again, the setup is similar to javascript:

  • view.addControllerListener(EVENT,myFunction);
  • view.addModelListener(EVENT,myFunction);
  • view.addViewListener(EVENT,myFunction);

An example: 

private function muteTracker(evt:ControllerEvent) { 
    trace('the new mute state is: '+evt.data['state']); 
};

view.addControllerListener(ControllerEvent.MUTE,muteTracker);

And an example removal call (4.4+ compatible): 

view.removeControllerListener(ControllerEvent.MUTE,muteTracker);

Again note that you need to include the com/jeroenwijering/events package in your plugin project in order to be able to strong-type your code and avoid compilation errors.

Plugin methods

In order to facilitate richer plugin interaction, the 4.3 player introduced an API method related to plugins. It is only available to other plugins; not to javascript:

  • getPlugin: returns the reference to a specific plugin. It can be used to call public methods or get public properties of a certain plugin.

Plugins

Here's an example call: 

var mtv:Object = view.getPlugin('controlbar');

Built-in plugin methods

There's two built-in player plugins that offer a public method:

  • The controlbar offers an addButton() call, used to insert a custom button in the controlbar. Available since 4.3
  • The dock offers an addButton() call, used to insert a custom button in the dock. Available since 4.5

Here's example code that tries to insert a button in the dock and then in the controlbar: 

var view:AbstractView;
var icon:DisplayObject;

function clickHandler(evt:MouseEvent):void { 
	trace('Demo button clicked!');
}; 

function initializePlugin(vie:AbstractView):void {
    view = vie;
    if(view.getPlugin('dock') && view.config['dock']) { 
        view.getPlugin('dock').addButton(icon,'click me!',clickHandler);
    } else if (view.getPlugin('controlbar')) {
        view.getPlugin('controlbar').addButton(icon,'myplugin',clickHandler);
    }
};