Player API

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

Creating A Flowplayer Instance

Creating a Wowza Flowplayer instance is synchronous. The first argument includes the selector or container you wish to store the Flowplayer instance. The second argument serves as the configuration object.

// video is a real HTML5Video tag
var video = flowplayer('#player',
  { token : "keyboardcat"
  , src   : ""


Flowplayer extends the standard Element, HTMLMediaElement, and HTMLVideoElement objects with its 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 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 the 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. Returns 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 Control the playback speed with this property. A value larger than 1 will fast forward. A positive value smaller than 1 will play the video in slow motion.
poster A URL to the poster image to display 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.


The following is a list of the methods in the Wowza 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) * Attaches an event handler function for one or more events to the selected elements. The first argument is either the event name as a string or an array of event names.
one(event, fn) * Same as on, but the handler function is executed 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() * Adds or changes configuration object. 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: ""});
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 sent 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 event, enabling cleanup of unsafe resources.

The play() method should only be used for starting initial playback. For subsequent play actions, such as when loading a new source with setSrc(), you need to use togglePlay().


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

Flowplayer offers an 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 a single event name, while the on listener can listen to multiple, different event types.

Events reference

The following is a list of the events emitted or used by Wowza 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. Due to the way mounting works, this event is only accessible inside of a custom extension.
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 found in the video's buffered attribute.
resize * Sent when the player dimensions are changed. This usually happens when the browser window is resized, but it can happen on other occasions as well.
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 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 if the volume is set of if 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 terminated.
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 objects for convenient access. For example, you can use it to view and debug all the emitted events as follows:

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

The object has the 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) {

The err argument contains information about the error as follows:

  • src - path to the source file
  • type - erroneous video type
  • code - 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 external JavaScript snippets with optional CSS that automatically run for each player instance on a page.

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

class CustomPlugin {
  init(opts, root, player) {
    console.log("configuration passed to player", opts)
    console.log("player container", root)
    console.log("player API", player)

    player.on("ended", () => console.log("playback ended"))

// register the plugin

The provided function is called for every flowplayer instance on the page right before the player is inserted or mounted on the page. The options are:

  • opts is the configuration object.
  • 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) {