Playlist

Features

Radiant Media Player playlist layout allows for a collection of video items to be displayed with an intuitive, mobile-ready UI. Playlist items are displayed on a scroll-able side panel and in-player arrows allow navigation between playlist items. We also support audio playlist.

By default, the playlist layout will take as much width as the parent element to the playlist container can provide and will automatically resize itself based on DOM context.

Video advertisement can be played each time a new playlist item is loaded within the player. A built-in error-recovery mechanism is also provided to skip playlist items that may be unavailable. Our playlist layout is also compatible with AirPlay and Google Cast.

A dedicated playlist API is available to programmatically control the playlist layout.

Playlist data set with a JSON file

The playlist player can be initialised by passing through the playlistLoc setting a URI to a JSON file holding playlist data. Here is a full example of well-formatted JSON file that can be used with Radiant Media Player playlist layout.

The JSON structure is as below. The required fields for each item are:

• src - streaming source for the playlist item
• contentMetadata:

  {
    "title": "Playlist Item 1",
    "description": "Description for playlist item 1",
    "id": "1111111111",
    "thumbnail": "https://www.radiantmediaplayer.com/media/playlist/poster/item-1-thumbnail.jpg",
    "duration": "09:56",
    "poster": [
      "https://www.radiantmediaplayer.com/media/playlist/poster/item-1.jpg"
    ]
  }

  • poster: poster frame for the playlist item - size should be equal to the initial player size (832x468 per default)
  • title: title for the playlist item
  • description: description for the playlist item
  • thumbnail (highly recommended) - URI to thumbnail frame for the playlist item (size should be 80x45) - if thumbnail information is not found poster data will be used

Optional fields for each playlist item are:

• adTagUrl - URI to the adTag to be loaded when the playlist item starts - if you use ads you must also set the player setting ads to true
• adTagWaterfall - an array of URI to be used for client-side waterfalling - see here for more information
• seekBarThumbnailsLoc - VTT file URI to be loaded with each playlist item to enable preview thumbnail support
• ccFiles - WebVTT closed captions files - see documentation
• chaptersLoc - WebVTT chapters files - see documentation
• sharingUrl and sharingCode (provided sharing: true setting is set - this will let you define individual sharing URL and code for each playlist item) - see sharing documentation
• logo - see logo documentation

Example:

{
  "playlist": [
    {
      "src": {
        "hls": "https://your-hls-url-1.m3u8"
      },
      "contentMetadata": {
        "title": "Playlist Item 1",
        "description": "Description for playlist item 1",
        "id": "1111111111",
        "thumbnail": "https://www.radiantmediaplayer.com/media/playlist/poster/item-1-thumbnail.jpg",
        "poster": [
          "https://www.radiantmediaplayer.com/media/playlist/poster/item-1.jpg"
        ]
      },
      "adTagUrl": "https://www.radiantmediaplayer.com/vast/tags/inline-linear.xml"
    },
    {
      "src": {
        "hls": "https://your-hls-url-2.m3u8"
      },
      "contentMetadata": {
        "title": "Playlist Item 2",
        "description": "Description for playlist item 2",
        "id": "2222222222",
        "thumbnail": "https://www.radiantmediaplayer.com/media/playlist/poster/item-2-thumbnail.jpg",
        "poster": [
          "https://www.radiantmediaplayer.com/media/playlist/poster/item-2.jpg"
        ]
      },
      "adTagUrl": "https://www.radiantmediaplayer.com/vast/tags/inline-linear-skippable.xml"
    },
    {
      "src": {
        "hls": "https://your-hls-url-3.m3u8"
      },
      "contentMetadata": {
        "title": "Playlist Item 3",
        "description": "Description for playlist item 3",
        "id": "3333333333",
        "thumbnail": "https://www.radiantmediaplayer.com/media/playlist/poster/item-3-thumbnail.jpg",
        "poster": [
          "https://www.radiantmediaplayer.com/media/playlist/poster/item-3.jpg"
        ]
      },
      "adTagUrl": "https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ct%3Dlinear&correlator="
    }
  ]
}

