JavaScript API Reference

This article provides a reference to all available JW Player JavaScript API calls. API calls below are grouped together in a logical way, while breaking each section into Getters, Setters, Events, and Miscellaneous.

Table Of Contents

Also, note that all Events below are using the on listener, however it is also possible to register or remove each event with on, once, or off. The use of trigger may also be used for custom events. For an introduction to JW7's API, see the JavaScript API Quick Start.

Note that this document is a reference for the JW Player 7 API, which has changed substantially since JW6. Existing JW6 event listeners will continue working with JW7, though we do suggest updating them to this newer model. For the JW6 API, see our JW6 Javascript Reference







 

All

.on('all')
This singular API call can be used to gather all information from the player's API. Note: This will output a large amount of information and may degrade browser performance if it is used for an extended period of time.

Setup

These API calls are used to set up players and learn when and with which technology is being instantiated. Both setup() and remove() fall under Miscellaneous due to the fact that they are not actually setting, but are rather building and removing players.

Miscellaneous

.setup(options)
Set up a new JW Player. The options parameter is required and must be in the form of an object. The only required property when setting up a JW Player embed is the file property. Without a file to play, JW Player cannot function. See the Configuration Options Reference for a full list of all JW Player configuration options.
.remove()
Being the reverse of the setup() call, this call will remove a JW Player from the page. It ensures the player stops playback, the DOM is re-set to its original state and all event listeners and timers are cleaned up. Any listeners will need to be reinstantiated if another player is set up.

Getters

.getProvider()
Returns the provider being utilized by JW Player for a particular media file. This replaces JW6's getRenderingMode(), as JW7 will always technically render in html5 mode, even if it is using a flash-based provider.
.getContainer()
Returns the div which JW Player is being set up. This includes the ID and all styles/classes being applied.

Events

.on('ready')
Fired when the player has initialized in either Flash or HTML5 and is ready for playback.
  • setupTime (Number): The amount of time (in milliseconds) for the player to go from setup() to ready.
.on('setupError')
Fired when neither the Flash nor HTML5 player could be setup. Event attributes:
  • message (String): The error message that describes why the player could not be setup
.on('remove')
Triggered when the player is taken off of a page via remove().

Playlist

These API calls are used for loading and retrieving the current playlist (of one or more items), as well as for navigating between playlist items.

The data model of a playlists is as follows:

  • The playlist is an Array, containing one or more playlist items.
  • Each item is an Object, containing the title (String), description (String), mediaid (String), image (String), sources (Array) and tracks (Array) properties.
  • The sources Array in turn contain a list of Objects, each with a file, type, label and default property.
  • The tracks Array in turn contain a list of Objects, each with a file, kind and default property.

Additionally, each playlist item has a file property, which acts as a shortcut to the file of the first entry in the sources Array. This shortcut makes it easier to do basic playlist loading or fetching, since most publishers will setup their playlist items with one file only.

See the Configurations Options Reference for a description of each property and some example playlists.

Getters

.getPlaylist()
Returns the player's current playlist array.
.getPlaylistIndex()
Returns the index of the currently active item in the playlist.
.getPlaylistItem(index)
Returns the playlist item object at the specified index. If the index is not specified, the currently playing playlistItem is returned.

Setters

.load(playlist)
Loads a new playlist into the player. The playlist parameter is required and can be either:
  • An Array, containing playlist items.
  • A String, referencing the location of an RSS feed/XML file.
For example, here's a simple call that loads a playlist with one item, with one source:
playerInstance.load([{file:"/assets/myVideo.mp4"}]);
.playlistItem(index)
Start playback of the playlist item at the specified index.

Events

.on('playlist')
Fired when a new playlist has been loaded into the player. Note this event is not fired as part of the initial playlist load (playlist is loaded when on('ready') is called). Event attributes:
  • playlist (Array): The new playlist; an array of playlist items.
.on('playlistItem')
Fired when the playlist index changes to a new playlist item. This event occurs before the player begins playing the new playlist item. Event attributes:
  • index (Number): Zero-based index into the playlist array (e.g. 0 is the first item).
  • playlist (Array): The new playlist; an array of playlist items.
