JavaScript API reference

This article provides a reference to all available JW Player JavaScript API calls.

• For an introduction to JW8's API, read our JavaScript API overview.
• For more in-depth instructions on implementation, see read Add a web player to a site.
• To see example code for each API call, visit our JW Player Demos and search by call.

The events in this reference use the on listener; however, it is also possible to register or remove each event with on, once, or off, or register custom events with trigger.

The following timeline illustrates the core subset of events, in chronological order, that are fired by a player configured to play on-demand videos with captions, audio tracks, casting, and advertising. The event order and the events that fire may differ for players configured differently.

Happy coding!

Setup

These API calls are used to create players and provide setup information.

jwplayer( div ).setup( options )

Creates a new JW Player on your web page.

The only required option when setting up a JW Player embed is the file property. See the Configuration Options Reference for a full list of all JW Player configuration options.

Sample

<div id="myDiv">This text will be replaced with a player.</div>
<script>
jwplayer("myDiv").setup({
  "file": "http://example.com/myVideo.mp4",
  "image": "http://example.com/myImage.png",
  "height": 360,
  "width": 640
});
</script>

Clicking an HTML element can also instantiate and immediately begin playback. By calling setup() followed by play(), the user interaction on the element gets propagated through to the instantiated player. This eliminates the need to interact with the player to play media post setup.

jwplayer().remove()

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. Any event listeners will need to be re-instantiated if another player is set up.

jwplayer().setConfig()

Set one or more of the following video attributes after the player has already setup.

setConfig({
  "repeat": true,
  "autostart": "viewable",
  "mute": false,
  "volume": 25
});

jwplayer().getProvider()

Returns the provider being utilized by JW Player for a particular media file. JW Player will always technically render in HTML5 mode, even if it is using a Flash-based provider.

NOTE: As per Adobe, Flash Player is no longer supported.

Returns an object with the following:

List of possible providers:

jwplayer().getContainer()

Returns the entire HTML of the div in which a JW Player instance exists. This includes all IDs, styles, classes, and content.

jwplayer().getEnvironment()

📘

In JW8, we've removed our browser/OS inspection utils, is* (isChrome, isAndroid, etc.), and have replaced them with this Environment object.

Returns the browser and operating system information in which the player thinks it's in.

Sample

{
  "Browser": {
    "chrome": true,
    "edge": false,
    "facebook": false,
    "firefox": false,
    "ie": false,    // Used for IE 11+
    "msie": false,    // Used for IE 10 and below
    "safari": false,
    "version": {
      "version": "60.0.3112.113",
      "major": 60,
      "minor": 0
    }
  },
  "OS": {
    "android": false,   // Android Chrome
    "androidNative": false,   // Android native browser
    "iOS": false,
    "mobile": false,
    "mac": true,
    "iPad": false,
    "iPhone": false,
    "windows": false,
    "version": {
      "version": "10_12_6",
      "major": 10,
      "minor": 12
    }
  },
  "Features": {
    "flash": true,   // Does the browser environment support Flash?
    "flashVersion": 26,
    "iframe": false    // Is the session in an iframe?
  }
}

jwplayer().getPlugin()

Targets a particular plugin for API calls. Currently functions with our Sharing and Related plugins.

jwplayer().on('ready')

Signifies when the player has been initialized and is ready for playback. This is the earliest point at which any API calls should be made.

Returns an object with the following:

jwplayer().on('setupError')

Fired when neither the player could be set up.

Returns an object with the following:

jwplayer().on('remove')

Triggered when the player is taken off of a page via jwplayer().remove();

All

jwplayer().on('all')

This singular API call can be used to gather all events from the player's API.

🚧

WARNING

This will output a large amount of information and may degrade browser performance if it is used for an extended period of time.

Advertising

👍

IMPORTANT

Video ad insertion requires a JW Player Enterprise license. Please contact our team to upgrade your account.

This API provides developers with more control over the functionality of the Advertising edition of JW Player. For VAST and IMA plugins, this API allows for things like impression verification, custom scheduling, and multiple companions.

jwplayer().getAdBlock()

Used to determine whether or not the player is detecting the presence of an ad blocker.

jwplayer().pauseAd(state)

Used to pause or resume ad playback.

jwplayer().playAd(tag)

Used to play an ad immediately, which is primarily useful for situations where the built-in ad schedule of JW Player cannot be used. (e.g. for live streaming or dynamic ads for playlist items)

We recommend to call playAd() in one of these following situations:

• Inside a JW Player event handler for beforePlay() to trigger a pre-roll
• Inside a JW Player event handler for onTime() to trigger a mid-roll
• Inside an event handler for on('BeforeComplete') to trigger a post-roll
• Outside of event handlers, only when the player is in the playing state

