JavaScript API reference

Review all available JW Player JavaScript API calls.

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

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.

📘

TIP

To view the order of player events for a player on your site, you can install JW Lens, a Chrome browser extension, and follow these steps to view the event order.

Core subset of events, in a timeline, fired for a player that has been configured to play on-demand videos, with captions, audio tracks, casting, and advertising

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.

AttributeDescription
div* string(Required) The target div that JW Player will replace
options* JSON(Required) Configuration options that will tell your player how to render itself

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.

PropertyDescriptionDefault
aspectratio 8.10.0+ string
                                                                     
Maintains proportions when width is a percentage

This property will not be used if the player has been configured with fixed dimensions. The value for this property must be entered in ratio x:y format.
-
autostart stringWhen true, playback will start automatically on desktop devices or when the player is 50% visible on mobile devices.

When set to viewable, playback will start automatically on desktop devices when the player is more than 50% visible in the active tab.
false
height 8.10.0+ numberDesired height of your video player (in pixels)

Should not be used with aspectratio.
360
mute booleanToggles the player's mute attributefalse
repeat booleanWhen true, starts playing the first playlist item after the playlist completesfalse
stretching 8.10.0+ stringResize images and video to fit player dimensions

  • uniform: Fits JW Player dimensions while maintaining aspect ratio

  • exactfit: Fits JW Player dimensions without maintaining aspect ratio

  • fill: Zooms and crops video to fill dimensions, maintaining aspect ratio

  • none: Displays the actual size of the video file (Black borders)
uniform
volume numberSets the volume of the player between 1-100-
width 8.10.0+ number | stringDesired width of your video player (in pixels or percentage)640
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.

Returns an object with the following:

ValueDescription
name string
                       
The name of the provider currently being used

List of possible providers:

ValuesDescription
html5
                                    
Displays whenever content renders natively within a video tag
shakaMPEG Dash Provider
hlsjsHLS content rendering with HLS HTML5 provider
flash_videoStatic video file with our Flash provider
flash_adaptiveStreaming HLS using Adobe Flash
flash_soundStatic audio file with Flash provider

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:

ValueDescription
setupTime number
                                                                     
The amount of time (in milliseconds) for the player to go from setup() to ready.
viewable numberIf the player is viewable or not.

jwplayer().on('setupError')

Fired when neither the player could be set up.

Returns an object with the following:

ValueDescription
message string
                                                                     
The error message that describes why the player could not be set up

jwplayer().on('remove')

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

ValueDescription
-No value returned


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.

ReturnsType
If the player detects an ad blockerBoolean

jwplayer().pauseAd(state)

Used to pause or resume ad playback.

AttributeDescription
state booleanSet whether or not the ad playback should be paused.

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)

AttributeDescription
tag* stringThe VAST tag URL that should be loaded into the player.

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:

ValueDescription
bidders arrayAn array of all bidders in the current bid request.
bidTimeout numberThe amount of milliseconds it will wait for the bids to return after user clicks to play.
client stringThe client that is currently being used

Possible Values:
   • dai
   • freewheel
   • googima
   • vast
floorPriceCents numberFloor price that the return bids need to beat to play.

Not returned when using dfp mediation layer
floorPriceCurrency stringThe currency of the floor price cents value.

Needs to be usd for Facebook. Only used for Facebook bids when mediation layer is set to jwp.
mediationLayerAdServer stringThe mediation layer, which is the decision-maker in what ad to run

Possible Values:
   • dfp
   • jwp
   • jwpdfp
   • jwpspotx
offset stringThe offset of the ad
type stringThe type of the event

This will always return adBidRequest
viewable numberIf the player is viewable or not.

Possible Values:
   • 0
   • 1

Each bidder object contains the following:

ValueDescription
id numberThe publisher ID used for header bidding for each of the bidder
name stringThe name of the bidder

Possible Values:
   See: advertising.bids.bidders[].name

jwplayer().on('adBidResponse')

Fired when header bidding returns response.

Return an object with the following:

ValueDescription
bidders arrayAn array of all bidders in the current bid request.
bidTimeout numberThe amount of milliseconds it will wait for the bids to return after user clicks to play.
client stringThe client that is currently being used

Possible Values:
   • dai
   • freewheel
   • googima
   • vast
floorPriceCents numberFloor price that the return bids need to beat to play.

Not returned when using dfp mediation layer
floorPriceCurrency stringThe currency of the floor price cents value.

Needs to be usd for Facebook. Only used for Facebook bids when mediation layer is set to jwp.
mediationLayerAdServer stringThe mediation layer, which is the decision-maker in what ad to run

Possible Values:
   • dfp
   • jwp
   • jwpdfp
   • jwpspotx
offset stringThe offset of the ad
placement stringValue sent in a bid request that identifies the location of a player

Possible Values:
   • article
   • banner
   • feed
   • floating
   • instream
   • interstitial
   • slider
type stringThe type of the event

This will always return adBidResponse
viewable numberIf the player is viewable or not.

Possible Values:
   • 0
   • 1

Bidder Object

Each bidder object contains the following:

ValueDescription
id numberThe publisher ID used for header bidding for each of the bidder
name stringThe name of the bidder

Possible Values:
   See: advertising.bids.bidders[].name
priceInCents numberThe price of the bid.

Only used when JW Player is the mediation layer
result stringThe result of the bidder's bid

Possible Values:
   • bid
   • noBid
   • timeout
tagKey numberThe tagKey of the bid returned.

Only used for SpotX bidder
timeForBidResponse numberTime taken for the bid to return in milliseconds
winner booleanSet to true when the bidder is the winning bid

Possible Values:
   • false
   • true

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.

ValueDescriptionType
-No value returned-

jwplayer().on('adBreakEnd')

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

Returns an object with the following:

ValueDescription
adposition stringAn ad's position.

Possible Values:
   • mid
   • post
   • pre
client stringThe ad client in use for the ad break.

Possible Values:
   • dai
   • freewheel
   • googima
   • vast
type stringThe type of the event is firing

This will always return adBreakEnd
viewable numberIf the player is viewable or not.

