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.
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"
}]
});
Property | Description |
---|---|
file* string | (Required) Media file specified in your setup or sources |
adschedule object | Schedule advertising for a specific media file See: playlist.adschedule |
description string | Short description of the item This description is displayed below the title. This can be hidden with the displaydescription option. |
image string | Poster image URL (displayed before and after playback) |
link string | If defined, when the video is shared from the player, the recipient will be referred to this URL |
mediaid string | Unique identifier of the media item Used by advertising, analytics and discovery services. |
minDvrWindow number | (HLS-only) In seconds, the minimum amount of content in an M3U8 required to trigger DVR mode NOTE: To always display DVR mode, set this property to 0. The default value is 120. |
recommendations string | URL to a feed that contains related items for a particular playlist item |
sources array | Used for quality toggling and alternate sources See: playlist.sources |
starttime number | Time in seconds to start a media item NOTE: When used with an MP4 video file, both seek and seeked events are triggered. Neither event is triggered when used with a DASH or HLS stream. |
title string | Title of the item This is displayed inside of the player prior to playback, as well as in the visual playlist. This can be hidden with the displaytitle option |
tracks array | Include captions, chapters, and thumbnails for media See: playlist.tracks |
withCredentials boolean | If true, "withCredentials" will be used to request a media file rather than CORS |
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.
There are two options available to configure ad break schedules:
- Manual ad break array: When using ad breaks you must define at least one ad break configured inside of the
adschedule
property. Each ad break should include anoffset
and atag
orvastxml
. - VMAP: You may also load an ad schedule from an external VMAP XML (string). See advertising.schedule and the code sample below for more information.
playlist: [{
file: "https://cdn.jwplayer.com/manifests/Q7TuS9Y9.m3u8",
adschedule: "https://playertest.longtailvideo.com/adtags/vmap2-nonlinear.xml"
}]
Property | Description |
---|---|
offset string OR number                                                                     | (Required) When to play the configured ad tag • pre : Ad plays as a preroll • post : Ad plays as a postroll• xx% : (VAST only) Ad plays after xx% of the content• number : Ad plays after the specified number of seconds |
tag string OR array | (Required) When a string, URL of the ad tag for VAST and IMA plugins, or a string place holder for FreeWheel (VAST/IMA plugins) When an array, URLs of the VAST ad tags to be used as fallbacks in the event that one or multiple ad tags fail to render When a VAST tag is used, ad tag targeting macros can be added to define features such as GDPR consent. Do not use this property and playlist[].adschedule[].vastxml within the same ad break. |
type string | Property indicating the format of the ad to be served within the ad break • linear : Video ad that interrupts video content playback • nonlinear : Static display ad that overlays a portion of the player and does not interrupt playback. No advertisting cuepoint is shown for this ad break.If a mix of linear and non-linear ads will serve within an ad break, do not set this property. The player will interrupt video playback for linear ads and will not interrupt video playback for non-linear ads. |
vastxml string | VAST XML ad tag that is requested during the configured ad break Do not use this property and advertising.schedule[].tag within the same ad break. |
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');
}
}]
}]
})
For HLSjs playback only.
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
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"
}]
}]
});
Property | Description |
---|---|
file string | (Required) URL to the video file, audio file, YouTube video or live stream of this playlist item source. |
default boolean | 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 |
drm object | An object containing DRM information for a particular source |
label string | Label of the media source, displayed in the manual quality selection menu. Set this if you have more than 2 qualities of your video. |
type string | Forces a media type. Only required when a file extension is missing or not recognized (Using .php or certain tokens, for example) |
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 and SRT format, though JW Player strongly suggests using WEBVTT if possible.
Property | Description | Default |
---|---|---|
default boolean                                                                     | Only for captions. Set this to true if you want a captions track to display by default | - |
file string | URL to the captions, chapters or thumbnails text track file. See Adding Closed Captions for an example setup. | - |
kind string | The kind of text track. "captions": Captions that display during video playback. "chapters": Places markers on the video er, displaying different sections "thumbnails": A list of thumbnails that appear when the mouse cursor hovers on the timeslider. | "captions" |
label string | Label of the text track. Is only used in setups with multiple captions, where the label is displayed in the CC selection menu. | index |
When using the playlist to load an RSS feed, these options are set in the feed. See the Adaptive streaming reference for a mapping of all playlist options to RSS format.