JavaScript API Reference

This article provides a reference to all the JW Player 6 JavaScript API calls available. For an introduction to using the player API see the JavaScript API Quick Start.


Table Of Contents

Setup

These API calls are used to setup players and learn when and with which technology players are instantiated.

getRenderingMode()
Returns the rendering mode in which the player is setup. Can be flash or html5.
setup(options)
Setup a new JW Player. The options parameter is required and in the form of an Object. The options block in turn always needs a file property. Without a file to play, JW Player instances cannot be setup. See the Configuration Options Reference for a 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.
onReady(callback)
Fired when the player has initialized in either Flash or HTML5 and is ready for playback. Has no attributes.
onSetupError(callback)
Fired when neither the Flash nor HTML5 player could be setup. Event attributes:
  • fallback (Boolean): This is set true when a download fallback is rendered instead of just an error message.
  • message (String): The error message that describes why the player could not be setup

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.

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.
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, pointing to the location of an RSS feed.
For example, here's a simple call that loads a playlist with one item, with one source:
jwplayer().load([{file:"/assets/myVideo.mp4"}]);
playlistItem(index)
Start playback of the playlist item at the specified index.
onPlaylist(callback)
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 onReady is called). Event attributes:
  • playlist (Array): The new playlist; an array of playlist items.
onPlaylistItem(callback)
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.
onPlaylistComplete(callback)
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's buffered into the player. This only applies to progressive downloads of media (MP4/FLV/WebM and AAC/MP3/Vorbis); streaming media (HLS/RTMP/YouTube) do not expose this behavior.

getBuffer()
Returns the current PlaylistItem's filled buffer, as a percentage (0 to 100) of the total video's length.
onBufferChange(callback)
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: is the player idle, buffering, playing or paused.

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.
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.
onPlay(callback)
Fired when the player enters the PLAYING state. Event attributes:
  • oldstate (String): the state the player moved from. Can be BUFFERING or PAUSED.
onPause(callback)
Fired when the player enters the PAUSED state. Event attributes:
  • oldstate (String): the state the player moved from. Can be BUFFERING or PLAYING.
onBuffer(callback)
Fired when the player enters the BUFFERING state. Event attributes:
  • oldstate (String): the state the player moved from. Can be IDLE, PLAYING or PAUSED.
onIdle(callback)
Fired when the player enters the IDLE state. Event attributes:
  • oldstate (String): the state the player moved from. Can be BUFFERING, PLAYING or PAUSED.
onComplete(callback)
Fired when an item completes playback. It has no event attributes.
onError(callback)
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 onSetupError (see above) to catch these errors.


Seek

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

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.
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.
onSeek(callback)
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.
onTime(callback)
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.

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.
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.
onMute(callback)
Fired when the player has gone into or out of the mute state. Event attributes:
  • mute (Boolean): New mute state.
onVolume(callback)
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.

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.
resize(width, height)
Resizes the player to the specified width and height, in pixels. It's also possible to set percentages (e.g. 50%).
onFullscreen(callback)
Fired when the player toggles to/from fullscreen. Event attributes:
  • fullscreen (Boolean): new fullscreen state.
onResize(callback)
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.

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.
setCurrentQuality(index)
Change the quality level to the provided index. The index must be within the list provided by getQualityLevels.
onQualityLevels(callback)
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.
onQualityChange (callback)
Fired when the active quality level is changed. Happens in respons 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.

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.

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.
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.
onCaptionsList(callback)
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.
onCaptionsChange (callback)
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.

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 }
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(controls)
Enable the built-in controls by setting them true, disable the controls by setting them false.
onControls(callback)
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.
onDisplayClick(callback)
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 Enterprise edition of JW Player. For VAST advertising, this API allows impression verification, custom scheduling, tag waterfalling and multiple companions. For IMA, this API allows inserting multiple companions (through onAdCompanions), while the other ad API calls are only available for VAST.

playAd(tag)
VAST only (no 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 playlists). 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.
onAdClick(callback)
VAST and IM). 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.
onAdCompanions(callback)
VAST and IMA. Fired whenever an ad contains companions. Event attributes:
  • tag (String): The ad tag that is currently playing.
  • companions (Array): An array with 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.
onAdComplete(callback)
VAST and IMA. Fired whenever an ad has completed playback. Event attributes:
  • tag (String): The ad tag that is currently playing.
onAdSkipped(callback)
VAST and IMA. Fired whenever an ad has been skipped. Event attributes:
  • tag (String): The ad tag that was skipped.
onAdError(callback)
VAST and IMA. Fired whenever an error prevents the ad from playing. 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 chasing the wrappers)
  3. no compatible creatives (e.g. only FLV video in HTML5)
  4. error playing creative (e.g. a 404 on the MP4 video)
  5. error loading ad tag (for all else)
onAdImpression(callback)
VAST and IMA. Fired whenever an ad starts playing back. At this point, the VAST tag is loaded and the creative selected. Event attributes:
  • tag (String): The ad tag that is currently playing.
onAdTime(callback)
VAST and IMA. Fired while ad playback is in progress. Event attributes:
  • tag (String): The ad tag that is currently playing.
  • position (Number): The current playback position in the ad creative.
  • duration (Number): The total duration of the ad creative.
onBeforePlay(callback)
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.
onBeforeComplete(callback)
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.

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!

onMeta(callback)
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