Possible Values:
   • 0: The player is below 50% or is in an inactive tab
   • 1: The player is at least 50% in view and is in the active tab

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"
}
ValueDescription
id stringDescriptive name of the ad break
offset number | stringPosition of an ad

Possible Values:
   • {number in seconds} (This occurs for mid-roll ad breaks.)
   • post
   • pre
tag stringURL of the ad tag
timeSinceLastAd numberDuration between the current ad break and the saved time of the last ad break

This value will always be less than the advertising.rules.timeBetweenAds value.
type stringThe type of the event is firing

This will always return 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:

ValueDescription
adposition stringAn ad's position.

Possible Values:
   • mid
   • post
   • pre
client stringThe ad client in use for the ad break.

Possible Values:
   • dai
   • freewheel
   • googima
   • vast
type stringThe type of the event is firing

This will always return adBreakStart
viewable numberIf the player is viewable or not.

Possible Values:
   • 0: The player is below 50% or is in an inactive tab
   • 1: The player is at least 50% in view and is in the active tab

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:

ValueDescription
clickThroughUrl stringThe redirect URL
client stringThe ad client in use for the ad break.

Possible Values:
   • dai
   • freewheel
   • googima
   • vast
creativetype stringThe type of ad that is just completed
tag stringThe URL of the ad tag that just completed

jwplayer().on('adCompanions')

VAST and IMA. Fired whenever an ad contains companions.

Returns an object with the following:

ValueDescription
companions arrayAn array with available companion information
tag stringThe URL of the ad tag that is currently playing

Every companion will return the following object:

ValueDescription
click stringURL to link to when clicking the companion. Only available if the type is static
creativeview arrayAn array of included creativeview event tracking pixels
height numberThe height of the companion in pixels
resource stringThe URL to the static/iframe resource, or the raw HTML content
type stringThe type of the creative: static, iframe, or HTML
width numberThe width of the companion in pixels

jwplayer().on('adComplete')

Fired whenever an ad has completed playback.

Returns an object with the following:

ValueDescription
client stringThe client that is currently being used

Possible Values:
   • dai
   • freewheel
   • googima
   • vast
creativetype stringThe type of ad that is just completed
tag stringThe URL of the ad tag that just completed
viewable numberIf the player is viewable or not.

Possible Values:
   • 0
   • 1

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:

ValueDescription
message stringThe ad error message.

See table below.
tag stringThe URL of the ad tag that produced the error
Possible Error MessagesCauses
ad tag emptyNo ad was available after searching wrapped ad tags
error playing creative404 on a creative file
error loading ad tagAll additional ad errors
invalid ad tagInvalid XML, Improperly formatted VAST syntax
no compatible creativesFLV video creative or VPAID SWF is attempting to play in HTML5 player

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:

ValueDescription
adposition stringAn ad's position.

Possible Values:
   • mid
   • post
   • pre
adsystem stringAdSystem referenced inside of the VAST XML
adtitle stringAdTitle referenced inside of the VAST XML
bidders arrayIMA-only An array of bidders who made bids on the ad slot. Only added if header bidding happened

Look at bidder object for what is contained in each bidder object.
clickThroughUrl stringThe URL of the page the user lands on when clicking the ad
client stringThe client that is currently being used

Possible Values:
   • dai
   • freewheel
   • googima
   • vast
creativetype stringVAST-only The MIME type of the current media file specified in the VAST XML
duration numberThe total duration of the ad creative
linear stringReturns if an ad is linear or nonlinear
mediafile objectVAST-only An object containing "file", which is the currently playing media item
tag stringThe URL of the ad tag that was started
timeLoading numberThe time in milliseconds the ad took to load
vastversion numberVAST-only The version of VAST referenced in the VAST XML
viewable numberIf the player is viewable or not.

Possible Values:
   • 0: Not viewable
   • 1: Viewable
wrapper arrayVAST-only An array of the AdSystems specified in any utilized ad wrappers; index denotes level of wrapper

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"
}
PropertyDescription
adBreakId stringUnique ID for each ad break

If there are multiple ads in the same ad break, all of the ads will have the same adBreakId.
adId stringFrom the ad XML, identity of the ad server that provides the creative

Definition derived from IAB Tech Lab
adPlayId stringUnique ID for each ad

If there are multiple ads in the same ad break, each ad has a different adPlayId.
adposition stringPosition of the ad

Possible Values:
   • mid
   • post
   • pre
adsystem stringFrom the ad XML, name of the ad server that returned the ad

Definition derived from IAB Tech Lab
adtitle stringFrom the ad XML, common name for the ad

Definition derived from IAB Tech Lab
advertiser stringFrom the ad XML, name of the advertiser as defined by the ad serving party

Definition derived from IAB Tech Lab
client stringThe client that is currently being used

Possible Values:
   • dai
   • freewheel
   • googima
   • vast
creativeAdId stringFrom the ad XML, the ad server’s unique identifier for the creative

Definition derived from IAB Tech Lab
creativetype stringMIME type of the current media file specified in the VAST XML
dealId stringFrom the ad XML, returns the first deal ID present in the wrapper chain for the current ad, starting from the top

Definition derived from Google
description stringFrom the ad XML, provides a long ad description

Definition derived from IAB Tech Lab
duration numberFrom the ad XML, time value for the duration of the linear ad in the format HH:MM:SS.mmm

Definition derived from IAB Tech Lab
id stringUnique ad ID
ima objectContains the currently playing ad instance from the IMA SDK, and the userRequestContext that JW Player passes to the IMA SDK when requesting an ad
item objectPlaylist item that is currently being played as the content
linear stringValue of the linear attribute of the ad XML

Possible Values:
   • linear
   • nonlinear
mediaFile objectFrom the ad XML, contains the video file for a linear ad

Definition derived from IAB Tech Lab
offset number | stringPosition of an ad

Possible Values:
   • {number in seconds} (This occurs for mid-roll ads)
   • post
   • pre
placement stringValue sent in a bid request that identifies the location of a player

Possible Values:
   • article
   • banner
   • feed
   • floating
   • instream
   • interstitial
   • slider
sequence numberReturns the sequence number with which the ad associated
tag stringURL of the ad tag
type stringCategory of the player event

