JavaScript API Quick Start

This article explains how to use the JavaScript API component of JW Player 7. This API can be used to enhance the functionality of your video embeds and/or to implement rich video-page interactions. It abstracts any differences between Flash and HTML5, so the code you write will work with both technologies.

The JW Player 7's API has greatly changed since JW 6. In this guide, there are some updates regarding best practices, as well as configuration of our new event handling. If you are looking for JW 6's Javascript API documents, please see our Legacy API Guide.

API Best Practices with JW Player 7

We encourage developers to stop using the jwplayer() syntax, and instead keep a reference to the player instance. Based on how JW Player 7 is engineered, this will actually save a few ms of time during player setup. For example:

var playerInstance = jwplayer('container');
//jwplayer('container').pause(); // BAD! :(
playerInstance.pause(); // Good :)

Because of this update, all subsequent references to the player's API in our articles will assume that there is a variable called playerInstance which refers to your player instance.

JW7 API Event Handling

JW Player's Events, which previously always included an on prefix, are now four separate methods based on Backbone.Events. This allows a player instance to be used as an event router and gives developers better options and control.

Currently, JW Player events support:

 

on('event')
Behaves similarly to JW6's on___() handling. Will continually listen for an event.
playerInstance.on(event, [callback], [context])
off('event')
Allows a developer to toggle an on event listener to off.
playerInstance.off(event, [callback], [context])
once('event')
Behaves similarly to on, however will only trigger once, until it is set up again.
playerInstance.once(event, [callback], [context])
trigger('event')
Capable of firing events to a listener. This replaces dispatchEvent.
playerInstance.trigger(event, [*args])

A quick example of old syntax vs new syntax can be seen below:

Old JW6 Syntax:
playerInstance.onVolume(function(event){
console.log("Volume Changed");
});
	
New JW7 Syntax:
playerInstance.on('volume', function(event){
console.log("Volume Changed");
});
	

JW7 Event Handling Example

The below event triggers every time a volume change is initiated. As a result, Javascript will fire an alert dictating what the volume has been changed to.

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

Deprecated JW Player API Calls

  • dispatchEvent should no longer be used. It is replaced by trigger
  • removeEventListener should no longer be used. It is replaced by off
  • config will no longer work.

Getting Started

Before it is possible to interact with a player, a player setup is required. Our Embedding Section contains several examples. In accordance to our JW7 best practices, here is a basic player embed:

<div id='myElement'>Loading the player ...</div>
<script type='text/javascript'>
var playerInstance = jwplayer('myElement');
  playerInstance.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:

  <a onclick='playerInstance.play()'>Toggle playback</a>
  <a onclick='alert(playerInstance.getVolume())'>Report volume</a>

Here is the combination of setup code and API links in action:

 

Toggle playback | Report volume

Multiple Players

When you have multiple players on a page, you must be specific about which player you want to interact with. In that case, there are two ways to select a player:

  • With the id of the element you instantiated the player over:
    var firstInstance = jwplayer();
    firstInstance.play();
    
  • With the index in the list of players on the page (Top to bottom, starting with 0):
    var secondInstance = jwplayer(1);
    secondInstance.play();

    Note the selector jwplayer(0) is actually the same as jwplayer().

Setter and Getter API Calls

Now that we've explored the updated JW Player 7 event model, it's time to venture into getting and setting your player's configuration options. These API calls largely remain the same from JW6.

  • Getter - Provides a way to retrieve variables and information from the player. For example:
    playerInstance.getVolume();
    
    will return the player's current volume.

  • Setter - Refers to a way to set a player value. This can be similar to setting your player's volume, changing the player's dimensions, or controlling playback. For example:
    playerInstance.setVolume(80);
    
    will set your player's volume to 80.

Cheat Sheet

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('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('adSkip')
on('beforePlay')
on('beforeComplete')
Metadata     on('meta')
Please sign in to leave your feedback for this article.

Still don't have JW Player? Get It Here