Last Updated: November 27, 2019

This article contains all configuration options JW Player supports.

Introduction

JW Player contains a number of configurable options. Some options, like width or mute, are top level, while other more advanced options may be nested, such as the ones used for skin customizations and advertising.

Here is an example setup that contains both setup options and specific advertising options:

jwplayer("myElement").setup({
  file: "https://example.com/myVideo.mp4",
  height: 360,
  width: 640,
  autostart: "viewable",
  advertising: {
    client: "vast",
    tag: "http://adserver.com/vastTag.xml"
  }
});

---

Setup Options

These are the options for configuring the layout and playback behavior of a player. Each is placed directly into the setup of the player.

Appearance

Stretching Examples

Behavior

Casting

Casting enables a viewer to use Google Cast or Apple AirPlay technologies to stream video and audio content to a compatible TV or sound system. By enabling the casting feature for a player, a viewer can tap an icon in the control bar to stream your content on a cast-compatible device. If no compatible device is detected by the player, no cast icon appears.

See also: FAQs

To enable casting, add an empty cast object in your setup.

jwplayer("myElement").setup({
  playlist: "https://cdn.jwplayer.com/v2/playlists/1a2Bc3d4",
  height: "auto",
  width: "100%",
  cast: {}
});

If you are using a custom receiver, assign the identifier of the custom receiver to the cast.customAppId property.

jwplayer("myElement").setup({
  playlist: "https://cdn.jwplayer.com/v2/playlists/1a2Bc3d4",
  height: "auto",
  width: "100%",
  cast: {
    customAppId: "XXXXXX"
  }
});

Media

Rendering and Loading

---

Advertising

This object configures the video advertising capabilities of JW Player and overrides advertising settings configured in the dashboard. If no schedule is specified, the ad will play as a preroll by default.

advertising.bids

Use this property to enable and configure Video Player Bidding with supported bidders.

jwplayer("myElement").setup({
  playlist: "https://cdn.jwplayer.com/v2/playlists/a12bc3D4", 
  advertising: {
    ...
    bids: {
      bidOnBreaks: 3,
      settings: {...},
      bidders: [...]
    }
  ...
  }
});

advertising.bids.bidders[]

jwplayer("myElement").setup({
  playlist: "https://cdn.jwplayer.com/v2/playlists/a12bc3D4", 
  advertising: {
    bids: {
      ...
      bidders: [
        {
          name: "SpotX",
          id: "85394"
        }
      ]
    }
  ...
  }
});

advertising.bids.bidders[].optionalParams

jwplayer("myElement").setup({
  playlist: "https://cdn.jwplayer.com/v2/playlists/a12bc3D4", 
  advertising: {
    bids: {
      ...
      bidders: [
        {
          name: "SpotX",
          id: "85395",
          optionalParams: {
            price_floor: 5.30,
            custom: {
              name: "custom_param_name_goes_here",
              value: "custom_param_value_goes_here"
            }
          }
        }
      ]
    }
  ...
  }
});

advertising.bids.settings

jwplayer("myElement").setup({
  playlist: "https://cdn.jwplayer.com/v2/playlists/a12bc3D4", 
  advertising: {
    ...
    bids: {
      ...
      settings: {
        mediationLayerAdServer: "jwp",
        floorPriceCents: 10,
        floorPriceCurrency: "usd",
        bidTimeout: 1000  
      }
    }
  ...
  }
});

advertising.bids.settings.buckets[]

advertising.companiondiv

This is an object with 3 properties: id, width and height. Set these to have JW Player load a companion ad from your VAST/IMA tag into a div on your page. See Companion Ads for more info.

For an overview of JW Player's advertising capabilities, see its dedicated Video Ads section.

jwplayer("myElement").setup({
  playlist: "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
  fwassetid: "test_asset",
  duration: 600,
  advertising: {
    ...
    freewheel: {
      networkid: 12345,
      adManagerUrl: "https://mssl.fwmrm.net/libs/adm/6.24.0/AdManager.js",
      serverid: "http://demo.v.fwmrm.net/ad/g/1",
      profileid: "12345:html5_test",
      sectionid: "test_site_section"
    }
  }
});

advertising.freewheel

advertising.rules

Use this property to control how frequently ads play back. See our Ad Rules Reference support article for more information.

jwplayer("myElement").setup({
  playlist: [...],
  advertising: {
    ...
    rules: {
      startOn: 2,
      frequency: 1,
      timeBetweenAds: 300,
      startOnSeek: "pre"
    }
  }
});

advertising.schedule

