JavaScript API

Global API access

Use the flowplayer function to get a global handle on the API. Here we attach two custom events to the API of all players which will be installed on the page:

flowplayer(function (api, root) {

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

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

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

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

  });

});

[View standalone demo]({{ config.flowplayer7.standalonedemos }}/api/access)

This anonymous callback function is provided by the Flowplayer library and is called every time a Flowplayer instance is created. Think of it as a "mini-plugin".

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 in the HEAD section of the page and before the page is loaded - before the DOM (Document Object Model) is ready.

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

Console screenshot

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

The global flowplayer function is the only place to catch the initial load event in non splash setups.

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:

• automatic: when the DOM is ready
• manual: after the specific instance has been initialized
• JavaScript: after the specific instance has been initialized or instant API access

Instant API access

The pure JavaScript installation allows instant API access to the specific instance:

var api = flowplayer("#player", {
  // player configuration goes here
});

Contrary to the other selective API access methods the API is accessible in a 1-step operation.

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;

API properties should be considered as read only. Use API methods to change the state of the player and its properties. Setting properties is only needed in advanced cases and situations which often should be avoided in the first place, like in [this demo]({{ config.flowplayer7.demos }}/scripting/recover.html) which recovers from an invalid video location.

When skinning is involved you can often achieve your scripting goals with pure CSS programming by defining rules for the state classes instead of querying JavaScript API properties.

Extension and plugin properties

The following properties are provided by player extensions and plugins. Follow the link in the third column for further details:

Video object

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

{
  // the length of the available buffer in seconds - not available over RTMP
  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,

  // whether the [server](index.html#server-side) supports random jumping on timeline
  seekable: true,

  // path to currently playing video as given on setup
  src: 'http://mydomain.com/video1.m3u8',

  // current playback position in seconds
  time: 5.27681660899654,

  // video format (media type)
  type: 'application/x-mpegurl',

  // array of video formats
  sources: [
    { type: 'application/x-mpegurl', src: '//mydomain.com/video1.m3u8', suffix: 'm3u8' },
    { type: 'video/mp4',  src: '//mydomain.com/video1.mp4',  suffix: 'mp4'  }
  ],

  // video filename suffix
  suffix: 'm3u8',

  // absolute URL of the video
  url: 'http://mydomain.com/video1.m3u8',

  // [HLS quality selection](setup.html#hls-quality-selection)
  qualities: [-1, 0, 1, 2, 3, 4],
  quality: -1,

  // the clip title (if configured)
  title: 'My video'
}

Check out [this demo]({{ config.flowplayer7.demos }}/api/videoinspect.html) which prints the entire video object to the page for inspection.

Extension and plugin video properties

The following video object properties are provided by player extensions and plugins. Follow the link in the third column for further details:

Methods

All methods return the API object, with the exception of shutdown(). This allows method chaining:

// re-enable the api for the 2nd player on the page and resume
flowplayer(1).disable(false).resume();

See also the methods for event handling.

Extension methods

The following methods are provided by player extensions. Follow the link in the second column for further details:

Load method

Load player

Without argument 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.

Load video

load() also accepts a clip object as argument in the same way a pure JavaScript installation does as value to the clip option. The video represented by this clip object is then loaded into an existing player instance:

api.load({
  sources: [
    { type: "application/x-mepgurl",
      src:  "//mydomain.com/video2.m3u8" },
    { type: "video/mp4",
      src:  "//mydomain.com/video2.mp4"  }
  ]
});

The following shorthands are available for the clip object argument:

• Array of sources

api.load([
  { mpegurl: "//mydomain.com/video2.m3u8" },
  {     mp4: "//mydomain.com/video2.mp4"  }
]);

This shorthand does not accept further clip or source options.

• URL as string

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

This shorthand does not accept further clip or source options. And it expects the same source types to be present as configured for the player instance referenced by the API. Additionally the sources must be available via HTTP and obey the same file naming scheme: they can only differ by their filename suffix.

The above shorthand could be applied successfully to the following player for example:

<div class="flowplayer">
   <video>
      <source type="application/x-mpegurl" src="//mydomain.com/video1.m3u8">
      <source type="video/mp4" src="//mydomain.com/video1.mp4">
   </video>
</div>

• Callback

api.load({
  sources: [
    { type: "application/x-mepgurl",
      src:  "//mydomain.com/video2.m3u8" },
    { type: "video/mp4",
      src:  "//mydomain.com/video2.mp4"  }
  ]
}, function (e, api, video) {;
  console.log(video.duration);
});

The callback function will be invoked when the player is ready and the new video is about to start.

Events

The attaching methods can be used to execute custom JavaScript when a specified event happens in the player. For example:

api.on("pause", function(e, api) {

   // do your thing when the player is paused

});

The first argument is the event name or a space separated string of several event names, and the second is a callback function which is fed with 2 or 3 arguments:

1. The event object; if the event was attached via jQuery, the jQuery event object. Provides fine-grained event control via its properties.
2. Provides a handle on the player API.
3. Optional, depends on the event.

The event properties, like target, type etc., can be inspected in the browser console:

api.on("mute", function (e) {
    console.log(e);
});

Here is a complete list of player events:

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.

Extension events

The cuepoint event is provided by 2 player extensions. Follow the link in the second column for further details:

Attaching events

The following methods attach (or detach) events:

Events can be attached either to the API, or, with the help of jQuery, to the container element.

