Playlists

The playlist is a powerful feature of the JWP player, used to play multiple video or audio files.

A playlist can be defined as one of the following data types:

string that refers to the URL of an RSS feed or JSON file
array that contains multiple media objects

playlist

The value of playlist is a single URL that refers to the RSS feed or JSON file containing the primary file, related assets, and metadata of each media item.

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

📘
We recommend setting the playlist value to a URL containing the list of media items contained in the playlist unless you have a unique use case, such as creating a playlist from externally-hosted (non-JWP) media that is not in a feed.

Dashboard

Follow these steps to create a playlist with JWP-hosted media from your JWP dashboard:

Create one of several types of customizable playlists through your JWP dashboard.
On the Developers tab for the playlist, copy the JSON URL.
Define the playlist property with the JSON URL.

API

Follow these steps to create a playlist with JWP-hosted media from the JWP API:

Create one of several types of customizable playlist through the API:

Copy the id from the API response.
In the following URL, replace the {PLAYLIST_ID} placeholder with the id value.
```
https://cdn.jwplayer.com/v2/playlists/{PLAYLIST_ID}
```

playlist[]

The value of playlist is an object that enables defining the primary file, related assets, and metadata of each media item.

jwplayer("myElement").setup({
    playlist: [
        {
            "file": "/assets/sintel.mp4",
            "mediaid": "d0dra573",
            "title": "Basic Playlist",
            "description": "A basic playlist item with a media item not hosted by JWP.",
            "image": "/assets/sintel.jpg",
            "starttime": 10,
            "adschedule": [...],
            "tracks": [...]
        },
        {
            "sources": [...],
            "mediaid": "ddr1x3v2",
            "title": "Playlist Item with Multiple Sources or Qualities",
            "description": "A playlist item with multiple media sources and a custom header and DVR window for the HLS source.",
            "image": "/assets/bigbuckbunny.jpg"
        },
        {
            "file": "/assets/bigbuckbunny_live_feature.m3u8",
            "mediaid": "ddrx3v3",
            "title": "Live Streaming Item with FreeWheel Asset ID",
            "description": "A live streaming playlist item that has a FreeWheel asset ID and streamtype within the freewheel object.",
            "fwassetid": "big_buck_bunny_live",
            "freewheel": {...},
            "streamtype": "live"
        }
    ]
});

Property	Description
file* string	(Required) Media file specified in your setup or sources
fwassetid* string	(FreeWheel - Required)FreeWheel identifier for content configured in FreeWheel MRM Example: `DemoVideoGroup.01`
adschedule string \| array	Ad break scheduling for specific media items in a playlist 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.
freewheel object	(FreeWheel) FreeWheel ad client settings See: playlist[].freewheel
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 This value is 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 To always display DVR mode, set this property to `0`. The default value is `120`.
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.
streamtype string	(FreeWheel) Indicates if the media item is a live streaming asset When using this property, set the value to `live`. NOTE: Do not use this property and `playlist[].freewheel.streamtype` within the same media item object.
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	The captions, chapters, or thumbnails for a media item
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.

A playlist ad schedule can be defined as one of the following data types:

string that refers to the URL of an ad tag
array that contains multiple ad break objects

playlist.adschedule

You can load an ad schedule from an external VMAP XML (string).

"adschedule": "https://playertest.longtailvideo.com/adtags/vmap2-nonlinear.xml"

playlist.adschedule[]

When using ad breaks 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.

"adschedule": [
    {
        "offset": "pre",
        "tag": "myAdTag.xml"
    },
    {
        "offset": 10,
        "tag": "myMidroll.xml",
        "type": "nonlinear"
    }
]

Property	Description
offset* string \| number	(Required) When to play the configured ad tag Possible Values: (number): (number) Ad plays after the specified number of seconds (xx%) (string - VAST only) Ad plays after xx% of the content `pre`: (string) Ad plays as a pre-roll `post`: (string) Ad plays as a post-roll
tag* string \| array	(Required) When a string, URL of the ad tag for VAST and IMA plugins, or a string place holder for FreeWheel (VAST/IMA) 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. NOTE: 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 Possible Values: `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 NOTE: Do not use this property and `advertising.schedule[].tag` within the same ad break.

playlist[].freewheel

"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",
    "streamtype": "live"
}

Property	Description
adManagerURL string	URL of the FreeWheel Ad Manager Example: `https://mssl.fwmrm.net/libs/adm/6.24.0/AdManager.js` NOTE: Your FreeWheel Solution Engineer or Account Representative can provide you with a versioned AdManager URL.
networkid number	FreeWheel identifier of a network Example: `96749`
profileid string	FreeWheel identifier of a particular application environment Example: `global-js`
sectionid string	FreeWheel identifier of a location where the video content plays Example: `DemoSiteGroup.01`
serverid string	URL of FreeWheel ad server Example: `http://demo.v.fwmrm.net/ad/g/1`
streamtype string	(FreeWheel) Indicates if the media item is a live streaming asset When using this property, set the value to `live`. NOTE: Do not use this property and `playlist[].streamtype` within the same media item object.

playlist[].sources[]

You can use sources[] to define multiple sources or qualities of the media item.

Source Usage Description

Multiple Sources If you list different file types in sources[], the player will use the order of media files to determine the failover sequence if a provider (HTML5, HLS, or DASH) fails to load a file.

