This article explains the basics of how to use the JavaScript API component of JWP. This API can be used to enhance the functionality of your video embeds or to implement rich page-level video interactions. Unless noted, there are no differences between HTML5 and Flash API calls, so the code you write will work across multiple technologies.



We strongly suggest that all API calls be made after the player is considered ready.

<br /> <hr />

## Get information with the JWP API

Certain API calls utilize a "get" prefix, which signifies that their express purpose is to return certain information. This may be in the form of an object, an array, a string, or a number. Each API call will have the expected output format listed in the full [JavaScript API Reference](🔗).

`GET` API calls can return information like:

  • An array of playlist items with `jwplayer().getPlaylist()`

  • The duration of a video with `jwplayer().getDuration()`

  • The current playback state of the video player with `jwplayer().getState()`

  • The current pixel dimensions of a JWP with `jwplayer().getHeight()` and `jwplayer().getWidth()`

<br /> <hr />

## Control and set with the JWP API

These types of API calls are used to control player behavior. Many of these calls expect a value to be passed along with it. For example, `setVolume()` expects a number from 1-100 to be included.

API calls can tell the player to do things like:

  • Pause playback with `jwplayer().pause(true)`

  • Set volume to 50% with `jwplayer().setVolume(50)`

  • Seek to 2 minutes into a video with `jwplayer().seek(120)`

<br /> <hr />

## Event listening with the JWP API

Certain events are triggered when the player _does_ something. JWP 8 bases its event structure on <a href="http://backbonejs.org/#Events" target="_blank">backbone.events</a>. This allows a player instance to be used as an event router and gives developers better options and control. Certain events also return information. We list this expected information in the full [JavaScript API Reference](🔗) document.

Currently, JWP events support the following event triggers:

ListenerDescriptionExample
on(_'event'_)Using an _on_ listener will continually listen for an event for a specified player. If this player is removed and set up again, the listener will also need to be reinstated.jwplayer().on(event, [callback], [context])
off(_'event'_)Signifies to stop listening for a particular eventjwplayer().off(event, [callback], [context])
once(_'event'_)Behaves similarly to on, however will only trigger for a single event, until it is set up again.jwplayer().once(event, [callback], [context])
trigger(_'event'_)Capable of firing events to a listener.jwplayer().trigger(event, [*args])

The below event triggers every time a volume change is initiated and will return a number called "volume" within an object.



<br /> <hr />

## Example: Using the JWP API

Before it is possible to interact with a player, a player setup is required. Here is the proper syntax for a basic player embed:



Once the player completes its setup, API calls can immediately be made. If you have one player on your page, it can always be accessed using the **playerInstance** reference function. For example:



<br /> <hr />

## Targeting multiple players

When you have multiple players on a page, you must be specific about which player you want to interact with. Let's assume that we have embedded two different players on the same page:



There are two ways that we can target a player.

ApproachDescription
By `<div id>`ID references the first player<br /><br />`jwplayer("myFirstPlayer").play();`
By indexAn index of 1 targets the _second_ player on the page<br /><br />`jwplayer(1).play();`



Not including an ID or index with your API call will always target the first player on a page.

<hr />

## Require.js and JWP

JWP is not currently supported within require js due to JWP needing to use jwplayer namespace. To avoid issues when require and jwplayer.js are on the same page, load jwplayer.js before the require.js script is loaded.



<br /> <hr />

## Cheat Sheet Reference

The table below acts as a cheat sheet of all API calls. The separate [JavaScript API Reference](🔗) guide contains a listing of all parameters for all API calls. Click on the name of a class in the table to jump to the corresponding section in the API Reference. Also, for the sake of simplicity, we are only referencing **on** events here. As mentioned above, these can also utilize **off**, **once**, and **trigger**.

ClassGettersSettersEvents
[Setup](🔗)getRenderingMode()setup()<br />remove()on('ready')<br />on('setupError')
[Playlist](🔗)getPlaylist()<br />getPlaylistIndex()<br />getPlaylistItem()load()<br />playlistItem()on('playlist')<br />on('playlistItem')<br />on('playlistComplete')
[Buffer](🔗)getBuffer()-on('bufferChange')
[Playback](🔗)getState()play()<br />pause()<br />stop()on('play')<br />on('pause')<br />on('buffer')<br />on('idle')<br />on('complete')<br />on('error')
[Seek](🔗)getPosition()<br />getDuration()seek()on('seek')<br />on('seeked')<br />on('time')
[Volume](🔗)getMute()<br />getVolume()setMute()<br />setVolume()on('mute')<br />on('volume')
[Resize](🔗)getWidth()<br />getHeight()<br />getFullscreen()resize()on('fullscreen')<br />on('resize')
[Quality](🔗)getQualityLevels()<br />getCurrentQuality()setCurrentQuality()on('levels')<br />on('levelsChanged')
[Captions](🔗)getCaptionsList()<br />getCurrentCaptions()setCurrentCaptions()on('captionsList')<br />on('captionsChange')
[Controls](🔗)getControls()<br />getSafeRegion()addButton()<br />removeButton()<br/>setControls()on('controls')<br />on('displayClick')
[Advertising](🔗)-playAd()on('adClick')<br />on('adCompanions')<br />on('adComplete')<br />on('adError')<br />on('adImpression')<br />on('adTime')<br />on('adSkipped')<br />on('beforePlay')<br />on('beforeComplete')
[Metadata](🔗)--on('meta')
[Sharing](🔗)-getPlugin('sharing').open()<br />getPlugin('sharing').close()getPlugin('sharing').on('open')<br />getPlugin('sharing').on('close')<br />getPlugin('sharing').on('click')
[Related](🔗)-getPlugin('related').open()<br />getPlugin('related').close()getPlugin('related').on('open')<br />getPlugin('related').on('close')<br />getPlugin('related').on('play')

<br />

<!-- Removes the automatic page-to-page navigation at the bottom of the page -->

<style> .rm-Pagination { display: none; } </style>