.on('playlistComplete')
Fired when the player is done playing all items in the playlist. However, if the repeat option is set true, this is never fired.

Buffer

These API calls are used to update clients with the percentage of a file that is buffered into the player. This only applies to progressive downloads of media (MP4/FLV/WebM and AAC/MP3/Vorbis); streaming media (HLS/RTMP/YouTube/DASH) do not expose this behavior.

Getters

.getBuffer()
Returns the current PlaylistItem's filled buffer, as a percentage (0 to 100) of the total video's length.

Events

.on('bufferChange')
Fired when the currently playing item loads additional data into its buffer. Event attributes:
  • buffer (Number): Percentage between 0 and 100 of the current media that is buffered.

Playback

These API calls are used to retrieve and change the current playback state of the player. Playback controllers are listed under Miscellaneous, as they directly control playback rather than the player state.

Note: JW7 will return playback states in lower case. If you are using JW6, states will be returned in all capital letters. We suggest using toUpperCase() if this affects your API setup.

Miscellaneous

.play(state)
Toggles playback of the player. If the state is set true the player will start playing, if set false the player will pause and if omitted, the player will toggle playback.
.pause(state)
Toggles playback of the player. If the state is set true the player will pause, if set false the player will start playing and if omitted, the player will toggle playback.
.stop()
Stops the player (returning it to the idle state) and unloads the currently playing media file.

Getters

.getState()
Returns the player's current playback state. These can be:
  • idle: either playback has not started or playback was stopped (due to a stop() call or an error). Either the play or the error icon is visible in the display.
  • buffering: user pressed play, but sufficient data to start playback has to be loaded first. The buffering icon is visible in the display.
  • playing: the video is currently playing. No icon is visible in the display.
  • paused: the video is currently paused. The play icon is visible in the display.

Events

.on('play')
Fired when the player enters the playing state. Event attributes:
  • oldstate (String): the state the player moved from. Can be buffering or paused.
.on('pause')
Fired when the player enters the paused state. Event attributes:
  • oldstate (String): the state the player moved from. Can be buffering or playing.
.on('buffer')
Fired when the player enters the buffering state. Event attributes:
  • newstate (String): The state the player moved to. Can be buffering, playing or paused.
  • oldstate (String): The state the player moved from. Can be idle, playing or paused.
  • reason (String): The reason why a buffer event occurred. Can be loading, complete, stalled, or error.
.on('idle')
Fired when the player enters the idle state. Event attributes:
  • oldstate (String): the state the player moved from. Can be buffering, playing or paused.
.on('complete')
Fired when an item completes playback. It has no event attributes.

.on('playAttempt')
Useful for QOE tracking - Triggered the instant a user attempts to play a file. This event fires before both the on('play') and on('beforePlay') events.

.on('firstFrame')
Useful for QOE tracking - Triggered by a video's first frame event (Or the instant an audio file begins playback). This event pinpoints when content playback begins.
  • loadTime (Number): The amount of time (In milliseconds) it takes for the player to transition from a playAttempt to a firstFrame event. Use this to determine the period of time between a user pressing play and the same user viewing their content.
.on('error')
Fired when a media error has occurred, causing the player to stop playback and go into idle mode. Event attributes:

Note: A media error event is not fired when a player setup error occurs. Use on('setupError') (see above) to catch these errors.


Seek

These API calls are used to retrieve and update the current media playback position.

Getters

.getPosition()
Returns the current playback position in seconds, as a number.
.getDuration()
Returns the currently playing PlaylistItem's duration in seconds, as a number. If a duration of -1 is returned, the current media is a live stream and therefore has no position, duration or seek capability.

Setters

.seek(position)
Jump to the specified position within the currently playing item. The position is required and must be provided as an integer, in seconds.

Events

.on('seek')
Fired after a seek has been requested either by scrubbing the controlbar or through the API. Event attributes:
  • position (Number): The position of the player before the player seeks (in seconds).
  • offset (Number): The user requested position to seek to (in seconds). Note the actual position the player will eventually seek to may differ, e.g. because Flash progressive can only seek to keyframes and HLS can only seek to fragment boundaries.
