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