@videojs/html 10.0.0-rc.2 → 10.0.0-rc.4

package/docs/reference/components/thumbnail.md

@@ -0,0 +1,321 @@
+# media-thumbnail
+
+Time-based thumbnail preview component for timeline scrubbing and hover previews
+
+## Quick Start: Video Track
+
+`<media-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`
+
+That track is cross-origin, and a cross-origin `<track>` only loads when the media element is CORS-enabled:
+
+```html
+<video src="video.mp4" crossorigin="anonymous">
+  <track
+    kind="metadata"
+    label="thumbnails"
+    src="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.vtt"
+    default
+  />
+</video>
+<media-thumbnail time="12"></media-thumbnail>
+```
+
+A same-origin track needs none of this.
+
+## Import
+
+```ts
+import '@videojs/html/ui/thumbnail';
+```
+
+## Anatomy
+
+```html
+<media-thumbnail>
+  <img alt="" decoding="async" />
+</media-thumbnail>
+```
+
+## Behavior
+
+The thumbnail root resolves an image for the current `time`, owns `src` and `srcset` on it, and reports its loading lifecycle.
+
+The `<img>` child is optional: leave it out and `<media-thumbnail>` draws an image of its own in its shadow DOM; supply one to replace it and compose overlays or loading indicators beside it. Any `crossorigin`, `loading`, or `fetchpriority` the supplied image already carries is yours and wins over the element’s own attributes; the rest are filled in.
+
+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 }[]`
+
+Text-track mode needs an enclosing player element because it reads track state from the player store. JSON modes (`thumbnails` property) work without a player.
+
+The component picks the latest thumbnail whose `startTime` is less than or equal to the current `time`, then scales/clips sprite tiles to fill CSS min/max constraints while preserving aspect ratio. Tiles scale up as well as down, so a preview whose `max-width` grows — a container query widening it in fullscreen, say — grows with it.
+
+### Cross-origin images
+
+Leave `crossOrigin` unset and the component follows the media element. A cross-origin thumbnail `<track>` only loads when the media is CORS-enabled, so the images its cues point at are fetched with that same mode. Skins get this for free, with nothing to thread through.
+
+Opt out to fetch them without CORS:
+
+```ts
+const thumbnail = document.querySelector('media-thumbnail');
+thumbnail.crossOrigin = null;
+```
+
+Leaving the `crossorigin` attribute off is not the opt out. An absent attribute means “follow the media element”; only the property set to `null` opts out.
+
+An empty value does not opt out either. The [CORS settings attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/crossorigin) reads anything other than `use-credentials` as Anonymous, so it is a value like any other.
+
+Thumbnails you supply through `thumbnails` never inherit, since they need not be related to the media element at all. Set `crossOrigin` yourself when those images need it.
+
+## 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;
+}
+```
+
+The image the element draws is exposed as a part. An `<img>` you supply is an ordinary child, so style it as a descendant:
+
+```css
+media-thumbnail::part(image),
+media-thumbnail > img {
+  border-radius: 4px;
+}
+```
+
+The element clips to the selected tile while the image inside spans the whole sprite sheet, so anything after the image in flow lands past the clip edge. Position the element and lay overlays over it:
+
+```css
+media-thumbnail {
+  position: relative;
+}
+
+media-thumbnail > .overlay {
+  position: absolute;
+  inset: 0;
+}
+```
+
+## Accessibility
+
+`<media-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**
+
+```html
+<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="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.vtt" default />
+      </video>
+      <media-thumbnail class="media-thumbnail" time="12"></media-thumbnail>
+    </media-container>
+  </video-player>
+</section>
+```
+
+**index.css**
+
+```css
+.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;
+}
+```
+
+**index.ts**
+
+```ts
+import '@videojs/html/video/player';
+import '@videojs/html/ui/container';
+import '@videojs/html/ui/thumbnail';
+```
+
+### JSON Array
+
+**index.html**
+
+```html
+<media-thumbnail class="html-thumbnail-json" time="12" style="max-width: 240px"></media-thumbnail>
+```
+
+**index.ts**
+
+```ts
+import '@videojs/html/ui/thumbnail';
+
+type DemoThumbnailImage = {
+  url: string;
+  startTime: number;
+  endTime?: number;
+};
+
+type ThumbnailDemoElement = HTMLElement & { thumbnails?: DemoThumbnailImage[] };
+
+const initializedDemos = new WeakSet<ThumbnailDemoElement>();
+
+function initializeDemos(): void {
+  document.querySelectorAll<ThumbnailDemoElement>('.html-thumbnail-json').forEach((thumbnail) => {
+    if (initializedDemos.has(thumbnail)) return;
+
+    initializedDemos.add(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,
+      },
+    ];
+  });
+}
+
+initializeDemos();
+document.addEventListener('astro:page-load', initializeDemos);
+```
+
+### JSON Sprite Array
+
+**index.html**
+
+```html
+<media-thumbnail class="html-thumbnail-json-sprite" time="12" style="max-width: 240px"></media-thumbnail>
+```
+
+**index.ts**
+
+```ts
+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 initializedDemos = new WeakSet<ThumbnailDemoElement>();
+
+function initializeDemos(): void {
+  document.querySelectorAll<ThumbnailDemoElement>('.html-thumbnail-json-sprite').forEach((thumbnail) => {
+    if (initializedDemos.has(thumbnail)) return;
+
+    initializedDemos.add(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 },
+      },
+    ];
+  });
+}
+
+initializeDemos();
+document.addEventListener('astro:page-load', initializeDemos);
+```
+
+## API Reference
+
+### media-thumbnail
+
+`<media-thumbnail>` — resolves and sizes a time-based thumbnail into an image.
+
+The element owns `src` and `srcset` on the active image. Left empty, it draws an image of its own in its shadow root. Supply an `<img>` child instead — `<media-thumbnail time="12"><img alt=""></media-thumbnail>` — to compose overlays or loading indicators beside the image the element controls. Any `crossorigin`, `loading`, or `fetchpriority` the child already carries wins over the element's own; the rest are filled in. Inside a skin, an `<img slot="thumbnail">` of yours replaces the one the skin carries.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `thumbnails` | `ThumbnailImage[]` | — | Pre-parsed thumbnail images — bypasses the automatic `<track>` detection. |
+| `time` | `number` | — | Time in seconds to display the thumbnail for. |
+
+#### State
+
+State is reflected as data attributes for CSS styling.
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `loading` | `boolean` | The thumbnail image is loading. |
+| `error` | `boolean` | The thumbnail image failed to load. |
+| `hidden` | `boolean` | Whether the component is hidden because no thumbnail is available and it is not loading. |
+
+#### Data attributes
+
+| Attribute | Description |
+| --- | --- |
+| `data-loading` | |
+| `data-error` | |
+| `data-hidden` | |

package/docs/reference/components/tiktok-video.md

@@ -0,0 +1,165 @@
+# tiktok-video
+
+Video component that plays TikTok videos through the TikTok embed player
+
+The [TikTok embed player](https://developers.tiktok.com/doc/embed-player) expects portrait video and won’t draw its chrome below 325×578, so the element starts at that size rather than the usual 300×150.
+
+## Import
+
+```bash
+pnpm add @videojs/tiktok-video
+```
+
+```ts
+import '@videojs/html/media/tiktok-video';
+```
+
+Or load it from the [CDN](../../guides/cdn.md):
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.4/media/tiktok-video.js"></script>
+```
+
+## Load a source
+
+`src` takes a TikTok video URL or a raw numeric video id. The `@user/video/<id>` URLs the app hands out, `share/video/<id>` links, and `player/v1/<id>` embed URLs all work.
+
+```html
+<tiktok-video src="https://www.tiktok.com/@_luwes/video/7527476667770522893"></tiktok-video>
+```
+
+## Controls
+
+TikTok always draws part of its own chrome: the center play button, author header, and social rail are always visible. `controls` adds the progress bar and control buttons on top of those. Without `controls`, the element ignores pointer events, so a [player skin](../../guides/skins.md) above it receives every click.
+
+## Deferred startup
+
+TikTok builds its player lazily: until something starts playback, the embed has no video element, reports a duration of 0, and silently drops commands. The element works around this by starting a muted autoplay and pausing it immediately, so the embed answers play, pause, and seek before the first play.
+
+Two settings opt out. `preload="none"` skips the warm-up, leaving the network untouched until the viewer presses play, and the controls inert until then. `controls` hands playback to TikTok’s own chrome instead.
+
+## Behavior
+
+- Mute works, but there’s no volume control: the embed reports a level but takes no command to set one.
+- No playback rate and no text tracks; captions are toggled with `engine.tiktok.closed_caption`.
+- `poster` and `playsInline` never reach the embed: it always plays inline and draws the video’s own cover image.
+- Changing `controls` or `loop` after the embed is up rebuilds it; rewriting the iframe URL is the only reload TikTok allows.
+
+## Examples
+
+### Basic Usage
+
+**index.html**
+
+```html
+<tiktok-video class="tiktok-video" src="https://www.tiktok.com/@_luwes/video/7527476667770522893" controls></tiktok-video>
+```
+
+**index.css**
+
+```css
+/* TikTok videos are portrait: the element floors itself at 325x578. */
+.tiktok-video {
+  display: block;
+  width: 325px;
+  height: 578px;
+  margin-inline: auto;
+}
+```
+
+**index.ts**
+
+```ts
+import '@videojs/html/media/tiktok-video';
+```
+
+## API Reference
+
+### Attributes
+
+These attributes configure the embedded media adapter:
+
+| Attribute | Type | Default |
+| --- | --- | --- |
+| `autoplay` | `boolean` | `false` |
+| `controls` | `boolean` | `false` |
+| `loop` | `boolean` | `false` |
+| `muted` | `boolean` | `false` |
+| `playsinline` | `boolean` | `true` |
+| `poster` | `string` | `''` |
+| `preload` | `MediaPreloadType` | `'metadata'` |
+| `src` | `string` | `''` |
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `autoplay` | `boolean` | `false` | |
+| `buffered` | `TimeRangeLike` | — | Read-only. |
+| `controls` | `boolean` | `false` | |
+| `currentSrc` | `string` | — | Read-only. |
+| `currentTime` | `number` | — | |
+| `defaultMuted` | `boolean` | `false` | |
+| `duration` | `number` | — | Read-only. |
+| `ended` | `boolean` | — | Read-only. |
+| `engine` | `Window \| null` | — | Read-only. The embed's window. TikTok publishes no player object; commands are posted to the frame. Null until rendered. |
+| `error` | `MediaError \| null` | — | Read-only. |
+| `isFullscreen` | `boolean` | — | Read-only. |
+| `loop` | `boolean` | `false` | |
+| `muted` | `boolean` | `false` | |
+| `paused` | `boolean` | — | Read-only. |
+| `played` | `{ length: number; start(index: number): number; end(index: number): number }` | — | Read-only. |
+| `playsInline` | `boolean` | `true` | |
+| `poster` | `string` | `''` | |
+| `preload` | `MediaPreloadType` | `'metadata'` | |
+| `readyState` | `number` | — | Read-only. |
+| `seekable` | `TimeRangeLike` | — | Read-only. |
+| `seeking` | `boolean` | — | Read-only. |
+| `source` | `{ src?: string; engine?: TikTokSourceEngineConfig } \| null` | `null` | TikTok URL or id in `src`, player params under `engine.tiktok`. Re-derives `src`; equal sources skip reload. |
+| `src` | `string` | `''` | |
+| `textTracks` | `TextTrackListLike` | — | Read-only. Always empty: `closed_caption` is the embed's only say over captions. |
+
+### Engine options
+
+#### `source.engine.tiktok`
+
+Pass [TikTok player parameters](https://developers.tiktok.com/doc/embed-player) under `source.engine.tiktok`, spelled exactly as TikTok spells them, each one `0` or `1`, plus anything TikTok adds next. [Media Sources](../../guides/media-sources.md) covers how engine options fit into a structured source.
+
+`autoplay`, `controls`, `loop`, and `muted` come from the props of the same name, so they have no `engine.tiktok` spelling.
+
+```ts
+const video = document.querySelector('tiktok-video');
+video.source = {
+  src: 'https://www.tiktok.com/@_luwes/video/7527476667770522893',
+  engine: { tiktok: { closed_caption: 0, rel: 1 } },
+};
+```
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `closed_caption` | `0 \| 1 \| undefined` | Show the closed-caption button. Defaults to `1`. |
+| `description` | `0 \| 1 \| undefined` | Show the video description. Defaults to `0`. |
+| `fullscreen_button` | `0 \| 1 \| undefined` | Show the fullscreen button. Defaults to `1`. |
+| `music_info` | `0 \| 1 \| undefined` | Show the track the video uses. Defaults to `0`. |
+| `native_context_menu` | `0 \| 1 \| undefined` | Show the browser's native context menu. Defaults to `1`. |
+| `play_button` | `0 \| 1 \| undefined` | Show the play button. Defaults to `1`. |
+| `progress_bar` | `0 \| 1 \| undefined` | Show the progress bar. Defaults to `1`. |
+| `referrerPolicy` | `ReferrerPolicy \| undefined` | `referrerpolicy` for the embed iframe. Not a TikTok player parameter. |
+| `rel` | `0 \| 1 \| undefined` | Draw related videos from TikTok's recommendations (`1`) or the author's own videos (`0`). Defaults to `1`. |
+| `timestamp` | `0 \| 1 \| undefined` | Show the current playback time and duration. Defaults to `1`. |
+| `volume_control` | `0 \| 1 \| undefined` | Show the volume control. Defaults to `1`. |
+
+### Methods
+
+Supports these media methods: `exitFullscreen`, `load`, `pause`, `play`, `requestFullscreen`.
+
+### Events
+
+Implements these standard media events through the embedded player: `durationchange`, `emptied`, `ended`, `error`, `loadedmetadata`, `loadstart`, `pause`, `play`, `playing`, `seeked`, `seeking`, `timeupdate`, `volumechange`, `waiting`.
+
+Also emits these Video.js-specific events:
+
+| Event | Description |
+| --- | --- |
+| `loadcomplete` | |
+| `sourcechange` | Fired when `source` changes, either directly or by resolving a new `src`. Read `source` for the new value. |