Client-side ad waterfalling with playlist items:

{
  "src": {
    "hls": "https://your-hls-url-1.m3u8"
  },
  "contentMetadata": {
    "title": "Playlist Item 1",
    "description": "Description for playlist item 1",
    "id": "1111111111",
    "thumbnail": "https://www.radiantmediaplayer.com/media/playlist/poster/item-1-thumbnail.jpg",
    "poster": [
      "https://www.radiantmediaplayer.com/media/playlist/poster/item-1.jpg"
    ]
  },
  "adTagUrl": "https://www.radiantmediaplayer.com/vast/tags/inline-linear.xml",
  "adTagWaterfall": [
    "https://www.radiantmediaplayer.com/vast/tags/inline-linear-1.xml?cb=__random-number__",
    "https://www.radiantmediaplayer.com/vast/tags/inline-linear-2.xml?url=__page-url__"
  ]
}

WebVTT closed captions through the ccFiles setting:

{
  "src": {
    "hls": "https://your-hls-url-1.m3u8"
  },
  "contentMetadata": {
    "title": "Playlist Item 1",
    "description": "Description for playlist item 1",
    "id": "1111111111",
    "thumbnail": "https://www.radiantmediaplayer.com/media/playlist/poster/item-1-thumbnail.jpg",
    "poster": [
      "https://www.radiantmediaplayer.com/media/playlist/poster/item-1.jpg"
    ]
  },
  "ccFiles": [
    [
      "en",
      "English",
      "https://www.radiantmediaplayer.com/media/vtt/captions/cc.vtt"
    ],
    [
      "fr",
      "Français",
      "https://www.radiantmediaplayer.com/media/vtt/captions/cc-fr.vtt"
    ]
  ]
}

Playlist code example - see this example here

Take note of the additional div elements required to display the playlist UI.

<script src="https://cdn.radiantmediatechs.com/rmp/10.1.4/js/rmp.min.js"></script>
<!-- Here is our specific markup for playlist -->
<div class="rmp-playlist-container">
  <div class="rmp-playlist-player-wrapper">
    <div id="rmp"></div>
  </div>
</div>
<script>
  const settings = {
    licenseKey: 'your-license-key',
    // if you want ads to show uncomment this next setting (ad data for each playlist item can be passed in JSON file)
    // ads: true,
    // our playlist settings
    playlistUpNextAutoplay: true,
    playlistEndedLoop: false,
    playlistLoc: 'https://www.radiantmediaplayer.com/media/playlist/playlist.json'
  };
  const rmp = new RadiantMP('rmp');
  // Initialization ... and done!
  async function initRmpPlayer() {
    try {
      await rmp.init(settings);
    } catch(error) {
      console.error('Radiant Media Player failed to initialize', error);
    }
  }
  initRmpPlayer();
</script>

Playlist data set with a JavaScript array of objects

Alternatively to passing playlist data as a JSON file you can pass those data through the playlistData setting as an array of objects. Each item of the array is an object representing a playlist item. The structure of this object follows the same pattern as the one described in the JSON file section above. Example:

const playlistData = [{
  src: {
    hls: "https://your-hls-url-1.m3u8"
  },
  "contentMetadata": {
    "title": "Playlist Item 1",
    "description": "Description for playlist item 1",
    "id": "1111111111",
    "thumbnail": "https://www.radiantmediaplayer.com/media/playlist/poster/item-1-thumbnail.jpg",
    "poster": [
      "https://www.radiantmediaplayer.com/media/playlist/poster/item-1.jpg"
    ]
  },
  adTagUrl: "https://www.radiantmediaplayer.com/vast/tags/inline-linear.xml"
}, {
  src: {
    hls: "https://your-hls-url-2.m3u8"
  },
  "contentMetadata": {
    "title": "Playlist Item 2",
    "description": "Description for playlist item 2",
    "id": "2222222222",
    "thumbnail": "https://www.radiantmediaplayer.com/media/playlist/poster/item-2-thumbnail.jpg",
    "poster": [
      "https://www.radiantmediaplayer.com/media/playlist/poster/item-2.jpg"
    ]
  },
  adTagUrl: "https://www.radiantmediaplayer.com/vast/tags/inline-linear-skippable.xml"
}];
...
const settings = {
  licenseKey: 'your-license-key',
  playlistUpNextAutoplay: true,
  playlistEndedLoop: false,
  playlistData
};

