Playlists

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.

Configuring Playlist as a String

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"
  }]
});
PropertyDescription
file* string(Required) If no file is specified in your setup or sources, this is a required configuration option
adschedule objectSchedule advertising for a specific media file

See: playlist.adschedule
description stringShort description of the item. It is displayed below the title. This can be hidden with the displaydescription option.
image stringPoster image URL. Displayed before and after playback.
mediaid stringUnique identifier of this item. Used by advertising, analytics and discovery services
minDvrWindow numberHLS-only In seconds, the minimum amount of content in an M3U8 required to trigger DVR mode. Set to 0 to always display DVR mode.(Defaults to 120)
recommendations stringURL to a feed that contains related items for a particular playlist item
sources arrayUsed for quality toggling and alternate sources

See: playlist.sources
starttime numberTime 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 stringTitle 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 arrayInclude captions, chapters, and thumbnails for media

See: playlist.tracks
withCredentials booleanIf 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[]

👍

IMPORTANT:

Video ad insertion requires a JW Player Enterprise license. Please contact our team to upgrade your account.

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 an offset and a tag or vastxml.

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"
 }]

PropertyDescription
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 stringProperty 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 stringVAST 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"
      }]
  }]
});
PropertyDescription
file string(Required) URL to the video file, audio file, YouTube video or live stream of this playlist item source.
default booleanSet 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 objectAn object containing DRM information for a particular source
label stringLabel of the media source, displayed in the manual quality selection menu. Set this if you have more than 2 qualities of your video.
type stringForces 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, SRT, and DFXP format, though JW Player strongly suggests using WEBVTT if possible.

PropertyDescriptionDefault
default boolean
                                                                     
Only for captions. Set this to true if you want a captions track to display by default-
file stringURL to the captions, chapters or thumbnails text track file. See Adding Closed Captions for an example setup.-
kind stringThe 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 stringLabel 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 Media Formats Reference for a mapping of all playlist options to RSS format.