@videojs/react 10.0.0-beta.30 → 10.0.0-beta.31

package/docs/reference/tiktok-video.md

@@ -0,0 +1,280 @@
+# TikTokVideo
+
+Video component that plays TikTok videos through the TikTok embed player
+
+Video component that plays TikTok videos through the [TikTok embed player](https://developers.tiktok.com/doc/embed-player). TikTok videos are portrait, and the player won’t draw its chrome below 325×578, so the element starts at that size rather than the usual 300×150.
+
+## 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.
+
+tsx
+
+```
+<TikTokVideo src="https://www.tiktok.com/@_luwes/video/7527476667770522893" />
+```
+
+## 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](../concepts/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
+
+App.tsx
+
+App.css
+
+```
+import { TikTokVideo } from '@videojs/react/media/tiktok-video';
+
+export default function BasicUsage() {
+  return (
+    <div className="tiktok-video">
+      <TikTokVideo src="https://www.tiktok.com/@_luwes/video/7527476667770522893" controls />
+    </div>
+  );
+}
+```
+```
+/* TikTok videos are portrait: the element floors itself at 325x578. */
+.tiktok-video {
+  display: block;
+  width: 325px;
+  height: 578px;
+  margin-inline: auto;
+}
+```
+
+## API Reference
+
+### Props
+
+Accepts these Video.js-specific props:
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`autoplay`
+
+`boolean`
+
+`false`
+
+`controls`
+
+`boolean`
+
+`false`
+
+`defaultMuted`
+
+`boolean`
+
+`false`
+
+`loop`
+
+`boolean`
+
+`false`
+
+`muted`
+
+`boolean`
+
+`false`
+
+`playsInline`
+
+`boolean`
+
+`true`
+
+`poster`
+
+`string`
+
+`''`
+
+`preload`
+
+`MediaPreloadType`
+
+`'metadata'`
+
+`source`
+
+`TikTokSource | null`
+
+`null`
+
+▸
+
+Description
+
+TikTok URL or id in `src`, player params under `engine.tiktok`. Re-derives `src`; equal sources skip reload.
+
+`src`
+
+`string`
+
+`''`
+
+### 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](../concepts/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.
+
+tsx
+
+```
+<TikTokVideo
+  source={{
+    src: 'https://www.tiktok.com/@_luwes/video/7527476667770522893',
+    engine: { tiktok: { closed_caption: 0, rel: 1 } },
+  }}
+/>
+```
+
+Option
+
+Type
+
+Details
+
+`closed_caption`
+
+`0 | 1`
+
+▸
+
+Description
+
+Show the closed-caption button. Defaults to `1`.
+
+`description`
+
+`0 | 1`
+
+▸
+
+Description
+
+Show the video description. Defaults to `0`.
+
+`fullscreen_button`
+
+`0 | 1`
+
+▸
+
+Description
+
+Show the fullscreen button. Defaults to `1`.
+
+`music_info`
+
+`0 | 1`
+
+▸
+
+Description
+
+Show the track the video uses. Defaults to `0`.
+
+`native_context_menu`
+
+`0 | 1`
+
+▸
+
+Description
+
+Show the browser's native context menu. Defaults to `1`.
+
+`play_button`
+
+`0 | 1`
+
+▸
+
+Description
+
+Show the play button. Defaults to `1`.
+
+`progress_bar`
+
+`0 | 1`
+
+▸
+
+Description
+
+Show the progress bar. Defaults to `1`.
+
+`referrerPolicy`
+
+`ReferrerPolicy`
+
+▸
+
+Description
+
+`referrerpolicy` for the embed iframe. Not a TikTok player parameter.
+
+`rel`
+
+`0 | 1`
+
+▸
+
+Description
+
+Draw related videos from TikTok's recommendations (`1`) or the author's own videos (`0`). Defaults to `1`.
+
+`timestamp`
+
+`0 | 1`
+
+▸
+
+Description
+
+Show the current playback time and duration. Defaults to `1`.
+
+`volume_control`
+
+`0 | 1`
+
+▸
+
+Description
+
+Show the volume control. Defaults to `1`.
+
+### Ref
+
+Forwards its ref to the rendered `<iframe>`. The ref is an [HTMLIFrameElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLIFrameElement). Control playback with the component props and player APIs rather than the iframe ref.

package/docs/reference/title.md

@@ -32,7 +32,7 @@ A title can come from two places. The player uses the first one that has a value
 
 If neither has a value, there is nothing to show and the title hides itself.
 
-The title is player input, not player state, so change it the way you set it in the first place. The store exposes the resolved `title` to read, and nothing to write.
+The title is player input, not player state, so change it the way you set it in the first place. The store exposes the resolved `title` to read, and nothing to write. That resolution belongs to the [metadata feature](./feature-metadata.md), which the video and audio presets include.
 
 tsx
 

package/docs/reference/twitch-video.md

@@ -0,0 +1,211 @@
+# TwitchVideo
+
+Video component that plays Twitch videos and live channels through the Twitch embed player
+
+Video component that plays Twitch videos and live channels through the [Twitch embed player](https://dev.twitch.tv/docs/embed/video-and-clips/). Twitch’s own chrome stays hidden by default, so it drops into a [player skin](../concepts/skins.md) like any other media component; set `controls` to use Twitch’s UI instead.
+
+## Load a source
+
+`src` takes a video URL (`twitch.tv/videos/<id>`) or a channel URL (`twitch.tv/<channel>`), with or without the `www.` and `go.` hosts. A channel URL plays the channel’s live stream. Clips (`clips.twitch.tv`) are a different embed and aren’t supported.
+
+tsx
+
+```
+<TwitchVideo src="https://www.twitch.tv/videos/106400740" />
+```
+
+## Live channels
+
+A channel embed behaves like a live media component:
+
+*   `duration` reports `Infinity` while the stream is live.
+*   Seeking is unavailable: the embed exposes no DVR window.
+*   The stream going away and coming back dispatch `offline` and `online` events.
+*   `loop` never repeats a channel; a live stream doesn’t end.
+
+## Parent hostnames
+
+Twitch checks the embedding page’s ancestors against a `parent` allowlist and won’t play unless the current page is on it. The element always includes your page’s own hostname, so a plain embed needs no setup. When your player is itself framed by other hostnames, name each of them under `engine.twitch.parent`:
+
+tsx
+
+```
+<TwitchVideo
+  source={{
+    src: 'https://www.twitch.tv/videos/106400740',
+    engine: { twitch: { parent: ['embed.example.com'] } },
+  }}
+/>
+```
+
+## Behavior
+
+*   Volume and mute both work, like a native `<video>`.
+*   `playbackRate` is reported but never applied: the embed has no rate command.
+*   `loop` restarts a finished video from the top; the embed has no loop parameter.
+*   `controls` is read when the embed is built; changing it later doesn’t take effect, since rebuilding the iframe would lose the playback session.
+*   Fullscreen targets the iframe, so Twitch’s own chrome shows in fullscreen.
+
+## Examples
+
+### Basic Usage
+
+App.tsx
+
+App.css
+
+```
+import { TwitchVideo } from '@videojs/react/media/twitch-video';
+
+export default function BasicUsage() {
+  return (
+    <div className="twitch-video">
+      <TwitchVideo src="https://www.twitch.tv/videos/106400740" controls />
+    </div>
+  );
+}
+```
+```
+.twitch-video {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+```
+
+## API Reference
+
+### Props
+
+Accepts these Video.js-specific props:
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`autoplay`
+
+`boolean`
+
+`false`
+
+`controls`
+
+`boolean`
+
+`false`
+
+`defaultMuted`
+
+`boolean`
+
+`false`
+
+`loop`
+
+`boolean`
+
+`false`
+
+`muted`
+
+`boolean`
+
+`false`
+
+`playsInline`
+
+`boolean`
+
+`true`
+
+`poster`
+
+`string`
+
+`''`
+
+`preload`
+
+`MediaPreloadType`
+
+`'metadata'`
+
+`source`
+
+`TwitchSource | null`
+
+`null`
+
+▸
+
+Description
+
+Twitch VOD or channel URL in `src`, plus embed parameters under `engine.twitch`. Replacing it re-derives `src`.
+
+`src`
+
+`string`
+
+`''`
+
+### Engine options
+
+#### `source.engine.twitch`
+
+Pass [Twitch embed parameters](https://dev.twitch.tv/docs/embed/video-and-clips/) under `source.engine.twitch`, spelled exactly as Twitch spells them, plus anything Twitch adds next. [Media Sources](../concepts/media-sources.md) covers how engine options fit into a structured source.
+
+`controls`, `autoplay`, and `muted` come from the props of the same name, and the video or channel comes from `src`, so none of those have an `engine.twitch` spelling.
+
+Option
+
+Type
+
+Details
+
+`collection`
+
+`string`
+
+▸
+
+Description
+
+Collection to play through, starting from the video named by `src`.
+
+`parent`
+
+`string | readonly string[]`
+
+▸
+
+Description
+
+Every hostname the embed may be framed by. Twitch checks the frame's ancestors against it and refuses to play when the current page is missing, which is why the page's own hostname is always included on top of this.
+
+`referrerPolicy`
+
+`ReferrerPolicy`
+
+▸
+
+Description
+
+`referrerpolicy` for the embed iframe. Not a Twitch embed parameter, so it never reaches the URL: the React player applies it to the iframe it renders, and the HTML player reads its own `referrerpolicy` attribute instead.
+
+`time`
+
+`string`
+
+▸
+
+Description
+
+Start position, spelled the way Twitch spells timestamps: `1h30m10s`.
+
+### Ref
+
+Forwards its ref to the rendered `<iframe>`. The ref is an [HTMLIFrameElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLIFrameElement). Control playback with the component props and player APIs rather than the iframe ref.