{"id":13908620,"url":"https://github.com/phloxic/videojs-sprite-thumbnails","last_synced_at":"2025-07-18T07:31:53.312Z","repository":{"id":38425278,"uuid":"131183730","full_name":"phloxic/videojs-sprite-thumbnails","owner":"phloxic","description":"Video.js plugin to display thumbnails from a sprite image when hovering over the progress bar","archived":false,"fork":false,"pushed_at":"2024-10-27T22:40:09.000Z","size":2561,"stargazers_count":52,"open_issues_count":1,"forks_count":13,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-27T23:08:23.668Z","etag":null,"topics":["javascript","video","videojs","videojs-plugin"],"latest_commit_sha":null,"homepage":"https://lastshiphome.de/en/movie","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/phloxic.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-26T16:37:29.000Z","updated_at":"2024-10-27T22:40:13.000Z","dependencies_parsed_at":"2023-12-09T12:22:50.476Z","dependency_job_id":"e392357e-af7b-422f-97a7-8bc5d2f691c2","html_url":"https://github.com/phloxic/videojs-sprite-thumbnails","commit_stats":{"total_commits":89,"total_committers":3,"mean_commits":"29.666666666666668","dds":0.4831460674157303,"last_synced_commit":"87e41c19cdb4d4cf58b488152b600a6e028250bb"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phloxic%2Fvideojs-sprite-thumbnails","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phloxic%2Fvideojs-sprite-thumbnails/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phloxic%2Fvideojs-sprite-thumbnails/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phloxic%2Fvideojs-sprite-thumbnails/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phloxic","download_url":"https://codeload.github.com/phloxic/videojs-sprite-thumbnails/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226372246,"owners_count":17614653,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","video","videojs","videojs-plugin"],"created_at":"2024-08-06T23:02:52.203Z","updated_at":"2025-07-18T07:31:53.303Z","avatar_url":"https://github.com/phloxic.png","language":"JavaScript","funding_links":[],"categories":["HarmonyOS"],"sub_categories":["Windows Manager"],"readme":"\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n- [videojs-sprite-thumbnails](#videojs-sprite-thumbnails)\n  - [Compatibility](#compatibility)\n  - [Features](#features)\n  - [Installation](#installation)\n  - [Usage](#usage)\n    - [`\u003cscript\u003e` Tag](#script-tag)\n    - [Browserify/CommonJS](#browserifycommonjs)\n    - [RequireJS/AMD](#requirejsamd)\n    - [CDN](#cdn)\n    - [Configuration](#configuration)\n      - [Three ways to configure the location of image assets](#three-ways-to-configure-the-location-of-image-assets)\n      - [The idxTag function](#the-idxtag-function)\n      - [Individual thumbnails](#individual-thumbnails)\n    - [Initialization](#initialization)\n    - [Disabling and enabling the plugin](#disabling-and-enabling-the-plugin)\n    - [Playlist example](#playlist-example)\n    - [CSS state classes](#css-state-classes)\n    - [Debugging](#debugging)\n  - [Mobile devices](#mobile-devices)\n  - [Migrating from v2.1.x](#migrating-from-v21x)\n  - [Constraints](#constraints)\n  - [License](#license)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n# videojs-sprite-thumbnails\n\nPlugin to display thumbnails when hovering over the progress bar.\n\n## Compatibility\n\nThis plugin version is compatible with Video.js v8.x. Compatible [releases](https://github.com/phloxic/videojs-sprite-thumbnails/releases) and [tags](https://github.com/phloxic/videojs-sprite-thumbnails/tags) are versioned v2.x.\n\nFor Video.js v6.x, v7.x compatibility switch to the [vjs6-7-compat branch](https://github.com/phloxic/videojs-sprite-thumbnails/tree/vjs6-7-compat).\n\n## Features\n\n- works with single or multiple sprites containing thumbnails and individual thumbnail images\n- easy to [configure](#configuration)\n- 3 convenient ways to [retrieve image assets](#three-ways-to-configure-the-location-of-image-assets)\n- optional [function](#the-idxtag-function) to customize access to numbered lists of sequential image assets\n- uses existing controlbar components: the [mouse time display](https://docs.videojs.com/mousetimedisplay) and its [time tooltip](https://docs.videojs.com/timetooltip)\n\n## Installation\n\n```sh\nnpm install --save videojs-sprite-thumbnails\n```\n\n## Usage\n\nTo include videojs-sprite-thumbnails on your website or web application, use any of the following methods.\n\n### `\u003cscript\u003e` Tag\n\nThis is the simplest case. Get the script in whatever way you prefer and include the plugin _after_ you include [video.js][videojs], so that the `videojs` global is available.\n\n```html\n\u003cscript src=\"/path/to/video.min.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"/path/to/videojs-sprite-thumbnails.min.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  const player = videojs('my-video');\n\n  // set up 160x90 thumbnails in single sprite.jpg, 1 per second\n  player.spriteThumbnails({\n    url: 'https://example.com/sprite.jpg',\n    width: 160,\n    height: 90,\n    columns: 10\n  });\n\u003c/script\u003e\n```\n\n### Browserify/CommonJS\n\nWhen using with Browserify, install videojs-sprite-thumbnails via npm and `require` the plugin as you would any other module.\n\n```js\nconst videojs = require('video.js');\n\n// The actual plugin function is exported by this module, but it is also\n// attached to the `Player.prototype`; so, there is no need to assign it\n// to a variable.\nrequire('videojs-sprite-thumbnails');\n\nconst player = videojs('my-other-video');\n\n// More than 0 rows in combination with inserting {index) in the url\n// signals a sprite sequence.\nplayer.spriteThumbnails({\n  interval: 3,\n  url: 'https://example.com/sprite_sequence-{index}.jpg',\n  columns: 5,\n  rows: 5,\n  width: 120,\n  height: 90\n});\n```\n\n### RequireJS/AMD\n\nWhen using with RequireJS (or another AMD library), get the script in whatever way you prefer and `require` the plugin as you normally would:\n\n```js\nrequire(['video.js', 'videojs-sprite-thumbnails'], function(videojs) {\n  const player = videojs('my-video');\n\n  player.spriteThumbnails({\n    url: 'https://example.com/sprite.jpg',\n    width: 160,\n    height: 90,\n    columns: 10\n  });\n});\n```\n\n### CDN\n\nSelect a 2.x version of videojs-sprite-thumbnails from the [CDN](https://unpkg.com/videojs-sprite-thumbnails@2/dist/).\n\nOr load the latest Video.js v8.x compatible release of the plugin via [script tag](#script-tag):\n\n```html\n\u003cscript src=\"https://unpkg.com/videojs-sprite-thumbnails@2.2.3/dist/videojs-sprite-thumbnails.min.js\"\u003e\u003c/script\u003e\n```\n\n### Configuration\n\noption | type | mandatory | default | description\n------ | ---- | --------- | ------- | -----------\n`url` | String | \u003ca id=\"url\" href=\"#url-as-is\"\u003esingle sprite\u003c/a\u003e | `\"\"` | Location of sprite image. Must be set by user.\n`urlArray` | Array | \u003ca id=\"urlarray\" href=\"urls-in-array\"\u003emultiple images\u003c/a\u003e | `[]` | Locations of images. Must be set by user.\n`url` | String | \u003ca id=\"taggedurl\" href=\"#url-by-string-expansion\"\u003emultiple images\u003c/a\u003e | `\"\"` | Locations of multiple images via template expansion. Must be set by user.\n`width` | Integer | \u0026#10004; | `0` | Width of a thumbnail in pixels.\n`height` | Integer | \u0026#10004; | `0` | Height of a thumbnail in pixels.\n`columns` | Integer | \u003ca id=\"columns\" href=\"#migrating-from-v21x\"\u003e\u0026#10004;\u003c/a\u003e | `0` | Number of thumbnail columns per image. Set both `columns` and `rows` to `1` for [individual thumbnails](#individual-thumbnails).\n`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.\n`interval` | Number |  | `1` | Interval between thumbnails in seconds.\n`idxTag` | \u003ca id=\"idxtag\" href=\"#the-idxtag-function\"\u003eFunction\u003c/a\u003e |  |  | Function determining how the `{index}` [template](#url-by-string-expansion) in the [`url`](#taggedurl) is expanded. Returns index as is by default.\n`responsive` | Integer |  | `600` | Width of player in pixels below which thumbnails are responsive. Set to `0` to disable.\n`downlink` | Number |  | `1.5` | Minimum of required [NetworkInformation downlink][downlink] where supported. Set to `0` to disable.\n\n#### Three ways to configure the location of image assets\n\n1. \u003ca id=\"url-as-is\" href=\"#url\"\u003e\u003ccode\u003eurl\u003c/code\u003e\u003c/a\u003e as String pointing to a single sprite image:\n```js\n{\n  url: 'https://example.com/single-sprite.jpg',\n  // [... more options]\n}\n```\n\n2. \u003ca id=\"urls-in-array\" href=\"#urlarray\"\u003e\u003ccode\u003eurlArray\u003c/code\u003e\u003c/a\u003e containing multiple (sprite) images:\n```js\n{\n  urlArray: [\n    'https://example.com/first.jpg',\n    'https://example.com/second.jpg',\n    'https://example.com/third.jpg'\n  ],\n  rows: 7,         // must be greater than 0\n  // [... more options]\n}\n```\n3. \u003ca id=\"url-by-string-expansion\" href=\"#taggedurl\"\u003e\u003ccode\u003eurl\u003c/code\u003e\u003c/a\u003e as String expanded by the `idxTag` [function](#the-idxtag-function):\n```js\n{\n  url: 'https://example.com/thumbs-{index}.jpg,\n  rows: 7,         // must be greater than 0\n  idxTag(index) {  // optional\n    return index;  // this is the default\n  },\n  // [... more options]\n}\n```\n\n#### The idxTag function\n\nThe function provided by this option can be used to generate various file naming schemes of sequential sprite images.\n\nExample for thumbnail images are numbered starting from 1, 4 digits long, and padded with leading zeroes:\n\n```js\nmyplayer.spriteThumbnails({\n  // [ more options ... ]\n  url: 'https://example.com/{index}.jpg',\n  idxTag(index) {\n    return `000${index + 1}`.slice(-4);\n  },\n  colums: 5,\n  rows: 5\n});\n```\n\nOf course the same can be achieved by setting [`urlArray`](#urlarray) to the full list of images:\n\n```js\nmyplayer.spriteThumbnails({\n  // [ more options ... ]\n  urlArray: [\n    'https://example.com/0001.jpg',\n    'https://example.com/0002.jpg',\n    'https://example.com/0003.jpg',\n    'https://example.com/0004.jpg'\n  ],\n  colums: 5,\n  rows: 5\n});\n```\n\n#### Individual thumbnails\n\nSet both `rows` and `columns` to `1`:\n\n```js\nmyplayer.spriteThumbnails({\n  // [ other options ]\n  url: 'https://example.com/individual-thumb-{index}.avif',\n  columns: 1,\n  rows: 1\n});\n```\n\n### Initialization\n\nThe plugin is initialized [every time video metadata is loaded](https://docs.videojs.com/player#event:loadedmetadata). 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](#playlist-example).\n\nThe image(s) are then loaded on demand, when the cursor hovers or moves over the progress bar.\n\n### Disabling and enabling the plugin\n\nThe plugin can temporarily be disabled or enabled by toggling its boolean `ready` state:\n\n```js\nvideojs.getPlayer('myplayer').spriteThumbnails().setState({ready: false});\n```\n\nDisable the plugin for a specific video about to be loaded:\n\n```js\nvideojs.getPlayer('myplayer').src([{\n  type: 'video/mp4',\n  src: 'https://example.com/nothumbs.mp4',\n  // disable plugin with empty options object\n  spriteThumbnails: {}\n}]);\n```\n\nNote that the empty `spriteThumbnails: {}` configuration in this context internally uses `spriteThumbnails: {url: '', urlArray: []}` to preserve inheritance of all other options.\n\n### Playlist example\n\n```js\nconst playlist = [\n  [{\n    type: 'video/webm',\n    src: 'https://example.com/video1.webm',\n\n    // only needed once, even if alternaive source is picked\n    spriteThumbnails: {\n      url: 'https://example.com/thumbnails1-{index}.jpg'\n    }\n  }, {\n    type: 'video/mp4',\n    src: 'https://example.com/video1.mp4'\n  }], [{\n    type: 'application/x-mpegurl',\n    src: 'https://example.com/video2.m3u8',\n    spriteThumbnails: {\n      url: 'https://example.com/thumbnails2-{index}.jpg'\n    }\n  }]\n];\n\nconst player = videojs('myplayer', {\n  // player configuration\n  // [...]\n  // load first video in playlist\n  sources: playlist[0],\n\n  plugins: {\n    // default thumbnail settings for this player\n    spriteThumbnails: {\n      width: 160,\n      height: 90,\n      columns: 5,\n      rows: 5\n    }\n  }\n});\n\n// play 2nd video by clicking on button with id=\"secondvideo\"\nvideojs.on(videojs.dom.$('button#secondvideo'), 'click', () =\u003e {\n  player.src(playlist[1]);\n  player.play();\n});\n```\n\n### CSS state classes\n\nThe plugin uses two CSS classes on the player element to signal the current state of plugin:\n\nclass name | plugin state\n---------- | ------------\n`vjs-sprite-thumbnails` | plugin is/not loaded\n`vjs-thumbnails-ready` | plugin is/not ready to show thumbnails\n\nThis allows for CSS directives which apply to player elements depending on plugin state:\n\n```css\n.video-js.vjs-thumbnails-ready .vjs-progress-holder {\n  background-color: green;\n}\n```\n\n### Debugging\n\nEach plugin instance has its own [log](https://docs.videojs.com/tutorial-plugins.html#logging) which can be used for targeted debugging. Its verbosity can be set by calling the player's [plugin name property](https://docs.videojs.com/tutorial-plugins.html#the-player-plugin-name-property):\n\n```js\nplayer.spriteThumbnails().log.level('debug');\n```\n\nThe call can also be chained directly to the [manual plugin setup](https://docs.videojs.com/tutorial-plugins.html#setting-up-a-plugin):\n\n```js\nconst player = videojs('example-player');\nplayer.spriteThumbnails({\n  url: 'https://example.com/thumbnails-{index}.jpg',\n  width: 240,\n  height: 100,\n  columns: 7,\n  rows: 6\n}).log.level('debug');\n```\n\n## Mobile devices\n\nSince version [8.22.0](https://github.com/videojs/video.js/releases/tag/v8.22.0)[^1] Video.js supports display of [time tooltips on mobile devices](https://github.com/videojs/video.js/commit/57d6ab65ea8dbbb7718c90754f4421918c3b2c28) by setting the player option `disableSeekWhileScrubbingOnMobile: true`. By consequence this configuration allows the plugin to show thumbnails on mobile devices.\n\n[^1]: `disableSeekWhileScrubbingOnMobile` was actually introduced in Video.js v8.21.0. However, there was a minor bug with hiding the tooltips. This was [solved](https://github.com/videojs/video.js/pull/8945/commits/79a0fc9379eef8c8ee36ff68ba73d9bae4bd01e2) in v8.22.0.\n\n\u003ch2 id=\"migrating-from-v21x\"\u003eMigrating from v2.1.x\u003c/h2\u003e\n\nPlugin version 2.2.0 introduced the *mandatory* option [`columns`](#columns). Thumbnail images are now [loaded on demand](https://github.com/phloxic/videojs-sprite-thumbnails/issues/56)  which interferes less with video playback. Please apply the option to your existing setups.\n\n## Constraints\n\n- To display thumbnails the plugin expects the control bar in its [default tree structure](https://docs.videojs.com/tutorial-components.html#default-component-tree) to be present.\n- Live streams are not supported.\n\n## License\n\nMIT. Copyright (c) Christian Ebert \u0026lt;bcc@phloxic.productions\u0026gt;\n\n\n[videojs]: http://videojs.com/\n[downlink]: https://developer.mozilla.org/docs/Web/API/NetworkInformation/downlink\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphloxic%2Fvideojs-sprite-thumbnails","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphloxic%2Fvideojs-sprite-thumbnails","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphloxic%2Fvideojs-sprite-thumbnails/lists"}