📘

NOTE

playAd() is not supported when using Player Bidding due to the potential impact on performance and user experience while the player is waiting for the bidding process to complete.

playAd() is also not supported with ad preloading. Since calling playAd() immediately plays an ad, there is no time to preload an ad.

jwplayer().skipAd()

Used to skip the currently playing ad. This allows developers to create their own controls for skipping ads. Works with IMA, VAST, and FreeWheel ad clients.

📘

NOTE

If an advertising.skipoffset is configured for the currently playing ad, calling skipAd() will have no effect unless the advertising.skipoffset is reached.

For VPAID ads, the ability to skip the ad via skipAd() is dependent on whether the VPAID creative allows the ad to be skippable.

jwplayer().on('adBidRequest')

Fired when header bidding starts requesting for bids.

Returns an object with the following:

Each bidder object contains the following:

jwplayer().on('adBidResponse')

Fired when header bidding returns response.

Return an object with the following:

Bidder Object

Each bidder object contains the following:

jwplayer().on('adBlock')

This event is fired when an ad plugin (Either VAST or Google IMA) is configured inside of the JW Player setup, and an ad blocker is detected on a viewer's browser. It is then possible to request a user disable their ad blocker to proceed.

jwplayer().on('adBreakEnd')

Fires when control is passed back to the player from the ad.

Returns an object with the following:

jwplayer().on('adBreakIgnored')

(VAST only) Fires when the time elapsed between the previous fully-watched ad break and the current ad break is less than the value defined by advertising.rules.timeBetweenAds

Returns an object with the following content.

{
    "id": "adbreak2",
    "tag": "{ad_tag_url}",
    "offset": 6,
    "timeSinceLastAd": 3.256,
    "type": "adBreakIgnored"
}

jwplayer().on('adBreakStart')

Fires after the ad request and immediately before the ad is loaded into the player. Only fires before the first ad inside of an ad break.

Returns an object with the following:

jwplayer().on('adClick')

VAST and IMA. Fired whenever a user clicks an ad to be redirected to its landing page.

Returns an object with the following:

jwplayer().on('adCompanions')

VAST and IMA. Fired whenever an ad contains companions.

Returns an object with the following:

Every companion will return the following object:

jwplayer().on('adComplete')

Fired whenever an ad has completed playback.

Returns an object with the following:

jwplayer().on('adError')

Fired whenever an error prevents the ad from playing.

📘

NOTE

This may fire multiple times for a single ad tag if Google IMA is being used.

Returns an object with the following:

jwplayer().on('adImpression')

VAST, IMA. Fired based on the IAB definition of an ad impression. This occurs the instant a video ad begins to play.

Returns an object with the following:

jwplayer().on('adItem')

Fires when the VAST XML has been parsed, loaded, and is ready for display

Returns an object containing the following content:

{
    "client": "googima",
    "placement": 1,
    "viewable": 1,
    "adposition": "pre",
    "tag": "{ad_tag_url}",
    "adBreakId": "1a2b3c4d5e6f",
    "adPlayId": "1a2b3c4d5e6f",
    "id": "1a2b3c4d5e6f",
    "ima": {
        ...
    },
    "adtitle": "LinearInlineSkippable",
    "adsystem": "GDFP",
    "creativetype": "video/mp4",
    "duration": 10,
    "linear": "linear",
    "description": "LinearInlineSkippable ad",
    "creativeAdId": "",
    "adId": "123456789",
    "universalAdId": [{
        ...
    }],
    "advertiser": "",
    "dealId": "",
    "mediaFile": {
        "file": "{linear_ad_video_file_url}"
    },
    "type": "adItem"
}

{
    "client": "vast",
    "placement": 1,
    "adBreakId": "6f5e4d3c2b1a",
    "adPlayId": "6f5e4d3c2b1a",
    "offset": "pre",
    "item": {
        ...
    },
    "type": "adItem"
}

jwplayer().on('adLoaded')

Fires when the VAST XML has been parsed, loaded, and is ready for display

Returns an object containing the following content:

{
    "client": "googima",
    "placement": 1,
    "viewable": 1,
    "adposition": "pre",
    "tag": "{ad_tag_url}",
    "adBreakId": "1a3c2b4d5e6f",
    "adPlayId": "1a3c2b4d5e6f",
    "id": "1a3c2b4d5e6f",
    "ima": {
        ...
    },
    "adtitle": "",
    "adsystem": "GDFP",
    "creativetype": "video/mp4",
    "duration": 10,
    "linear": "linear",
    "description": "",
    "creativeAdId": "",
    "adId": "232859236",
    "universalAdId": [],
    "advertiser": "",
    "dealId": "",
    "mediaFile": {
        "file": "{linear_ad_video_file_url}"
    },
    "type": "adLoaded"
}

