Configuration Options Reference

Home / Customization / Configuration Options Referenc...

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.

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 oradvertising). 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 playlistconfiguration 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-rightor 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 Adsplayer 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 Adseditions. 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 asjwplayer.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 asjwplayer.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 touniform.

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