This is always adItem for the event.
universalAdId objectFrom the ad XML, unique creative identifier that is maintained across systems for the purpose of tracking ad creative

Definition derived from IAB Tech Lab
viewable numberIndicates if the player is viewable or not

Possible Values:
   • 0
   • 1

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"
}
PropertyDescription
adBreakId stringUnique ID for each ad break

If there are multiple ads in the same ad break, all of the ads will have the same adBreakId.
adId stringFrom the ad XML, identity of the ad server that provides the creative

Definition derived from IAB Tech Lab
adPlayId stringUnique ID for each ad

If there are multiple ads in the same ad break, each ad has a different adPlayId.
adposition stringPosition of the ad

Possible Values:
   • mid
   • post
   • pre
adschedule objectAd break information
adsystem stringFrom the ad XML, name of the ad server that returned the ad
adtitle stringFrom the ad XML, common name for the ad

Definition derived from IAB Tech Lab
advertiser stringFrom the ad XML, name of the advertiser as defined by the ad serving party

Definition derived from IAB Tech Lab
client stringThe client that is currently being used

Possible Values:
   • dai
   • freewheel
   • googima
   • vast
creativeAdId stringFrom the ad XML, the ad server’s unique identifier for the creative

Definition derived from IAB Tech Lab
creativetype stringMIME type of the current media file specified in the ad XML
dealId stringFrom the ad XML, returns the first deal ID present in the wrapper chain for the current ad, starting from the top

Definition derived from Google
description stringFrom the ad XML, provides a long ad description

Definition derived from IAB Tech Lab
duration numberFrom the ad XML, time value for the duration of the linear ad in the format HH:MM:SS.mmm

Definition derived from IAB Tech Lab
id stringUnique ad ID
ima objectContains the currently playing ad instance from the IMA SDK, and the userRequestContext that JW Player passes to the IMA SDK when requesting an ad
item objectPlaylist item that is currently being played as the content
linear stringValue of the linear attribute of the ad XML

Possible Values:
   • linear
   • nonlinear
mediaFile objectFrom the ad XML, contains the video file for a linear ad

Definition derived from IAB Tech Lab
offset number | stringPosition of an ad

Possible Values:
   • {number in seconds} (This occurs for mid-roll ads)
   • post
   • pre
placement stringValue sent in a bid request that identifies the location of a player

Possible Values:
   • article
   • banner
   • feed
   • floating
   • instream
   • interstitial
   • slider
sequence numberReturns the sequence number with which the ad associated
tag stringURL of the ad tag
timeLoading integerTime the ad took to load in milliseconds
type stringCategory of the player event

This is always adLoaded for the event.
universalAdId objectFrom the ad XML, unique creative identifier that is maintained across systems for the purpose of tracking ad creative

Definition derived from IAB Tech Lab
viewable numberIndicates if the player is viewable or not

Possible Values:
   • 0
   • 1
wcount numberWaterfall count
witem numberWaterfall index

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"
}
ValueDescription
adManager objectObject containing the ad manager configuration
type stringCategory of the player event

This is always adManager for this event.

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:

ValueDescription
metadata objectObject containing the metadata from the ad

The values contained within the object will vary based on the ad.



jwplayer().on('adPause')

Fired whenever an ad is paused.

Returns an object with the following:

ValueDescription
creativetype stringVAST-only The MIME type of the current media file specified in the VAST XML
newstate stringThe new state of the player

This should be "paused"
oldstate stringThe state of the player prior to ad pause
pauseReason 8.7.0+ stringReason ad playback has been paused

Possible Values:
   • clickthrough: Viewer clicked an ad
   • external: Native VPAID controls or jwplayer().pauseAd()
   • interaction: Viewer clicked the pause control on the player
tag stringThe URL of the ad tag that is currently playing.
viewable numberIf the player is viewable or not.

Possible Values:
   • 0: Not viewable
   • 1: Viewable


jwplayer().on('adPlay')

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

Returns an object with the following:

ValueDescription
creativetype stringVAST-only The MIME type of the current media file specified in the VAST XML
newstate stringThe new state of the player

This should be "paused"
oldstate stringThe state of the player prior to ad pause
tag stringThe URL of the ad tag that is currently playing.
viewable numberIf the player is viewable or not.

Possible Values:
   • 0: Not viewable
   • 1: Viewable

jwplayer().on('adRequest')

Fired whenever an ad is requested by the player.

Returns an object with the following:

ValueDescription
adposition stringAn ad's position.

Possible Values:
   • mid
   • pre
   • post
client stringThe client that is currently being used

Possible Values:
   • freewheel
   • googima
   • vast
offset number | stringAn ad's position.

Will return a number (in seconds) of a midroll's position

Possible Values:
   • {number}
   • post
   • pre
tag stringThe URL of the ad tag that is being requested
viewable numberIf the player is viewable or not.

Possible Values:
   • 0: Not viewable
   • 1: Viewable

jwplayer().on('adSchedule')

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

Returns an object with the following:

ValueDescription
adbreaks arrayAn array of objects, each containing information about an ad break.
client stringThe ad client in use for the ad schedule

Possible Values:
   • freewheel
   • googima
   • vast
placement stringValue sent in a bid request that identifies the location of a player

Possible Values:
   • article
   • banner
   • feed
   • floating
   • instream
   • interstitial
   • slider
tag stringThe URL of the ad schedule.

jwplayer().on('adSkipped')

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

Returns an object with the following:

ValueDescription
client stringThe client that is currently being used

Possible Values:
   • freewheel
   • googima
   • vast
creativetype stringThe type of ad that was skipped
tag stringThe URL of the ad tag that was skipped

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. This differs from an adImpression, since the advertisement may not yet be visible.

Returns an object with the following:

ValueDescription
creativetype stringThe MIME type of the VPAID creative
tag stringThe URL of the ad tag that was started.
viewable numberIf the player is viewable or not.

Possible Values:
   • 0: Not viewable
   • 1: Viewable

jwplayer().on('adTime')

Fired while ad playback is in progress.

Returns an object with the following:

ValueDescription
client stringThe client that is currently being used

Possible Values:
   • dai
   • freewheel
   • googima
   • vast