{
    "client": "vast",
    "placement": 1,
    "adBreakId": "1a2b3c4d5e6f",
    "adPlayId": "1a2b3c4d5e6f",
    "offset": "pre",
    "id": "dlsjb0-test",
    "tag": "{ad_tag_url}",
    "adposition": "pre",
    "sequence": 1,
    "witem": 1,
    "wcount": 1,
    "adsystem": "",
    "adschedule": {
        ...
    },
    "item": {
        ...
    },
    "timeLoading": 57,
    "type": "adLoaded"
}

jwplayer().on('adManager')

Starting with JW Player 8.8.0, use jwplayer().on('adsManager')

FreeWheel only. Fires when the ad manager is loaded into the player.

This event allows publishers to integrate additional FreeWheel ad manager functionality before ad playback.

Response

This event returns an object similar to the following:

{
  "adManager": {...},
  "type": "adManager"
}

jwplayer().on('adMeta')

VAST only. Continuously triggers when new metadata has been received from the ad by the player. Values may vary based on the ad itself.

Returns an object with the following:

jwplayer().on('adPause')

Fired whenever an ad is paused.

Returns an object with the following:

jwplayer().on('adPlay')

Fired whenever an ad starts playing or when an ad is unpaused.

Returns an object with the following:

jwplayer().on('adRequest')

Fired whenever an ad is requested by the player.

Returns an object with the following:

jwplayer().on('adSchedule')

VAST only. Fires when the ad schedule is loaded and parsed by the plugin.

Returns an object with the following:

jwplayer().on('adLoadedXML')

VAST only. Fires when the VAST ad client loads an ad tag. The response contains an XML parameter that exposes the XML downloaded from the tag as well as the same object properties as other ad events, such as adBreakId, adPlayId, adPosition, client, and tag.

jwplayer().on('adSkipped')

(VAST, IMA) Fired whenever an ad has been skipped.

Returns an object with the following:

jwplayer().on('adStarted')

(VPAID - VAST, FW | all ads - IMA) This API will trigger when an ad creative signals to our player that it is starting.

Returns an object with the following:

jwplayer().on('adTime')

Fired while ad playback is in progress.

Returns an object with the following:

jwplayer().on('adViewableImpression')

VAST and IMA. Fires only when both of the following conditions are met:

• Ad has played for two consecutive seconds
• At least 50% of the player is in the viewport.

Use the adViewableImpression to track the viewability of your ad impressions. The ad viewable impressions metric is comparable to Google's TrueView viewable impression metric.

Returns an object with the following:

{
    "client": "googima",
    "placement": 1,
    "viewable": 1,
    "adposition": "pre",
    "tag": "{google_ad_tag}",
    "adBreakId": "1a2b3c4d5e6f",
    "adPlayId": "1a2b3c4d5e6f",
    "id": "1a2b3c4d5e6f",
    "ima": {
        ...
    },
    "adtitle": "External Linear Inline",
    "adsystem": "GDFP",
    "creativetype": "video/mp4",
    "duration": 10,
    "linear": "linear",
    "description": "External Linear Inline ad",
    "creativeAdId": "",
    "adId": "697x312-p",
    "universalAdId": [{
        ...
    }],
    "advertiser": "",
    "dealId": "",
    "mediaFile": {
        ...
    },
    "type": "adViewableImpression"
}

{
    "client": "vast",
    "placement": 1,
    "adBreakId": "f61a2b3c4d5e",
    "adPlayId": "f61a2b3c4d5e",
    "offset": "pre",
    "id": "f61a2b3c4d5e",
    "tag": "{ad_tag_url}",
    "adposition": "pre",
    "sequence": 1,
    "witem": 1,
    "wcount": 1,
    "adsystem": "Ad System",
    "adschedule": {
        ...
    },
    "adtitle": "VPAID 2 Linear",
    "description": "VPAID 2 Linear Video Ad",
    "adId": "1234567",
    "advertiser": "",
    "advertiserId": "",
    "creativeId": "",
    "creativeAdId": "",
    "dealId": "",
    "request": {},
    "response": {
        ...
    },
    "conditionalAdOptOut": false,
    "vastversion": 3,
    "clickThroughUrl": "https://click-through-url.com",
    "mediaFileCompliance": true,
    "mediafile": {
        ...
    },
    "viewable": 1,
    "creativetype": "application/javascript",
    "type": "adViewableImpression"
}

jwplayer().on('adWarning')