Playlist settings

playlistLoc: String

This set the location to the JSON file that hold information about the playlist. It can either be a fully qualified URL or a local/absolute path. Note that the playlist JSON file is loaded with XMLHttpRequest and thus it must be delivered with proper CORS setting for cross-site requests. Default: ''.

playlistData: Array

This setting sets the initial playlist data based on an JavaScript array of objects. Default: []. If both playlistLoc and playlistData are set playlistData will prevail. See above for an example. Default: [].

playlistCallback: Function

This setting allows for a custom callback (Promise) to be run during the playlist mechanism after a new playlist item has been requested (including the first item) but before it actually starts loading playlist data for that item. The playlist item loading process will only resume when the Promise from the custom callback resolves or rejects. This allows for use-cases that require the playlist item loading process to pause, like header bidding for video ads, to be handled in a playlist scenario. Default: null. Usage example:

const adTags = [
  'https://www.radiantmediaplayer.com/vast/tags/inline-linear-1.xml',
  'https://www.radiantmediaplayer.com/vast/tags/inline-linear.xml',
  'https://www.radiantmediaplayer.com/vast/tags/inline-linear-skippable.xml',
  'https://www.radiantmediaplayer.com/vast/tags/non-linear.xml'
];
let adIndex = 0;
const playlistCallback = () => {
  return new Promise((resolve, reject) => {
    // run something async
    setTimeout(() => {
      if (adIndex === 4) {
        adIndex = 0;
      }
      rmp.loadAds(adTags[adIndex]);
      adIndex++;
      resolve();
    }, 1000);
  });
};
const settings = {
  licenseKey: 'your-license-key',
  width: 640,
  height: 360,
  ads: true,
  // pass async playlist callback
  playlistCallback,
  playlistLoc: 'https://www.radiantmediaplayer.com/media/playlist/playlist-no-ad.json'
};
const rmp = new RadiantMP('rmp');
// Initialization ... and done!
async function initRmpPlayer() {
  try {
    await rmp.init(settings);
  } catch(error) {
    console.error('Radiant Media Player failed to initialize', error);
  }
}
initRmpPlayer();

playlistUpNextAutoplay: Boolean

By default when a playlist item ends the next playlist item is automatically played. Default: true. Setting this setting to false will cause the player to not autoplay the next item.

playlistEndedLoop: Boolean

By default when the last item of the playlist ends the player stops and remains on the last item. When playlistEndedLoop is set to true and the last item of the playlist ends the player will automatically start loading and displaying the first item in the playlist (e.g. playlist loop). Default: false. When playlistEndedLoop is set to true playlistUpNextAutoplay must also be set to true to have effect.

Playlist API

Playlist API events

playlistitemloaded

Fires when a new playlist item has successfully loaded

playlistcomplete

Fires when a playlist has reached its end

error

Fires when a new playlist item has failed to load

Playlist API methods

getPlaylistItem() (Number)

const playlistItem = rmp.getPlaylistItem();

This method returns Number representing the index of the currently loaded playlist item.

setPlaylistItem(index) Promise.<|WarningData>

rmp.setPlaylistItem(1);