Multiple events can be attached in one call by passing their names in a space separated string in the first argument:

api.on("fullscreen fullscreen-exit", function (e, api) {
    if (/exit/.test(e.type)) {
       // do something after leaving fullscreen
    } else {
       // do something after going fullscreen
    }
});

API event binding

Normally events are simply attached to the API, like in the example above.

Events attached to the API return the API object.

jQuery event binding

You can also bind your events directly to the jQuery object referencing the container element. For example:

$(".flowplayer:first").on("pause", function(e, api) {
  // do something on pause
});

This makes for seamless integration of the Flowplayer API into custom jQuery plugins.

Events attached via jQuery return the jQuery object of the container element.

As this is a jQuery event, the this keyword refers to the root or container element of the player within the callback. It corresponds to the currentTarget property of the first argument.

Name space

All Flowplayer events can be confined to a specific name space when you attach them:

api.on("pause.mypause", function (e, api) {
  // do something on pause
});

Flowplayer event name spaces work as in jQuery, but do not require jQuery to be loaded. They come in handy for instance if you want to turn off a specific callback:

// turns off pause.mypause, but not the entire pause callback
api.off("pause.mypause");

Attaching to JavaScript installation

Events can immediately be attached to the API of a specific JavaScript installation:

flowplayer("#player", {
  // player configuration goes here
}).on("pause", function (e, api) {
  // do something on pause with this player
});

Attaching to manual installation

Events can immediately be attached to the container jQuery object of a specific manual installation:

$(".player").flowplayer({
  // player configuration goes here
}).on("pause", function (e, api) {
  // do something on pause with these players
});

Event chaining

All Flowplayer events return the API, or, if attached via jQuery the jQuery object of the container element. Therefore event bindings can be chained:

api.on("pause", function (e, api) {
  // do something on pause
}).on("resume", function (e, api) {
  // do something on resume
});

Event prevention

In some situations it is desireable to prevent player events from happening or to limit their scope, and optionally take a different action. To achieve this the Flowplayer API offers two methods which can be chained to the event variable provided by first arg

[This demo]({{ config.flowplayer7.demos }}/lookandfeel/noseek.html) gives an example of both methods in action to show how seeking can be disabled.

Engines

Flowplayer ships with two engines named html5 and flash. They share a common engine interface which is implemented as follows:

var engineImpl = function (player, root) {

    var engine = {
        engineName: engineImpl.engineName,

        pick: function (sources) {
            // engine specific picking mechanism

        },

        load: function (video) {
            // how this engine loads the video

        },

        resume: function () {
            // how this engine resumes playback

        },

        /* etc. */

    };

    return engine;
};

engineImpl.engineName = "myengine";
engineImpl.canPlay = function (type, conf) {
    // return boolean whether this engine can play media of type type
    // in the player configuration conf

};
// prepend the engine to the existing engines
flowplayer.engines.unshift(engineImpl);

Look for the implementation details in Github.

window.flowplayer

The flowplayer function is used for accessing the player, making extensions and engines. It also provides the 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 which are supported by the browser
flowplayer.engines

flowplayer.set

The flowplayer.set method allows to extend the existing global configuration without discarding other existing top-level settings, thereby offering more flexibility compared to specifying the flowplayer.conf object directly.

A typical scenario where this comes in handy: All pages on a site load a default script which contains Flowplayer configuration settings, but you want to override selected settings without discarding others:

flowplayer.set({
    // all videos on this page have a 4:3 aspect ratio
    ratio: 3/4,
    // all players on this page should use a splash setup
    splash: true,
    // common hlsjs configuration to all players
    hlsjs: {
        startLevel: -1
    }
});

Like anything relating to global configuration, flowplayer.set should be used only in the HEAD section of your page, before the DOM is ready.

flowplayer.support

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:

• android - {{ since('7.0.4') }} returns information about the current Android device, false otherwise
• autoplay - {{ since('7.0.4') }} whether autoplay is supported; synonymous to firstframe
• animation - CSS3 animation support
• browser - returns information about current browser and version
• cachedVideoTag - whether video tag can be cached
• dataload - whether any video data can be loaded before hitting play
• flashVideo - flash video support
• flex - whether flexible boxes are supported
• firstframe - support for display of first video frame on load; synonymous to autoplay
• fullscreen - native HTML5 fullscreen support
• fullscreen_keyboard - keyboard support in fullscreen mode
• hlsDuration - whether duration of HLS stream is natively recognized
• iOS - returns information about current iOS device
• inlineBlock - CSS inline-block support
• inlineVideo - support for playing video inline
• mutedAutoplay - {{ since('7.1.0') }} whether the (mobile) browser supports muted autoplay
• seekable - support for seeking when video is ready
• subtitles - native subtitle support
• svg - whether scalable vector graphics for the skin are supported
• touch - touch interface support
• video - HTML5 video support
• volume - volume support via JavaScript API
• zeropreload - whether preload="none" completely disables preloading

Refer to [this page]({{ config.flowplayer7.demos }}/videotest/support.html) for the results with your current browser.

Migration from Version 5

The second argument provided by the anonymous callback of the global API setup function is not a jQuery object anymore but a reference to the container element itself. If jQuery is loaded, you can still access the container element the jQuery way like this:

flowplayer(function (api, root) {
  root = $(root);
  // ... code referring to root as jQuery object
});

[recover]: {{ config.flowplayer7.demos }}//scripting/recover.html

[MINITOC]