.on('seeked')
Triggered when content playback resumes after seeking. As opposed to on('seek'), this API listener will only trigger when playback actually continues.
.on('time')
While the player is playing, this event is fired as the playback position gets updated. This may occur as frequently as 10 times per second. Event attributes:
  • duration (Number): Duration of the current item in seconds.
  • position (Number): Playback position in seconds.

Note that seeking for progressive downloads in Flash mode only works within the already downloaded portion. When seeking beyond that section, the video seeks to the last downloaded frame. This issue is not present for HTML5, so should only be relevant for IE8.


Volume

These API calls are used to change the playback volume of the player. Note they only work on desktop browsers, not on mobile devices.

Getters

.getMute()
Returns the player's current audio muting state (true when there's no sound).
.getVolume()
Returns the current playback volume percentage, as a number from 0 to 100.

Setters

.setMute(state)
Change the player's mute state (no sound). If the state is undefined, perform a muting toggle. Otherwise, mute the player if true, and unmute if false.
.setVolume(volume)
Sets the player's audio volume percentage, as a number between 0 and 100.

Events

.on('mute')
Fired when the player has gone into or out of the mute state. Event attributes:
  • mute (Boolean): New mute state.
.on('volume')
Fired when the player audio volume percentage was changed. Event attributes:
  • volume (Number): New volume percentage.

Resize

These API calls are used to retrieve and update the current player dimensions and fullscreen state. Note there is no API call to set fullscreen, due to phishing-related security restrictions in both Flash and HTML5.

Getters

.getFullscreen()
Returns the current fullscreen state (true or false).
.getHeight()
Returns the player's current height, in pixels.
.getWidth()
Returns the player's current width, in pixels.

Setters

.resize(width, height)
Resizes the player to the specified width and height, in pixels. It's also possible to set percentages (e.g. 50%).

Events

.on('fullscreen')
Fired when the player toggles to/from fullscreen. Event attributes:
  • fullscreen (Boolean): new fullscreen state.
.on('resize')
Fired when the player's on-page dimensions have changed. Is not fired in response to a fullscreen change. Event attributes:
  • width (Number): The new width of the player.
  • height (Number): The new height of the player.

Quality

These API calls are used to listen to or update the video quality if multiple quality levels of a video are provided.

Getters

.getQualityLevels()
Returns an array with quality levels from the player. Each level is an object that contains a label property.
.getCurrentQuality()
Returns the index of the currently active quality level.
.getVisualQuality()
Returns information about the currently playing quality. This will include label, bitrate, index, and resolution, as well as the reasons that this quality was selected.

Setters

.setCurrentQuality(index)
Change the quality level to the provided index. The index must be within the list provided by getQualityLevels().

Events

.on('levels')
Fired when the list of available quality levels is updated. Happens e.g. shortly after a playlist item starts playing. Event attributes:
  • levels (Array): the full array with new quality levels.
.on('levelsChanged')
Fired when the active quality level is changed. Happens in response to e.g. a user clicking the controlbar quality menu or a script calling setCurrentQuality. Event attributes:
  • currentQuality (Number): index of the new quality level in the getQualityLevels() array.
.on('visualQuality')
Fired when the active quality level is changed for HLS. This is different than on('qualityChange') since this will trigger when adaptive streaming automatically shifts quality. In addition, this will also provide reasons why this change happened, as well as information about how and why this change was triggered. Event attributes:
  • mode (String): The type of quality selection that has been enabled with the player. This will read auto when a user is relying on our automatic quality determination or manual when a user has selected a static quality.
  • reason (String): Why the quality was changed. This can be initial choice
  • label (String): Information about the quality that was changed. This will display your label, bitrate, index, and resolution. This returns the same information as getVisualQuality().

Audio Tracks API

These API calls are used to listen to or update the audio track if multiple audio tracks of a video are provided.

Getters

.getAudioTracks()
Returns an array with audio tracks from the player. Each track is an object that contains a label property.
.getCurrentAudioTrack()
Returns the index of the currently active audio track.

