Configuration Options Reference

This article acts a reference to all configuration options JW Player supports. Configuration options tell a player instance which media to play and how to layout and behave on your page.

Table Of Contents

Introduction

JW Player contains a large number of configuration options. Some of these options (like width or file) are directly placed into an embed code. Other, more advanced options are grouped into config options blocks (like listbar or advertising). Here is an example setup that contains both flavors:

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

Web developers will recognize the JavaScript Object Notation (JSON) syntax of these setup blocks. While writing player setups, beware of common JSON requirements, like the need for a comma after all but the last element in a list.

Basic Options

These are the basic options for configuring the layout and playback behaviour of a player:

aspectratio
This option, used to setup JW Player for responsive design, is set to the video display aspect ratio, for example "16:9". When the width of the player changes, it then automatically scales its height accordingly. When the aspectratio is set, the height option is ignored. See Making JW Player Responsive for more info.
autostart
Automatically start playing the video on page load. Can be true or false (default). Autostart does not work on mobile devices (iOS and Android). See Autostarting Videos for more info.
controls
Whether to display the video controls (controlbar, display icons and dock buttons). Can be false or true (default). When false, use the JavaScript API to control the chromeless player.
file
URL to a single video file, audio file, YouTube video or live stream to play. See for example the MP4 Video Embed article. Note this option is ignored if the playlist configuration block is used.
height
Height of the player in pixels. We recommend setting this to at least 180, so all UI elements will fit. However, it can be set to a small size (e.g. 40) for audio-only playback. Defaults to 270.
image
URL to a poster image to display before playback starts. For audio-only media, the poster image stays visible during playback. See for example the MP4 Video Embed article. Note this option is ignored if the playlist configuration block is used.
mute
Whether to have the sound muted on startup or not. Can be false (default) or true. Mute does not work on mobile devices (iOS and Android). See Autostarting Videos for more info.
primary
Which rendering mode to use for rendering the player if both are available. Can be html5 (default) or flash.
repeat
Whether to loop playback of the playlist or not. Can be true (keep playing forever) or false (stop playback when completed). Defaults to false.
skin
Which skin to use for styling the player (the default skin is named Six). Is set to either the name of one of our 8 Pro skins (e.g. five) or the URL of a custom skin (e.g. http://example.com/skin.xml).
width
Width of the player. Defaults to 480 pixels. We recommend setting this to at least 320 pixels, since otherwise certain UI elements may not fit. It can also be set to "100%" to enable responsive design, in combination with the aspectratio option.
androidhls
The default value for this flag is false. Set this value to true if you would like the JW Player to play HLS video sources on Android devices 4.1 and greater.

The Playlist

The playlist is a powerful feature of JW Player, used to load multiple items of content into a single player. For each item, the playlist can carry metadata, multiple media sources (e.g. for HD toggle) and multiple text tracks (e.g. for CC toggle).

The playlist can act both as an option and as a block. In the first case, the playlist is pointed to an RSS feed that contains all content items and their properties. For example:

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

When acting as a block, the playlist contains an array of items instead of a straight options list. Also, every playlist item in turn contains array for sources and/or tracks. Here is a quick example setup with a playlist block containing one item with one media source and one text track:

jwplayer("myElement").setup({
    playlist: [{
        image: "/assets/sintel.jpg",
        sources: [{ 
          file: "/assets/sintel.mp4"
        }],
        title: "Sintel Movie Trailer",
        tracks: [{
          file: "/assets/captions.vtt"
        }]
    }]
});

The following playlist item options are available:

playlist[].title
Title of the item. It is displayed inside the play icon before playback starts, plus in the listbar.
playlist[].description
Short description of the item. It is displayed in the listbar.
playlist[].mediaid
Unique identifier of this item. Used by advertising, analytics and discovery services.
playlist[].image
Poster image representing the item. Displayed before and after playback, plus in the listbar.
playlist[].sources[].file
URL to the video file, audio file, YouTube video or live stream of this playlist item source. See the HD Quality Toggle article for an example setup.
playlist[].sources[].label
Label of the media source, displayed in the manual HD selection menu. Set this if you have more than 2 qualities of your video. See below for more info.
playlist[].sources[].default
Set this to true for the media source you want to play on startup. If this isn't set for any source, the first one is used. Note the option should be placed in quotes because "default" is a reserved JavaScript keyword in IE8.
playlist[].sources[].type
Media type of the source. Is only needed when the file property does not contain a recognized file extension (like .mp4 for mp4). The Media Formats Reference lists all supported types.
playlist[].tracks[].file
URL to the captions, chapters or thumbnails text track file. See Adding Closed Captions for an example setup.
playlist[].tracks[].kind
The kind of text track. Possible values are captions (the default), chapters and thumbnails.
playlist[].tracks[].label
Label of the text track.Is only used in setups with multiple captions, where the label is displayed in the CC selection menu.
playlist[].tracks[].default
Only for captions. Set this to true if you want the captions track to display by default. If no default is set, captions are not shown on startup. Note the option should be placed in quotes because "default" is a reserved JavaScript keyword in IE8.
playlist[].adschedule[].adbreak[]
This is used to set a unique ad schedule per playlist item.
playlist[].adschedule[].adbreak[].offset
This is used to set the offset for each adbreak within the ad schedule of a playlist item.
playlist[].adschedule[].adbreak[].tag
This is used to set the ad tag for each adbreak within the ad schedule of a playlist item.

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

Listbar Block

This options block configures a sidebar that displays all playlist entries in a scrollable list. It is available in all player editions.

listbar.position
Position of the listbar relative to the video display. Can be bottom (below the display), none (no bar; the default) or right (to the right of the display).
listbar.size
Width (if position is right) or height (if position is bottom) of the listbar. This is basically the amount of pixels the bar "steals" from the video window. Is 180 by default.
listbar.layout
Layout of the playlist items in the listbar. Can be basic (only title) or extended (image, title and description). The default is extended.

See Display a Playlist Sidebar for more information.

Captions Block

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. It is available in all player editions.

captions.color
Hex color of the captions text. Is ffffff by default.
captions.fontSize
Size of the captions text. Is 15 points by default.
captions.fontFamily
Family of the captions text. Is sans by default.
captions.fontOpacity
Alpha value of the captions text. Is 100 by default.
captions.backgroundColor
Hex color of the caption characters background. Is 000000 by default.
captions.backgroundOpacity
Alpha value of the caption characters background. Is 75 by default.
captions.edgeStyle
Method by which the captions characters are separated from their background. Is none by default.
captions.windowColor
Hex color of the background of the entire captions area. Is 000000 by default.
captions.windowOpacity
Alpha value of the background of the entire captions area. Is 0 by default.

See Styling Captions for FCC Compliance for more information.

RTMP Block

This options block controls the more esoteric functionalities of the RTMP streaming protocol. It is available in all player editions.

rtmp.bufferlength
This option controls how much data to maintain in the video buffer. A small buffer means faster starts/seeks, but a higher chance of re-buffering. The default is 3 seconds.
rtmp.subscribe
This option enables the FC Subscribe mechanism use by older streaming servers to manage load balancing. The default is false (don't use it).
rtmp.securetoken
This option, supported for older Wowza instances, provides a security token to JW Player, which then amends this option to the RTMP application URL. Is empty by default.

See Using RTMP Streaming for more information.

Logo Block

This options block configures a clickable watermark that is displayed over the video. It is available in the Pro, Premium and Ads editions.

logo.file
Location of an external JPG, PNG or GIF image to be used as watermark (e.g. /assets/logo.png). We recommend using 24 bit PNG images with transparency, since they blend nicely with the video.
 
logo.hide
By default (false), the logo remains visible all the time. When this option is set to true, the logo will automatically show and hide along with the other player controls.
logo.link
HTTP URL to jump to when the watermark image is clicked (e.g. http://example.com/). If it is not set, a click on the watermark does nothing in particular.
logo.margin
The distance of the logo from the edges of the display. The default is 8 pixels.
logo.position
This sets the corner in which to display the watermark. It can be top-right (the default), top-left, bottom-right or bottom-left. Note the default position is preferred, since the logo won't interfere with the controlbar, captions, overlay ads and dock buttons.

See Branding Your Player for more information.

Sharing Block

This options block controls an overlay with social sharing options: copy embed code, copy video link and share video to Facebook, Twitter & Email. It is available in the Pro, Premium and Ads player editions.

sharing
Setting an empty sharing{} options block will already enable the social sharing overlay. Without the nested config options, it will show the page URL link, but no embed code.
sharing.link
URL to display in the video link field. If no link is set, the URL of the current page is used. Example:
http://example.com/videos/12345/
sharing.code
Embed code to display in the embed code field. If no code is set, the field is not shown. Example:
<iframe src="http://example.com/12345.html" />
sharing.heading
Short, instructive text to display at the top of the sharing screen. The default is Share Video. Also is displayed as a tooltip for the sharing icon.

See Social Sharing Overlay for more information.

GA Block

This options block configures the built-in integration with Google Analytics. It is available in the Premium and Ads player editions.

ga
Setting an empty ga{} options block will already enable the Google Analytics integration. None of the nested config options are required. Do note the Google Analytics JavaScript library needs to be included in your page.
ga.idstring
By default, JW Player 6 sets the action of a play/complete event to the file playlist property. This option allows setting the action to a different playlist item property, like title or mediaid.
ga.trackingobject
By default, JW Player 6 presumes the Google Analytics library is available in JavaScript as a global variable called _gaq. This is the variable Google Analytics uses in all its examples and documentation. If you gave the Google Analytics object a different name (e.g. pageTracker), set this option to notify the JW Player.

See Connecting Google Analytics for more information.

Related Block

This options block controls an overlay with related videos. It is available in the Premium and Ads player editions.

related.file ( required )
Location of an RSS file with related videos, e.g. http://example.com/related.xml.
related.onclick
This determines what to do when the user clicks a thumbnail: jump to the page URL of the related video (link) or play the related video inline (play). The default is link.
related.oncomplete
Whether to display the related videos screen when the video is completed. When set to false, the screen does not automatically pop up. It is true by default.
related.heading
Single line heading displayed above the grid with related videos. Generally contains a short call-to-action. The default is Related Videos. This heading also displays as a tooltip on the related icon.
related.dimensions
This sets the width and height of each thumbnail in pixels. The default is 140x80. Set this to a different value to make the thumbnails larger (e.g. 240x160) or smaller (e.g. 120x70). Note the overlay always renders a fixed 10px spacing between the thumbs.

See Display Related Videos for more information.

Advertising Block

This options block configures the video advertising capabilities of JW Player. It is available in the Ads edition.

advertising.client
Sets which advertising system you are using. Can be vast (for IAB VAST/VPAID/VMAP ads) or googima (for Google Interactive Media Ads).
advertising.tag
Set this to URL of the VAST or IMA pre-roll ad tag to play. Use the advertising.schedule option to setup midrolls, postrolls and overlays. See Basic Preroll Video Ads for more info.
advertising.schedule
Use this option to load an entire advertising schedule to JW Player, containing multiple ads. The option can be the URL to a VMAP schedule or an inline JSON block with ads. Note the advertising.tag options is ignored if this option is set. See Scheduling Ad Breaks for more info.
advertising.admessage
During linear ad playback, JW Player shows the following message in the controlbar: Ad: your video resumes in XX seconds. Use this option to customize that message.
advertising.companiondiv
This is a configuration block with 3 properties: id, width and height. Set these to have JW Player load companion ads from your VAST/IMA tag into your page. See Companion Ads for more info.
advertising.skipoffset
By default, linear video ads cannot be skipped. Set this option to the number of seconds in the ad, after which you want an ad to be skipped. See Skipping Ads for more info.

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

SiteCatalyst Block

This options block configures the built-in integration with Adobe SiteCatalyst. It is available in the Ads player edition.

sitecatalyst
Setting an empty sitecatalyst{} options block will enable the Adobe SiteCatalyst integration. None of the nested config options are required. Do note the Adobe SiteCatalyst JavaScript library needs to be included in your page.
sitecatalyst.mediaName
By default, JW Player always sends the title property of an item to SiteCatalyst. If the title is not set, JW Player uses the file property, stripped of its filepath and querystring. If you want to use a custom mediaName, use this option to set it.
sitecatalyst.playerName
By default, JW Player always sends the DOM ID of the player to siteCatalyst. If you want to use a custom playerName, use this option to set it.

See Connecting Adobe SiteCatalyst for more information.

Other Options

These are more obscure one-off options, available to tweak the internals of JW Player:

  • none (keep original dimensions)
  • exactfit (stretch disproportionally),
  • uniform (stretch proportionally; black borders) 
  • fill (stretch proportionally; parts cut off)
abouttext
Custom text to display in the right-click menu. Can only be set for the Pro, Premium and Ads editions. The default is About JW Player 6.x.xxx.
aboutlink
Custom URL to link to when clicking the right-click menu. Can only be set for the Pro, Premium and Ads editions. The default is http://www.jwplayer.com/learn-more/.
displaytitle
By default, JW Player will display the title of an audio/video file inside the play icon in the middle of the display when set. If you have set a title, but don't want it to display here, set this option to false.
fallback
By default, JW Player renders a nice download link to the video if HTML5/Flash are not supported. Set this option to false to disable this (the original HTML is not touched).
flashplayer
Alternative location from where to load jwplayer.flash.swf. By default, this file is in the same location as jwplayer.js. In certain edge cases though (e.g. CDN-ing the players), you may want to host them separately.
html5player
Alternative location from where to load jwplayer.html5.js. By default, this file is in the same location as jwplayer.js. In certain edge cases though (e.g. CDN-ing the players), you may want to host them separately.
startparam
Querystring parameter for seeking to not-yet-download portions of FLV or MP4 files in Flash mode. Not needed for HTML5 (where this works by default). See Pseudostreaming in Flash for more info.
stagevideo
Set this flag to false to disable GPU-accelerated image compositing in the Flash rendering mode. With some combinations of H264 parameters and GPU cards, we see inconsistent issues with rendering of the video image. Disabling Stage Video fixes this issue.
stretching
How to resize images and video to fit the display. If stretching is not set within your embed, JW Player defaults to uniform.
uniform - Will fit JW Player dimensions while maintaining original aspect ratio (Black bars)

exactfit - Will fit JW Player dimensions without maintaining aspect ratio

fill - Will stretch and zoom video to fill dimensions, while maintaining aspect ratio

none - Displays the actual size of the video file. (Black borders)




 
 
 
Please sign in to leave your feedback for this article.

Still don't have JW Player? Get It Here