NOTE: If a file loads successfully but encounters an error during streaming, the player will not switch to the next provider in the list.

Multiple Qualities If you list different file qualities of the same file type in the sources[], the player will list the various quality options for a viewer to select from the quality menu.

This approach is useful when streaming technologies like HLS or DASH cannot be used.

NOTE: When multiple qualities are defined, the player will not automatically switch between qualities to accommodate bandwidth or download speeds.

Source Usage	Description
Multiple Sources	If you list different file types in `sources[]`, the player will use the order of media files to determine the failover sequence if a provider (HTML5, HLS, or DASH) fails to load a file. NOTE: If a file loads successfully but encounters an error during streaming, the player will not switch to the next provider in the list.
Multiple Qualities	If you list different file qualities of the same file type in the `sources[]`, the player will list the various quality options for a viewer to select from the quality menu. This approach is useful when streaming technologies like HLS or DASH cannot be used. NOTE: When multiple qualities are defined, the player will not automatically switch between qualities to accommodate bandwidth or download speeds.

"sources": [
    {
        "file": "myVideo.m3u8",
        "onXhrOpen": function(xhr, url) {
            xhr.setRequestHeader('customHeader', 'customHeaderValue');
        }
    },{
        "file": "myVideo.mp4"
    },{
        "file": "myVideo.webm"
    }
]

"sources": [
    {
        "file": "myVideo-720p.mp4",
        "label": "HD"
    },{
        "file": "myVideo-480p.mp4",
        "label": "SD",
        "default": true
    }
]

Property	Description
file* string	(Required) URL to the video file, audio file, YouTube video, or live stream of this playlist item source
default boolean	(Multiple Qualities) Sets a specific media source to play on startup when set to `true`. When this property is not set for any quality source, the source listed first is used.
drm object	DRM information for a particular source See: `playlist[].sources[].drm`
label string	(Multiple Qualities) Label of the media source, displayed in the manual quality selection menu Set this if you have more than two qualities of your video.
onXhrOpen function	(Multiple Sources) Allows adding custom headers to media XHR requests for HLSjs playback You can use the `onXhrOpen` callback to add custom headers to media XHR requests. This callback gets executed after `XMLHTTPRequest.open()` and before `XMLHTTPRequest.send()` for HLS manifest, key, and segment requests made by the player. IMPORTANT: This is not available in Safari browsers where HLS is played natively.
type string	(Multiple Qualities) Forces a media type NOTE: This property must defined only when a file extension is missing or not recognized, such as using .php or certain tokens.

playlist[].sources[].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.

"sources": [
    {
        "file": "myClearkeyStream.mpd",
        "drm": {
            "clearkey": {
                "key": "1234clear5678key",
                "keyId": "fefde00d-efde-adbf-eff1-baadf01dd11d"
            }
        }
    }
]

"sources": [
    {
        "file": "myFairplayStream.m3u8",
        "drm": {
            "fairplay": {
                "certificateUrl": "http://myfairplay.com/fairplay/cert",
                "processSpcUrl": "http://myfairplay.com/fairplay/ckc"
            }
        }
    }
]

"sources": [
    {
        "file": "myPlayreadyStream.mpd",
        "drm": {
            "playready": {
                "url": "http://myplayreadyurl.com/drm"
            }
        },
    }
]

"sources": [
    {
        "file": "myWidevineStream.mpd",
        "drm": {
            "widevine": {
                "url": "http://mywidevineurl.com/drm"
            }
        }
    }
]

Property	Description
certificateUrl string	(Fairplay) Path to the certificate which is part of the session data used to initialize the `keySession.certificateUrl`
key string	(Clearkey) Key required to decrypt DRM content
keyId string	(Clearkey) Key ID specified in the mpd's `default_KID` value
processSpcUrl function \| string	(Fairplay) Path to the license server If the URL needs to be constructed dynamically, a custom function can be passed to this configuration option which returns the URL
url string	(Playready, Widevine) URL of the license server

See our drm section for more information.

playlist[].tracks[]

A track can be attached to media for captions, thumbnails, or chapters:

Thumbnail and chapter files must be in WEBVTT format.
Captions accept WEBVTT and SRT format. JWP strongly suggests using WEBVTT format.

"tracks": [
    {
        "file": "https://cdn.jwplayer.com/tracks/abcd1234.vtt",
        "kind": "chapters",
        "label": "Big Buck Bunny"
    },
    {
        "file": "https://cdn.jwplayer.com/tracks/abce1235.vtt",
        "kind": "captions",
        "label": "English"
    },
    {
        "file": "https://cdn.jwplayer.com/strips/J8iBKS1l-120.vtt",
        "kind": "thumbnails"
    }
]

Property	Description
default boolean	(Captions only) Sets a specific captions track to display by default when set to `true`
file string	URL of the captions, chapters or thumbnails text track file
kind string	Kind of text track Possible Values: `captions`: (Default) Captions that display during video playback `chapters`: Places markers on the video or displaying different sections `thumbnails`: List of thumbnails that appear when the mouse cursor hovers on the timeslider
label string	Label of the text track This value is only used in setups with multiple captions, where the label is displayed in the CC selection menu. Default: (Index of the text track)