Documentation

Preview Thumbnails

Introduction

Radiant Media Player supports the loading of preview thumbnails (snapshot from a scene at a given timestamp) for video content. These thumbnails are displayed in a tooltip that is shown when a user hovers the seek bar. This is particularly helpful for better seeking into long-form content.

We support 2 kinds of thumbnail track:

Thumbnail track in DASH manifest

With Radiant Media Player 7.5 release we support thumbnail track found in DASH manifest according to latest DASH-IF IOP specification (4.3 at time of writing). Thumbnail track must be embedded in EssentialProperty tag with @schemeIdUri set to "http://dashif.org/guidelines/thumbnail_tile" for the player to recognise these tracks and properly display thumbnails in its seek-bar.

Thumbnail track loaded through WebVTT files

The thumbnails should be assembled into a mosaic (multiple thumbnails stitched together into a single image a.k.a thumbnail sprites). This is for better performance and a smoother user experience while seeking. The mosaic of thumbnails can be in JPEG, PNG or GIF format though we generally recommend using JPEG. Each individual image from the mosaic of thumbnails must be 128px in width. The thumbnail height should be calculated based on the aspect ratio of the video. Below are examples of how to generate a properly formatted mosaic of thumbnails with ffmpeg that will work with Radiant Media Player.

Radiant Media Player uses WebVTT files to load and parse thumbnails. The WebVTT file consists of a list of cues with the following data:

  • The time-range the current thumbnail represents. Note that the range needs to be in (HH:)MM:SS.MMM format. Only this exact notation will be parsed.
  • The URI to the thumbnail for this time-range. The URI is relative to the WebVTT file location (not to the page). Each individual image from the mosaic of thumbnails can be located by appending its coordinates using spatial media fragment (xywh format). You can also have one specific URI for each image.

Preview thumbnails are supported for on-demand video only. They will not show on mobile device where the seek-bar cannot be hovered.

WebVTT file

WEBVTT

00:00.000 --> 00:05.000
assets/bbb-sprite.jpg#xywh=0,0,128,72

00:05.000 --> 00:10.000
assets/bbb-sprite.jpg#xywh=128,0,128,72

00:10.000 --> 00:15.000
assets/bbb-sprite.jpg#xywh=256,0,128,72

00:15.000 --> 00:20.000
assets/bbb-sprite.jpg#xywh=384,0,128,72

A complete example can be viewed here.

WebVTT files should be saved in UTF-8 encoding to prevent character issues.

We also support referencing multiple sprites within the same VTT file:

WEBVTT

00:00.000 --> 00:05.000
assets/bbb-sprite-1.jpg#xywh=0,0,128,72

00:05.000 --> 00:10.000
assets/bbb-sprite-1.jpg#xywh=128,0,128,72

00:10.000 --> 00:15.000
assets/bbb-sprite-2.jpg#xywh=256,0,128,72

00:15.000 --> 00:20.000
assets/bbb-sprite-2.jpg#xywh=384,0,128,72

We also support referencing multiple images without xywh data (not recommended due to poorer performance):

WEBVTT

00:00.000 --> 00:05.000
assets/bbb-sprite-1.jpg
            
00:05.000 --> 00:10.000
assets/bbb-sprite-2.jpg
            
00:10.000 --> 00:15.000
assets/bbb-sprite-3.jpg
            
00:15.000 --> 00:20.000
assets/bbb-sprite-4.jpg

Player code example - see this example here

Preview thumbnails are passed to the player with the seekBarThumbnailsLoc setting (default value for seekBarThumbnailsLoc is an empty string). This setting must be a string pointing to a URI representing the location of the WebVTT file holding the preview thumbnails. Note that the WebVTT file is loaded with XMLHttpRequest and thus it must be delivered with proper CORS setting for cross-site requests.

<script src="https://cdn.radiantmediatechs.com/rmp/9.14.1/js/rmp.min.js"></script>
<div id="rmp"></div>
<script>
const src = {
  hls: 'https://your-hls-url.m3u8'
};
const settings = {
  licenseKey: 'your-license-key',
  src: src,
  width: 640,
  height: 360,
  // here we tell the player where to look for the WebVTT preview thumbnails file
  seekBarThumbnailsLoc: 'https://www.radiantmediaplayer.com/media/vtt/thumbnails/bbb-thumbnails.vtt',
  contentMetadata: {
    poster: [
      'https://your-poster-url.jpg'
    ]
  }
};
const rmp = new RadiantMP('rmp');
rmp.init(settings);
</script>

Preview thumbnails API

Preview thumbnails API methods

getThumbnails()

rmp.getThumbnails();

This method returns a String URI for the current preview thumbnails VTT file loaded in the player.

setThumbnails(newVTTThumbnailsURI)

rmp.setThumbnails('https://your-server-url/new-thumbnails.vtt');

This method sets the preview thumbnails VTT file to be loaded by the player.

Preview thumbnails API events

thumbnailsloaded

Thumbnails VTT file has been loaded.

thumbnailsparsed

Thumbnails VTT file has been parsed.

See warning 8000, 8001, 8002, 8003 for failing notices at loading/parsing thumbnails.

Generating the mosaic of thumbnails with FFmpeg and the associated WebVTT file

First you will need to create your mosaic image file with FFmpeg, then the corresponding VTT file.

To make your day easier we have released a node.js based VTT file generation script for our preview thumbnails feature. You can find all instructions on how to proceed in our GitHub repository: rmp-create-vtt-thumbnails.

Content duration considerations

If you are not using multiple sprites, you may need to adjust the frequency at which you pick thumbnails from a video stream based on content duration. For short-form content, it is best to pick them at shorter intervals (like extracting one frame every 2 seconds) while for long-form content the gap between frame extraction should be higher. This is because the seek-bar will always be limited in size on your viewer device and providing too much frames for your mosaic can have adverse effects like confusing navigation or loading a mosaic image that is unnecessary large for the viewer use-case. Here are some suggestions for gaps in frame extraction based on content duration:

  • duration <= 2 minutes: one frame every 2 seconds
  • 2 minutes < duration <= 10 minutes: one frame every 5 seconds
  • 10 minutes < duration <= 30 minutes: one frame every 10 seconds
  • 30 minutes < duration <= 60 minutes: one frame every 20 seconds
  • 60 minutes > duration: one frame every 30 seconds
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License.

©2015-2024 Radiant Media Player. All Rights Reserved.