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

PropertyDescription
aspectratio string
                                                                     
Maintains proportions when width is a percentage. Will not be used if the player is a static size.
Must be entered in ratio "x:y" format.
controls booleanWhether to display the video controls (control bar and display icons)

Default: true
displaydescription booleanConfigures if the description title of a media file should be displayed

Default:true
displayHeading 8.6.0+ boolean(Outstream only) Controls if heading above the outstream player is displayed

Possible values include:

false: No heading is shown

true: Heading is shown with default text: Advertisement.

Use intl.{lang}.displayHeading to customize or localize text.

Default: false
displayPlaybackLabel 8.6.0+ booleanEnables call-to-action text beneath the play button on the player idle screen.

When set to true, you can potentially see up to a 5% increase in the number of times viewers click the play button to watch a video.

The default call-to-action text is "Play." You can also localize this message for your viewers.

Default: false
displaytitle booleanConfigures if the title of a media file should be displayed

Default: true
height numberThe desired height of your video player (in pixels). Should be omitted when aspectratio is configured

Default: 360
horizontalVolumeSlider 8.18.4+ booleanDisplays the volume slider horizontally within the control bar

If the player is in audio mode, a horizontal slider will always be displayed.

By default, the volume slider is displayed as a vertical slider above the control bar.

Default: false
qualityLabels arrayBy default, the JW Player will set video quality levels using information from the manifest files. Use this configuration option to apply a custom quality label to a desired bandwidth in kbps, works for HLS and DASH. For example: qualityLabels:{"2500":"High","1000":"Medium"}
nextUpDisplay booleanConfigures whether the Next Up modal is displayed
renderCaptionsNatively 8.0.1+ boolean(Chrome and Safari only) Determines if the renderer of the browser or of the player is used to display captions

Possible values include:

true: Captions render using the renderer of the browser.

false: Captions render using the renderer of the player.

Note: See also: captions

Default:
   • false (Chrome)
   • true (Safari)
stretching stringResize images and video to fit player dimensions. See graphic below for examples
"uniform" — Fits JW Player dimensions while maintaining aspect ratio
"exactfit": Will fit JW Player dimensions without maintaining aspect ratio
"fill"— Will zoom and crop video to fill dimensions, maintaining aspect ratio
"none" — Displays the actual size of the video file. (Black borders)

Default: uniform
width number | stringThe desired width of your video player (in pixels or percentage)

Default: 640

Stretching Examples

480480

Stretching examples



Behavior

PropertyDescriptionDefault
aboutlink stringCustom URL to link to when clicking the right-click menuhttps://www.jwplayer.com/learn-more
abouttext stringCustom text to display in the right-click menu-
allowFullscreen boolean 8.22.0+When set to false, fullscreen functionality is completely disabled in the player including tapping, clicking, keyboard shortcuts, and API access. Can be re-enabled through the corresponding API method.true
autostart stringWhether the player will attempt to begin playback automatically when a page is loaded. Set to 'viewable' to have player autostart if 50% is viewable.false
defaultBandwidthEstimate 8.3.0+ numberWhen set, suggests an initial bandwidth estimate (in bits per second) which overrides the default bandwidth estimate of the player for new viewers to your site

Use case: New users to your site may experience low-quality video for several seconds before the quality adapts to the connection speed at which content is delivered. This speed may be limited by their connection speed. In this case, you would want to confirm that the majority of your viewers have fast connections.

NOTE: Since this property sacrifices player performance for video quality, it is strongly recommended not to set this property. The player is optimized to select the best bandwidth after several seconds.
50000
generateSEOMetadata 8.26.1+ booleanEnables Google SEO Optimization.false
liveSyncDuration 8.12.0+ numberDefines the distance from the live edge in seconds in the following scenarios:

• The player attempts to start a live or DVR stream
• A user clicks the Live button to return to the live content of the stream

This property can accept any value between 5-30. Leave blank in 8.19.0+ for the player to determine target latency based on the stream.
defaults to 25 <8.19.0
mute booleanConfigures if the player should be muted during playback

If a user overrides this property, the user’s action will persist for the duration of the user session. For example, if all players are configured with mute: true and a user unmutes a player, each subsequent player that the user encounters will start unmuted.
false
nextupoffset 8.9.0+ number | stringConfigures when the Next Up card displays during playback

