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:
The Player API instance.
- Type
- Api
addPlugin(name, pluginInstance) → {void}
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. |
Returns:
- Type
- void
attachMedia() → {Api}
Reattaches a player instance to it's underlying video tag.
- Deprecated:
- Yes
Returns:
The Player API instance.
- Type
- Api
castToggle() → {Api}
Toggles the presence of the Airplay button in Safari (calls HTMLMediaElement.webkitShowPlaybackTargetPicker).
Does not affect the Chromecast button in Chrome.
Returns:
The Player API instance.
- Type
- Api
createInstream() → {InstreamAdapter}
Creates a new instance of the instream adapter. If present, the previous instance created is destroyed first.
Returns:
The instream instance.
- Type
- InstreamAdapter
detachMedia() → {Api}
Detaches a player instance from it's underlying video tag. Used to stop recording state changes before an ad break begins.
- Deprecated:
- Yes
Returns:
The Player API instance.
- Type
- Api
getAdBlock() → {boolean}
Checks for the presence of an ad blocker. Implemented by jwplayer-commercial.
Returns:
Was an ad blocker is detected?
- Type
- boolean
getAudioTracks() → {Array.<AudioTrackOption>}
Gets the list of available audio tracks.
Returns:
An array of AudioTrackOption objects representing the current media's audio tracks.
- 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:
The captions styling configuration
- 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:
An array of CaptionsTrackOption objects.
- Type
- Array.<CaptionsTrackOption>
getConfig() → {object}
Gets a static representation of the player's model.
Returns:
A copy of the player model.
- Type
- object
getContainer() → {HTMLElement}
Gets the player's top level DOM element.
Returns:
The player's div container.
- Type
- HTMLElement
getControls() → {boolean}
Gets whether or not controls are enabled.
Returns:
Are controls enabled?
- 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:
The index of the active quality level.
- Type
- number
getCurrentTime() → {number}
Gets the current value for video.currentTime
Returns:
The value for video.currentTime in seconds
- 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:
The merged result of the current playlist item's "meta" events.
- 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:
An array of PlaylistItem objects.
- Type
- Array.<PlaylistItem>
getPlaylistIndex() → {number}
Gets the index of the current playlist item.
Returns:
The index of the current playlist item.
- 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:
An object containing the name of the current playback provider.
- Type
- ProviderInfo
getQualityLevels() → {Array.<QualityOption>}
Gets the list of available quality options.
Returns:
An array of QualityOption objects.
- 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:
The SafeRegion calculated using the player's current width, height and controlbar when not excluded.
- 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:
The current stretch mode.
- 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:
The last VisualQuality object returned for the current playlist item.
- 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 triggered the "complete" event or began the next item. This state is entered when playing postroll ads.
Returns:
Is the "beforeComplete" event being propagated or interrupted by instream?
- Type
- boolean
isBeforePlay() → {boolean}
Checks if playback has been requested, but not yet attempted. This state is entered when playing preroll ads.
Returns:
Is the "beforePlay" event being propagated or interrupted by instream?
- 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:
The Player API instance.
- 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:
The Player API instance.
- 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:
The Player API instance.
- 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:
The Player API instance.
- 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:
The Player API instance.
- Type
- Api
pause(metaopt) → {Api}
Pauses playback.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
meta |
object |
<optional> |
An optional argument used to specify cause. |
Returns:
The Player API instance.
- Type
- Api
pauseAd(toggle) → {void}
Pauses or toggles ad playback. Implemented by ad plugins.
Parameters:
| Name | Type | Description |
|---|---|---|
toggle |
boolean | Specifies whether ad playback should be paused or resumed. |
Returns:
- Type
- void
play(metaopt) → {Api}
Starts playback.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
meta |
object |
<optional> |
An optional argument used to specify cause. |
Returns:
The Player API instance.
- Type
- Api
playAd(adBreak) → {void}
Plays an ad. Implemented by ad plugins.
Parameters:
| Name | Type | Description |
|---|---|---|
adBreak |
string | Array | The ad tag or waterfall array. |
Returns:
- Type
- void
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 |
object |
<optional> |
An optional argument used to specify cause. |
Returns:
The Player API instance.
- 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 |
object |
<optional> |
An optional argument used to specify cause. |
Returns:
The Player API instance.
- 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 |
object |
<optional> |
An optional argument used to specify cause. |
Returns:
The Player API instance.
- 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:
The Player API instance.
- Type
- Api
qoe() → {PlayerQoE}
Gets the QoE properties of the player and current playlist item.
Returns:
An object containing a snapshot of QoE metrics.
- Type
- PlayerQoE
registerPlugin(name, minimumVersion, pluginClass) → {void}
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. |
Returns:
- Type
- void
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:
The Player API instance
- 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:
The Player API instance.
- 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:
The Player API instance.
- 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 |
object |
<optional> |
An optional argument used to specify cause. |
Returns:
The Player API instance.
- Type
- Api
setCaptions(captionsStyles) → {Api}
Sets captions styles.
Parameters:
| Name | Type | Description |
|---|---|---|
captionsStyles |
object | The captions styling configuration to apply. |
- Since:
- v7.5.0
Returns:
The Player API instance.
- Type
- Api
setConfig(options) → {Api}
Updates the player's config options.
Parameters:
| Name | Type | Description |
|---|---|---|
options |
object | The configuration options to update. |
- Since:
- v7.12.0
Returns:
The Player API instance.
- 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:
The Player API instance.
- 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:
The Player API instance.
- Type
- Api
setCurrentAudioTrack(index) → {void}
Sets the active audio track.
Parameters:
| Name | Type | Description |
|---|---|---|
index |
number | The index of the audio track to select. |
Returns:
- Type
- void
setCurrentCaptions(index) → {void}
Sets the active captions option.
Parameters:
| Name | Type | Description |
|---|---|---|
index |
number | The index of the captions option to select. |
Returns:
- Type
- void
setCurrentQuality(index) → {void}
Sets the active quality option.
Parameters:
| Name | Type | Description |
|---|---|---|
index |
number | The index of the quality level to select. |
Returns:
- Type
- void
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:
The Player API instance.
- 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:
The Player API instance.
- 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:
The Player API instance.
- 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:
The Player API instance
- Type
- Api
setVolume(level) → {Api}
Set the player's volume level.
Parameters:
| Name | Type | Description |
|---|---|---|
level |
number | A value from 0-100. |
Returns:
The Player API instance.
- Type
- Api
skipAd() → {Api}
Calls skipAd on the active instream adapter instance if present.
Returns:
The Player API instance.
- Type
- Api
stop() → {Api}
Stops any active playback.
Returns:
The Player API instance.
- 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:
The Player API instance.
- Type
- Api