# 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](/docs/wowza-flowplayer/player/configure).


```javascript
// 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 (*).

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

| Property | 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()](/docs/wowza-flowplayer/player/player-api#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 full-screen 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. |


## 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.

| 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](/docs/wowza-flowplayer/player/configure/#video-source). |
| `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: "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 full-screen mode. The optional `flag` attribute forces the normal sized (`false`) or full-screen (`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 `flowplayer.events.REAP` event, enabling cleanup of unsafe resources. |


Info
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()`.

## 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:


```js
// 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:


```js
// Same as above, but with jQuery
$(player).on(flowplayer.events.SEEKING, (ev) => {
  // Run your listener
});
```

Of course, you can use the standard [addEventListener](//developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener) call to register the listener because our API is the actual `video` object. For example:


```js
// 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](https://developer.mozilla.org/en-US/docs/Web/Guide/Events/Media_events) are available. To learn how you can view a full list of player events, see the [Event names](/docs/wowza-flowplayer/player/player-api/#event-names) section.

| Event | Description |
|  --- | --- |
| `flowplayer.events.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, it's possible for this event to occur multiple times. |
| `flowplayer.events.CUEPOINT_START*` | Sent when a configured cuepoint is entered. |
| `flowplayer.events.CUEPOINT_END*` | Sent when a configured cuepoint is terminated. |
| `flowplayer.events.DATA` | Send when the first frame of the video has finished loading. |
| `flowplayer.events.ENDED` | Sent when playback completes. |
| `flowplayer.events.STANDARD_ERROR` | Sent when an error occurs and uses our library of standardized error messages. For more, see [error handling](/docs/wowza-flowplayer/player/player-api#error-handling). |
| `flowplayer.events.REAP` | Sent when a player instance is about to be removed from the DOM, and any unsafe references are about to be reaped, which allows Single Page Applications (SPAs) to perform the necessary resource cleanups. This is important when working with frontend frameworks like React. This event should never be emitted directly, only listened to. |
| `flowplayer.events.FULLSCREEN_ENTER*` | Sent when the player enters the full-screen mode. |
| `flowplayer.events.FULLSCREEN_EXIT*` | Sent when the player leaves the full-screen mode. |
| `flowplayer.events.METADATA` | Sent when the video's metadata has finished loading. All attributes (like `HTMLVideoElement.duration`) now contain as much useful information as they're going to. |
| `flowplayer.events.LOAD_START` | Sent when loading of the video begins. |
| `flowplayer.events.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 plugin](/docs/wowza-flowplayer/player/player-api#custom-plugins). |
| `flowplayer.events.PAUSE` | Sent when playback is paused. |
| `flowplayer.events.PLAYING` | Sent when the video begins to play either for the first time, after having been paused, or after ending and then restarting. |
| `flowplayer.events.PROGRESS` | Sent periodically to inform of the video download progress. The download information can be found in the video's `buffered` attribute. |
| `flowplayer.events.QUALITY_CHANGE` | Sent when the player changes video quality. |
| `flowplayer.events.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. |
| `flowplayer.events.SEEKED` | Sent when a seek operation completes. |
| `flowplayer.events.SEEKING` | Sent when a seek operation begins. |
| `flowplayer.events.SOURCE*` | Sent right before the player `src` attribute is set. This allows you to change the video URL before playback. |
| `flowplayer.events.TIME_UPDATE` | Sent when the time indicated by the element's `currentTime` attribute has changed. |
| `flowplayer.events.VIEW_ENTER*` | Sent when the player becomes visible for the user. |
| `flowplayer.events.VIEW_LEAVE*` | Sent when the player leaves the users viewport and is no longer visible. |
| `flowplayer.events.VOLUME_CHANGE` | Sent when the `volume` attribute or the `muted` attribute changes. |
| `flowplayer.events.WAITING` | Sent when video is waiting for the data to be downloaded from the server. |


### 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:


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

The `flowplayer.events` object has the following structure:


```json
{
  "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](/docs/wowza-flowplayer/plugins/about-plugins/#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.

Info
* The beta version released with Wowza Flowplayer 3.28.1 doesn't standardize error codes for ad-related events.
* If you intend to use the `MediaError` object and the browser's underlying error handling behavior, see the MDN Web Docs.


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


```js
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:


```JavaScript
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...});
```


```TypeScript
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:


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