creativetype string(VAST only) The MIME type of the current media file specified in the VAST XML
duration numberThe total duration of the ad creative
position numberThe current playback position in the ad creative in seconds
sequence numberReturns the sequence number the ad is a part of
tag stringThe URL of the ad tag that is currently playing
viewable numberIf the player is viewable or not.

Possible Values:
   • 0
   • 1

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"
}
PropertyDescription
adBreakId stringUnique ID for each ad break

If there are multiple ads in the same ad break, all of the ads will have the same adBreakId.
adId stringFrom the ad XML, identity of the ad server that provides the creative

Definition derived from IAB Tech Lab
adPlayId stringUnique ID for each ad

If there are multiple ads in the same ad break, each ad has a different adPlayId.
adposition stringPosition of the ad

Possible Values:
   • mid
   • post
   • pre
adschedule objectAd break information
adsystem stringFrom the ad XML, name of the ad server that returned the ad

Definition derived from IAB Tech Lab
adtitle stringFrom the ad XML, common name for the ad

Definition derived from IAB Tech Lab
advertiser stringFrom the ad XML, name of the advertiser as defined by the ad serving party

Definition derived from IAB Tech Lab
advertiserId stringFrom the ad XML, optional identifier for the advertiser, provided by the ad server

Definition derived from IAB Tech Lab
clickThroughUrl stringFrom the ad XML, URI to the advertiser’s site that the media player opens when a viewer clicks the ad

Definition derived from IAB Tech Lab
client stringThe client that is currently being used

Possible Values:
   • dai
   • freewheel
   • googima
   • vast
conditionalAdOptOut boolean(VPAID-only) Used to tell the player to not play ads with the conditionalAd attribute inside of the VAST response
creativeId stringFrom the ad XML, identifier of the ad server that provides the creative

Definition derived from IAB Tech Lab
creativeAdId stringFrom the ad XML, the ad server’s unique identifier for the creative

Definition derived from IAB Tech Lab
creativetype stringMIME type of the current media file specified in the VAST XML
dealId stringFrom the ad XML, returns the first deal ID present in the wrapper chain for the current ad, starting from the top

Definition derived from Google
description stringFrom the ad XML, provides a long ad description

Definition derived from IAB Tech Lab
duration numberFrom the ad XML, time value for the duration of the linear ad in the format HH:MM:SS.mmm

Definition derived from IAB Tech Lab
id stringUnique ad ID
ima objectContains the currently playing ad instance from the IMA SDK, and the userRequestContext that JW Player passes to the IMA SDK when requesting an ad
linear stringValue of the linear attribute of the ad XML

Possible Values:
   • linear
   • nonlinear
mediafile | mediaFile objectFrom the ad XML, contains the video file for a linear ad

Definition derived from IAB Tech Lab
mediaFileCompliance booleanIndicates if the ad is mediaFile compliant

To be compliant, one of the following conditions must be met:

   • .m3u8
   • VPAID
   • At least three quality level per MIME type
offset stringPosition of an ad

Possible Values:
   • {number in seconds} (This occurs for mid-roll ads)
   • post
   • pre
placement stringValue sent in a bid request that identifies the location of a player

Possible Values:
   • article
   • banner
   • feed
   • floating
   • instream
   • interstitial
   • slider
request objectXML HTTP request to the ad tag URL
response objectXML response received from the request
sequence numberReturns the sequence number with which the ad associated
tag stringURL of the ad tag
type stringCategory of the player event

This is always adViewabilityImpression for the event.
universalAdId objectFrom the ad XML, unique creative identifier that is maintained across systems for the purpose of tracking ad creative

Definition derived from IAB Tech Lab
vastversion numberFrom the ad XML, official version with which the VAST response is compliant

Definition derived from IAB Tech Lab
viewable numberIndicates if the player is viewable or not

Possible Values:
   • 0
   • 1
wcount numberWaterfall count
witem numberWaterfall index

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"
}
ValueDescription
adErrorCode numberJW Player ad warning code
code numberVAST warning code
message stringAd error message
tag stringURL of the ad tag that produced the error
type stringCategory of player event

This is always adWarning for this event.

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": {}
}
ValueDescription
adsManager objectObject containing the ad manager configuration

See Google's and FreeWheel's documentation for the properties returned by the respective SDK.
type stringCategory of the player event

This is always adsManager for this event.
videoElement object(IMA only) Video tag used for playback

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

ValueDescriptionType
-No value returned-

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

ValueDescriptionType
-No value returned-


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

ReturnsType
An array of each audio track object

These are based on information listed in the M3U8 manifest
Array
ValueDescription
autoselect booleanIf no explicit preference is chosen, can be chosen based on system language
defaulttrack booleanReturns true if the track should be chosen by default
language stringThe two-letter language code for the chosen audio track
name stringThe given name for the chosen audio track

jwplayer().getCurrentAudioTrack()

ReturnsType
The index of the currently active audio track.

Will return -1 if there are no alternative audio tracks
Number

jwplayer().setCurrentAudioTrack(index)

AttributeDescription
index* numberChange the audio track to the provided 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:

ValueDescription
levels arrayAn array containing the new audio track objects

Returns the same information as getAudioTracks()

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:

ValueDescription
currentTrack numberIndex of the new quality level in the getAudioTracks() array.


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

DescriptionType
A percentage (0-100) of the video's current loaded amountNumber

jwplayer().on('bufferChange')

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

Returns an object with the following:

ValueDescription
bufferPercent numberPercentage between 0 and 100 of the current media that is buffered.
duration numberCurrent media's duration (In seconds)
metadata object(Flash HLS-Only) Contains bandwidth and droppedFrames values

See below for more info.
position numberCurrent position of the media file (in seconds)

Metadata Object

ValueDescription
bandwidth numberCurrent download speed in bits per second.
droppedFrames numberAmount of dropped frames caused by a buffer change.


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.

AttributeDescription
styles* objectAn object containing the desired caption styles and values (See example below)
ValueDescription
backgroundColor stringThe color of the text background

Default: #000000
backgroundOpacity numberAdjusts the transparency of the text background as a percentage

Default: 100
color stringText color

Default: #ffffff
edgeStyle stringSurrounds text with a particular style

Default: none

