Order Now AdSolution Sign Up | Login » Bits on the Run Sign Up | Login »

Flash Plugin API Reference

JW Player 5 supports an extremely flexible API for plugins, that can be built in ActionScript). It is possible to read the config/playlist variables of the player, call player functions, and listen for Flash Events.

Version 5 also supports plugins and JavaScript for version 4 of the player, although some features may not be compatible with version 5.

If you're looking for documentation on the JavaScript API, see the JW Player 5 JavaScript API Reference doc on the LongTail Video support site.

Contents

Initialization

All plugins have to define a function called initPlugin(player, config). This function will be called by the player when it is initialized. A reference to the IPlayer player is passed to this function, so the plugin can instantly read the config/playlist, call player functions and assign event listeners.

Plugins also need to implement a resize(width, height) function and an id getter. 

import com.longtailvideo.jwplayer.player.IPlayer;
import com.longtailvideo.jwplayer.plugins.PluginConfig;

public class MyPlugin extends Sprite implements IPlugin {

	private static var myID:String = "myplugin";

	private var api:IPlayer;
	private var config:PluginConfig;

	public function initPlugin(player:IPlayer, conf:PluginConfig):void {	
		this.api = player;
		this.config = conf;
	}

	public function get id():String {	
		return myID;
	}

	public function resize(width:Number, height:Number):void {	
		// Implement resizing if necessary
	}
}

Note: You need to include the com.longtailvideo.jwplayer.player package in your plugin project in order to be able to strong-type your code and avoid compilation errors.

Plugin Config

In addition to the player's API (player:IPlayer), initPlugin also receives a PluginConfig object. This object contains all of the plugin's configuration parameters. For example, if the configuration option myplugin.opt1 is passed into the player's embed code, it will be available to myplugin in the PluginConfig object passed to its initPlugin method: 

  var opt1:String = conf['opt1'];

Player Configuration

Plugins can access the player's configuration directly through the player's API:

Example

    private var _player:IPlayer;
    
    function initPlayer(player:IPlayer, config:PluginConfig):void {
        _player = player;
        
        getVariables();
    }
    
    function getVariables():void {
        // See what the repeat flashvar was configured to
        var repeat:String = _player.config.repeat
        // The current width of the controlbar
        var barWidth:Number = _player.config.pluginConfig('controlbar')['width'];
    }

Playlist

Calling player.playlist returns the player's Playlist, which contains all the entries in the playlist (PlaylistItems). For a single file, the list will have just one entry.

Properties

Methods

PlaylistItem

The PlaylistItem object represents an individual item in the playlist. It contains all of the default playlist item properties, as well as any custom properties defined in the playlist for that item.

Example

   // Get the playlist
   var list:IPlaylist = player.playlist;
   // The currently playing item's file URL
   var currentFile:String = list.currentItem.file;
   // The second-to-last playlist item's title
   var title:String = list.getItemAt(list.length-2).title;
   
   // Add an additional item to the playlist, at the end
   var newItem:PlaylistItem = new PlaylistItem();
   item.file = 'http://example.com/video.mp4';
   item.title = 'A new video';
   list.insertItem(item);

Player commands

The Flash Plugin API exposes the following player commands:

Here are some examples of how to call these functions: 

// Mute the player
player.mute(true);
// Load a new video into the player
player.load("http://example.com/videos/video.mp4");

Player Locking

The player offers a locking API to block playback and prevent the user (and other plugins) from performing player operations.

Methods

Properties

Example

   var _player:IPlayer;
   
   function initPlugin(player:IPlayer, config:PluginConfig):void {
        _player = player;
   }
    
   function lockThePlayer():void {
        _player.lock(this, gotTheLock);
   }
   
   function gotTheLock():void {
        trace("Lock has been granted.  Doing something.");
        doSomething();
        trace("Now unlock the player");
        _player.unlock(this);
   }

Setting listeners

Any of the events described in the Player Events page can be listened for using the Flash Event model. To listen for a player event, simply call the addEventListener() function on the player API, and pass in the event's ID constant and your event handler.

An example: 

private function muteTracker(evt:MediaEvent) { 
    trace('the new mute state is: '+evt.mute); 
}

player.addEventListener(MediaEvent.JWPLAYER_MEDIA_MUTE, muteTracker);

You can also remove event listeners in the standard way: 

player.removeEventListener(MediaEvent.JWPLAYER_MEDIA_MUTE, muteTracker);

Note that you need to include the com.longtailvideo.jwplayer.events package in your plugin project in order to be able to strong-type your code and avoid compilation errors.

Player Controls

The player contains several built-in user controls, which have their own APIs. The components are available through the API via the player's "components" property. For example, to execute the controlbar's hide() function, you would call:

player.controls.controlbar.hide()

Here's example code that checks to see if the dock has been enabled. If so, it inserts a dock icon. If not, the plugin adds a custom icon to the controlbar. 

var api:IPlayer;
var icon:DisplayObject;

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

function initPlugin(player:IPlayer, conf:PluginConfig):void {
    api = player;
    if(api.config.dock) { 
        api.controls.dock.addButton(icon, "Click here", clickHandler);
    } else {
        api.controls.controlbar.addButton(icon, "Click here", clickHandler);
    }
}

Skinning

Flash plugins can hook into the player's XML Skinning Model through the player's skin property, which contains the getSkinElement() method:

Example

The plugin grabs the 

  // Embedded version of the asset
  [Embed(source="./assets/icon.png")]
  private const EmbeddedIcon:Class;
  // Icon display object
  private var icon:DisplayObject;
  
  public function get id():String {
    return "myplugin";
  }
  
  public function initPlugin(player:IPlayer, conf:PluginConfig):void {
    // Grab the icon from the skin if it exists
    icon = player.skin.getSkinElement(this.id, "icon");
    
    if (icon == null) {
       icon = new EmbeddedIcon();
    }
  }

In the XML skin, a skin designer could then skin the icon element, by adding a folder with the same name as your plugin containing the graphics, and adding the following to the skin's XML manifest file: 

<component name="myplugin">
   <elements>
      <element name="icon" src="icon.png" />
   </elements>
</component>