Player API

Flowplayer API is a powerful extension for the HTML5 video object, with a small set of it's own properties, methods and event types. Most are for convenience and some extensions normalizes the API so that it works consistently across browsers.

Creating A Flowplayer Instance
Creating A Flowplayer Instance via the Cloud-hosted API
Properties
Methods
Events
Event reference
Error handling
Custom extensions
Global object

If you are using Flowplayer 7 please head here

Creating A Flowplayer Instance

When using the javascript api, creating a Flowplayer instance is synchronous. The first argument is the selector or container you wish to have the Flowplayer instance live inside of, the second argument is the configuration Object.

// video is a real HTML5Video tagvar video = flowplayer('#player',

{ token : "keyboardcat"

, src : "cdn.example.com/video.mp4"

})

Creating A Flowplayer Instance via the Cloud-hosted API

When using cloud-hosted players, all of the Flowplayer libraries are loaded asynchronously in parallel to reduce startup time. This means that we must know that the cloud hosted resources have finished loading and it is safe to access the api of a given player. In these asynchronous environments you can access the flowplayer.cloud Promise to ensure that all of the parallel loading is done.

For example a cloud-based player will look similar to this:

Flowplayer-hosted videoSelf-hosted video

{

"src": "f576651c-4cc6-4664-84fa-bb3b35ef1aba"

}

</script</div>

flowplayer.cloud.then(function() {

// this is now the same synchronous environment

// but we know all cloud assets are ready

// since this was the target of the cloud loader

// we just want a reference to the Flowplayer instance

var video = flowplayer("#async-player")

console.log('flowplayer instance', video);

});</script>

auto-initializing a cloud-hosted player can only happen on a tag that is not <head> or <body>

Cloud embeds intelligently detect if they are located in a container other than <head> and <body> to automatically create a Flowplayer instance. Adding a cloud hosted asset loader to a <head> or <body> tag will mean the loader will not automatically create the Flowplayer instances on resolving, since it is impossible to determine the best strategy in these setups.

This does not mean you cannot use the cloud-based player to manage configuration from the Platform, it just requires some special consideration. We have this advanced cloud-based single-page application as a demonstration of how mix the two.

Properties

Flowplayer extends the standard Element, HTMLMediaElement and HTMLVideoElement objects with it's own set of properties.

All Flowplayer specific properties are marked with an asterisk symbol (*)

We won't touch the prototypes of the standard HTML "host objects". Only the individual DOM nodes are extended.

Methods

List of the methods in Flowplayer API. All Flowplayer specific properties are marked with an asterisk symbol (*) . Generic methods are defined in the HTML5MEdiaElement specifications

Events

Almost every API operation starts by listening to a player event — a specific action that happened during the existence of a player. For example when the playback starts or ends, when player goes to fullscreen mode.

Flowplayer offers on method to hook your event handlers to the player. It works as follows:

// listen "seeking" and "seeked" events

video.on('seeking seeked', function(e) {

// e.type is the event type such as "seeking"

var type = e.type

})

And since the API is a regular DOM object you can use alternatively your favorite UI library for events. Here's how you do the job with jQuery:

// same as above, but with jQuery

$(video).on('seeking seeked', function(e) {

// run your listener

})

Of course you can use the standard addEventListener call to register the listener, because our API is the actual video object. For example:

video.addEventListener('ended', function() {

// playback ended

})

Note that addEventListener accepts only single event name, while the onlistener can listen to multiple different event types.

Event reference

List of the events emitted or used by Flowplayer. This list is not exhaustive, as all Media Events are available.