Possible Values:
   • none
   • depressed
   • dropshadow
   • raised
   • uniform
fontFamily stringThe style of text to use

Default: Arial, sans-serif
fontOpacity numberAdjusts the transparency of text as a percentage

Default: 100
fontSize numberThe size of text.

Note: Does not affect cases where native rendering occurs

Default: 20
windowColor stringSurrounds text box with chosen color from edge to edge of the video
windowOpacity numberSets the transparency of the window as a percentage

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)

ValueDescription
id stringThe URL of the sideloaded caption file
label stringThe label that is configured in the player setup.

Stream-Embedded Captions

ValueDescription
id numberThe index of the caption.
label stringThe label specified within the embedded captions

jwplayer().getCurrentCaptions()

DescriptionType
The index of the currently active captions track.Number

jwplayer().setCurrentCaptions(index)

AttributeDescription
index* numberChange the visible captions track to the provided 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:

ValueDescriptionType
tracksAn array with all included captions tracks(Including "off"). Includes the same information as getCaptionsList()Array

jwplayer().on('captionsChanged')

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

Returns an object with the following:

ValueDescriptionType
trackIndex of the new active captions trackNumber


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"
}
ValueDescriptionType
activeIndicates that casting has started (true) or has stopped (false)Boolean
availableIndicates a device is (true) or is not (false) available for casting

When a device is available to be cast to, the cast icon appears in the player control bar.
Boolean
deviceNameName that the viewer assigns to device (receiver)

This property is only populated when "cast.active": "true".
String
typeCategory of player event

This is always cast for this event.
String

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:

ValueDescriptionType
controlsNew state of the controls.Boolean

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.

ValueDescriptionType
-No value returned-

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.

AttributeDescriptionTypeRequired
imgThe image that will be used as the button icon. Can be the url to an image or the content of an SVG in string. Monochromatic, white icons of 24x24 pixels work well.StringYes
tooltipA tooltip label to display when the button is hovered.StringYes
callbackThe JavaScript function that is called when the button is clicked.FunctionYes
idThe string used to identify the button. It must be unique across all buttons (an error is thrown otherwise).StringYes
btnClassAn optional CSS class name added to the button element.StringNo

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"
    }
]);
AttributeDescription
begin* numberCue location relative to the start of the media item, in seconds
text* stringLabel for the cue
cueType 8.14.0+ string
                                           
Class name for the cue

When defined, the value of this property creates a CSS class with the name .jw-cue-type-{cueType_VALUE}. This class can then be styled with the selector .jw-slider-time .jw-cue-type-{cueType_VALUE}

The example above creates: .jw-cue-type-custom. To style all cues associated with this CSS class, use the selector .jw-slider-time .jw-cue-type-custom for all cues associated with this class.

jwplayer().getControls()

DescriptionType
Returns whether or not the built-in controls are currently enabledBoolean

jwplayer().getCues()

DescriptionType
Returns an array of cues displayed in the time sliderArray

jwplayer().getSafeRegion()

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

Returns an object with the following:

ValueDescriptionType
xStarting point on the X axis with JW Player. Will always be 0.Number
yStarting point on the Y axis with JW Player. Will always be 0.Number
widthCurrent viewable container widthNumber
heightCurrent viewable container height, subtracting control bar heightNumber

jwplayer().removeButton(id)

Removes a custom button from the control bar.

AttributeDescriptionTypeRequired
idThe id used to identify the button to remove.StringYes

jwplayer().setControls(state)

AttributeDescriptionTypeRequired
stateSets the display of the built-in JW Player controls. Not including a state will toggle the appearance.BooleanNo

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"
  }
]);
AttributeDescriptionTypeRequired
beginCue location relative to the start of the media item, in secondsNumberYes
textLabel for the cueStringYes

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

ValueDescription
shouldFloat booleanTells the player to float if true or stop floating if false

No return value


jwplayer().getFloating() 8.17.0+

Return value

ValueDescription
(return value) booleanReturns true if the player is currently floating, and false if the player is currently not floating


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
    }
}
ValueDescription
metadata objectObject containing all of the information relevant to the HLS #EXT-X-DATERANGE tag

   • attributes array: EXT-X-DATERANGE:<attribute-list>

   • content string: Content following the HLS tag

   • duration number: Duration of the EXT-X-DATERANGE

   • end number: End time of the cue in seconds, relative to currentTime of stream

   • endDate string: EXT-X-DATERANGE end date in UTC

   • start number: Start time of the cue in seconds, relative to currentTime of stream

   • startDate string: EXT-X-DATERANGE start date in UTC

   • tag string: Name of the HLS manifest tag



This is always EXT-X-DATERANGE for this event.
metadataTime numberStart time, in seconds, of the metadata cue
metadataType stringSubcategory of meta event

This is always date-range for this event subcategory.
type stringCategory of player event

This is always meta for this event.

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
        }
    }
}
ValueDescription
metadata objectObject containing all of the information relevant to the HLS #EXT-X-DATERANGE tag

See: metadata object
metadataTime numberStart time, in seconds, of the metadata cue
metadataType stringSubcategory of meta event

This is always emsg for this event subcategory.
type stringCategory of player event

This is always meta for this event.
meta emsg metadata object
ValueDescription
duration numberDuration of the EXT-X-DATERANGE
end numberEnd time of the cue in seconds, relative to currentTime of stream
id numberField identifying this instance of the message
messageData arrayBody of the message
metadataType stringSubcategory of meta event

This is always emsg for this event subcategory.
presentationTimeOffset numberOffset that the event starts, relative to the start of the segment this is contained in (in units of timescale)
start numberStart time of the cue in seconds, relative to currentTime of stream
schemeIdUri stringIdentifies the message scheme
timescale numberProvides the timescale, in ticks per second

ID3 metadata

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

{
  "type": "meta",
  "metadataType": "id3",
  "metadataTime": 0,
  "metadata": {
    ...          
  }
}
ValueDescription
metadata objectObject containing all of the information relevant to the HLS ID3 tag
metadataTime numberStart time, in seconds, of the metadata cue
metadataType stringSubcategory of meta event

This is always id3 for this event subcategory.
type stringCategory of player event

