# Class: Api

## Api(element)

#### new Api(element)

Class representing the jwplayer() API. Creates an instance of the player.

##### Parameters:

Name | Type | Description
--- | --- | ---
`element` | HTMLElement | The element that will be replaced by the player's div container.

### Members

#### (readonly) _

Returns the Underscore module from the player instance. Used by plugins.

Deprecated:

  - TODO: in version 8.0.0-0

#### (readonly) _events :object

A map of event listeners.

##### Type:

- object

#### (readonly) _qoe :Timer

The internal QoE Timer.

##### Type:

- Timer

#### (readonly) Events

Returns the Events module from the player instance. Used by plugins to listen to player events.

Deprecated:

  - TODO: in version 8.0.0-0

#### (readonly) id :string

The player's query id. This matches the id of the element used to create the player at the time is was setup.

##### Type:

- string

#### (readonly) plugins :object

A map of plugin instances.

##### Type:

- object

#### (readonly) uniqueId :number

The player's unique id.

##### Type:

- number

#### (readonly) utils

Returns the Utils module from the player instance. Used by plugins.

Deprecated:

  - TODO: in version 8.0.0-0

#### (readonly) version :string

##### Type:

- string

### Methods

#### addButton(img, tooltip, callback, id, btnClassopt) → {Api}

Adds or updates a button in the player's control bar. The button is only displayed when controls are active.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`img` | string |  | The image that will be used as the button icon. Can be the url to an image or the content of an SVG in string.
`tooltip` | string |  | A tooltip label to display when the button is hovered.
`callback` | function |  | A callback to invoke when the button is clicked.
`id` | string |  | The id of the button to add or update.
`btnClass` | string | <optional> | CSS classes to add to the button element.

##### Returns:

Type
  Api

#### addPlugin(name, pluginInstance)

Adds a plugin instance to the player's instance.

##### Parameters:

Name | Type | Description
--- | --- | ---
`name` | string | The name of the plugin.
`pluginInstance` | any | The plugin instance.

#### attachMedia()

Reattaches a player instance to it's underlying video tag. Used after ad breaks to record state changes and resume playback.

Deprecated:

  - TODO: in version 8.0.0-0

#### castToggle() → {Api}

Toggles the presence of the Airplay button in Safari (calls `HTMLMediaElement.webkitShowPlaybackTargetPicker`). Does not affect the Chromecast button in Chrome.

##### Returns:

Type
  Api

#### createInstream() → {InstreamAdapter}

Creates a new instance of the instream adapter. If present, the previous instance created is destroyed first.

##### Returns:

Type
  InstreamAdapter

#### detachMedia()

Detaches a player instance from it's underlying video tag. Used to stop recording state changes before an ad break begins.

Deprecated:

  - TODO: in version 8.0.0-0

#### getAdBlock() → {boolean}

Checks for the presence of an ad blocker. Implemented by jwplayer-commercial.

##### Returns:

- Returns true when an ad blocker is detected, otherwise false.

Type
  boolean

#### getAudioTracks() → {Array.<AudioTrackOption>}

Gets the list of available audio tracks.

##### Returns:

Type
  Array.<AudioTrackOption>

#### getBuffer() → {number}

Gets the percentage of the media's duration which has been buffered.

##### Returns:

A number from 0-100 indicating the percentage of media buffered.

Type
  number

#### getCaptions() → {object}

Gets the captions style.

##### Returns:

Type
  object

#### getCaptionsList() → {Array.<CaptionsTrackOption>}

Gets the list of available captions tracks. The first item in the array will always be the "off" option, regardless of whether the media contains captions.

##### Returns:

Type
  Array.<CaptionsTrackOption>

#### getConfig() → {object}

Gets a static representation of the player's model.

##### Returns:

Type
  object

#### getContainer() → {HTMLElement}

Gets the player's top level DOM element.

##### Returns:

Type
  HTMLElement

#### getControls() → {boolean}

Gets whether or not controls are enabled.

##### Returns:

Type
  boolean

#### getCurrentAudioTrack() → {number}

Gets the index of the active audio track.

##### Returns:

The index of the active audio track, or -1 if there are no alternative audio tracks.

Type
  number

#### getCurrentCaptions() → {number}