VAST only. Signals a non-fatal warning that is not critical to the playback of an ad.

{
  "message": "Tracking events are missing breakStart, breakEnd, or error for AdBreak",
  "code": 1002,
  "adErrorCode": 70001,
  "type": "adWarning",
  "tag": "{ad_tag_url}"
}

jwplayer().on('adsManager')

Fires when the ad manager is loaded into the player.

This event allows publishers to integrate additional ad manager functionality before ad playback.

❗️

WARNING

Using this event to integrate additional functionality could impact ad playback.

Response

This event returns an object similar to the following:

{
  "adsManager": {...},
  "type": "adsManager",
  "videoElement": {}
}

jwplayer().on('beforeComplete')

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

jwplayer().on('beforePlay')

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

Audio Tracks

These API calls are used to listen to or update the audio track if multiple audio tracks of a video are provided.

jwplayer().getAudioTracks()

jwplayer().getCurrentAudioTrack()

jwplayer().setCurrentAudioTrack(index)

jwplayer().on('audioTracks')

Fired when the list of available audio tracks is updated. Happens shortly after a playlist item starts playing.

Returns an object with the following:

jwplayer().on('audioTrackChanged')

Fired when the active audio track is changed.

Happens in response to e.g. a user clicking the audio tracks menu or a script calling setCurrentAudioTrack().

Returns an object with the following:

Buffer

These API calls are used to update clients with the percentage of a file that is buffered into the player. This only applies to VOD media; live streaming media (HLS/DASH) does not expose this behavior.

jwplayer().getBuffer()

jwplayer().on('bufferChange')

Fired when the currently playing item loads additional data into its buffer.

Returns an object with the following:

Metadata Object

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. The JavaScript API can be used to log captions usage or build your own CC menu outside JW Player. It is also possible to set caption styles dynamically using setCaptions() without having to reload the player.

📘

