JAVASCRIPT INTERACTION

Setting up the player

In order to use the javascript API, you'll have to set up the player with a specific ID and the enablejs flashvar set to true. When using the SWFObject embed method, the embed code will look like this:

<script type="text/javascript" src="/embed/swfobject.js"></script>

<div id="container">This text will be replaced</div>

<script type="text/javascript">
  var so = new SWFObject('/embed/mediaplayer.swf','jstest','400','220','8');
  so.addParam('allowscriptaccess','always');
  so.addParam('allowfullscreen','true');
  so.addVariable('width','400');
  so.addVariable('height','220');
  so.addVariable('file','/upload/dvdmenu.flv');
  so.addVariable('javascriptid','jstest');
  so.addVariable('enablejs','true');
  so.write('container');
</script>

This embed code has assigned the ID jstest to the mediaplayer (both in the SWFObject creation and with the javascriptid flashvar!), and it sets the flashvar enablejs to true. Note that it is nicer to include the swfobject.js file in head of your HTML document, but I've included it here for completeness. The important thing is that now all is set to communicate with javascript.

Sending events and getting updates

Let's first take a look at controlling playback of the mediaplayer through javascript. This can be done by defining three javascript functions:

<script type="text/javascript">
function sendEvent(swf,typ,prm) { 
  thisMovie(swf).sendEvent(typ,prm); 
};
function getUpdate(typ,pr1,pr2,swf) {};
function thisMovie(swf) {
  if(navigator.appName.indexOf("Microsoft") != -1) {
    return window[swf];
  } else {
    return document[swf];
  }
};
</script>

The first function can send specific events to the mediaplayer, for example 'playpause' to pause or resume the player. If you want to playpause the player from the above example, you can call the javascript function sendEvent('jstest','playpause');. Note that we don't need the prm parameter here, but some other events do. Here's a complete overview of all events you can send to the player, plus possible parameter (no fullscreen event indeed):

1. getlink, index: navigate to the link of playlistitem index.
2. next : play the next playlistitem.
3. playitem, index: play playlistitem index
4. playpause: toggle the playback status.
5. prev: play the previous playlistitem.
6. scrub, seconds: scrub the current item to position seconds.
7. stop: stop playing and buffering.
8. volume, percent: set the volume to percent percent.

The second function is automatically called by the player every time a playback variable is updated. You can define the contents of the function yourself in order to further process the information. If, for example, you want to do something in javascript every time the state of the player changes, you can define the function like this:

function getUpdate(typ,pr1,pr2,swf) { 
  if(typ == 'state') { alert('the current state is: '+pr1'); }
};

Of course, there's a lot more updates that can be received. Here's the complete list:

1. item, index: the currently playing playlistitem.
2. load, percent: the percentage loaded of the current item.
3. size, width,height: the dimensions of the current item.
4. state, index: the current playback state.
5. time, elapsed, remaining: the current elapsed and remaining time.
6. volume, percent: the current volume.

Note that the last parameter (swf) of the getUpdate() function will contain the value you've set to the javascriptid flashvar. It's useful if you control multiple players on one page, so you know which player is sending the updates. If you only have one player it's not needed; you can then remove the javascriptid line in the embed code.

The third function is a general purpose one, needed to connect to the SWF. Nothing special, but always make sure you have it defined. Now let's have a look at the player we've just set up:

This text will be replaced

1. pause/resume the movie.
2. The current state is:  (0=stop,1=buffer,2=play).

Loading files on-the-fly

Next to controlling the playback of the player, you can also load new mediafiles into the player through javascript. This is done with the loadFile() function you'll have to define in your javascript as well:

function loadFile(swf,obj) { 
  thisMovie(swf).loadFile(obj); 
};

The second parameter of this function accepts an object with all the properties a playlist entry can contain. You can send just the file (e.g. {file:'/upload/afraid.flv}) or playlist (e.g. {file:'http://blip.tv/?1=1&s=posts&skin=rss'}), but you can also send additional properties (e.g. {file:'/upload/corrie.flv', image:'/upload/corrie.jpg', captions:'/upload/corrie.xml'}). Once again, here's the real-life example:

This text will be replaced

1. load a single file
2. load a playlist from BLIP.tv
3. load a file with preview image.

Manipulating playlists

The last set of functions available in this API are those for runtime playlist manipulation:

function getLength(swf) { 
  var len = thisMovie(swf).getLength();
};
function addItem(swf,obj,idx) { 
  thisMovie(swf).addItem(obj,idx); 
};
function removeItem(swf,idx) { 
  thisMovie(swf).removeItem(idx); 
};
function itemData(swf,idx) { 
  var obj = thisMovie(swf).itemData(idx); 
};

The getLength() function simply returns the number of items the playlist contains.

The addItem() function adds an item to the playlist at position idx. If idx is omitted, the item is loaded to the end. The item (obj) can contain the same properties as the one in the loadFile() function.

The removeItem() function removes the playlistitem that is at position idx. If omitted, the last item is popped. If item idx is currently playing, the player stops. If there's only one item in the playlist, this function silently fails.

With the itemData() function, you can request an obj that contains all properties of the current playlistitem. This is especially useful to display content of the playlist (title, author, link, etc) in HTML. Once again, the same properties as loadFile(), addItem() and the playlists are supported. In action:

This text will be replaced

1. get the length of the playlist
2. add a video to the second playlist position
3. remove the second playlistitem.
4. get the properties of the second playlistitem.

Examples and support

This tutorial only described the bare functions the mediaplayer / imagerotator API contains. For a list of real-life usage examples of the API, take a look at the demo pages from Lars Nyboe Andersen. If you also have an example of the javascript API in action, please report!

For more support on the javascript API, I've created a distinct forum category. Please check there what might be wrong with your setup, or what might be possible with the API.

.. or check the sitemap