A positive value is an offset from the start of the video. A negative value is an offset from the end of the video. This property can be defined either as a number (-10) or a percentage as a string ("-2%")
-10
pipIcon 8.21.0+ stringAdds a Picture in Picture icon and right click menu options to supported desktop browsers only

Setting this option to disabled removes this icon. You can also hide this icon with CSS.
enabled
playbackRateControls booleanWhether to display a settings menu to adjust playback speed. If true, the pre-defined options available in the menu are 0.5x, 1x, 1.25x, 1.5x, and 2x. An array can be passed to customize the menu options using playbackRates. Note: This feature is not currently supported in Android with HLS streams.false
playbackRates 8.0+ array of numbersCustom playback rate options to display in the settings menu.[0.25, 0.75, 1, 1.25]
playlistIndex 8.15.0+numberItem within a playlist to start playback

Within the playlist, the first index is 0.

If the playlistIndex value is negative, the index starts counting from the end of the playlist. A negative value cannot exceed the absolute number of playlist items. For example, in a playlist of 5 items, "playlistIndex": -5 is the lowest acceptable negative number.

This property applies to JSON, RSS, and array playlists.
-
repeat booleanConfigures if the player should loop content after a playlist completesfalse


Media

📘

The following properties are related to media that is loaded into the player.

You should use the playlist object to define the content that is loaded into the player.

If you have a single content item to load in a player, you can use the following properties to define this item directly within jwplayer().setup. If you are planning on using multiple media items, these can also be used inside of a playlist array.

PropertyDescriptionDefault
file string
                                                                     
URL to a single video file, audio file, or live stream to play

Can also be configured inside of a sources array
-
description stringA description of your video or audio item-
image stringURL to a poster image to display before playback starts.-
mediaid stringUnique identifier of this item. Used by advertising, analytics and discovery services-
title stringThe title of your video or audio item-
type stringDefining the video file type is required when using a media file url that does not have an extension.

Possible values:

• aac
• mp4
• f4a
• f4v
• hls
• m3u
• m4v
• mov
• mp3
• mpeg
• oga
• ogg
• ogv
• vorbis
• webm
-

📘

YouTube and RTMP media formats are no longer supported.8.0+



Rendering and Loading

PropertyDescriptionDefault
base stringConfigures an alternate base path for skins and providers/
flashplayer < 8.19.0 string

As per Adobe, Flash Player is no longer supported.
Specifies an alternate directory of jwplayer.flash.swf/
hlsjsdefault booleanMakes HLSjs the default provider when using Chrome for Android. Disable to use the browser's default provider.true
liveTimeout 8.1.9+ numberConfigures how a stalled live manifest is handled

This property accepts a positive number in seconds, but values between 1-10 are ignored. Set this property to 0 to configure a stream to never time out.

The player will continue requesting manifests until it times out. If a live manifest does not update after being requested for longer than liveTimeout, the stream will end with an error event. If you want a stream to end immediately, include an end tag in the manifest.

This configuration option only handles stalled manifests, not issues with segment loading. A chunk that results in a 404, for example, will still error out.
30
loadAndParseHlsMetadata booleanTo enable HLS playback in Safari to trigger the same metadata events that are triggered during HLS playback in Chrome, the player will make additional requests to HLS playlists provided they contain PROGRAM-DATE-TIME tags that the player can use to embed timed metadata.

Possible values include the following:

true: The player loads and parses the playlist manifest as it is loaded by Safari and synchronizes the results with media playback. This will also result in multiple manifest requests

false: Prevents the player from sideloading live HLS manifests to parse out-of-band manifest metadata that Safari does not expose like DATERANGE, CUE-OUT, CUE-IN, and DISCONTINUITY tags.
true
preload stringTells the player if content should be loaded prior to playback. Useful for faster playback speed or if certain metadata should be loaded prior to playback:

none: Player will explicitly not preload content. (Recommended if you are concerned about excess content usage.)
metadata: Loads the manifest and buffers a maximum of one segment of media for HLS and Dash streams.
auto: Loads the manifest and buffers approximately 30 seconds worth of media segments.
metadata