This is always meta for this event.

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
  }
}
ValueDescriptionType
durationLength of the media assetNumber
heightHeight dimension of the media assetNumber
metadataTypeSubcategory of meta event

This is always media for this event subcategory.
String
seekRangeTime range representing how much video is available to buffer in live stream or for seeking in DVR

end: (Number) End time of the time range in seconds, relative to currentTime of stream

start: (Number) Start time of the time range in seconds, relative to currentTime of stream
Object
typeCategory of player event

This is always meta for this event.
String
widthWidth dimension of the media assetNumber

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
  }
}
ValueDescriptionType
metadataObject containing all of the information relevant to the HLS #EXT-X-PROGRAM-DATE-TIME tag

end: (Number) End time of the cue in seconds, relative to currentTime of stream

programDateTime: (String) Date and time of the program metadata in UTC

start: (Number) Start time of the cue in seconds, relative to currentTime of stream
Object
metadataTimeStart time, in seconds, of the metadata cueNumber
metadataTypeSubcategory of meta event

This is always program-date-time for this event subcategory.
String
programDateTimeDate and time of the program metadata in UTCString
typeCategory of player event

This is always meta for this event.
String

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
  }
}
ValueDescriptionType
metadataObject containing all of the information relevant to the HLS #EXT-X-CUE-OUT, #EXT-X-CUE-IN tags

content: (String) Content following the HLS manifest tag

end: (Number) End time of the cue in seconds, relative to currentTime of stream

start: (Number) Start time of the cue in seconds, relative to currentTime of stream

tag: (String) Name of the HLS manifest tag
This is always EXT-X-CUE-OUT or EXT-X-CUE-IN for this event.
Object
metadataTimeStart time, in seconds, of the metadata cueNumber
metadataTypeSubcategory of meta event

This is always scte-35 for this event subcategory.
String
typeCategory of player event

This is always meta for this event.
String

Unknown metadata

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

{
  "type": "meta",
  "metadataType": "unknown",
  ...
}
ValueDescriptionType
metadataTypeSubcategory of meta event

This is always unknown for this event subcategory.
String
typeCategory of player event

This is always meta for this event.
String

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
  }     
}
ValueDescriptionType
metadataObject containing all of the information relevant to the HLS #EXT-X-DATERANGE tag

attributes: (Array) EXT-X-DATERANGE:<attribute-list>

content: (String) Content following the HLS tag

duration: (Number) Duration of the EXT-X-DATERANGE

end: (Number) End time of the cue, in seconds, relative to currentTime of stream

endDate: (String) EXT-X-DATERANGE end date in UTC

start: (Number) Start time of the cue, in seconds, relative to currentTime of stream

startDate: (String) EXT-X-DATERANGE start date in UTC

tag: (String) Name of the HLS manifest tag
This is always EXT-X-DATERANGE for this event.
Object
metadataTimeStart time, in seconds, of the metadata cueNumber
metadataTypeSubcategory of meta event

This is always date-range for this event subcategory.
String
typeCategory of player event

This is always metadataCueParsed for this event.
String

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
        }
    }
}
ValueDescription
metadata objectObject containing all of the information relevant to the HLS #EXT-X-DATERANGE tag

See: metadata object
metadataTime numberStart time, in seconds, of the metadata cue
metadataType stringSubcategory of meta event

This is always emsg for this event subcategory.
type stringCategory of player event

This is always metadataCueParsed for this event.
metadataCueParsed emsg metadata object
ValueDescription
duration numberDuration of the EXT-X-DATERANGE
end numberEnd time of the cue in seconds, relative to currentTime of stream
id numberField identifying this instance of the message
messageData arrayBody of the message
metadataType stringSubcategory of meta event

This is always emsg for this event subcategory.
presentationTimeOffset numberOffset that the event starts, relative to the start of the segment this is contained in (in units of timescale)
start numberStart time of the cue in seconds, relative to currentTime of stream
schemeIdUri stringIdentifies the message scheme
timescale numberProvides the timescale, in ticks per second

ID3 metadata

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

{
  "type": "metadataCueParsed",
  "metadataType": "id3",
  "metadataTime": 0,
  "metadata": {
    ...          
  }
}
ValueDescriptionType
metadataObject containing all of the information relevant to the HLS ID3 tagObject
metadataTimeStart time, in seconds, of the metadata cueNumber
metadataTypeSubcategory of meta event

This is always id3 for this event subcategory.
String
typeCategory of player event

This is always metadataCueParsed for this event.
String

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
  }
}
ValueDescriptionType
metadataObject containing all of the information relevant to the HLS #EXT-X-PROGRAM-DATE-TIME tag

end: (Number) End time of the cue, in seconds, relative to currentTime of stream

programDateTime: (String) Date and time of the program metadata in UTC

start: (Number) Start time of the cue, in seconds, relative to currentTime of stream
Object
metadataTimeStart time, in seconds, of the metadata cueNumber
metadataTypeSubcategory of meta event

This is always program-date-time for this event subcategory.
String
programDateTimeDate and time of the program metadata in UTCString
typeCategory of player event

This is always metadataCueParsed for this event.
String

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
  }
}
ValueDescriptionType
metadataObject containing all of the information relevant to the HLS #EXT-X-CUE-OUT, #EXT-X-CUE-IN tags

content: (String) Content following the HLS manifest tag

end: (Number) End time of the cue, in seconds, relative to currentTime of stream

start: (Number) Start time of the cue, in seconds, relative to currentTime of stream

tag: (String) Name of the HLS manifest tag
This is always EXT-X-CUE-OUT or EXT-X-CUE-IN for this event.
Object
metadataTimeStart time, in seconds, of the metadata cueNumber
metadataTypeSubcategory of meta event

This is always scte-35 for this event subcategory.
String
typeCategory of player event

This is always metadataCueParsed for this event.
String


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.

ValueDescriptionType
-No value returned-

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.

ValueDescriptionType
-No value returned-

jwplayer().stop()

Stops the player, returning it to the idle state.

ValueDescriptionType
-No value returned-

jwplayer().getState()

Returns the player's current playback state.

