videojs-sprite-thumbnails

- videojs-sprite-thumbnails
- Compatibility
- Features
- Installation
- Usage
-


`

$3

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

`js
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
});
`

$3

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

`js
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
});
});
`

$3

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:

`html

`

$3

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][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:
`js
{
url: 'https://example.com/single-sprite.jpg',
// [... more options]
}
`

2. urlArray containing multiple (sprite) images:
`js
{
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:
`js
{
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:

`js
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:

`js
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:

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

$3

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.

$3

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

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

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

`js
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.

$3

`js
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();
});
`

$3

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:

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

$3

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:

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

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

`js
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');
`

Mobile devices

Since version 8.22.0[^1] Video.js supports display of time tooltips on mobile devices by setting the player option disableSeekWhileScrubbingOnMobile: true. By consequence this configuration allows the plugin to show thumbnails on mobile devices.

[^1]: disableSeekWhileScrubbingOnMobile was actually introduced in Video.js v8.21.0. However, there was a minor bug with hiding the tooltips. This was solved in v8.22.0.

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.
- Live streams are not supported.

License

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

[videojs]: http://videojs.com/
[downlink]: https://developer.mozilla.org/docs/Web/API/NetworkInformation/downlink