Player API

Wowza Flowplayer's API is a powerful extension of the HTML5 video object that provides its own set of properties, methods, and event types. The API allows developers to control the player programmatically and to interact with its features. Some of these features are provided for convenience, while others serve to normalize the API so it works consistently across different browsers.

Create a player instance

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

// Video is contained in an HTML5 video tag
const player = flowplayer("#player",
  { 
    src   : "cdn.example.com/video.mp4",
    token : "[your-player-token]"
  }
);

Properties

The Wowza Flowplayer extends the standard Element, HTMLMediaElement, and HTMLVideoElement objects with its own set of properties. All Wowza Flowplayer specific properties are marked with an asterisk symbol (*).

Methods

The following is a list of the methods in the Wowza Flowplayer API. All Wowza Flowplayer specific methods are marked with an asterisk symbol (*). Generic methods are defined in the HTML5MEdiaElement specifications.

Events

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 into full-screen mode.

The Player API offers an on() method to hook event handlers to the player. It works as follows:

// Listen to a seeking event
player.on(flowplayer.events.SEEKING, (ev) => {
  // ev.type is the event type, such as "seeking"
  const type = ev.type;
  console.log(`Event type: ${type}`);
});

Since the API is a regular DOM object, you can also use your favorite JavaScript library for events. Here's an example with jQuery:

// Same as above, but with jQuery
$(player).on(flowplayer.events.SEEKING, (ev) => {
  // 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:

// Use ended event from HTMLMediaElement interface
player.addEventListener("ended", () => {
  console.log("The video has ended.");
});

Events reference

The following is a list of some of the events emitted or used by Wowza Flowplayer. All Wowza Flowplayer specific events are marked with an asterisk symbol *. This list is not exhaustive, as all Media Events are available. To learn how you can view a full list of player events, see the Event names section.

Event names

All supported event names are listed in the flowplayer.events object for convenient access. You can use this object to view and debug all events emitted by a player instance as follows:

player.on(Object.values(flowplayer.events), (e) => {
  console.info(e.type);
});

The flowplayer.events object has the following structure:

{
  "AUDIO_ONLY_SOURCE": "audioonlysource",
  "BEFORE_PAUSE": "beforepause",
  "BEFORE_PLAY": "beforeplay",
  "CAN_PLAY": "canplay",
  "CLICK": "click",
  "CONFIG": "config",
  "CONTEXT_MENU": "contextmenu",
  "CUEPOINTS": "cuepoints",
  "CUEPOINT_END": "cuepointend",
  "CUEPOINT_START": "cuepointstart",
  ...
  "RESIZE": "resize",
  "SCROLL": "scroll",
  "SEEK_CANCEL": "seek:cancel",
  "SEEK_QUEUED": "seek:queued",
  "SEEKED": "seeked",
  "SEEKING": "seeking",
  "SET_QUALITY": "quality:set",
  "SOURCE": "src",
  "STATE": "state",
  "TIME_UPDATE": "timeupdate",
  "TOUCH_CANCEL": "touchcancel",
  "TOUCH_END": "touchend",
  "TOUCH_MOVE": "touchmove",
  "TOUCH_START": "touchstart",
  "VIDEO_TRACK_SELECT": "tracks:video:select",
  "VIDEO_TRACKS": "videoTracks",
  "VIEW_ENTER": "viewenter",
  "VIEW_LEAVE": "viewleave",
  "VOLUME_CHANGE": "volumechange",
  "WAITING": "waiting",
  "WEBKIT_NEEDKEY": "webkitneedkey"
}

Plugin events

For more information about working with plugin events, see the Plugin events section.

Error handling

With Wowza Flowplayer 3.28.1, we added a standard STANDARD_ERROR event that can be used to capture a list of customized player error codes. This standardized approach, which is still in the beta phase, was developed in conjunction with the Streaming Video Technology Alliance (SVTA). See this example for a full listing of available error codes.

In this case, the flowplayer.events.STANDARD_ERROR event allows you to deal with exceptions. For example:

const player = flowplayer("#player", {
  // Load a media source that doesn't exist
  src: "https://video.example/playlist.m3u8",
  token: "[your-player-token]"
});

player.on(flowplayer.events.STANDARD_ERROR, (err) => {
  console.log(err.detail);
});

The previous example logs an error object in the console with errorKey, error message, and error id properties that can help to troubleshoot your player instance. These details also display in the player UI. Additionally, you can also access the flowplayerErrorCode, config.fatal, and config.resource properties. The config.resource property can identify the resource that's causing the error. For more, see this demo.

Custom plugins

Wowza Flowplayer extensions are external JavaScript snippets with optional CSS that automatically run for each player instance on a page. All extensions are ternary or three-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
const flowplayerWithPlugin = flowplayer(CustomPlugin);

flowplayerWithPlugin("#player", {...config here...});

class CustomPlugin implements Plugin<CustomConfig> {
  init(opts: CustomConfig, root: PlayerRoot, player: 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
const flowplayerWithPlugin = flowplayer(CustomPlugin);

flowplayerWithPlugin("#player", {...config here...});

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. Wowza 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, you can loop through all player instances on the page with the following:

flowplayer.instances.forEach((api) => {
  console.info(api);
});