ReturnsDescriptionType
idleEither playback has not started or playback was stopped due to a stop() call or an error. In this state, either the play or the error icon is visible in the display.String
bufferingThe user pressed play, but sufficient data to start playback has not yet loaded. The buffering icon is visible in the display.String
playingThe video is currently playing. No icon is visible in the display.String
pausedThe video is currently paused. The play icon is visible in the display.String

jwplayer().on('autostartNotAllowed')

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

Returns an object with the following:

ValueDescriptionPossible OutputsType
errorAn object containing the error, most likely an AbortError.-Object
reasonThe reason why the player could not autostart."autoplayDisabled"String
typeThe type of event that is fired."autostartNotAllowed"String

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:

ValueDescriptionPossible OutputsType
oldstateThe state the player moved from.buffering | playingString
viewableIf the player is viewable or not.0 | 1Number
playReasonThe reason for the play, such as interaction, API, external, or a custom reason.String

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:

ValueDescriptionPossible ValuesType
oldstateThe state the player moved from.buffering | playingString
viewableIf the player is viewable or not.0 | 1Number
pauseReasonThe reason for the pause, such as interaction, API, external, or a custom reason.String

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:

ValueDescriptionType
errorThe error that resulted from the play promise.Object
itemReturns everything in the playlist item.Object
playReasonThe reason for the play, such as interaction, API, external, or a custom reason.String

jwplayer().on('buffer')

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

Returns an object with the following:

ValueDescriptionPossible ValuesType
oldstateThe state the player moved from.buffering | playingString
newstateThe state the player moved to.idle | playing | pausedString
reasonThe reason why a buffer event occurred.loading | complete | stalled | errorString

jwplayer().on('idle')

Fired when the player enters the idle state.

Returns an object with the following:

ValueDescriptionPossible OutputsType
oldstateThe state the player moved from.buffering | playing | pausedString

jwplayer().on('complete')

Fired when an item completes playback.

ValueDescriptionType
-No value returned-

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:

ValueDescriptionType
loadTimeThe amount of time (In milliseconds) it takes for the player to transition from a play attempt to a firstFrame event.Number
viewableIf the player is viewable or not.Number

jwplayer().on('error')

Signals a critical error in the playback process.

Returns an object with the following:

ValueDescriptionType
codeIdentifier for the error
See JW Player Errors Reference for a list of possible errors.
Number
messageText for the detected error
See JW Player Errors Reference for a list of possible errors.
String
sourceErrorLower level error or event, caught by the player, which resulted in this errorObject or null
typeCategory of error
This will always return error.
String

jwplayer().on('warning')

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

Returns an object with the following:

ValueDescriptionType
codeIdentifier for the warning
See JW Player Errors Reference for a list of possible warnings.
Number
messageText for the detected warning
See JW Player Errors Reference for a list of possible warnings.
String
sourceErrorLower level error or event, caught by the player, which resulted in this warningObject or null
typeCategory of warning
This will always return warning.
String

jwplayer().on('playbackRateChanged')

Fired when the playback rate has been changed.

Returns an object with the following:

ValueDescriptionType
playbackRateThe new playback rateNumber
positionThe position of the video when the playback rate was changedNumber

jwplayer().getPlaybackRate()

ReturnsType
The current playback rate.Number

jwplayer().setPlaybackRate(rate)

AttributeDescriptionTypeRequired
rateAccepts any numeric value between 0.25 and 4. The playback rate is clamped if rate is out of range.NumberNo


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:

ValueDescriptionType
descriptionA description specified inside of the playlistString
mediaidA unique media identifier for a particular piece of content, regardless of the format usedString
fileProvides a shortcut to sources[0].file. Alternative files are listed in the allSources arrayString
imageThe poster image file loaded inside of the playerString
preloadPreload status for current item. Can be: metadata | auto | noneString
titleThe title of the playlist itemString
tracksThe full array of tracks included with the playlist item, similar to getCaptionsList()Array
sourcesAn array that contains a single object with information about the currently utilized sourceArray
allSourcesAn array of all configured sources for the current playlist itemArray

📘

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:

ValueDescriptionType
fileThe file used in the source array itemString
labelA label assigned to a particular qualityString
typeThe media typeString
defaultIf this media source has been defined as a default for playbackBoolean

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

ValueDescriptionType
fileThe file used containing any utilized tracksString
labelIf using captions, the configured label assigned to a particular qualityString
kindThe type of tracks assigned to the video. Can be: captions | chapters | thumbnailsString

jwplayer().next();

Tells JW Player to immediately play the next playlist item


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.

DescriptionType
An array of objects from the current playlistArray

jwplayer().getPlaylistItem(index)

AttributeDescriptionTypeRequired
indexRetrieves the same information as getPlaylist(), but for a single playlist itemNumberNo

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


jwplayer().getPlaylistIndex()

DescriptionType
The numerical index of the currently loaded playlist item.Number

jwplayer().load(playlist)

Loads a new playlist into the player.

AttributeDescriptionTypeRequired
playlistThe playlist to load into the player.Array | StringYes

Types of Playlists

DescriptionType
An array of playlist item objects. See above for correct syntaxArray
A URL referencing the location of an RSS/XML/JSON fileString

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.

AttributeDescriptionTypeRequired
indexThe index of a playlist item you wish to playNumberYes

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:

ValueDescriptionType
playlistThe new playlist array; Provides the same output as getPlaylist()Array

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:

ValueDescriptionType
indexIndex of the currently playing playlist itemNumber
itemThe current playlist item; Provides the same output as getPlaylistItem()Object

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.

ValueDescriptionType
-No value returned-

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);
ArgumentDescription
callbackA null argument or a function that is passed with the arguments index and item

When the callback is a function, it can be invoked asynchronously and pass item (a playlist item) and index (the index of the item in the playlist). When the callback returns a Promise, playlist progression is blocked until the Promise is resolved. If the Promise resolves with a valid playlist object, that object will replace the item in the playlist. Since Promises only resolve once, the function is not repeated when the same item is played more than once.

There can only be one active callback. By calling this method again, any existing callback and playlist item Promises are removed.

When the callback is null, the callback and all playlist item promises are removed. See also: removePlaylistItemCallback()

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
}
ArgumentDescription
indexValid playlist item index or -1 for the next recommended item



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

