JavaScript API

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
 
});
 
});

JavaScript

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:

screenshot

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);

JavaScript

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:

propertydefault valuedescription
confObjectthe initial configuration object
currentSpeed1v5.1 the current playback speed level:
- 1 = normal speed
less than 1 = slow motion
greater than 1 = fast forward
disabledFalsetrue while the player is disabled
enginethe chosen video engine - either "html5" or "flash"
finishedFalsetrue while the player is stopped at the end of the video
isFullscreenFalsetrue while the player is in fullscreen mode
loadingFalsetrue while the player is being loaded
mutedFalsetrue while the player is muted
pausedFalsetrue while the player is paused
playingFalsetrue while the player is playing
readyFalsetrue once the player API is ready and completely loaded
seekingFalsetrue while the player is seeking
splashFalsetrue while the player is in splash state
videoObjectthe current video object
volumeLevel0.8the 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;

JavaScript

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'
}

JavaScript

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

Methods

methoddescription
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();

JavaScript

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");

JavaScript

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>

HTML

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' }
]);

JavaScript

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);
 
});

JavaScript

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
 
});

JavaScript

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:

eventwhen it fires
beforeseekBefore 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.
disableWhen the player toggles between disabled and normal state. In disabled mode the UI elements cannot be used.
errorWhen an error occurred. The 3rd argument provides an object featuring the code and message properties. See the error table below.
finishWhen playback has finished.
fullscreenWhen the player goes to fullscreen mode.
fullscreen-exitWhen player exits fullscreen mode.
loadFirst 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.
muteWhen the player's mute state is toggled.
pauseWhen playback is paused.
progressWhen 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.
readyWhen the video is fully loaded and video metadata (such as duration) becomes available from the video object which is provided by the 3rd argument.
resumeWhen playback is resumed.
seekWhen seeking is completed at the target position. Since v5.4.2 the 3rd argument gives access to the target position.
speedv5.1 When the playback speed is changed. The new level is provided by the 3rd argument.
stopv5.2 When playback is stopped by the stop() method.
unloadWhen the player goes back to the splash state.
volumeWhen 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 codeerror message
1Video loading aborted
2Network error
3Video not properly encoded
4Video file not found
5Unsupported video
6Skin not found
7SWF file not found
8Subtitles not found
9Invalid RTMP URL
10Unsupported 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) {
 
});

JavaScript

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...
 
};
 
};

JavaScript

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

JavaScript

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.