`

An index of 0 implies that captions are off.

jwplayer().setCaptions(styles)

Changes the appearance of captions without having to reload the player. All colors should be in hex value.

Example:

jwplayer().setCaptions({"color": "#ffffff", "backgroundColor": "#000000"});

jwplayer().getCaptionsList()

Returns an array of objects based on available captions. Information for each object may vary depending on the caption types.

📘

The event is only triggered when captions are present. The list is cleared on each .on('playlistItem') event.

Sideloaded Captions (VTT, SRT, DFXP)

Stream-Embedded Captions

jwplayer().getCurrentCaptions()

jwplayer().setCurrentCaptions(index)

jwplayer().on('captionsList')

Fired when the list of available captions tracks changes. This event is the ideal time to set default captions with the API.

📘

captionsList will always return an array of at least 1 item due to off, but will trigger again once captions are fully loaded. We suggest only changing captions when the tracks array length exceeds 1.

Returns an array with the following:

jwplayer().on('captionsChanged')

Triggered whenever the active captions track is changed manually or via API.

Returns an object with the following:

Cast

This API call allows a developer to listen for cast events.

jwplayer().on('cast')

Triggered when a cast property changes

{
  "available": true,
  "active": true,
  "deviceName": "ViewerTV",
  "type": "cast"
}

jwplayer().stopCasting()

Immediately end the current current Chromecast session if one exists.

Controls

This API call allows developers to interact with the built-in player controls (control bar and display icons).

📘

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.

jwplayer().on('controls')

Fired when controls are enabled or disabled by a script.

Returns an object with the following:

jwplayer().on('displayClick')

Fired when a user clicks the video display. Especially useful for wiring your own controls when the built-in ones are disabled.

📘

The default click action (toggling play/pause) will still occur if controls are enabled.

jwplayer().addButton(img, tooltip, callback, id, btnClass)

Adds a custom button to the player's control bar.

Placement:
Buttons are added to the righthand-side grouping of icons in the control bar. Buttons are added all the way to the left of the grouping, except if there is a logo in the control bar. In this case, buttons will be added to the right of the logo. Multiple buttons are added from right to left in the order they are entered.

Styling:
While the icon attribute will display any image provided as a URL, we recommend inlining SVGs here instead of providing an external path. This allows the button to map to skin.controlbar.icons and skin.controlbar.iconsActive customization options.

jwplayer().addCues([cues])

Adds an array of cues to the existing cues displayed on the time slider

New cues are appended to cues already on the time slider.

jwplayer("myElement").addCues([
    {
        "begin": 60,
        "cueType": "custom"
        "text": "Cue Text"
    }
]);

jwplayer().getControls()

jwplayer().getCues()

jwplayer().getSafeRegion()

Used to ensure that any visual assets don't overlap with JW Player controls.

Returns an object with the following:

jwplayer().removeButton(id)

Removes a custom button from the control bar.

jwplayer().setAllowFullscreen(allowFullscreen)

jwplayer().setControls(state)

jwplayer().setCues([cues])

Sets the cues displayed on the time slider

New cues replace the existing displayed cues.

jwplayer("myElement").setCues([
  {
    begin: 120,
    text: "First cue"
  }, 
  {
    begin: 575,
    text: "Second cue"
  }
]);

Passing an empty array as the argument will clear all of the cues from the time slider.

jwplayer('myElement').setCues([]);

Floating Player

The player allows for a user to update the floating state of the player dynamically.

jwplayer().on('float')

Fires when a floating player starts and stops floating.

jwplayer().setFloating(shouldFloat)

No return value

jwplayer().getFloating()

Return value

Metadata

This API call allows developers to listen for metadata embedded in the media file (e.g. dimensions or ID3 timed metadata in HLS streams).

jwplayer().on('meta')

Triggered when playback enters the time range where new metadata becomes active. Metadata can be returned in one of the following formats listed below.

Date range metadata

Fires when playback enters the section of an HLS stream tagged with #EXT-X-DATERANGE

{
    "type": "meta",
    "metadataType": "date-range",
    "metadataTime": 10,
    "metadata": {
        "tag": "EXT-X-DATERANGE",
        "content": "ID=309726842,PLANNED_DURATION=30.000,START_DATE=2018-10-30 20:45:29.216158+00:00,SCTE35-OUT=TBD",
        "attributes": [{
                "name": "ID",
                "value": "309726842"
            },
            {
                "name": "PLANNED_DURATION",
                "value": 30
            },
            {
                "name": "START_DATE",
                "value": "2018-10-30 20:45:29.216158+00:00"
            },
            {
                "name": "SCTE35-OUT",
                "value": "TBD"
            }
        ],
        "start": 10,
        "end": 40,
        "startDate": "2018-10-30 20:45:29.216158+00:00",
        "endDate": null,
        "duration": 30.0
    }
}

meta data range metadata

EMSG metadata

Fires when the meta event is happening in conjunction with meta start time

{
    "type": "meta",
    "metadataType": "emsg",
    "metadataTime": 1594650340,
    "metadata": {
        "metadataType": "emsg",
        "id": 159465034,
        "schemeIdUri": "urn:scte:scte35:2013:xml",
        "timescale": 90000,
        "presentationTimeOffset": 900000,
        "duration": 900000,
        "start": 1594650340,
        "end": 1594650350,
        "messageData": {
            "0": 60,
            "1": 83,
            "2": 112,
            "3": 108,
            ... 
            "386": 62
        }
    }
}

meta emsg metadata

ID3 metadata

Fires when playback enters the section of an HLS stream containing ID3 tags

{
  "type": "meta",
  "metadataType": "id3",
  "metadataTime": 0,
  "metadata": {
    ...          
  }
}

Media metadata

Fires when the initial metadata of a video has loaded

{
  "type": "meta",
  "metadataType": "media",
  "duration": 60,
  "height": 1280,
  "width": 720,
  "seekRange": {
    "start": 0,
    "end": 60
  }
}

meta media seekRange

Program-date-time metadata

Fires when playback enters the section of an HLS stream tagged with #EXT-X-PROGRAM-DATE-TIME

{
  "type": "meta",
  "metadataType": "program-date-time",
  "programDateTime": "2018-09-28T16:50:46Z",
  "metadataTime": 19.9,
  "metadata": {
    "programDateTime": "2018-09-28T16:50:46Z",
    "start": 19.9,
    "end": 29.9
  }
}

SCTE-35 metadata

Fires when playback enters a section of an HLS stream tagged with #EXT-X-CUE-OUT, #EXT-X-CUE-IN

{
  "type": "meta",
  "metadataType": "scte-35",
  "metadataTime": 10,
  "metadata": {
    "tag": "EXT-X-CUE-OUT",
    "content": "...",
    "start": 10,
    "end": 40
  }
}

Unknown metadata

Indicates that a meta event from a third-party media provider or legacy Flash has fired

{
  "type": "meta",
  "metadataType": "unknown",
  ...
}

jwplayer().on('metadataCueParsed')

Triggered once the metadata cue point is buffered

Date range metadata

Fires when the player buffers a section of an HLS stream tagged with #EXT-X-DATERANGE

{
  "type": "metadataCueParsed",
  "metadataType": "date-range",
  "metadataTime": 10,
  "metadata": {
    "tag": "EXT-X-DATERANGE",
    "content": "ID=309726842,PLANNED_DURATION=30.000,START_DATE=2018-10-30 20:45:29.216158+00:00,SCTE35-OUT=TBD",
    "attributes": [
      {
        "name": "ID",
        "value": "309726842"
      },
      {
        "name": "PLANNED_DURATION",
        "value": 30
      },
      {
        "name": "START_DATE",
        "value": "2018-10-30 20:45:29.216158+00:00"
      },
      {
        "name": "SCTE35-OUT",
        "value": "TBD"
      }
    ],
    "start": 10,
    "end": 40,
    "startDate": "2018-10-30 20:45:29.216158+00:00",
    "endDate": null,
    "duration": 30.0
  }     
}

EMSG metadata (metadataCueParsed)

{
    "type": "metadataCueParsed",
    "metadataType": "emsg",
    "metadataTime": 1594650340,
    "metadata": {
        "metadataType": "emsg",
        "id": 159465034,
        "schemeIdUri": "urn:scte:scte35:2013:xml",
        "timescale": 90000,
        "presentationTimeOffset": 900000,
        "duration": 900000,
        "start": 1594650340,
        "end": 1594650350,
        "messageData": {
            "0": 60,
            "1": 83,
            "2": 112,
            "3": 108,
            ... 
            "386": 62
        }
    }
}

metadataCueParsed emsg metadata object

ID3 metadata

Fires when playback buffers a section of an HLS stream containing ID3 tags

{
  "type": "metadataCueParsed",
  "metadataType": "id3",
  "metadataTime": 0,
  "metadata": {
    ...          
  }
}

Program-date-time metadata

Fires when the player buffers a section of an HLS stream tagged with #EXT-X-PROGRAM-DATE-TIME

{
  "type": "metadataCueParsed",
  "metadataType": "program-date-time",
  "programDateTime": "2018-09-28T16:50:46Z",
  "metadataTime": 19.9,
  "metadata": {
    "programDateTime": "2018-09-28T16:50:46Z",
    "start": 19.9,
    "end": 29.9
  }
}

SCTE-35 metadata

Fires when the player buffers a section of an HLS stream tagged with #EXT-X-CUE-OUT, #EXT-X-CUE-IN

{
  "type": "metadataCueParsed",
  "metadataType": "scte-35",
  "metadataTime": 10,
  "metadata": {
    "tag": "EXT-X-CUE-OUT",
    "content": "...",
    "start": 10,
    "end": 40
  }
}

Playback

These API calls are used to retrieve and change the current playback state of the player.

jwplayer().play()

Sets the play state of the JW Player. Calling play() while media is playing does nothing.

jwplayer().pause()

Pauses playback, changing the state of JW Player from playing to paused. Calling pause() while media is already paused does nothing.

Note: When using this method with a non-DVR live stream, the player will appear paused. After this, when play() is called, the stream restarts from the live edge.

jwplayer().stop()

Stops the player, returning it to the idle state.

jwplayer().getState()

Returns the player's current playback state.

jwplayer().on('autostartNotAllowed')

{
    "code": 303220,
    "error": "The play method is not allowed by the user agent or the platform in the current context, possibly because the user denied permission.",
    "reason": "autoplayDisabled",
    "type": "autostartNotAllowed"
}

Fired when the player is configured to autostart but the browser's settings are preventing it.

Returns an object with the following:

jwplayer().on('play')

Fired when the player enters the playing state


The play event fires when non-advertising media within the player begins playback. To listen for an ad break play event, use jwplayer().on('adPlay').

Returns an object with the following:

jwplayer().on('pause')

Fired when the player enters the paused state


The pause event fires when non-advertising media within the player is paused. To listen for an ad break pause event, use jwplayer().on('adPause').

Returns an object with the following:

jwplayer().on('playAttemptFailed')

Fired when playback is aborted or blocked. A failed play attempt does not result in a play. Pausing the video or changing the media results in play attempts being aborted. In mobile browsers play attempts are blocked when not started by a user gesture.

Returns an object with the following:

jwplayer().on('buffer')

Fired when the player starts playback and when the player enters a buffering state.

Returns an object with the following:

jwplayer().on('idle')

Fired when the player enters the idle state.

Returns an object with the following:

jwplayer().on('complete')

Fires each time the end of a video is reached.

This does not fire if the viewer advances playlist items prior to the end of a video, or if next() is called.

jwplayer().on('firstFrame')

Use this to determine the period of time between a user pressing play and the same user viewing their content. Triggered by a video's first frame event (or the instant an audio file begins playback). This event pinpoints when content playback begins.

Returns an object with the following:

jwplayer().on('error')

Signals a critical error in the playback process.

Returns an object with the following:

jwplayer().on('warning')

Signals a failure that is not critical to the setup or playback process.

Returns an object with the following:

jwplayer().on('playbackRateChanged')

Fired when the playback rate has been changed.

Returns an object with the following:

jwplayer().getPlaybackRate()

jwplayer().setPlaybackRate(rate)

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. When accessed via the API, a playlist is an Array, containing one or more objects. Each of these objects contains the following:

📘

NOTE

Each playlist item has a file property at the highest level, which acts as a shortcut to the file of the first entry in the sources object.

The sources array contains a single object with information about the currently utilized source:

The tracks array contains a list of objects based on any configured tracks:

jwplayer().next();

Tells JW Player to immediately play the next playlist item.

jwplayer().on('nextClick')

Fires after the next button (in the control bar) or the next up overlay is clicked.

jwplayer().getPlaylist()

Returns an array of objects from a playlist. Any additional custom playlist properties will also be returned. See the playlist section above for the structure of these objects.

jwplayer().getPlaylistItem(index)

If no number is specified, the current playlist item's information will be returned.

jwplayer().getPlaylistIndex()

jwplayer().load(playlist)

Loads a new playlist into the player.

Types of Playlists

JSON Playlist Example

jwplayer('myElement').load([{
  file: "/videos/myVideo.mp4",
  image: "/images/myImage.png",
  title: "My Favorite Video!",
  description: "This has lots of kittens in it!"
}]);

jwplayer().load("https://mywebsite.com/myplaylist.json");

jwplayer().playlistItem(index)

Start playback of the playlist item at the specified index.

jwplayer().on('playlist')

Fired when an entirely new playlist has been loaded into the player.

📘

NOTE

This event is not fired as part of the initial playlist load. Please use on('ready') in these cases.

Returns an object with the following:

jwplayer().on('playlistItem')

Fired when the playlist index changes to a new playlist item. This event occurs before the player begins playing the new playlist item.

Returns an object with the following:

jwplayer().on('playlistComplete')

Fired when the player is done playing all items in the playlist. If the repeat option is set true, this will not be triggered.

jwplayer().setPlaylistItemCallback(callback)

Registers a playlist item callback that can modify or block the progression of a playlist

The playlist item callback accepts two arguments, the playlist item, and its index in the playlist. There are four outcomes the callback can produce:

1. Return from the callback synchronously to allow the item to load and play without changes
2. Return a promise that resolves with a new or modified playlist item
3. Return a promise that resolves without changes
4. Return a promise that rejects to skip loading and playback of that item

jwplayer().setPlaylistItemCallback(function(item, index) {
  console.log(item); // The playlist item that will be loaded
  console.log(index); // The playlist item’s index in the playlist

  // Return from the callback synchronously to allow the item to load and play without changes
  if (item.verified) {
    return;
  }

  // Return a promise to block playlist progression until resolved
  return new Promise(function(resolve, reject) {
    return doSomethingAsync(item).then(function(result) {
      if (result.ok) {
        if (result.modifiedItem) {
          // Resolve the promise to resume loading and playback with a new item
          resolve(result.modifiedItem);
          
        } else {
          // Resolve the promise to resume loading and playback without changes
          resolve();
        }
      } else {
        // Reject the promise to skip playback of the playlist item
        reject();
      }
    });
  }); 
});

jwplayer().setPlaylistItemCallback(null);

jwplayer().removePlaylistItemCallback()

Removes the callback and all playlist item Promises

This can also be set with jwplayer().setPlaylistItemCallback(null).

jwplayer().removePlaylistItemCallback();

jwplayer().getPlaylistItemPromise(index)

Gets the Promise for a particular playlist item

The Promise resolves once the retrieved item begins to preload or play.

jwplayer().getPlaylistItemPromise(index) {
  // Add behavior or function
}

Quality

These API calls are used to listen to or update the video quality if multiple quality levels of a video are provided. Quality levels are sorted and given index numbers.

📘

NOTE

An index of 0 will always be "Auto".

jwplayer().getQualityLevels()

Each object contains the following:

jwplayer().getCurrentQuality()

Returns the index of the current active quality level. The indexes provided vary based on the amount of available qualities. See the table below to understand how quality indexes function

jwplayer().getVisualQuality()

Returns an object containing information about the current quality of a video stream.

List of Reasons

jwplayer().setCurrentQuality(index)

Change the quality level to the provided index. The index must not exceed the amount of available qualities.

jwplayer().on('levels')

Fired when the list of available quality levels is updated. Happens e.g. shortly after a playlist item starts playing.

Returns an object with the following:

jwplayer().on('levelsChanged')

Fired when the active quality level is changed. Happens in response to e.g. a user clicking an option in the quality menu or a script calling setCurrentQuality.

Returns an object with the following:

jwplayer().on('visualQuality')

Fired when the active quality level is changed for HLS. This is different than levelsChanged since this will trigger when adaptive streaming automatically shifts quality.

Returns an object with the following:

Possible Reasons

Related

Similar to sharing, the related API examples below will assume that the following code is implemented:

jwplayer().on('ready', function(event){
  relatedPlugin = jwplayer().getPlugin('related');
});

relatedPlugin.open();

Opens the recommendations user interface. If the displayMode is set to overlay, this will pause content if it is currently playing.

relatedPlugin.close();

Closes the recommendations user interface. This will resume content.

relatedPlugin.on('open');

Triggers when the recommendations interface is opened.

Returns an object with the following:

relatedPlugin.on('close');

Triggers when the recommendations interface is closed.

Returns an object with the following:

relatedPlugin.on('play');

Triggers when a user selects an object in a related feed.

Returns an object with the following:

Resize

These API calls are used to retrieve and update the current player dimensions and fullscreen state.

jwplayer().getFullscreen()

jwplayer().getHeight()

jwplayer().getWidth()

jwplayer().resize(width, height)

Resizes the player to the specified width and height.

📘

NOTE

Decimal-point values are allowed to be passed in to the method, but they will be rounded when the player sets the size.

jwplayer().resize('50%', 250)

jwplayer().on('fullscreen')

Fired when the player toggles to/from fullscreen.

Returns an object with the following:

jwplayer().on('resize')

Fired when the player's on-page dimensions have changed. Is not fired in response to a fullscreen change.

Returns an object with the following:

Seek

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

jwplayer().getPosition()

Intended to return the viewer's current position in a media file. Values may vary depending on the type of media. See the table below for more information.

📘

NOTE

¹ Seeking to a live position will include a buffer of approximately -30 seconds.

jwplayer().getDuration()

The total length of the media file. This varies depending on VOD or live content. See the table below for more information.

jwplayer().seek(position)

Jump to the specified position within the currently playing item.

jwplayer().on('seek')

Fired after a seek has been requested either by scrubbing the control bar or through the API.

Returns an object with the following:

seek.seekRange

📘

NOTE

Seeking is often based on keyframe availability. The actual position the player will eventually seek to may differ from what was specified.

jwplayer().on('seeked')

Triggered when video position changes after seeking, as opposed to on('seek') which triggers as a seek occurs.

jwplayer().on('time')

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.

Returns an object with the following:

Sharing

Sharing API calls work in conjunction with our getPlugin() method. For instance, all of our sharing instances are using the getPlugin(‘sharing’) API call to refer to this particular plugin. The following will target our sharing plugin:

jwplayer().on('ready', function(event){
  sharingPlugin = jwplayer().getPlugin('sharing');
});

All sharingPlugin references below will assume that the above code is implemented on your page.

sharingPlugin.open()

Opens the sharing plugin. This will also pause content if it is triggered during playback.

sharingPlugin.close()

Closes the sharing plugin if it is opened. This will resume playback if the sharing overlay was triggered during content.

sharingPlugin.on('open')

Listens for the opening of the plugin.

sharingPlugin.on('close')

Listens for the closing of the plugin.

sharingPlugin.on('click')

Triggered whenever somebody shares content from within the sharing plugin.

Returns an object with the following:

Viewability

📘

NOTE

We do not recommend using viewability API with iframes.

jwplayer().getPercentViewable()

Returns a number between 0 and 1 that represents the player's visible percentage. If the player is completely out of the viewport or if it is in an inactive tab, this getter returns.

jwplayer().getViewable()

This getter will return 1 if 50% of the player is in view and is in the active tab. If it is below 50% or is in an inactive tab, it will return 0.

jwplayer().on('viewable')

When the player is viewable, a viewable event is fired with a viewable value of 1. When hidden, it fires with a value of 0.

Volume

These API calls are used to change the playback volume of the player.

📘

NOTE

Setting volume will only work on desktop browsers, not on mobile devices.

jwplayer().getMute()

📘

NOTE

This may be independent from the volume value. Volume 0 does not mean that content is set to mute.

jwplayer().getVolume()

jwplayer().setMute(state)

jwplayer().setVolume(volume)

📘

NOTE

Decimal-point values are allowed to be passed in to the method, but they will be rounded when the player sets the volume.

jwplayer().on('mute')

Triggered when the player has gone in or out of a mute state.

Returns an object with the following:

jwplayer().on('volume')

Triggered when the player's volume is changed.

Returns an object with the following: