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
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');
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');
require('videojs-sprite-thumbnails');
const player = videojs('my-other-video');
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.1/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
url
as String pointing to a single sprite image:
{
url: 'https://example.com/single-sprite.jpg',
}
urlArray
containing multiple (sprite) images:
{
urlArray: [
'https://example.com/first.jpg',
'https://example.com/second.jpg',
'https://example.com/third.jpg'
],
rows: 7,
}
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({
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({
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({
url: 'https://example.com/individual-thumb-{index}.avif',
columns: 1,
rows: 1
});
Initialization
The plugin is initialized on plugin setup and every time the player starts to load a video. 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',
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',
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', {
sources: playlist[0],
plugins: {
spriteThumbnails: {
width: 160,
height: 90,
columns: 5,
rows: 5
}
}
});
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>