Use this property to load an entire advertising schedule to JW Player, containing multiple ad breaks. The property value can be a URL to a VMAP schedule or an inline JSON block with ads. This schedule will then be applied to each playlist item. For scheduling ads for individual playlist items, see scheduling ads for playlist items.

Ad Schedules with VMAP Files

If you are planning on using a VMAP file, add the link to a VMAP .xml file as the value for schedule:

jwplayer("myElement").setup({
  playlist: "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
  advertising: {
    client: "vast",
    adscheduleid: "t4Xk5tsF",
    schedule: "myvmap.xml"
  }
});

The VMAP schedule will then be applied to each playlist item. See our article about VMAP schedules for more information.

Embedded Ad Schedules with JSON

In order to use a JSON-formatted schedule, you must define at least one ad break configured inside of the schedule property. Each ad break should include an offset and a tag or vastxml.

jwplayer("myElement").setup({
  playlist: "https://cdn.jwplayer.com/v2/playlists/a12bc3D4",
  advertising: {
    client: "vast",
    adscheduleid: "p4Xk5lsZ",
    schedule: [
      {
        tag: "myPreroll.xml",
        offset: "pre",
        custParams: {
          testkey1: "testval1",
          testkey2: "testval2"
        },
      },
      {
        vastxml: "<VAST version='2.0'> ... </VAST>",
        offset: "50%"
      }
    ]
  }
});

---

Auto pause

Automatically pauses the player based on certain rules

By default, adding an empty autoPause object enables the auto pause player functionality and also sets viewability: true.

jwplayer("myElement").setup({
  playlist: "https://example.com/myVideo.mp4",
  ...
  autoPause: {
    viewability: true,
    pauseAds: true
  }
});

---

Captions

This options block configures the styling of closed captions in the player for desktop browsers. On iOS/Android, a system settings menu provides exactly the same settings, as these are mandated by the FCC.

See Styling Captions for FCC Compliance for more information.

---

DRM

Configuration options related to DRM for MPEG DASH (Playready, Widevine, Clearkey) and HLS streams (Fairplay).

JW Player includes the ability to add DRM to a specific playlist source. Using this method will allow your browser to choose the correct DRM method when multiple DRM types are configured. We highly suggest updating any configurations to use this new method.

For more information regarding DRM, and for examples, please view our support article.

drm.playready

Playready DRM is specific to Internet Explorer 11 and Edge on Windows 8.1 or higher operating systems.

drm.widevine

Widevine DRM is specific to Google Chrome on non-iOS devices. Widevine will also function on Firefox browsers for desktop systems.

drm.[widevine/playready].headers

Adding customized HTTP header data to license requests is possible with the "headers" configuration. This replaces the static "customData" configuration option in both widevine and playready scenarios. It is also possible to add multiple custom http headers by including multiple objects in the "headers" array.

DRM can be configured in the following way:

drm: {
  playready: {
    url: "mydrmserver.com",
    headers: [{
      name: "customData",
      value: "hereismycustomdatastring"
    }]
  }
}

In previous versions, adding "customData" would look like the following:

drm: {
  playready: {
    url: "mydrmserver.com",
    customData: "hereismycustomdatastring"
  }
}

drm.fairplay

JW Player includes configuration options for custom Fairplay integrations. For more information and examples regarding custom Fairplay DRM integrations, please view our support article.

drm.clearkey

A basic form of DRM that lists a decryption key inside of your player configuration. This is the least secure form of DRM, though it is the simplest to implement across browsers. There are no additional server resources required to decrypt content with this method. Clearkey is supported in both Chrome and Firefox browsers.

---

Float on scroll

Keeps the player visible when the original player location is scrolled out of view by minimizing it to a corner of the screen

On devices in portrait orientation, the player becomes fixed to the top of the page using its original dimensions.

When floating, the viewer can drag the player to reposition it. This functionality is disabled during ad playback.

By default, adding an empty floating object enables the floating player functionality and also sets dismissible: true.

Use the following CSS classes to customize the floating player:

• .jw-flag-floating .jw-wrapper
• .jw-float-icon

jwplayer("myElement").setup({
  playlist: "https://cdn.jwplayer.com/v2/playlists/1a2Bc3d4",
  ...
  floating: {
    dismissible: true
  }
});

---

Google Analytics (ga)

This object configures the built-in integration with Google Analytics.

Google's separate JavaScript library and config needs to be included in your page's head in order to send events with JW Player. Setting an empty "ga":{} options block will enable basic Google Analytics integration. No additional nested config options are required.

See Connecting Google Analytics for more information.

---

Internationalization

The intl object allows you to add new language translations, customize translations for player text and aria-label values, and access the benefits of the automated player localization feature.