Gets the index of the active captions selection.

##### Returns:

The index of the active selection option, or 0 if captions are off.

Type
  number

#### getCurrentQuality() → {number}

Gets the index of the active quality selection.

##### Returns:

Type
  number

#### getDuration() → {number}

Gets the duration of the current playlist item.

##### Returns:

The duration in seconds. Live streams always return `Infinity`. DVR streams return a negative value, indicating how far back playback is from the live edge.

Type
  number

#### getEnvironment() → {Environment}

Gets information about the current session's environment

##### Returns:

An object detailing the current session's browser, operating system, and supported features.

Type
  Environment

#### getFullscreen() → {boolean}

Gets the player's fullscreen state.

##### Returns:

Whether or not the player is in fullscreen mode.

Type
  boolean

#### getHeight() → {number}

Gets the player's height.

##### Returns:

The height of the player in pixels.

Type
  number

#### getItemMeta() → {object}

Gets all metadata for the current playlist item.

##### Returns:

Type
  object

#### getMute() → {boolean}

Gets the player's mute state.

##### Returns:

Whether or not the player is muted.

Type
  boolean

#### getPlaybackRate() → {number}

Gets the rate at which playback should occur while media is playing.

Since:
  - v7.12.0
Default Value:
  - 1.0

##### Returns:

The playback rate of the media element (`HTMLMediaElement.playbackRate`).

Type
  number

#### getPlaylist() → {Array.<PlaylistItem>}

Gets the player's playlist.

##### Returns:

Type
  Array.<PlaylistItem>

#### getPlaylistIndex() → {number}

Gets the index of the current playlist item.

##### Returns:

Type
  number

#### getPlaylistItem(indexopt) → {PlaylistItem|null}

Gets the current playlist item, or the item specified by `index`.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`index` | number | <optional> | A 0-based index of the desired playlist item.

##### Returns:

Returns `null` when `index` is out of range.

Type
  PlaylistItem | null

#### getPlugin(name) → {any}

Gets the specified plugin instance.

##### Parameters:

Name | Type | Description
--- | --- | ---
`name` | string | The name of the plugin.

##### Returns:

The plugin instance.

Type
  any

#### getPosition() → {number}

Gets the current playback time of the active media item.

##### Returns:

The current playback time in seconds. Live streams return the number of seconds played relative to when playback started (not since the live stream started). DVR streams return a negative value, indicating how far playback is from the live edge.

Type
  number

#### getProvider() → {ProviderInfo}

Gets information about how the player is handling playback.

##### Returns:

Type
  ProviderInfo

#### getQualityLevels() → {Array.<QualityOption>}

Gets the list of available quality options.

##### Returns:

Type
  Array.<QualityOption>

#### getSafeRegion(excludeControlbaropt) → {SafeRegion}

Gets the area of the player not obscured by controls.

##### Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`excludeControlbar` | boolean | <optional> | true | When set to false, the safe region will not exclude the area used by the controlbar.

##### Returns:

Type
  SafeRegion

#### getState() → {'idle'|'buffering'|'playing'|'paused'|'complete'}

Gets the player state.

##### Returns:

The current state of the player.

Type
  'idle' | 'buffering' | 'playing' | 'paused' | 'complete'

#### getStretching() → {'uniform'|'exactfit'|'fill'|'none'}

Gets the mode of stretching used to fit media in the player.

##### Returns:

Type
  'uniform' | 'exactfit' | 'fill' | 'none'

#### getViewable() → {1|0}

Gets the player's viewability.

Since:
  - v7.10.0

##### Returns:

Returns `1` when more than half the player is in the document viewport and the page's tab is active. Also returns `1` when the player is in fullscreen mode. `0` otherwise.

Type
  1 | 0

#### getVisualQuality() → {VisualQuality}

Gets information about the visual quality of the active media.

##### Returns:

Type
  VisualQuality

#### getVolume() → {number}

Gets the player's volume level.

##### Returns:

A number from 0-100.

Type
  number

#### getWidth() → {number}

Gets the player's width.

##### Returns:

The width of the player in pixels.

Type
  number

#### isBeforeComplete() → {boolean}

Checks if the player has finished playing the current playlist item, but has not yet transitioned to the "complete" state or began the next item. This state is entered when playing postroll ads.

