Flowplayer-JavaScript API

source url: https://flowplayer.org/docs/api.html

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:

property	default value	description
conf	Object	the initial configuration object
currentSpeed	1	v5.1 the current playback speed level: - 1 = normal speed less than 1 = slow motion greater than 1 = fast forward
disabled	False	true while the player is disabled
engine		the chosen video engine - either "html5" or "flash"
finished	False	true while the player is stopped at the end of the video
isFullscreen	False	true while the player is in fullscreen mode
loading	False	true while the player is being loaded
muted	False	true while the player is muted
paused	False	true while the player is paused
playing	False	true while the player is playing
ready	False	true once the player API is ready and completely loaded
seeking	False	true while the player is seeking
splash	False	true while the player is in splash state
video	Object	the current video object
volumeLevel	0.8	the current volume level between 0 and 1

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

method	description
disable([flag])	disable() without argument toggles between disabled and normal API state. disable(true) disables and disable(false) enables the API. While the API is disabled loading, pausing, resuming and seeking is not possible. The progress bar is greyed out (color configurable via CSS).
fullscreen()	Toggles between native fullscreen mode and initial screen size. When native fullscreen support is not present the player expands to the full size of the browser window. Note: Many browsers allow this method to work only from events which are triggered by user interaction, like "click", and not for example from player events like "ready" which happen at moments undetermined by the user.
load([video], [callback])	Loads the player with the specified video. See the section on the load method.
mute([flag])	mute() without argument toggles between muted and normal state. mute(true) mutes and mute(false) unmutes. Since v5.2 the original volume level is remembered between page loads.
next()	Advances to the next clip in a playlist setup.
pause([callback])	Pauses playback.
play(index)	v5.1 Plays the clip of a playlist specified in the zero based index argument. For example: play(0) plays the first clip.
play([video], [callback])	v5.1 Alias for the load method.
prev()	Jumps to the previous clip in a playlist setup.
resume()	Resumes playback.
seek(time, [callback])	Seeks to the given position in seconds. for example 13.5 The callback is executed once after the seek.
seek(flag, [callback])	v5.1 seek(true) seeks 10% forward and seek(false) seeks 10% backward. The callback is executed once after the seek.
seekTo(position, [callback])	v5.1 seekTo(1) jumps to 10% on the timeline, seekTo(2) goes to 20% and so on. The callback is executed once after the seek finishes.
seekTo()	v5.1 Seeks to last seek position. Same as pressing "." on the keyboard.
stop()	Pauses playback and seeks to the beginning of the video. In a poster setup the player goes back into poster state.
speed(rate, [callback])	v5.1 Sets the speed level to the given rate. 1 = normal speed less than 1 = slow motion greater than 1 = fast forward The callback is executed once after the speed has changed.
speed(flag, [callback])	v5.1 Changes the speed based on the speed configuration variable. speed(false) switches backward on the speed array and speed(true) switches forward. The callback is executed once after the speed has changed.
toggle()	Toggles between pause and play.
unload()	In a splash setup unloads the player back to the splash state.
volume(level)	Set the volume level to a decimal value between 0 (no volume) - 1 (full volume). Since v5.2 the volume level is remembered between page loads.

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:

event	when it fires
beforeseek	Before seeking starts at the origin position. Since v5.4.2 the 3rd argument gives access to the seek target position. By calling event.preventDefault() (where event is the callback's 1st argument) or returning false the seek can be stopped.
disable	When the player toggles between disabled and normal state. In disabled mode the UI elements cannot be used.
error	When an error occurred. The 3rd argument provides an object featuring the code and message properties. See the error table below.
finish	When playback has finished.
fullscreen	When the player goes to fullscreen mode.
fullscreen-exit	When player exits fullscreen mode.
load	First event in the lifecycle of the player and the video, before the configured video or a new video starts playing. Offers an opportunity to alter the video properties. The 3rd argument provides the video object featuring basic data like src, but not yet the video metadata from the server (such as duration). Returning false will prevent the video from loading.
mute	When the player's mute state is toggled.
pause	When playback is paused.
progress	When the playhead moves forward. Happens approximately every 250 milliseconds during playback. The 3rd argument provides the current playback position, i.e. the current value of the time property of the video object.
ready	When the video is fully loaded and video metadata (such as duration) becomes available from the video object which is provided by the 3rd argument.
resume	When playback is resumed.
seek	When seeking is completed at the target position. Since v5.4.2 the 3rd argument gives access to the target position.
speed	v5.1 When the playback speed is changed. The new level is provided by the 3rd argument.
stop	v5.2 When playback is stopped by the stop() method.
unload	When the player goes back to the splash state.
volume	When the volume level is changed. The new level is provided by the 3rd argument.

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:

error code	error message
1	Video loading aborted
2	Network error
3	Video not properly encoded
4	Video file not found
5	Unsupported video
6	Skin not found
7	SWF file not found
8	Subtitles not found
9	Invalid RTMP URL
10	Unsupported video format. Try installing Adobe Flash.

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.