Global API access

Use the flowplayer function to get a global handle on the API:

flowplayer(function (api, root) {

  api.bind("load", function () {

    // do something when a new video is about to be loaded

  }).bind("ready", function () {

    // do something when a video is loaded and ready to play

  });

});

View standalone demo.

This anonymous callback function is provided by the Flowplayer library and is called every time a Flowplayer instance is created.

You use it to customize the default behaviour of all players on your page in a similar manner as you set global configuration options, and thus it should be called right after the flowplayer script is included on the page and before the page is loaded - before $(document).ready.

The API is provided by the first argument and it looks like this in the browser console:

Via the second argument - called root above - you can access the root or container element of the player.

Selective API access

Once the players are installed initialized you can access specific player instances like this:

// get the first player

var api = flowplayer();

// same thing with jQuery

api = $(".flowplayer:first").data("flowplayer");

// and the second player

api = flowplayer(1);

// .. with jQuery

api = $(".flowplayer:eq(1)").data("flowplayer");

// use any jQuery selector

api = $(".mycustom.flowplayer").data("flowplayer");

// return the API in given jQuery object

api = flowplayer($(".myplayer"));

// or DOM object

var elem = document.getElementById("myplayer");

api = flowplayer(elem);

The installation method determines when you have access to selected APIs:

1. automatic: when the DOM (document object model) is    ready
2. manual: after the specific instance has been    initialized

Properties

During its life cycle the player is in varying states which are reflected in the the properties of the API. Here is a complete list of the API properties:

Depending on the state of the player at the moment when you grab the API or call one of its methods, the full depth of its properties might be not be available.

For example: Before the player is ready video metadata such as its duration has not been processed and is therefore undefined. Similarly you cannot obtain a sensible value for the current playback position at all times. A safe way to retrieve that position would be:

var api = flowplayer(), currentPos;

// get the current position, default to 0

currentPos = api.ready ? api.video.time : 0;

Video object

The video property is a reference to the currently playing video. Here is an example:

{

  // the length of downloaded bytes in seconds - HTML5 only

  buffer: 15.43,

  // flag indicating whether the buffer is fully loaded

  buffered: false,

  // length of video in seconds

  duration: 18.85,

  // width of video file in pixels

  width: 640

  // height of video in pixels

  height: 280,

  // current index in the playlist (since v5.1)

  index: 0,

  // true in case the clip is the last in a playlist (since v5.1)

  is_last: false,

  // whether the server supports random jumping on timeline

  seekable: true,

  // path to currently playing video as given on setup

  src: 'http://mydomain.com/video1.mp4',

  // current playback position in seconds

  time: 5.27681660899654,

  // video format (media type)

  type: 'mp4',

  // array of video formats

  sources: [

    { type: 'webm', src: 'http://mydomain.com/video1.webm', suffix: 'webm' },

    { type: 'mp4',  src: 'http://mydomain.com/video1.mp4',  suffix: 'mp4'  },

    { type: 'ogg',  src: 'http://mydomain.com/video1.ogv',  suffix: 'ogv'  }

  ],

  // video filename suffix

  suffix: 'mp4',

  // absolute URL of the video

  url: 'http://mydomain.com/video1.mp4'

}

Check out this demo which prints the entire video object to the page for inspection.

Methods

All methods return the API object

Load method

The load() method initializes player and video from the splash state on demand:

api.load();

A VIDEO or OBJECT tag is created depending on browser or engine preference.

You can also change the currently playing video, load it into an existing player instance. For example:

api.load("http://mydomain.com/my/another/video2.mp4");

This will play a new video. The player will use the same video formats as specified in the initial configuration. For example, let's say the player is configured like this:

<div class="flowplayer">

   <video>

      <source type="application/x-mpegurl" src="http://mydomain.com/video1.m3u8">

      <source type="video/webm" src="http://mydomain.com/video1.webm">

      <source type="video/mp4" src="http://mydomain.com/video1.mp4">

      <source type="video/ogg" src="http://mydomain.com/video1.ogv">

   </video>