##### Returns:

Type
  boolean

#### isBeforePlay() → {boolean}

Checks if playback has been requested, but the player has not begun to play. This state is entered when playing preroll ads.

##### Returns:

Type
  boolean

#### load(toLoad, feedDataopt) → {Api}

Stop any active playback, and loads either a new playlist, a new playlist item, or an item already in the current playlist.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`toLoad` | string | Array.<PlaylistItem> | PlaylistItem | number |  | The feed url, playlist, playlist item, or playlist item index to load.
`feedData` | object | <optional> | The feed data to associate with playlist items. Only applied when passing in a playlist or playlist items.

##### Returns:

Type
  Api

#### next() → {Api}

Stops any active playback, and plays the next up item specified by the related plugin. The next up item is the next playlist item, or the first recommended video when at the end of the playlist.

Since:
  - v7.7.0

##### Returns:

Type
  Api

#### off(nameopt, callbackopt, contextopt) → {Api}

Removes one or more callbacks.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`name` | string | <optional> | The event name. If null, all bound callbacks for all events will be removed.
`callback` | function | <optional> | If null, all callbacks for the event will be removed.
`context` | any | <optional> | If null, all callbacks with that function will be removed.

##### Returns:

Type
  Api

#### on(name, callback, contextopt) → {Api}

Adds an event listener.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`name` | string |  | The event name. Passing "all" will bind the callback to all events.
`callback` | function |  | The event callback.
`context` | any | <optional> | The context to apply to the callback's function invocation.

##### Returns:

Type
  Api

#### once(name, callback, contextopt) → {Api}

Adds an event listener which is triggered at most once. The listener is removed after the first call.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`name` | string |  | The event name. Passing "all" will bind the callback to all events.
`callback` | function |  | The event callback.
`context` | any | <optional> | The context to apply to the callback's function invocation.

##### Returns:

Type
  Api

#### pause(metaopt) → {Api}

Pauses playback.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`meta` | object | <optional> | An optional argument used to specify cause.

##### Returns:

Type
  Api

#### pauseAd(toggle)

Pauses or toggles ad playback. Implemented by ad plugins.

##### Parameters:

Name | Type | Description
--- | --- | ---
`toggle` | boolean | Specifies whether ad playback should be paused or resumed.

#### play(metaopt) → {Api}

Starts playback.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`meta` | object | <optional> | An optional argument used to specify cause.

##### Returns:

Type
  Api

#### playAd(adBreak)

Plays an ad. Implemented by ad plugins.

##### Parameters:

Name | Type | Description
--- | --- | ---
`adBreak` | string | Array | The ad tag or waterfall array.

#### playlistItem(index, metaopt) → {Api}

Stops any active playback, and plays the item at the 0-based index in the playlist.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`index` | number |  | If outside the range of the playlist, the value will be wrapped to the playlist length.
`meta` |  | <optional> | An optional argument used to specify cause.

##### Returns:

Type
  Api

#### playlistNext(metaopt) → {Api}

Stops any active playback, and plays the next item in the playlist. When the player is at the end of the playlist, this will play the first playlist item.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`meta` |  | <optional> | An optional argument used to specify cause.

##### Returns:

Type
  Api

#### playlistPrev(metaopt) → {Api}

Stops any active playback, and plays the previous item in the playlist. When the player is at the beginning of the playlist, this will play the last playlist item.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`meta` |  | <optional> | An optional argument used to specify cause.

##### Returns:

Type
  Api

#### playToggle(metaopt) → {Api}

Toggles playback between play and pause.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`meta` | object | <optional> | An optional argument used to specify cause.

##### Returns:

Type
  Api

#### qoe() → {PlayerQoE}

Gets the QoE properties of the player and current playlist item.

##### Returns:

Type
  PlayerQoE

#### registerPlugin(name, minimumVersion, pluginClass)

Registers a plugin class with the player library.

##### Parameters:

Name | Type | Description
--- | --- | ---
`name` | string | The name of the plugin.
`minimumVersion` | string | The minimum player version required by the plugin.
`pluginClass` | function | The plugin function or class to instantiate with new player instances.

#### remove() → {Api}

