Player API

Table of contents

Introduction

Flowplayer Native's 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.

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 tag
var 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 video source
<div id="async-player" data-player-id="cdcc4202-ef0b-4e03-a43a-d1fcf6d83157">
  <script src="//cdn.flowplayer.com/players/ffdf2c44-aa29-4df8-a270-3a199a1b119e/native/flowplayer.async.js">
    {
      "src": "f576651c-4cc6-4664-84fa-bb3b35ef1aba"
    }
  </script>
</div>
  • Self-hosted video source
<<div id="async-player" data-player-id="cdcc4202-ef0b-4e03-a43a-d1fcf6d83157">
  <script src="//cdn.flowplayer.com/players/ffdf2c44-aa29-4df8-a270-3a199a1b119e/native/flowplayer.async.js">
    {
      "src": "//edge.flowplayer.org/bauhaus.m3u8"
    }
  </script>
</div>
<script>
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.

    • Property name
    • Description
    • cuepoints *
    • All the configured cuepoints where the time and end properties have been set. This array can be dynamically changed while the player is running.
    • currentSrc
    • Returns a the absolute URL of the current video
    • currentTime
    • A float indicating the current playback time in seconds. Setting this value seeks the video to the new time.
    • disabled *
    • A boolean specifying whether the player is disabled and the user cannot seek forward using the mouse or keyboard. Player is disabled and enabled with toggleDisable() method.
    • duration
    • Returns a float indicating the length of the video in seconds, or 0 if no video data is available.
    • ended
    • Returns a boolean flag that indicates whether the video element has finished playing.
    • in_fullscreen *
    • A boolean specifying whether the player is in fullscreen mode
    • in_viewport *
    • A boolean specifying whether the player is inside the scrollable area and visible for the user.
    • muted
    • Returns a boolean flag that determines whether audio is muted. true if the audio is muted and false otherwise.
    • opts
    • A reference to the configuration state of the player.
    • paused
    • Returns a boolean flag that indicates whether the video element is paused.
    • playbackRate
    • You can control the speed of the playback with this property. A value larger than 1 will fast forward. A positive value smaller than 1 will play the video in slowmotion.
    • poster
    • A URL to the poster image to show until the user plays (or seeks).
    • root *
    • The root element of the video player. This is the immediate parent element of the video tag.
    • volume
    • A float indicating the audio volume, from 0.0 (silent) to 1.0 (loudest).
    • width
    • The width of the video's display area in pixels.

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

    • Method name
    • Description
    • pause()
    • Pauses the video playback.
    • on(events, fn) *
    • Attach an event handler function for one or more events to the selected elements. The first argument is either the event name as string or an array of event names.
    • one(event, fn) *
    • Same as on but the handler function is excecuted only once.
    • off(event, fn) *
    • Removes the event handler with the specified event type.
    • setSrc(src) *
    • Sets the video source to be played. The src attribute can be a string or an object similar to the src property.
    • setOpts() *
    • add or change configuration objects (usually used in conjunction with setSrc()). You can use all top-level config options like subtitle: , logo:, ima: etc. Sample: setOpts({subtitles:{ tracks:[{ src: "1.vtt", label: "English", default: true }, { src: "2.vtt", label: "Spanish", default : false }]}, logo: "https://myserver.com/logo.png"});
    • toggleDisable(flag) *
    • Disables and enables the player. The optional flag attribute forces disabled mode (true) or enabled mode (false). Disabled player cannot be seeked forward.
    • toggleFullScreen(flag) *
    • Toggles between normal and fullscreen mode. The optional flag attribute forces the normal sized (false) or fullscreen (false) mode. The custom "fullscreenenter" and "fullscreenexit" events are send respectively.
    • toggleMute() *
    • Toggles between muted and original volume level.
    • togglePlay(flag) *
    • Toggles between playing and paused mode. The optional flag attribute forces the playback (true) or paused state (false). Use this for initial playback of a source configured with setSrc() and when changing the state.
    • destroy
    • Removes a Flowplayer instance from flowplayer.instances and emits the flowplayer.events.REAP event, enabling cleanup of unsafe resources.

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

// or with a single event
video.on('seeked', function(e) { ... })

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 on listener can listen to multiple different event types.

Events 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.
    • 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',
  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(err) {
  console.info(e.code)
})

The err argument 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 flowplayer like 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)
})
From Flowplayer 7 Managed player
Results