Introduction to the Javascript API

This article explains the basics of how to use the JavaScript API component of JW Player. 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.

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


Getting Information with the JW Player 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 JW Player with jwplayer().getHeight() and jwplayer().getWidth()

Controlling and setting with the JW Player 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)

Event listening with the JW Player API

Certain events are triggered when the player does something. JW Player 8 bases its event structure on backbone.events. 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, JW Player events support the following event triggers:

Listener Description Example
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 event jwplayer().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. This replaces dispatchEvent from JW6. 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.

jwplayer().on('volume', function(e) {
alert("Volume is changed to: "+ e.volume);
});

Example: Using the JW Player API

Before it is possible to interact with a player, a player setup is required. Our Embedding Article contains several examples. Here is the proper syntax for a basic player embed:

<div id='myElement'>Loading the player...</div>
<script type='text/javascript'>
  jwplayer("myElement").setup({
    "file": "/uploads/example.mp4",
    "image": "/uploads/example.jpg"
  });
</script>

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:

<script>
jwplayer("myElement").on('complete', function(){
alert("Complete fired - Your content has completed!");
});
</script>

<a href="javascript:jwplayer('myElement').play();">Toggle playback</a>
<a href="javascript:alert('The volume of the player is: ' + jwplayer('myElement').getVolume());">Report volume</a>

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:

<div id='myFirstPlayer'>Loading the first player...</div>
<div id='mySecondPlayer'>Loading the player...</div>

<script type='text/javascript'>

jwplayer("myFirstPlayer").setup({
"file": "/uploads/example.mp4",
"image": "/uploads/example.jpg"
});

jwplayer("mySecondPlayer").setup({
"file": "/uploads/example2.mp4",
"image": "/uploads/example2.jpg"
});

</script>

There are two ways that we can target a player:

1 - Include the id of the player div:

// ID references the first player
jwplayer("myFirstPlayer").play();

2 - Include the index of player you wish to target

// An index of 1 targets the second player on the page
jwplayer(1).play();
Not including an ID or index with your API call will always target the first player on a page.

Require.js and JW Player

JW Player is not currently supported within require js due to JW Player 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.

Example:

<script src='jwplayer.js'>
<script src='requirejs.js'>

Cheat Sheet Reference

The table below act as a cheat sheet of all API calls. The separate JavaScript API Reference guide contains an 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.

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