Asynchronously removes the player from the page. A "remove" event is fired once removal begins. Playback is stopped, and the DOM used by the player is reset. All event listeners attached to the player are removed.

##### Returns:

Type
  Api

#### removeButton(id) → {Api}

Removes a button from the player's control bar.

##### Parameters:

Name | Type | Description
--- | --- | ---
`id` | string | The id of the button to remove.

##### Returns:

Type
  Api

#### resize(width, heightopt) → {Api}

Sets the player width and height.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`width` | number | string |  | Set the width in pixel (number) or CSS measurement units ('100%', '100em')
`height` | number | string | <optional> | Set the height in pixel (number) or CSS measurement units ('100%', '100em') When specified, the "aspectratio" option included at setup is cleared.

##### Returns:

Type
  Api

#### seek(position, metaopt) → {Api}

Seeks to a specific time within the active media. Resumes playback if the player is paused.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`position` | number |  | The time to seek to.
`meta` |  | <optional> | An optional argument used to specify cause.

##### Returns:

Type
  Api

#### setCaptions(captionsStyles) → {Api}

Sets captions styles.

##### Parameters:

Name | Type | Description
--- | --- | ---
`captionsStyles` | object |

Since:
  - v7.5.0

##### Returns:

Type
  Api

#### setConfig(options) → {Api}

Updates the player's config options.

##### Parameters:

Name | Type | Description
--- | --- | ---
`options` |  |

Since:
  - v7.12.0

##### Returns:

Type
  Api

#### setControls(toggleopt) → {Api}

Toggles player controls.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`toggle` | boolean | <optional> | Specifies whether controls should be enabled or disabled.

##### Returns:

Type
  Api

#### setCues(sliderCues) → {Api}

Sets the list of cues to be displayed on the time slider.

##### Parameters:

Name | Type | Description
--- | --- | ---
`sliderCues` | Array.<SliderCue> | The list of cues.

##### Returns:

Type
  Api

#### setCurrentAudioTrack(index)

Sets the active audio track.

##### Parameters:

Name | Type | Description
--- | --- | ---
`index` | number |

#### setCurrentCaptions(index)

Sets the active captions option.

##### Parameters:

Name | Type | Description
--- | --- | ---
`index` | number |

#### setCurrentQuality(index)

Sets the active quality option.

##### Parameters:

Name | Type | Description
--- | --- | ---
`index` | number |

#### setFullscreen(toggleopt) → {Api}

Toggles fullscreen state. Most browsers require a user gesture to trigger entering fullscreen mode.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`toggle` | boolean | <optional> | Specifies whether to enter or exit fullscreen mode.

##### Returns:

Type
  Api

#### setMute(toggleopt) → {Api}

Toggles the player's mute state.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`toggle` | boolean | <optional> | Specifies whether to mute or unmute the player.

##### Returns:

Type
  Api

#### setPlaybackRate(playbackRate) → {Api}

Sets the player's default playeback rate. During playback, the rate of the current media will be set immediately if supported. Not supported when streaming live.

##### Parameters:

Name | Type | Description
--- | --- | ---
`playbackRate` | number | The desired rate of playback. Limited to numbers between 0.25-4.0.

Since:
  - v7.12.0

##### Returns:

Type
  Api

#### setup(options) → {Api}

Creates a new player on the page and asynchronously begins setup. A "ready" event is triggered on success. A "setupError" event is triggered on failure.

##### Parameters:

Name | Type | Description
--- | --- | ---
`options` | object | The player configuration options.

##### Returns:

Type
  Api

#### setVolume(level) → {Api}

Set the player's volume level.

##### Parameters:

Name | Type | Description
--- | --- | ---
`level` | number | A value from 0-100.

##### Returns:

Type
  Api

#### skipAd() → {Api}

Calls `skipAd` on the active instream adapter instance if present.

##### Returns:

Type
  Api

#### stop() → {Api}

Stops any active playback.

##### Returns:

Type
  Api

#### trigger(name, argsopt) → {Api}

Triggers one or more events. By default, the player will invoke callbacks inside a try-catch block to prevent exceptions from breaking normal player behavior. To disable this safety measure set `jwplayer.debug` to `true`.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`name` | string |  | The event name.
`args` | object | <optional> | An object containing the event properties.

##### Returns:

Type
  Api