• videojs-sprite-thumbnails
  • Compatibility
  • Features
  • Installation
  • Usage
    • <script> Tag
    • Browserify/CommonJS
    • RequireJS/AMD
    • CDN
    • Configuration
      • Three ways to configure the location of image assets
      • The idxTag function
      • Individual thumbnails
    • Initialization
    • Disabling and enabling the plugin
    • Playlist example
    • CSS state classes
    • Debugging
  • Migrating from v2.1.x
  • Constraints
  • License

videojs-sprite-thumbnails

Plugin to display thumbnails when hovering over the progress bar.

Compatibility

This plugin version is compatible with Video.js v8.x. Compatible releases and tags are versioned v2.x.

For Video.js v6.x, v7.x compatibility switch to the vjs6-7-compat branch.

Features

• works with single or multiple sprites containing thumbnails and individual thumbnail images
• easy to configure
• 3 convenient ways to retrieve image assets
• optional function to customize access to numbered lists of sequential image assets
• uses existing mouse time tooltip

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>
  const player = videojs('my-video');

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

Browserify/CommonJS

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

const 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');

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

// More than 0 rows in combination with inserting {index) in the url
// signals a sprite sequence.
player.spriteThumbnails({
  interval: 3,
  url: 'https://example.com/sprite_sequence-{index}.jpg',
  columns: 5,
  rows: 5,
  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) {
  const player = videojs('my-video');

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

CDN

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

Or load the latest Video.js v8.x compatible release of the plugin via script tag:

<script src="https://unpkg.com/videojs-sprite-thumbnails@2.2.3/dist/videojs-sprite-thumbnails.min.js"></script>

Configuration

option	type	mandatory	default	description
url	String	single sprite	""	Location of sprite image. Must be set by user.
urlArray	Array	multiple images	[]	Locations of images. Must be set by user.
url	String	multiple images	""	Locations of multiple images via template expansion. Must be set by user.
width	Integer	✔	0	Width of a thumbnail in pixels.
height	Integer	✔	0	Height of a thumbnail in pixels.
columns	Integer	✔	0	Number of thumbnail columns per image. Set both columns and rows to 1 for individual thumbnails.
rows	Integer	multiple images	0	Number of thumbnail rows per image. If set, the plugin will expect a sequence of images. The last image may have fewer rows.
interval	Number		1	Interval between thumbnails in seconds.
idxTag	Function			Function determining how the {index} template in the url is expanded. Returns index as is by default.
responsive	Integer		600	Width of player in pixels below which thumbnails are responsive. Set to 0 to disable.
downlink	Number		1.5	Minimum of required NetworkInformation downlink where supported. Set to 0 to disable.

Three ways to configure the location of image assets

1. url as String pointing to a single sprite image:

{
  url: 'https://example.com/single-sprite.jpg',
  // [... more options]
}

2. urlArray containing multiple (sprite) images:

{
  urlArray: [
    'https://example.com/first.jpg',
    'https://example.com/second.jpg',
    'https://example.com/third.jpg'
  ],
  rows: 7,         // must be greater than 0
  // [... more options]
}

3. url as String expanded by the idxTag function:

{
  url: 'https://example.com/thumbs-{index}.jpg,
  rows: 7,         // must be greater than 0
  idxTag(index) {  // optional
    return index;  // this is the default
  },
  // [... more options]
}

The idxTag function

The function provided by this option can be used to generate various file naming schemes of sequential sprite images.

Example for thumbnail images are numbered starting from 1, 4 digits long, and padded with leading zeroes:

myplayer.spriteThumbnails({
  // [ more options ... ]
  url: 'https://example.com/{index}.jpg',
  idxTag(index) {
    return `000${index + 1}`.slice(-4);
  },
  colums: 5,
  rows: 5
});

Of course the same can be achieved by setting urlArray to the full list of images:

myplayer.spriteThumbnails({
  // [ more options ... ]
  urlArray: [
    'https://example.com/0001.jpg',
    'https://example.com/0002.jpg',
    'https://example.com/0003.jpg',
    'https://example.com/0004.jpg'
  ],
  colums: 5,
  rows: 5
});

Individual thumbnails

Set both rows and columns to 1:

myplayer.spriteThumbnails({
  // [ other options ]
  url: 'https://example.com/individual-thumb-{index}.avif',
  columns: 1,
  rows: 1
});

Initialization

The plugin is initialized every time video metadata is loaded. It monitors all video sources for an optional spriteThumbnails property. Any existing plugin configuration is updated by merging this spriteThumbnails object into the current configuration. Typical use cases are playlists.

The image(s) are then loaded on demand, when the cursor hovers or moves over the progress bar.

Disabling and enabling the plugin

The plugin can temporarily be disabled or enabled by toggling its boolean ready state:

videojs.getPlayer('myplayer').spriteThumbnails().setState({ready: false});

Disable the plugin for a specific video about to be loaded:

videojs.getPlayer('myplayer').src([{
  type: 'video/mp4',
  src: 'https://example.com/nothumbs.mp4',
  // disable plugin with empty options object
  spriteThumbnails: {}
}]);

Note that the empty spriteThumbnails: {} configuration in this context internally uses spriteThumbnails: {url: '', urlArray: []} to preserve inheritance of all other options.

Playlist example

const 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-{index}.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-{index}.jpg'
    }
  }]
];

const 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,
      columns: 5,
      rows: 5
    }
  }
});

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

CSS state classes

The plugin uses two CSS classes on the player element to signal the current state of plugin:

class name	plugin state
vjs-sprite-thumbnails	plugin is/not loaded
vjs-thumbnails-ready	plugin is/not ready to show thumbnails

This allows for CSS directives which apply to player elements depending on plugin state:

.video-js.vjs-thumbnails-ready .vjs-progress-holder {
  background-color: green;
}

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:

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

Migrating from v2.1.x

Plugin version 2.2.0 introduced the mandatory option columns. Thumbnail images are now loaded on demand which interferes less with video playback. Please apply the option to your existing setups.

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 and 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>