videojs-sprite-thumbnails

Plugin to display thumbnails from a sprite image when hovering over the progress bar.

Usage no npm install needed!

<script type="module">
  import videojsSpriteThumbnails from 'https://cdn.skypack.dev/videojs-sprite-thumbnails';
</script>

README

videojs-sprite-thumbnails

Plugin to display thumbnails from a sprite image when hovering over the progress bar.

Features

Installation

npm install --save videojs-sprite-thumbnails

Usage

To include videojs-sprite-thumbnails on your website or web application, use any of the following methods.

<script> Tag

This is the simplest case. Get the script in whatever way you prefer and include the plugin after you include video.js, so that the videojs global is available.

<script src="//path/to/video.min.js"></script>
<script src="//path/to/videojs-sprite-thumbnails.min.js"></script>
<script>
  var player = videojs('my-video');

  // setup 160x90 thumbnails in sprite.jpg, 1 per second
  player.spriteThumbnails({
    url: 'https://example.com/sprite.jpg',
    width: 160,
    height: 90
  });
</script>

Browserify/CommonJS

When using with Browserify, install videojs-sprite-thumbnails via npm and require the plugin as you would any other module.

var videojs = require('video.js');

// The actual plugin function is exported by this module, but it is also
// attached to the `Player.prototype`; so, there is no need to assign it
// to a variable.
require('videojs-sprite-thumbnails');

var player = videojs('my-other-video');

player.spriteThumbnails({
  interval: 3,
  url: 'https://example.com/another-sprite.jpg',
  width: 120,
  height: 90
});

RequireJS/AMD

When using with RequireJS (or another AMD library), get the script in whatever way you prefer and require the plugin as you normally would:

require(['video.js', 'videojs-sprite-thumbnails'], function(videojs) {
  var player = videojs('my-video');

  player.spriteThumbnails({
    url: 'https://example.com/sprite.jpg',
    width: 160,
    height: 90
  });
});

CDN

Select a version of videojs-sprite-thumbnails from the CDN.

Configuration

option type mandatory default description
url String ✔ Sprite image location.
width Integer ✔ Width of a thumbnail in pixels.
height Integer ✔ Height of a thumbnail in pixels.
interval Number 1 Interval between thumbnail frames in seconds.
responsive Integer 600 Width of player in pixels below which thumbnails are reponsive. Set to 0 to disable.
downlink Number 2 Minimum of required NetworkInformation downlink where supported. Set to 0 to disable.

Initialization

The plugin is initialized at player setup. This is sufficient when the player will play only one video and use its thumbnails. The single sprite image will be preloaded at player setup, usually on page load.

The plugin also monitors all video sources on loadstart for a spriteThumbnails property which configures the plugin for this specific video. A typical use case are playlists. Each sprite image is loaded before playback of the video to which it pertains.

Playlist example

var playlist = [
  [{
    type: 'video/webm',
    src: 'https://example.com/video1.webm',

    // only needed once, even if alternaive source is picked
    spriteThumbnails: {
      url: 'https://example.com/thumbnails1.jpg'
    }
  }, {
    type: 'video/mp4',
    src: 'https://example.com/video1.mp4'
  }], [{
    type: 'application/x-mpegurl',
    src: 'https://example.com/video2.m3u8',
    spriteThumbnails: {
      url: 'https://example.com/thumbnails2.jpg'
    }
  }]
];

var player = videojs('myplayer', {
  // player configuration
  // [...]
  // load first video in playlist
  sources: playlist[0],

  plugins: {
    // default thumbnail settings for this player
    spriteThumbnails: {
      width: 160,
      height: 90
    }
  }
});

// play 2nd video by clicking on button with id="secondvideo"
videojs.on(videojs.dom.$('button#secondvideo'), 'click', function () {
  player.src(playlist[1]);
  player.play();
});

Debugging

Each plugin instance has its own log which can be used for targeted debugging. Its verbosity can be set by calling the player's plugin name property:

player.spriteThumbnails().log.level('debug');

The call can also be chained directly to the manual plugin setup:

var player = videojs('example-player');
player.spriteThumbnails({
  url: 'https://example.com/thumbnails.jpg',
  width: 240,
  height: 100
}).log.level('debug');

Constraints

  • To display thumbnails the plugin expects the control bar in its default tree structure to be present.
  • On some devices the mouse time display its time tooltip are disabled by default, and consequently thumbnails will not be shown.
  • Live streams are not supported.

License

MIT. Copyright (c) Christian Ebert <bcc@phloxic.productions>