@videojs/html 10.0.0-beta.23 → 10.0.0-beta.24

package/docs/reference/thumbnail.md

@@ -0,0 +1,364 @@
+# media-thumbnail
+
+Time-based thumbnail preview component for timeline scrubbing and hover previews
+
+## Quick Start: Video Track
+
+`Thumbnail` can read thumbnail cues directly from your video track. Add a `<track>` with `kind="metadata"` and `label="thumbnails"` to your media element.
+
+[Mux](https://www.mux.com?utm_source=videojs&utm_campaign=vjs10) provides this as `storyboard.vtt`:
+
+`https://image.mux.com/{PLAYBACK_ID}/storyboard.vtt`
+
+html
+
+```
+<video src="video.mp4">
+  <track
+    kind="metadata"
+    label="thumbnails"
+    src="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.vtt"
+    default
+  />
+</video>
+<media-thumbnail time="12"></media-thumbnail>
+```
+
+## Anatomy
+
+html
+
+```
+<media-thumbnail time="12"></media-thumbnail>
+```
+
+## Behavior
+
+`Thumbnail` resolves an image for the current `time`.
+
+Supported source formats:
+
+*   Text track: `<track kind="metadata" label="thumbnails" src="...vtt">`
+*   JSON array: `{ url, startTime, endTime? }[]`
+*   JSON sprite array: `{ url, startTime, endTime?, width, height, coords }[]`
+
+In React, text-track mode needs `Player.Provider` because it reads track state from the player store. JSON modes (`thumbnails` prop) work without `Provider`.
+
+The component picks the latest thumbnail whose `startTime` is less than or equal to the current `time`, then scales/clips sprite tiles to fit CSS min/max constraints while preserving aspect ratio.
+
+## Styling
+
+Use state data attributes for pure CSS styling:
+
+css
+
+```
+media-thumbnail[data-hidden] {
+  display: none;
+}
+
+media-thumbnail[data-loading] {
+  opacity: 0.6;
+}
+
+media-thumbnail[data-error] {
+  outline: 1px solid #ef4444;
+}
+```
+
+## Accessibility
+
+`Thumbnail` is decorative by default (`aria-hidden="true"`). It is intended for visual preview UX (for example, timeline hover previews) rather than primary accessible content.
+
+## Examples
+
+### Text Track (VTT)
+
+index.html
+
+index.css
+
+index.ts
+
+```
+<section class="demo">
+    <video-player>
+        <media-container>
+            <video
+                class="media"
+                src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
+                preload="auto"
+                muted
+                playsinline
+                crossorigin="anonymous"
+            >
+                <track
+                    kind="metadata"
+                    label="thumbnails"
+                    src="/docs/demos/thumbnail/basic.vtt"
+                    default
+                />
+            </video>
+            <media-thumbnail class="media-thumbnail" time="12"></media-thumbnail>
+        </media-container>
+    </video-player>
+</section>
+```
+```
+.demo {
+  position: relative;
+  display: block;
+  max-width: 280px;
+}
+
+.media {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  pointer-events: none;
+  opacity: 0;
+}
+
+.media-thumbnail {
+  display: block;
+  width: auto;
+  min-width: 0;
+  max-width: 240px;
+}
+
+.media-thumbnail[data-hidden] {
+  display: none;
+}
+```
+```
+import '@videojs/html/video/player';
+import '@videojs/html/ui/thumbnail';
+```
+
+### JSON Array
+
+index.html
+
+index.ts
+
+```
+<media-thumbnail time="12" style="max-width: 240px;"></media-thumbnail>
+```
+```
+import '@videojs/html/ui/thumbnail';
+
+type DemoThumbnailImage = {
+  url: string;
+  startTime: number;
+  endTime?: number;
+};
+
+type ThumbnailDemoElement = HTMLElement & { thumbnails?: DemoThumbnailImage[] };
+
+const thumbnail = document.querySelector<ThumbnailDemoElement>('media-thumbnail');
+if (thumbnail) {
+  thumbnail.thumbnails = [
+    {
+      url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg?time=0',
+      startTime: 0,
+      endTime: 10,
+    },
+    {
+      url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg?time=10',
+      startTime: 10,
+      endTime: 20,
+    },
+    {
+      url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg?time=20',
+      startTime: 20,
+    },
+  ];
+}
+```
+
+### JSON Sprite Array
+
+index.html
+
+index.ts
+
+```
+<media-thumbnail time="12" style="max-width: 240px;"></media-thumbnail>
+```
+```
+import '@videojs/html/ui/thumbnail';
+
+type DemoThumbnailImage = {
+  url: string;
+  startTime: number;
+  endTime?: number;
+  width?: number;
+  height?: number;
+  coords?: { x: number; y: number };
+};
+
+type ThumbnailDemoElement = HTMLElement & { thumbnails?: DemoThumbnailImage[] };
+
+const thumbnail = document.querySelector<ThumbnailDemoElement>('media-thumbnail');
+if (thumbnail) {
+  thumbnail.thumbnails = [
+    {
+      url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.jpg',
+      startTime: 0,
+      endTime: 10,
+      width: 284,
+      height: 160,
+      coords: { x: 0, y: 0 },
+    },
+    {
+      url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.jpg',
+      startTime: 10,
+      endTime: 20,
+      width: 284,
+      height: 160,
+      coords: { x: 284, y: 0 },
+    },
+    {
+      url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.jpg',
+      startTime: 20,
+      width: 284,
+      height: 160,
+      coords: { x: 568, y: 0 },
+    },
+  ];
+}
+```
+
+## API Reference
+
+### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`crossOrigin`
+
+`'anonymous' | 'use-credentials' | '' ...`
+
+`—`
+
+▸
+
+Attribute
+
+`cross-origin`
+
+Description
+
+CORS setting forwarded to the inner `<img>`.
+
+Type
+
+`'anonymous' | 'use-credentials' | '' | null`
+
+`fetchPriority`
+
+`'high' | 'low' | 'auto'`
+
+`—`
+
+▸
+
+Attribute
+
+`fetch-priority`
+
+Description
+
+Image fetch priority hint forwarded to the inner `<img>`.
+
+`loading`
+
+`'eager' | 'lazy'`
+
+`—`
+
+▸
+
+Attribute
+
+`loading`
+
+Description
+
+Image loading strategy forwarded to the inner `<img>`.
+
+`time`
+
+`number`
+
+`—`
+
+▸
+
+Attribute
+
+`time`
+
+Description
+
+Time in seconds to display the thumbnail for.
+
+### State
+
+State is reflected as data attributes for CSS styling.
+
+Property
+
+Type
+
+Details
+
+`loading`
+
+`boolean`
+
+▸
+
+Description
+
+The thumbnail image is loading.
+
+`error`
+
+`boolean`
+
+▸
+
+Description
+
+The thumbnail image failed to load.
+
+`hidden`
+
+`boolean`
+
+▸
+
+Description
+
+No thumbnail is available and not loading — the component should be hidden.
+
+### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-loading`
+
+`data-error`
+
+`data-hidden`