Event type
Description
fullscreenenter *
Sent when player enters the fullscreen mode.
fullscreenexit *
Sent when player leaves the fullscreen mode.
ended
Sent when playback completes.
error
Sent when an error occurs. Learn more about error handling.
loadeddata
The first frame of the video has finished loading.
loadedmetadata
The video's metadata has finished loading; all attributes (like HTMLVideoElement.duration) now contain as much useful information as they're going to.
loadstart
Sent when loading of the video begins.
mount *
Sent when the player interface is completely rendered and you can access all the elements with CSS and JavaScript. This event is only accessible inside of a custom extension, due to the way mounting works.
pause
Sent when playback is paused.
playing
Sent when the video begins to play either for the first time, after having been paused, or after ending and then restarting.
progress
Sent periodically to inform of the video download progress. The download information can be is found in the video's buffered attribute.
resize *
Sent when the player dimensions are changed. This usually (but not necessarily) happens when the browser window is resized.
seeked
Sent when a seek operation completes.
seeking
Sent when a seek operation begins.
src *
Sent right before the player src attribute is set. This allows you to change the video URl before the playback.
timeupdate
The time indicated by the element's currentTime attribute has changed.
viewenter *
Sent when the player becomes visible for the user.
viewleave *
Sent when the player leaves the users viewport and is longer visible.
volumechange
Sent when the audio volume changes both when the volume is set and when the muted attribute is changed.
waiting
Sent when video is waiting for the data to be downloaded from the server.
cuepoints *
Sent when cuepoints are attached to the video, the attaching and parsing of cuepoints is possibly asynchronous depending on how they are registered, and this is the only safe way to interact with them. In the event of cuepoints being merged or changed (ala changing subtitle l), it is possible for this event to occur multiple times.
cuepointstart *
Sent when a configured cuepoint is entered.
cuepointend *
Sent when a configured cuepoint is leaved.
fp:reap
Sent when a flowplayer instance is about to be removed from the DOM, and any unsafe references are about to be reaped, which allows Single Page Applications to perform the necessary resource cleanups. This is important when working with front-end frameworks like React. This event should never be emitted directly, only listened to

Event names

All supported event names are listed in flowplayer.events objects to convenient access. You can, for example, use it to view and debug all the emitted events as follows

video.on(Object.values(flowplayer.events), function(e) {

console.info(e.type)

})

The flowplayer.events object has following structure

{

FULLSCREEN_ENTER: 'fullscreen_enter',

FULLSCREEN_EXIT: 'fullscreen_exit',

ENDED: 'ended',

ERROR: 'error',

DATA: 'data',

METADATA: 'metadata',

LOAD_START: 'load_start',

MOUNT: 'mount',

PAUSE: 'pause',

PLAYING: 'playing',

PROGRESS: 'progress',

RESIZE: 'resize',

SEEKED: 'seeked',

SEEKING: 'seeking',

SOURCE: 'source',

TIME_UPDATE: 'time_update',

VIEW_ENTER: 'view_enter',

VIEW_LEAVE: 'view_leave',

VOLUME_CHANGE: 'volume_change',

WAITING: 'waiting',

CUEPOINTS: 'cuepoints',

CUEPOINT_START: 'cuepoint_start',

CUEPOINT_END: 'cuepoint_end',

REAP: 'fp:reap'

}

Error handling

The error event allows you to deal with exceptions. For example

video.on('error', function(e) {

console.info(e.error.type)

})

The error property contains information about the error as follows:

src - path to the source file
type - erroneous video type

code - a numeric error code that can have following values

2: Not connected to the internet
4: Video file not found
5: Unsupported video file type
8: Captions file not found

Custom extensions

Flowplayer extensions are extenal JavaScript snippets with optional CSS that are automatically run for each player instance on a page.

All extensions are ternary (3 argument) functions that are passed to flowplayerlike this:

flowplayer(function(opts, root, video) {

// listen to the events and do your stuff

video.on('ended', function() {

// make woodoo

})

Here's a demo that renders a custom mute button above the player:

The provided function is called for every flowplayer instance on the page right before the player is inserted (ie "mounted") on the page. The options are

opts is the configuration object and
root is the root element of the player UI
video is the HTMLVideoElement of the media

All extensions typically listen to the events and act on them.

Flowplayer itself is built as a list of extensions.

Global object

The global flowplayer object has a set of properties and tools that are mainly targeted for plugin developers. For example

// loop trough all player instances on the page

flowplayer.instances.forEach(function(api) {

console.info(api)

})

Event type
Description
commit
The SHA1 hash of the player version being used such as 098a6693e6937da777caac66d372a555a6a3e445. This hash can be used to verify the exact version of the player.
instances
All flowplayer instances on the page
mq
A micro sized jQuery implementation for the most basic operations. Definitely notcompatible with the standard jQuery.
observable
A general utility for emitting and listening to event streams.
states
A dictionary of different states that are supported. These are the CSS class names that are set/unset to the root element while the player is functioning. For example is-playing is present at flowplayer.statues.PLAYING
support
List of boolean flags about the browser environment. For eaxmple flowplayer.support.android is true when the user is on Android phone.
util
Various utility functions for making AJAX requests or pretty printing seconds.
version
The player version in human readable form, such as "1.1.5"