@videojs/html 10.0.0-rc.1 → 10.0.0-rc.3

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

@@ -0,0 +1,157 @@
+# cloudflare-video
+
+Video component that plays Cloudflare Stream videos through the Stream player
+
+[Cloudflare Stream](https://developers.cloudflare.com/stream/) runs in an embedded player. Its own chrome stays hidden by default, so it drops into a [player skin](../../guides/skins.md) like any other media component; set `controls` to use Cloudflare’s UI instead.
+
+## Import
+
+```bash
+pnpm add @videojs/cloudflare-video
+```
+
+```ts
+import '@videojs/html/media/cloudflare-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.3/media/cloudflare-video.js"></script>
+```
+
+## Load a source
+
+`src` takes a raw 32-character video UID, any `cloudflarestream.com` or `videodelivery.net` URL, or a signed token. Watch, embed, iframe, manifest, and thumbnail URLs all carry the UID in the same position, and a signed token stands in for the UID wherever one appears.
+
+```html
+<cloudflare-video src="https://watch.videodelivery.net/bfbd585059e33391d67b0f1d15fe6ea4"></cloudflare-video>
+```
+
+## Signed playback
+
+For [signed URLs](https://developers.cloudflare.com/stream/viewing-videos/securing-your-stream/), pass the signed token wherever the UID would go: as the whole `src`, or inside a Stream URL. Keep your customer subdomain when your URLs name one. Cloudflare serves signed and access-controlled videos only from `customer-<code>.cloudflarestream.com`, so the element preserves that origin instead of collapsing it onto the shared host.
+
+## Behavior
+
+A few things work differently from a native `<video>` element, because the Stream embed doesn’t expose them:
+
+- The embed owns text tracks: `textTracks` stays empty, and `engine.cloudflare.defaultTextTrack` picks the track to show.
+- Picture-in-picture is unavailable, and the player reports it as unsupported.
+- Fullscreen targets the iframe, so Cloudflare’s own chrome shows in fullscreen.
+- `playsInline` has no effect: the Stream embed always plays inline.
+
+## Examples
+
+### Basic Usage
+
+**index.html**
+
+```html
+<cloudflare-video class="cloudflare-video" src="https://watch.videodelivery.net/bfbd585059e33391d67b0f1d15fe6ea4" controls></cloudflare-video>
+```
+
+**index.css**
+
+```css
+.cloudflare-video {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+```
+
+**index.ts**
+
+```ts
+import '@videojs/html/media/cloudflare-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` | `{ play(): Promise<void> \| void; pause(): void; addEventListener(type: string, listener: ((event: Event) => void)): void; removeEventListener(type: string, listener: ((event: Event) => void)): void; src: string; currentTime: number; volume: number; muted: boolean; playbackRate: number; loop: boolean; autoplay: boolean; controls: boolean; preload: string; poster: string; paused: boolean; ended: boolean; seeking: boolean; duration: number; buffered: TimeRanges; played: TimeRanges; videoWidth: number; videoHeight: number } \| null` | — | Read-only. Underlying Stream SDK player instance (null until the SDK loads). |
+| `error` | `MediaError \| null` | — | Read-only. |
+| `isFullscreen` | `boolean` | — | Read-only. |
+| `loop` | `boolean` | `false` | |
+| `muted` | `boolean` | `false` | |
+| `paused` | `boolean` | — | Read-only. |
+| `playbackRate` | `number` | — | |
+| `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?: CloudflareSourceEngineConfig } \| null` | `null` | Structured source: `src` plus embed parameters under `engine.cloudflare`. Replacing it re-derives `src`. |
+| `src` | `string` | `''` | |
+| `textTracks` | `TextTrackListLike` | — | Read-only. Always empty: the SDK exposes no track API, and the embed owns the track picked by `defaultTextTrack`. |
+| `videoHeight` | `number` | — | Read-only. |
+| `videoWidth` | `number` | — | Read-only. |
+| `volume` | `number` | — | |
+
+### Engine options
+
+#### `source.engine.cloudflare`
+
+Pass [Stream player parameters](https://developers.cloudflare.com/stream/viewing-videos/using-the-stream-player/) under `source.engine.cloudflare`, spelled exactly as Cloudflare spells them, plus anything Cloudflare adds next. They’re serialized onto the embed URL untouched, and the embed reads them once, when its URL is built. [Media Sources](../../guides/media-sources.md) covers how engine options fit into a structured source.
+
+`controls`, `autoplay`, `loop`, `muted`, `preload`, and `poster` come from the props of the same name, so they have no `engine.cloudflare` spelling.
+
+```ts
+const video = document.querySelector('cloudflare-video');
+video.source = {
+  src: 'bfbd585059e33391d67b0f1d15fe6ea4',
+  engine: { cloudflare: { primaryColor: '#f03e3e', startTime: '5m30s' } },
+};
+```
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `ad-url` | `string \| undefined` | VAST tag to play as a pre-roll ad. Reported through the `stream-ad*` events. |
+| `defaultTextTrack` | `string \| undefined` | BCP 47 language of the text track to show by default (`'en'`, `'de'`). |
+| `letterboxColor` | `string \| undefined` | Any CSS color for the letterbox bars around a video that does not fill the player. |
+| `primaryColor` | `string \| undefined` | Any CSS color for the progress bar and other player accents. |
+| `referrerPolicy` | `ReferrerPolicy \| undefined` | `referrerpolicy` for the embed iframe. Not a Cloudflare player parameter. |
+| `startTime` | `number \| string \| undefined` | Where playback starts, in seconds or as a time string (`'5m30s'`). |
+
+### Methods
+
+Supports these media methods: `exitFullscreen`, `load`, `pause`, `play`, `requestFullscreen`.
+
+### Events
+
+Implements these standard media events through the embedded player: `durationchange`, `emptied`, `error`, `loadedmetadata`, `loadstart`, `volumechange`.
+
+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. |

package/docs/reference/components/controls.md

@@ -0,0 +1,266 @@
+# media-controls
+
+Container component for composing and auto-hiding video player controls on user interaction
+
+## Import
+
+```ts
+import '@videojs/html/ui/controls';
+import '@videojs/html/ui/controls-backdrop';
+import '@videojs/html/ui/controls-content';
+import '@videojs/html/ui/controls-group';
+```
+
+## Anatomy
+
+Import the component and assemble its parts:
+
+```html
+<media-controls>
+  <media-controls-backdrop></media-controls-backdrop>
+  <media-controls-content>
+    <media-controls-group></media-controls-group>
+  </media-controls-content>
+</media-controls>
+```
+
+## Behavior
+
+If the user is active, or if the video is paused, this component will show controls. Otherwise, it will hide them after a short delay.
+
+User activity is tracked via pointer movement, keyboard input, and focus events on the player container. On touch devices, a quick tap toggles visibility. `mouseleave` immediately sets the user as inactive.
+
+`visibility` selects between the two modes. The default, `auto`, follows the player’s controls visibility state as described above. `always` keeps the controls visible and reports the user as active regardless of playback or idle state, and works without the controls feature. The idle delay itself is not configurable.
+
+```html
+<media-controls visibility="always">
+  <media-controls-content>...</media-controls-content>
+</media-controls>
+```
+
+## Styling
+
+`<media-controls>` is a state and context provider that also reflects the controls state data attributes. `<media-controls-content>` is the interactive controls surface and receives the same controls state data attributes.
+
+`<media-controls-backdrop>` is an optional presentational sibling of `<media-controls-content>`. It receives the same controls state data attributes, allowing its styling and transitions to be authored independently from the controls surface.
+
+By default, controls have the following styles:
+
+```css
+/* Click-through: clicks pass through controls to video beneath */
+media-controls-content {
+  pointer-events: none;
+}
+
+media-controls-group {
+  pointer-events: auto;
+}
+
+media-controls-backdrop {
+  position: absolute;
+  inset: 0;
+  transition: opacity 0.35s;
+}
+
+/* Fade transition */
+media-controls-content {
+  transition: opacity 0.25s;
+}
+
+media-controls-content:not([data-visible]) {
+  opacity: 0;
+}
+
+media-controls-backdrop:not([data-visible]) {
+  opacity: 0;
+}
+```
+
+## Accessibility
+
+No ARIA role is applied to `<media-controls>` or `<media-controls-content>` — they provide state and layout, not a landmark. `<media-controls-backdrop>` is always hidden from assistive technology. `<media-controls-group>` automatically receives `role="group"` when an `aria-label` or `aria-labelledby` attribute is provided; otherwise no role is assigned.
+
+## Examples
+
+### Basic Usage
+
+**index.html**
+
+```html
+<video-player class="video-player">
+  <media-container>
+    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
+
+    <media-controls>
+      <media-controls-backdrop class="controls-backdrop"></media-controls-backdrop>
+      <media-controls-content class="media-controls">
+        <media-controls-group class="controls-group" aria-label="Playback controls">
+          <media-play-button class="button media-play-button">
+            <span class="paused">Play</span>
+            <span class="playing">Pause</span>
+          </media-play-button>
+          <media-time class="time" type="current"></media-time>
+        </media-controls-group>
+      </media-controls-content>
+    </media-controls>
+  </media-container>
+</video-player>
+```
+
+**index.css**
+
+```css
+.video-player media-container {
+  position: relative;
+  display: block;
+}
+
+.video-player media-container video {
+  width: 100%;
+}
+
+.media-controls {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: flex-end;
+  padding: 12px;
+  pointer-events: none;
+  transition: opacity 0.25s;
+}
+
+.controls-backdrop {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+  background: linear-gradient(to top, rgba(0, 0, 0, 0.45), transparent 45%);
+  opacity: 1;
+  transition: opacity 0.35s;
+}
+
+.controls-backdrop:not([data-visible]),
+.media-controls:not([data-visible]) {
+  opacity: 0;
+}
+
+.controls-group {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+  pointer-events: auto;
+}
+
+.time {
+  display: inline-flex;
+  gap: 4px;
+  align-items: center;
+  padding-block: 8px;
+  padding-inline: 16px;
+  font-size: 14px;
+  color: black;
+  background: rgba(255, 255, 255, 0.75);
+  border: 1px solid rgba(255, 255, 255, 0.25);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+
+.button {
+  padding-block: 8px;
+  padding-inline: 16px;
+  font-size: 14px;
+  color: black;
+  cursor: pointer;
+  background: rgba(255, 255, 255, 0.75);
+  border: 1px solid rgba(255, 255, 255, 0.25);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+
+.button .paused,
+.button .playing {
+  display: none;
+}
+
+.media-play-button[data-paused] .paused {
+  display: inline;
+}
+
+.media-play-button:not([data-paused]) .playing {
+  display: inline;
+}
+```
+
+**index.ts**
+
+```ts
+import '@videojs/html/video/player';
+import '@videojs/html/ui/container';
+import '@videojs/html/ui/controls';
+import '@videojs/html/ui/controls-backdrop';
+import '@videojs/html/ui/controls-content';
+import '@videojs/html/ui/controls-group';
+import '@videojs/html/ui/play-button';
+import '@videojs/html/ui/time';
+```
+
+## API Reference
+
+### media-controls
+
+Tracks controls visibility, reflects it as data attributes, and shares it with its descendant controls parts. Hiding the controls closes any popup open inside it.
+
+#### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `visibility` | `'auto' \| 'always'` | `'auto'` | Whether controls follow player visibility state or remain visible. |
+
+#### State
+
+State is reflected as data attributes for CSS styling.
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `visible` | `boolean` | Whether the controls are visible. |
+| `userActive` | `boolean` | Whether the user has recently interacted with the player. |
+
+#### Data attributes
+
+| Attribute | Description |
+| --- | --- |
+| `data-visible` | Present when controls are visible. |
+| `data-user-active` | Present when the user has recently interacted. |
+
+### media-controls-backdrop
+
+Presentational backdrop that reflects its owning controls surface's state.
+
+#### Data attributes
+
+| Attribute | Description |
+| --- | --- |
+| `data-visible` | Present when controls are visible. |
+| `data-user-active` | Present when the user has recently interacted. |
+
+### media-controls-content
+
+Interactive surface that reflects its owning controls state.
+
+#### Data attributes
+
+| Attribute | Description |
+| --- | --- |
+| `data-visible` | Present when controls are visible. |
+| `data-user-active` | Present when the user has recently interacted. |
+
+### media-controls-group
+
+Layout group for related controls; sets `role="group"` when labeled.
+
+#### Data attributes
+
+| Attribute | Description |
+| --- | --- |
+| `data-visible` | Present when controls are visible. |
+| `data-user-active` | Present when the user has recently interacted. |

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

@@ -0,0 +1,111 @@
+# dash-video
+
+DASH video element powered by dash.js for adaptive bitrate streaming
+
+> **Caution: Unstable API**
+>
+> This API works today, but its shape is still settling and may change in a minor release. The implementation underneath is production quality; what is not final is how you configure it from Video.js. Pin your version and check the changelog when you upgrade.
+
+DASH video element powered by [dash.js](https://github.com/Dash-Industry-Forum/dash.js/) for MPEG-DASH adaptive bitrate streaming.
+
+## Import
+
+```bash
+pnpm add @videojs/dash-video
+```
+
+```ts
+import '@videojs/html/media/dash-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.3/media/dash-video.js"></script>
+```
+
+## Examples
+
+### Basic Usage
+
+**index.html**
+
+```html
+<media-container class="media-container">
+  <dash-video src="https://dash.akamaized.net/akamai/streamroot/050714/Spring_4Ktest.mpd" autoplay muted playsinline loop></dash-video>
+</media-container>
+```
+
+**index.css**
+
+```css
+.media-container {
+  position: relative;
+  display: block;
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+```
+
+**index.ts**
+
+```ts
+import '@videojs/html/ui/container';
+import '@videojs/html/media/dash-video';
+```
+
+## API Reference
+
+### Attributes
+
+Forwards these standard media attributes to the internal `<video>`. See the [MDN media element reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video): `autopictureinpicture`, `autoplay`, `controls`, `controlslist`, `crossorigin`, `disablepictureinpicture`, `disableremoteplayback`, `loading`, `loop`, `muted`, `playsinline`, `poster`, `preload`, `src`.
+
+These Video.js-specific attributes configure media behavior:
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `stream-type` | `MediaStreamType` | — | Current stream type (`'on-demand'`, `'live'`, or `'unknown'`). Defaults to `'unknown'`; detecting hosts update it automatically, and consumers can set it to override detection. |
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `contentData` | `MediaContentData \| undefined` | — | Read-only. |
+| `engine` | `dashjs.MediaPlayerClass` | — | Read-only. Underlying playback engine — the dash.js `MediaPlayerClass` instance. An advanced escape hatch for direct engine access; normal playback is driven through this element's own properties and methods. |
+| `isFullscreen` | `boolean` | — | Read-only. |
+| `isPictureInPicture` | `boolean` | — | Read-only. |
+| `liveEdgeStart` | `number` | — | Read-only. |
+| `source` | `{ src?: string; engine?: DashEngineConfig } \| null` | `null` | Structured source: the MPD URL in `src`, plus dash.js settings in `engine.dashJs`. Replacing it re-derives `src`. Dash.js takes settings on a live player, so changing `engine.dashJs` re-applies them in place instead of recreating the engine. |
+| `src` | `string` | `''` | |
+| `streamType` | `MediaStreamType` | — | Current stream type (`'on-demand'`, `'live'`, or `'unknown'`). Defaults to `'unknown'`; detecting hosts update it automatically, and consumers can set it to override detection. |
+| `targetLiveWindow` | `number` | — | Read-only. |
+| `webkitCurrentPlaybackTargetIsWireless` | `boolean \| undefined` | — | Read-only. |
+| `webkitPresentationMode` | `WebKitPresentationMode \| undefined` | — | Read-only. |
+| `webkitSetPresentationMode` | `((mode: WebKitPresentationMode) => void) \| undefined` | — | Read-only. |
+
+Also exposes these properties from the native media API. See [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) for details: `autoplay`, `buffered`, `controls`, `crossOrigin`, `currentSrc`, `currentTime`, `defaultMuted`, `defaultPlaybackRate`, `disablePictureInPicture`, `disableRemotePlayback`, `duration`, `ended`, `error`, `loop`, `muted`, `paused`, `playbackRate`, `played`, `playsInline`, `poster`, `preload`, `readyState`, `remote`, `seekable`, `seeking`, `textTracks`, `title`, `videoHeight`, `videoWidth`, `volume`.
+
+### Methods
+
+Supports these media methods. See [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) for details: `addTextTrack`, `canPlayType`, `exitFullscreen`, `exitPictureInPicture`, `load`, `pause`, `play`, `requestFullscreen`, `requestPictureInPicture`.
+
+### Events
+
+Re-dispatches these standard media events from the internal media element: `abort`, `addtrack`, `canplay`, `canplaythrough`, `change`, `contentdatachange`, `durationchange`, `emptied`, `ended`, `enterpictureinpicture`, `error`, `leavepictureinpicture`, `loadeddata`, `loadedmetadata`, `loadstart`, `pause`, `play`, `playing`, `progress`, `ratechange`, `removetrack`, `resize`, `seeked`, `seeking`, `stalled`, `suspend`, `timeupdate`, `volumechange`, `waiting`.
+
+Also emits these Video.js-specific events:
+
+| Event | Description |
+| --- | --- |
+| `sourcechange` | Fired when `source` changes, either directly or by resolving a new `src`. Read `source` for the new value. |
+
+### CSS custom properties
+
+| Variable | Description |
+| --- | --- |
+| `--media-video-border-radius` | Border radius of the video element. |
+| `--media-object-fit` | Object fit for the video. |
+| `--media-object-position` | Object position for the video. |
+| `--media-caption-track-duration` | Duration of the caption track transition. |
+| `--media-caption-track-delay` | Delay before the caption track transition. |
+| `--media-caption-track-y` | Vertical offset of the caption track. |