</div>

The player will attempt to use video2.m3u8, video2.webm, video2.mp4 or video2.ogv depending on the browser. All formats and filename suffixes must be the same for both videos and the videos must be delivered via HTTP. Alternatively you can explicitly specify the video formats and URLs as an array listing the video src to type mappings as objects:

api.load([

  { mpegurl: 'http://mydomain.com/my/other/video.m3u8' },

  {    webm: 'http://mydomain.com/my/other/video.webm' },

  {     mp4: 'http://mydomain.com/my/other/video.mp4'  },

  {     ogg: 'http://mydomain.com/my/other/video.ogv'  }

]);

The player attempts to pick the formats in the given order depending on browser support - note the shortened spec for the application/x-mpegurl type. If the video locations do not obey a consistent filename and filename suffix naming scheme or if the videos are delivered via RTMP for the Flash engine you must use this method, the argument then cannot be a simple string.

You can provide an event callback function in the second argument. It will be called when the player is ready and the new video is about to start. For example:

api.load("http://mydomoain.com/other/video.mp4", function (event, api, video) {

  // the new video is about to start

  console.info(video.duration);

});

Events

Use the bind() method to execute your own JavaScript when a specified event happens in the player. For example:

api.bind("pause", function(e, api) {      // do your thing   });

The first argument is the event name, and the second is a callback function which is fed with 2 or 3 arguments:

1. The jQuery event object.    This jQuery convention allows fine grained control of the event object's    properties.
2. Provides a handle on the player API.
3. Optional, depends on the event.

Within the callback the this keyword refers to the root element of the player - the container element. It corresponds to the currentTarget property of the first argument.

Here is a full list of events:

Note: You will often find that Flowplayer's CSS programming capabilities provide a more elegant way to customize the player's look and feel dynamically according to its state.

Error codes

Error codes and error messages returned by the third argument of the error event are mapped the following way:

Errors 1 through 4 are HTML5 video exceptions, errors 5 through 10 are Flowplayer exceptions.

jQuery

You can also bind your events directly to the jQuery object. For example

$(".flowplayer:first").bind("pause", function(e, api) {   });

Internally we use the jQuery mechanism so you can use all the goodies such as binding, unbinding, one and namespaces. These work both against the API object and the jQuery object.

Engines

Currently there are two engines: html5 and flash. They share a common engine interface that is implemented as follows:

flowplayer.engine.html = function(api, root) {

   // perform initialization here

   ...

   // return the API

   return {

      resume: function() {

      },

      pause: function() {

      }

      // etc...

   };

};

One might want to make an implementation with Silverlight for WMV support (rather not). Look for the implementation details in Github

window.flowplayer

Flowplayer function is used for accessing the player, making extensions and engines. It also has following properties

// version number

var version = flowplayer.version;

// default configuration for all players (v5.1)

flowplayer.defaults;

// global configuration to override defaults

flowplayer.conf = { };

// list of engines that are supported by the browser

flowplayer.engine

flowplayer.support

v5.1 flowplayer.support is a collection of properties that represent the presence of different browser features. If for example HTML5 video is supported then flowplayer.support.videois true. Here are the supported properties:

• animation - HTML animation support
• dataload - whether any video data can be loaded before hitting play
• flashVideo - flash video support
• firstframe - support for display of first video frame on load
• fullscreen - native HTML5 fullscreen support
• fullscreen_keyboard - keyboard support in fullscreen mode
• hlsDuration - v5.4 whether duration of HLS stream is natively recognized
• inlineBlock - CSS inline-block support
• inlineVideo - v5.4 support for playing video inline
• seekable - v5.4 support for seeking when video is ready
• subtitles -  native subtitle support
• touch - touch interface support
• video -  HTML video support
• volume - volume support via JavaScript API
• zeropreload - whether preload="none" completely disables preloading

Flowplayer HTML5 v5.0 extended the jQuery.support but this is now deprecated. Use flowplayer.support instead.