For each language, use a two-letter or locale-specific language code to define language-specific objects. Use the code example and tables below to configure the intl object.

jwplayer("myElement").setup({
  ...
  intl: {
    
    // Quebec french sub-block
    fr-ca: {
      play: "reproduire"
    },
    
    // french sub-block
    fr: {
      replay: "Repeter",
      play: "jouer"
    },  
  
    // spanish sub-block
    es: {
      replay: "Repetir"
    },
  
    // frisian sub-block
    fy: {
      advertising: {
        loadingAd: "Advertinsje lade"
      }
    }
  }
});

intl.{lang}.advertising object

This object localizes the player text and ARIA labels of the advertising object.

intl.{lang}.errors object

This object localizes the error messages displayed in the player.

intl.{lang}.related object

This object localizes the player text and ARIA labels of the related object.

intl.{lang}.sharing object

This object localizes the player text and ARIA labels of the sharing object.

intl.{lang}.shortcuts object

This object localizes the keyboard shortcut menu items.

Transition table

Use the table below to copy old customization or translation values to the corresponding intl.{lang}.{property}.

---

Logo

This options block configures a clickable watermark that is overlayed on the video.

Example

jwplayer("myElement").setup({
  file: "http://example.com/myVideo.mp4",
  logo: {
    file: "/assets/jw-logo-red-46px.png",
    link: "https://www.jwplayer.com",
    hide: "true",
    position: "top-left"
  }
});

---

Playlists

The playlist is a powerful feature of JW Player, used to play multiple video or audio files.

A playlist can be either a string, referring to the URL of an RSS feed or JSON file, or an array of media objects.

Configuring Playlist as a String

jwplayer("myElement").setup({
  playlist: "http://example.com/myPlaylist.json"
});

playlist[]

Configuring Playlist as an Array

jwplayer("myElement").setup({
  playlist: [{
      file: "/assets/sintel.mp4",
      image: "/assets/sintel.jpg",
      title: "Sintel Trailer",
      mediaid: "ddra573"
    },{
      file: "/assets/bigbuckbunny.mp4",
      image: "/assets/bigbuckbunny.jpg",
      title: "Big Buck Bunny Trailer",
      mediaid: "ddrx3v2"
  }]
});

In addition to standard media information, (title, description, mediaid) it is also possible to insert additional metadata, using custom properties. This information must be entered inside of a playlist, and cannot be set directly inside of a setup block.

playlist[].adschedule[]

The playlist[].adschedule[] property is used for scheduling ad breaks throughout specific playlist items. You must define at least one ad break configured inside of the adschedule property. Each ad break should include an offset and a tag or vastxml.

jwplayer("myElement").setup({
  playlist: [{
      title: "One Media Item",
      description: "Only One media item in a playlist!",
      file: "myFile.mp4",
      mediaid: "ddrx3v2",
      image: "myImage.png",
      adschedule: [{
          offset: "pre",
          tag: "myAdTag.xml"
        },
        {
          offset: 10,
          tag: "myMidroll.xml"
      }]
  }]
});

playlist[].sources[]

Sources are inserted into playlist objects and are lists of files. Sources serve a dual purpose, depending on the files used:

• Use different file types: Alternate "fallback" media sources
• Use the same file type: Toggle quality with static video files

Alternate Media Sources

If using different file types, sources prioritizes which file to play only in the case when a provider (HTML5, HLS, or DASH) fails to load. If there is an error with a stream, the player will not failover to the next provider. In the example below, the player will attempt to play myVideo.m3u8 as a first choice.

In the event that a browser cannot play an m3u8, the player is intelligent enough to choose myVideo.mp4 instead. In the event that an mp4 cannot be played, the player will attempt the webm format before producing an error.

jwplayer("myElement").setup({
  playlist: [{
    title: "One Playlist Item With Multiple Sources",
    description: "Three Sources - One Playlist Item",
    image: "myImage.png",
    mediaid: "ddrx3v2",
    sources: [{
        file: "myVideo.m3u8"
      },{
        file: "myVideo.mp4"
      },{
        file: "myVideo.webm"
    }]
  }]
});

Sources with DRM

