Videojs - VTT Sprite Thumbnails

Add preview thumbnails from VTT file

The separate thumbnails plugin supports the loading of preview thumbnails from a WebVTT file. WebVTT is a plain text format, part of the HTML5 standard, that is mainly used for providing closed captions and chapters. You can also use the VTT specification to define preview thumbnails and display them over the progressbar based on a list of VTT cues. The VTT metadata file contains links to the actual thumbnail image, which can be in JPG, PNG, or GIF format.
To use the thumnails plugin, you must load it first, right after the video.js script, e.g.

Code snippet

 <script src="/videojs/video.min.js"></script>
 <script src="/videojs/nuevo.min.js"></script>
 <script src="/videojs/plugins/thumbnails.min.js"></script>

There are two methods to load the VTT file, process the VTT protocol and display thumbs. One stable method that works across all browsers and devices is to provide the VTT file URL in the plugin's src option.

Code snippet

 <script>
 let player = videojs("my_player_id");
 player.nuevo();
 player.thumbnails({ src:"vtt-thumbnails-url" })
 </script>

You can also provide the VTT file through a video track element. The track element must contain src and metada="kind" parameters. Single or multiple tracks can be included in an HTML video element or loaded through the loadTracks function once the video is loaded.

Code snippet

 <script>
 let player = videojs("my_player_id");
 player.nuevo();
 player.thumbnails();
 player.on('loadeddata',function(){
 var tracks=[
 {kind:'metadata',src:"//path-to-thumbnails-vtt-file"},
 {kind:'captions',src:"//path-to-captions-vtt-file",srclang:"en",label:"English", default:1},
 {kind:'captions',src:"//path-to-captions-vtt-file",srclang:"de",label:"German" }
 ]
 player.loadTracks(tracks);
 });
 </script>

There are two methods to prepare and include thumbnail image(s) for a VTT file.

Thumbnails from single images.

For each thumbnail, you must prepare a single image in JPG, PNG, or GIF format. Though it is suggested to keep the same size for each image, it can also be a different size, but you should keep the same display ratio for each image. In the VTT file, just enter the image path (relative or absolute) for each time cue.

Code snippet

 WEBVTT

 00:00.000 --> 00:05.000
 /assets/thumbnail_1.jpg

 00:05.000 --> 00:10.000
 /assets/thumbnail_2.jpg

 00:10.000 --> 00:15.000
 /assets/thumbnail_3.jpg

 00:15.000 --> 00:20.000
 /assets/thumbnail_4.jpg

The default size of a single thumbnail is 160x90 pixels. If you prefer another size, you can set it as a plugin's option.

Code snippet

 player.thumbnails({ src:"vtt-thumbnails-url", width:192, height:108 });

Thumbnails from sprite image

To limit file size, avoid loading delays, and limit the number of server requests, the thumbnails plugin supports Thumbnail Sprites - multiple thumbnails in one tiled image.

In the VTT file, the individual thumbnails are identified by appending their coordinates to the thumbnail URL, e.g.

Code snippet

 WEBVTT

 00:00.000 --> 00:05.000
 /assets/thumbnails.jpg#xywh=0,0,160,90

 00:05.000 --> 00:10.000
 /assets/thumbnails.jpg#xywh=0,160,0,90

 00:10.000 --> 00:15.000
 /assets/thumbnails.jpg#xywh=0,320,0,90

 00:15.000 --> 00:20.000
 /assets/thumbnails.jpg#xywh=0,480,0,90

The size of the single thumbnail from the sprite image is determined by the VTT xywh definition.
If relative paths are used for thumbs, you may need to define the basePath plugin's option.

Code snippet

 player.thumbnails({ basePath: "global-path-or-url", src:"vtt-thumbnails-url" });

The thumbnails plugin allows you to display a ghost thumb in the size of the video poster while you press the mouse down and keep it moving over the progress bar. You only need to enable the appropriate Nuevo plugin's option.

Code snippet

 player.nuevo({ ghostThumb:true })
 player.thumbnails({ src:"vtt-thumbnails-url" });

The VTT sepcification and peraring sprite image are exactly the same as for JWPlayer, described here. Since JWPlayer is popular, we believe that many users are familiar with this technique and are able to prepare tiled images.

We also prepared our own bash script to generate a tiled image from video and a VTT file with one command. It is free to download and use by logged-in users below.