DescriptionType
Returns an array of objects based on each quality level of a media itemArray

Each object contains the following:

ValueDescriptionType
bitrateThe bitrate of the media fileNumber
heightThe height of the media fileNumber
widthThe width of the media fileNumber
labelThe label used for a qualityString

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

DescriptionType
Index of the current qualityNumber

jwplayer().getVisualQuality()

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

ValueDescriptionType
modeThe current quality mode. Can be auto if adaptive is enabled or manual if a static quality is setString
levelInformation about the current selected quality. See getQualityLevels for the full list of available informationObject
reasonThe reason that a quality was selected. See table below for more informationString

List of Reasons

ReasonDescription
initial choiceThe user had this quality set as a default and did not change it
autoAn automatic quality change occurred
apiThe user chose a static quality after playback began, or an API was used to set it

jwplayer().setCurrentQuality(index)

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

AttributeDescriptionTypeRequired
indexSets stream quality to a specified indexNumberYes

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:

ValueDescriptionType
widthThe new width of the playerNumber
levelsThe full array of qualities, including the new additions. Includes the same information as getQualityLevels()Array

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:

ValueDescriptionType
currentQualityindex of the new quality level in the getQualityLevels() arrayNumber

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:

ValueDescriptionType
modeThe current type of quality selection. auto = automatic quality switching | manual = static qualityString
labelInformation about the new quality that was switched to. This returns the same information as getVisualQuality()String
reasonWhy the quality was changed. See table below for possible reasonsString

Possible Reasons

reasonDescription
initial choiceThe user had this quality set as a default and did not change it
autoAn automatic quality change occurred
apiThe user chose a static quality after playback began, or an API was used to set it


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.

ValueDescriptionType
-No value returned-

relatedPlugin.close();

Closes the recommendations user interface. This will resume content.

ValueDescriptionType
-No value returned-

relatedPlugin.on('open');

Triggers when the recommendations interface is opened.

Returns an object with the following:

ValueDescriptionType
methodThe method used to open the plugin. (api, complete, or click)String
urlURL of the feed that was loaded into the player.String
itemsAn object of all objects that have been loaded into the related plugin.Object

relatedPlugin.on('close');

Triggers when the recommendations interface is closed.

Returns an object with the following:

ValueDescriptionType
methodThe method used to open the plugin. (api, complete, or click)string

relatedPlugin.on('play');

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

Returns an object with the following:

ValueDescriptionType
itemMetadata for the chosen item specified in the feed.Object
autoReturns true if started via autoplay; false if manually started.Boolean
positionOrdinal position of the related video that has been chosen.Number


Resize

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


jwplayer().getFullscreen()

ReturnsType
The current fullscreen state; true if fullscreen, false if notBoolean

jwplayer().getHeight()

ReturnsType
The player's current height, in pixelsNumber

jwplayer().getWidth()

ReturnsType
The player's current width, in pixelsNumber

jwplayer().resize(width, height)

Resizes the player to the specified width and height.

AttributeDescriptionTypeRequired
widthThe new desired width of the player in pixels (number) or percent (string)Number | StringYes
heightThe new desired height of the player. Must be specified in pixels (number)NumberYes

📘

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:

ValueDescriptionType
fullscreenThe player's new fullscreen stateBoolean

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:

ValueDescriptionType
widthThe new width of the playerNumber
heightThe new height of the playerNumber


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.

Media TypeDescriptionType
VODThe current playback position for a VOD file, in secondsNumber
LiveHow long the current stream has been playing, in secondsNumber
DVRA negative value, indicating how far behind the viewer is from the stream's live position.1Number

📘

NOTE

1 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.

Media TypeDescriptionType
VODThe length of a loaded VOD file, in secondsNumber
LiveLive streams will always return a duration of infinityNumber
DVRThe total amount of buffer in the DVR stream, in secondsNumber

jwplayer().seek(position)

Jump to the specified position within the currently playing item.

AttributeDescriptionTypeRequired
positionThe position (in seconds) to seek toNumberYes

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:

ValueDescription
currentTime 8.19.0+ numberThe position of the stream before the player seeks (in seconds).
duration 8.19.0+ numberDuration of the current playlist item (in seconds).
position numberThe position of the player before the player seeks (in seconds).
seekRange 8.19.0+ objectTime range representing how much video is available for seeking in DVR streams or for buffering in live streams

See seek.seekRange
offset numberThe position that has been requested to seek to (in seconds).

seek.seekRange

ValueDescription
end numberEnd time of the range relative to the currentTime of the stream (in seconds)
start numberStart time of the range relative to the currentTime of the stream (in seconds)


📘

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.

ValueDescriptionType
-No value returned-

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:

ValueDescriptionType
durationDuration of the current playlist item in seconds.Number
positionPlayback position in seconds.Number
viewableIf the player is viewable or not.Number


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.

ValueDescriptionType
-No value returned-

sharingPlugin.close()

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

ValueDescriptionType
-No value returned-

sharingPlugin.on('open')

Listens for the opening of the plugin.

ValueDescriptionType
-No value returned-

sharingPlugin.on('close')

Listens for the closing of the plugin.

ValueDescriptionType
-No value returned-

sharingPlugin.on('click')

Triggered whenever somebody shares content from within the sharing plugin.

Returns an object with the following:

ValueDescriptionType
methodLabel of the sharing method that was usedString


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

DescriptionType
If the player is currently muted or notBoolean

📘

NOTE

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


jwplayer().getVolume()

ReturnsType
The current playback volume, as a percentage from 0 to 100.Number

jwplayer().setMute(state)

AttributeDescriptionTypeRequired
stateSet the mute state of the player. If the state is undefined, mute is toggled.BooleanNo

jwplayer().setVolume(volume)

AttributeDescriptionTypeRequired
volumeSet the volume of the player between 1-100NumberYes

📘

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:

ValueDescriptionType
muteThe player's new mute stateBoolean

jwplayer().on('volume')

Triggered when the player's volume is changed.

Returns an object with the following:

ValueDescriptionType
volumeNew volume percentage (0-100)Number

Updated about 6 hours ago


JavaScript API reference


Review all available JW Player JavaScript API calls.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.