Returns a Promise that resolves if setPlaylistItem request was successful or rejects to a WarningData Object. This method sets the current playlist item being displayed. index input parameter should be a Number representing the playlist item to be displayed. srcchanged or error event will fire when this method has completed (see setSrc API docs for more information).

getPlaylistLoc() (String)

const playlistLoc = rmp.getPlaylistLoc();

This method returns a String, the URI to the playlist JSON file.

setPlaylistLoc(newPlaylistLoc) Promise.<|WarningData>

const newPlaylistLoc = 'https://www.radiantmediaplayer.com/media/playlist/playlist.json';
rmp.setPlaylistLoc(newPlaylistLoc).then(() => {
  console.log('setPlaylistLoc has completed');
}).catch(warning => {
  console.warn(warning);
});

Returns a Promise that resolves if setPlaylistLoc request was successful or rejects to a WarningData Object. This method allows to dynamically update the playlist player with a new set of playlist data based on a new JSON file URI. srcchanged or error event will fire when this method has completed, as the first item of the new playlist will be automatically loaded (see setSrc API docs for more information).

getPlaylistData() (Array of Object)

const playlistData = rmp.getPlaylistData();

This method returns an ordered Array of Object where each Object represents a playlist item (will return [{}] when no playlist is loaded).

setPlaylistData(newPlaylistData) Promise.<|WarningData>

const newPlaylistData = [{
  src: {
    hls: "https://your-hls-url-1.m3u8"
  },
  contentMetadata: {
    title: "Playlist Item 1",
    description: "Description for playlist item 1",
    id: "1111111111",
    thumbnail: "https://www.radiantmediaplayer.com/media/playlist/poster/item-1-thumbnail.jpg",
    poster: [
      "https://www.radiantmediaplayer.com/media/playlist/poster/item-1.jpg"
    ]
  },
  adTagUrl: "https://www.radiantmediaplayer.com/vast/tags/inline-linear.xml"
}, {
  src: {
    hls: "https://your-hls-url-2.m3u8"
  },
  contentMetadata: {
    title: "Playlist Item 2",
    description: "Description for playlist item 2",
    id: "2222222222",
    thumbnail: "https://www.radiantmediaplayer.com/media/playlist/poster/item-2-thumbnail.jpg",
    poster: [
      "https://www.radiantmediaplayer.com/media/playlist/poster/item-2.jpg"
    ]
  },
  adTagUrl: "https://www.radiantmediaplayer.com/vast/tags/inline-linear-skippable.xml"
}];

try {
  await rmp.setPlaylistData(newPlaylistData);
} catch(warning) {
  console.warn(warning);
}

This method allows to dynamically update the playlist player with a new set of data. You can pass a new array of object (see playlistData setting). srcchanged or error event will fire when this method has completed (see setSrc API docs for more information).

setPlaylistItemCallback(Function)

rmp.setPlaylistItemCallback(customCallback);

This method sets dynamically the playlistCallback setting. This setting allows for a custom callback (Promise-based) to be run during the playlist item changing mechanism after a new playlist item has been requested (including the first item) but before it actually starts loading playlist data for that item. The playlist item loading process will only resume when the Promise from the custom callback resolves or rejects. This allows for use-cases that requires the playlist item loading process to pause, like header bidding for video ads, to be handled. Pass a simple function that returns null to reset playlistCallback setting to null.

Additional support notes

360 video content

You can use 360 video content with our playlist layout but all items within the playlist have to be 360 video

Logging & billing considerations

Each time a new item starts in the playlist layout, a player start is counted (PLATFORM Edition customers only).

Analytics consideration

Each time a new item starts in the playlist layout, a playerstart event is sent to Google Analytics, but it will use as label the contentTitle of the new item. This allows to identify when a specific playlist item is started. Other events, like adimpression or enterfullscreen, will also be sent to Google Analytics when a new media item starts in the playlist layout, but with the updated label as well.

Unsupported features with the playlist layout:

• Ad scheduler
• DRM content - you may use setSrc API method to change source with DRM support