Reference (Web Player)

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.

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

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)

Event listening with the JWP API

Certain events are triggered when the player does something. JWP 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, JWP events support the following event triggers:

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 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:

<div id="myElement">Loading the player...</div>

<script type='text/javascript'>
  jwplayer("myElement").setup({
    playlist: "https://cdn.jwplayer.com/v2/playlists/xxxxYYYY"
  });
</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({
    playlist: "https://cdn.jwplayer.com/v2/playlists/xxxxYYYY"
  });

  jwplayer("mySecondPlayer").setup({
    playlist: "https://cdn.jwplayer.com/v2/playlists/xxxxYYY2"
  });
</script>

There are two ways that we can target a player.

📘

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

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.

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

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.