Setters

.setCurrentAudioTrack(index)
Change the audio track to the provided index. The index must be within the list provided by getAudioTracks.

Events

.on('audioTracks')
Fired when the list of available audio tracks is updated. Happens e.g. shortly after a playlist item starts playing. Event attributes:
  • levels (Array): the full array with new quality levels.
.on('audioTrackChange')
Fired when the active audio track is changed. Happens in repsponse to e.g. a user clicking the audio tracks menu or a script calling setCurrentAudioTrack(). Event attributes:
  • currentTrack (Number): index of the new quality level in the getAudioTracks() array.

Captions

These API calls are used to listen to or update the active captions track if one or more closed captions tracks are provided with a video. This API can be used to log captions usage or build your own CC menu outside JW Player.

Getters

.getCaptionsList()
Returns an array with captions tracks from the player. Each track is an object that contains a label property.
.getCurrentCaptions()
Returns the index of the currently active captions track. Note the captions are Off if the index is 0.

Setters

.setCurrentCaptions(index)
Change the visible captions track to the provided index. The index must be within the list provided by getCaptionsList. Note an index of 0 always turns the captions Off.

Events

.on('captionsList')
Fired when the list of available captions tracks is updated. Happens shortly after a playlist item starts playing. Event attributes:
  • tracks (Array): the full array with new captions tracks.
.on('captionsChange')
Fired when the active captions track is changed. Happens in respons to e.g. a user clicking the controlbar CC menu or a script calling setCurrentCaptions(). Event attributes:
  • track (Number): index of the new active captions track in the getCaptionsList() array. Note the captions are Off if the track is 0.

Controls

This API call allows developers to interact with the built-in player controls (dock buttons, controlbar and display icons). Note that enabled controls will still fade out during playback if the video has no keyboard/mouse focus. When controls are disabled, JW Player is completely chrome-less.

Getters

.getControls()
Returns whether the built-in controls are currently enabled.
.getSafeRegion()
Returns an array with the region of the display not used by the controls. Scripts and plugins use this information to ensure their visual assets don't overlap with the controls. An example region the call can return is:
{ x:0, y:30, width:480, height:200 }

Setters

.addButton(icon, label, handler, id)
Adds a button to the dock. Attributes:
  • icon (String): The URL to a GIF, JPG or PNG image that is displayed in the button. Monochromatic, white icons of about 20x20 pixels work well with many skins.
  • label (String): Human-readable label of the button (e.g. Buy this Video), visible in a tooltip on rollover.
  • handler (Function): The JavaScript function that is called when the button is clicked.
  • id (String): The string used to identify the button. It must be unique across all buttons (an error is thrown otherwise).
.removeButton(id)
Removes a button from the dock. Attributes:
  • id (String): The id used to identify the button when it was added.
.setControls(Boolean)
Enable the built-in controls by setting them true, disable the controls by setting them false.

Events

.on('controls')
Fired when controls are enabled or disabled by a script. Event attributes:
  • controls (Boolean): New state of the controls. Is true when the controls were just enabled.
.on('displayClick')
Fired when a user clicks the video display. Especially useful for wiring your own controls when the built-in ones are disabled. Note the default click action (toggling play/pause) will still occur if controls are enabled. There are no event attributes.

Advertising

This API provides developers with more control over the advertising functionality of the Advertising edition of JW Player. For VAST and IMA advertising plugins, this API allows impression verification, custom scheduling, tag waterfalling and multiple companions.

Setters

.playAd(tag)
VAST and IMA. Used to play an ad right now, which is primarily useful for situations where the built-in ad schedule of JW Player cannot be used.(e.g. for live streaming or dynamic ads for playlist items) It has a single attribute:
  • tag (String): The VAST tag that should be loaded into the player.

We recommend to only call playAd in one of these four situations:

  1. inside a JW Player event handler for onBeforePlay(), to trigger a pre-roll.
  2. inside a JW Player event handler for onTime(), to trigger a mid-roll.
  3. inside a event handler for onBeforeComplete(), to trigger a post-roll.
  4. Outside of event handlers, only when the player is in the playing state.