When using DRM, we highly suggest placing the drm block inside of the appropriate media source. This ensures the correct media and DRM pair gets chosen for the appropriate browser. For example:

  "sources": [{
      "file": "myFairplayStream.m3u8",
      "drm": {
        "fairplay": {
          "certificateUrl": "http://myfairplay.com/fairplay/cert",
          "processSpcUrl": "http://myfairplay.com/fairplay/ckc"
        }
      }
    },{
      "file": "myWidevineStream.mpd",
      "drm": {
        "widevine": {
          "url": "http://mywidevineurl.com/drm"
          }
      }
    },{
      "file": "myPlayreadyStream.mpd",
      "drm": {
        "playready": {
          "url": "http://myplayreadyurl.com/drm"
          }
      },{
      "file": "myClearkeyStream.mpd",
      "drm": {
        "clearkey": {
          "key": "1234clear5678key",
          "keyId": "fefde00d-efde-adbf-eff1-baadf01dd11d"
          }
      }
    }]

See our drm section for more information.

Manifest and Segment Requests with Custom Headers

You can add custom headers to media XHR requests by using the onXhrOpen callback. This gets executed after XMLHTTPRequest.open() and before XMLHTTPRequest.send() for HLS manifest, key and segment requests made by the player. This is not available in Safari browsers where HLS is played natively.

jwplayer().setup({
  playlist: [{
      sources: [{
          file: 'video.m3u8',
          onXhrOpen: function(xhr, url) {
            xhr.setRequestHeader('customHeader', 'customHeaderValue');
          }
      }]
  }]
})

Quality Settings for Video Files

In the event that a streaming technology like HLS or DASH cannot be used, listing video files of different qualities will enable a quality selection settings menu in the player. Compared to other streaming methods, it has the following drawbacks:

• No automatic switching, based on bandwidth or download speed
• Changing qualities may cause playback stuttering
• Pseudostreaming may need to be configured in cases where Flash is used

jwplayer("myElement").setup({
  playlist: [{
      title: "One Playlist Item With Multiple Qualities",
      description: "Two Qualities - One Playlist Item",
      sources: [{
          file: "myVideo-720p.mp4",
          label: "HD"
        },{
          file: "myVideo-480p.mp4",
          label: "SD"
      }]
  }]
});

playlist[].tracks[]

Tracks can be attached to media for three possible reasons: captions, thumbnails, or chapters. Thumbnail and chapter files must be in WEBVTT format. Captions accept WEBVTT, SRT, and DFXP format, though JW Player strongly suggests using WEBVTT if possible.

When using the playlist to load an RSS feed, these options are set in the feed. See the Media Formats Reference for a mapping of all playlist options to RSS format.

360 videos

Playlist configuration options described above can be used with spherical videos. Below are 360-specific options.

playlist[].variations

jwplayer("myElement").setup({
  playlist: [{
      file: "https://content.jwplatform.com/v2/media/zyXw4321",
      image: "https://cdn.jwplayer.com/thumbs/zyXw4321-720.jpg",
      variations: {
        images: [{
            image: "https://content.jwplatform.com/v2/media/zyXw4321/thumbnails/63a2zb84.jpg?width=720",
            id: "63a2zb84",
            weight: 0.25
          },
          {
            image: "https://content.jwplatform.com/v2/media/zyXw4321/thumbnails/oig5z424.jpg?width=720",
            id: "oig5z424",
            weight: 0.25
          },
          {
            image: "https://content.jwplatform.com/v2/media/zyXw4321/thumbnails/6067i00p.jpg?width=720",
            id: "6067i00p",
            weight: 0.25
          },
          {
            image: "https://content.jwplatform.com/v2/media/zyXw4321/thumbnails/w1zluc60.jpg?width=720",
            id: "w1zluc60",
            weight: 0.25
          }
        }]
      }
  }]
});

playlist[].variations.images

---

Related

This object controls the playlist appearance and behaviors.

---

Sharing

This options block controls a settings submenu with social sharing options: copy embed code, copy video link and share video to social networks.

Setting an empty "sharing":{} options block will enable the social sharing menu and icon in the control bar. Without the nested config options, it will show the page URL link with default sharing sites, but no embed code.

Available Built-In Social Networks

Example

jwplayer("myElement").setup({
  file: "http://example.com/myVideo.mp4",
  sharing: {
    sites: ["reddit","facebook","twitter"]
  }
});

See our Social Sharing support article for more information.

---

Skin

JW8 comes with 11 new skin configuration options out of the box. With such granular control over brand identity, it’s easier than ever to customize the player.

Color Customization

Color can be specified as a hex value, RGBA color value, or color name.^8.0+

Backward Compatability

JW8 continues to support the three color customization options from 7.x, skin.active, skin.inactive, skin.background, though the colors may map slightly differently in the new major version.

The table below shows how the three JW7 customization options map to the new JW8 options. You can use both JW7 and JW8 options in an 8 player, with the more specific JW8 configurations overriding JW7 ones when both apply to the same element. Note that there’s no JW7 mapping to the new skin.timeslider.rail option.

Custom Skins

For more information regarding custom skins, see our Branding documentation.