Events

.on('beforePlay')
Fired just before the player begins playing. Unlike the onPlay event, the player will not have begun playing or buffering when triggered, which makes this the right moment to insert preroll ads using playAd(). It has no event attributes.
.on('beforeComplete')
Fired just before the player completes playing. Unlike the onComplete event, the player will not have moved on to either showing the replay screen or advancing to the next playlistItem, which makes this the right moment to insert post-roll ads using playAd(). It has no event attributes.
.on('adClick')
VAST and IMA. Fired whenever a user clicks an ad to be redirected to its landing page. Event attributes:
  • tag (String): The ad tag that is currently playing.
.on('adCompanions')
VAST and IMA. Fired whenever an ad contains companions. Event attributes:
  • tag (String): The ad tag that is currently playing.
  • companions (Array): An array of all companions that were encountered.

Every item in the companions element in turn has the following attributes:

  1. width (Number): width of the companion in pixels.
  2. height (Number): height of the companion in pixels.
  3. type (String): one of static, html or iframe.
  4. resource (String): Depending upon the type, this is the URL to the static/iframe resource, or the raw HTML content.
  5. click (String): URL to link to when clicking the companion. Only available if the type is static.
.on('adComplete')
VAST and IMA. Fired whenever an ad has completed playback. Event attributes:
  • tag (String): The ad tag that is currently playing.
.on('adSkipped')
VAST and IMA. Fired whenever an ad has been skipped. Event attributes:
  • tag (String): The ad tag that was skipped.
.on('adError')
VAST and IMA. Fired whenever an error prevents the ad from playing. Note: Based on how Google's SDK operates, this event may fire multiple times for a single tag if Google IMA is being used. If you are using onAdError to track errors with Google IMA, this should be taken into account.
Event attributes:
  • tag (String): The ad tag that is currently playing.
  • message (String): The error message.

The following error messages are possible:

  1. invalid ad tag (e.g. invalid XML, broken VAST)
  2. ad tag empty (e.g. no ad available after playing through wrapped ads)
  3. no compatible creatives (e.g. FLV video creative in HTML5)
  4. error playing creative (e.g. a 404 on the MP4 video)
  5. error loading ad tag (for all else)
.on('adRequest')
VAST only. Fired whenever an ad is requested by the player. Event attributes:
  • tag (String): The ad tag that is being requested.
  • adposition (String): Whether an ad is in a pre, mid, or post position.
.on('adImpression')
VAST and IMA. Fired based on the IAB definition of an ad impression. This occurs the instant a video ad begins to play. Event attributes:
  • tag (String): The ad tag that is currently playing.
  • creativetype (String): The type of ad that is being played.
  • adposition (String): Defines if an ad called in a pre, mid, or post position
.on('adTime')
VAST and IMA. Fired while ad playback is in progress. Event attributes:
  • tag (String): The ad tag that is currently playing.
  • position (String): The current playback position in the ad creative.
  • duration (Number): The total duration of the ad creative.
  • sequence (Number): Returns the sequence number the ad is a part of.
.on('adPause')
VAST and IMA. Fired whenever an ad is paused. Event attributes:
  • tag (String): The ad tag that is currently playing.
.on('adPlay')
VAST and IMA. Fired whenever an ad starts playing. Will fire after an ad is unpaused. Event attributes:
  • tag (String): The ad tag that is currently playing.

Note this JavaScript API section includes examples on doing impression verification, custom scheduling, tag waterfalling and multiple companions with the Advertising API.


Metadata

This API call allows developers to listen for metadata embedded in the media file (e.g. dimensions or TX3G cues in MP4 files). It is intended debugging purposes. Do not rely on this API in production environments, since metadata callbacks are subject to sudden change!

Events

.on('meta')
Fired when new metadata has been broadcasted by the player. Event attributes:
  • metadata (Object): Object containing the new metadata. This can be metadata hidden in the media (XMP, ID3, keyframes) or metadata broadcasted by the playback provider (bandwidth, quality switches).
Please sign in to leave your feedback for this article.

Still don't have JW Player? Get It Here