@videojs/html 10.0.0-beta.9 → 10.0.0-rc.2

package/docs/reference/audio-track-radio-group.md

@@ -0,0 +1,394 @@
+# media-audio-track-radio-group
+
+A menu radio group for selecting an audio track
+
+Creates radio items from the player audio track state and selects the enabled track.
+
+## Import
+
+ts
+
+```
+import '@videojs/html/ui/audio-track-radio-group';
+```
+
+## Anatomy
+
+html
+
+```
+<media-audio-track-radio-group>
+  <template>
+    <media-menu-radio-item>
+      <span data-part="label"></span>
+      <media-menu-item-indicator></media-menu-item-indicator>
+    </media-menu-radio-item>
+  </template>
+</media-audio-track-radio-group>
+```
+
+## Behavior
+
+The group is available when the configured media exposes more than one audio track. Labels use the track label, then language, then kind. Pass `formatTrack` to customize the visible labels.
+
+`<media-audio-track-radio-group>` generates `<media-menu-radio-item>` children. Add an optional `<template>` with a single `<media-menu-radio-item>` to customize each generated item.
+
+## Styling
+
+Attribute
+
+Values
+
+Description
+
+`data-audio-track`
+
+`string`
+
+Current audio track value.
+
+`data-disabled`
+
+Present / absent
+
+Present when audio track selection is disabled.
+
+`data-hidden`
+
+Present / absent
+
+Present when multiple audio tracks are unavailable.
+
+`data-availability`
+
+`"available"` / `"unavailable"`
+
+Whether multiple audio tracks are available.
+
+Unavailable groups receive the native `hidden` attribute.
+
+## Accessibility
+
+The group uses the menu radio group pattern.
+
+The element receives an accessible label from the `label` property or defaults to `Audio`.
+
+## Examples
+
+### Basic usage
+
+Audio
+
+index.html
+
+index.css
+
+index.ts
+
+```
+<video-player class="video-player">
+  <media-container>
+    <hlsjs-video
+      class="video-media"
+      src="https://stream.mux.com/s41JYeqIpBMBzE4OzxDyGR2yrp2hD1CQ6gJN9SlVGDQ.m3u8"
+      autoplay
+      crossorigin="anonymous"
+      muted
+      playsinline
+      loop
+    ></hlsjs-video>
+    <div class="menu-bar">
+      <button type="button" commandfor="audio-menu" class="settings-trigger">Audio</button>
+      <media-menu id="audio-menu" side="top" align="end" class="menu">
+        <media-menu-content>
+          <media-audio-track-radio-group class="menu-group" label="Audio tracks">
+            <template>
+              <media-menu-radio-item class="menu-item">
+                <span data-part="label"></span>
+                <media-menu-item-indicator force-mount class="menu-indicator">✓</media-menu-item-indicator>
+              </media-menu-radio-item>
+            </template>
+          </media-audio-track-radio-group>
+        </media-menu-content>
+      </media-menu>
+    </div>
+  </media-container>
+</video-player>
+```
+```
+.video-player media-container {
+  position: relative;
+  display: block;
+}
+
+.video-media {
+  width: 100%;
+}
+
+.menu-bar {
+  position: absolute;
+  right: 10px;
+  bottom: 10px;
+}
+
+.menu-bar:has([data-availability="unavailable"]) {
+  display: none;
+}
+
+.settings-trigger {
+  padding: 6px 16px;
+  color: black;
+  cursor: pointer;
+  background: rgba(255, 255, 255, 0.75);
+  border: 1px solid rgba(255, 255, 255, 0.35);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+
+.menu {
+  --media-menu-side-offset: 8px;
+  box-sizing: border-box;
+  min-width: 180px;
+  max-width: var(--media-menu-available-width, var(--media-popover-available-width, none));
+  max-height: var(--media-menu-available-height, var(--media-popover-available-height, none));
+  padding: 6px;
+  overflow: auto;
+  overscroll-behavior: none;
+  font-size: 14px;
+  color: white;
+  background: rgba(0, 0, 0, 0.88);
+  border-radius: 8px;
+  backdrop-filter: blur(10px);
+}
+
+.menu-group {
+  display: grid;
+  gap: 2px;
+}
+
+.menu-item {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  justify-content: space-between;
+  min-height: 32px;
+  padding: 0 10px;
+  font: inherit;
+  color: inherit;
+  cursor: pointer;
+  background: none;
+  border: 0;
+  border-radius: 6px;
+}
+
+.menu-item[data-highlighted] {
+  background: rgba(255, 255, 255, 0.16);
+}
+
+.menu-indicator {
+  opacity: 0;
+}
+
+media-menu-radio-item[aria-checked="true"] .menu-indicator {
+  opacity: 1;
+}
+```
+```
+import '@videojs/html/video/player';
+import '@videojs/html/ui/container';
+import '@videojs/html/media/hlsjs-video';
+import '@videojs/html/ui/menu';
+import '@videojs/html/ui/audio-track-radio-group';
+```
+
+## API Reference
+
+### 
+
+media-audio-track-radio-group
+
+Owns audio-track option state and shares it with an enclosing menu. Does not render a DOM element.
+
+#### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`disabled`
+
+`boolean`
+
+`false`
+
+▸
+
+Attribute
+
+`disabled`
+
+Description
+
+Whether audio track selection is disabled.
+
+`formatTrack`
+
+`string) | function`
+
+`formatTrackLabel`
+
+▸
+
+Attribute
+
+`format-track`
+
+Description
+
+Custom formatter for visible track labels.
+
+Type
+
+`((track: MediaAudioTrack) => Text | string)`
+
+`label`
+
+`object`
+
+`''`
+
+▸
+
+Attribute
+
+`label`
+
+Description
+
+Custom label for the options group.
+
+Type
+
+`{ key: string; text: string } | string | ((state: AudioTrackRadioGroupState) => Text | string)`
+
+#### State
+
+State is reflected as data attributes for CSS styling.
+
+Property
+
+Type
+
+Details
+
+`label`
+
+`{ key: string; text: string } | string`
+
+`value`
+
+`string`
+
+▸
+
+Description
+
+Current radio-group value.
+
+`options`
+
+`readonly Option[]`
+
+▸
+
+Description
+
+Ordered options displayed by platform adapters.
+
+`disabled`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the entire option group is disabled.
+
+`hidden`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the option group is hidden because no meaningful selection is available.
+
+`availability`
+
+`'available' | 'unavailable'`
+
+▸
+
+Description
+
+Whether the media exposes a meaningful selection.
+
+#### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-audio-track`
+
+`string`
+
+▸
+
+Description
+
+Current audio track value.
+
+`data-disabled`
+
+▸
+
+Description
+
+Present when audio track selection is disabled.
+
+`data-hidden`
+
+▸
+
+Description
+
+Present when audio track selection is unavailable.
+
+`data-availability`
+
+`'available' | 'unavailable'`
+
+▸
+
+Description
+
+Indicates audio track availability (`available` or `unavailable`).
+
+#### Events
+
+Event
+
+Description
+
+`value-change`
+
+Fired when the selected value changes.

package/docs/reference/audio.md

@@ -0,0 +1,74 @@
+# audio
+
+Native audio playback that can provide media to a Video.js player
+
+## Import
+
+The media element is the browser’s native `<audio>`. Import the audio player registration when it should provide media to Video.js:
+
+ts
+
+```
+import '@videojs/html/audio/player';
+```
+
+## Anatomy
+
+html
+
+```
+<audio>
+  <source />
+</audio>
+```
+
+## Use with a player
+
+Place a native `<audio>` anywhere inside `<audio-player>`. It becomes that player’s media provider automatically.
+
+## Native behavior
+
+Video.js does not replace the native audio API. Use `src` for one URL or add child [`<source>` elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/source) when the browser should choose between candidates. See [Media sources](../concepts/media-sources.md) when you need an HLS, Mux, Spotify, or other playback adapter.
+
+`<audio>` is the native element itself. Set its attributes and properties, listen for native media events, and access it through an `HTMLAudioElement` reference.
+
+See MDN for the complete [`<audio>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/audio), [`HTMLAudioElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLAudioElement), and shared [`HTMLMediaElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement) APIs.
+
+## Examples
+
+### Basic Usage
+
+This native audio element uses a child source and browser controls while providing media to the surrounding Video.js player. The shared demo MP4 supplies its audio track, so the `<source>` does not claim an audio-only MIME type.
+
+index.html
+
+index.css
+
+index.ts
+
+```
+<audio-player>
+  <media-container class="html-audio-basic">
+    <audio class="html-audio-basic__media" controls preload="metadata">
+      <source src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" />
+    </audio>
+  </media-container>
+</audio-player>
+```
+```
+.html-audio-basic {
+  display: grid;
+  width: 100%;
+  padding: 24px;
+  background: #e5e7eb;
+  border-radius: 8px;
+  place-items: center;
+}
+
+.html-audio-basic__media {
+  width: 100%;
+}
+```
+```
+import '@videojs/html/audio/player';
+```

package/docs/reference/background-video-skin.md

@@ -0,0 +1,39 @@
+# background-video-skin
+
+The background preset's chrome-less skin for ambient video
+
+The only skin of the background preset: a chrome-less surface that sizes ambient video with no visible controls. See [Skins](../concepts/skins.md) for how packaged skins work and [Presets](../concepts/presets.md) for what the background preset ships.
+
+## Import
+
+ts
+
+```
+import '@videojs/html/background/skin';
+```
+
+The import registers the skin and every UI element it composes. The [CDN](../concepts/cdn.md) player bundle registers this skin together with its player:
+
+html
+
+```
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.2/background.js"></script>
+```
+
+## Usage
+
+The skin goes between the player and the media element. It sizes the ambient video and renders no visible controls.
+
+html
+
+```
+<background-video-player>
+  <background-video-skin>
+    <background-video src="video.mp4"></background-video>
+  </background-video-skin>
+</background-video-player>
+```
+
+## Styling
+
+Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](../how-to/customize-skins.md#style-a-packaged-skin) documents the properties. The background video skin cannot be ejected.

package/docs/reference/background-video.md

@@ -0,0 +1,95 @@
+# background-video
+
+Decorative background video element with automatic muting and looping
+
+Decorative background video for a source the browser can play natively. By default it’s muted, looped, and autoplaying.
+
+`<background-video>` renders a `<video>` inside shadow DOM and fills the box you give the component. Use the opt-out attributes in the [API reference](#api-reference) to change its playback defaults.
+
+An HLS URL only works where the browser has native HLS playback. See [Add a background video](../how-to/add-a-background-video.md) to choose a cross-browser HLS or Mux path and set up layout, poster, and decorative semantics.
+
+## Import
+
+ts
+
+```
+import '@videojs/html/media/background-video';
+```
+
+Or load it from the [CDN](../concepts/cdn.md):
+
+html
+
+```
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.2/media/background-video.js"></script>
+```
+
+## Examples
+
+### Basic Usage
+
+index.html
+
+index.css
+
+index.ts
+
+```
+<div class="container">
+  <background-video src="https://stream.mux.com/601n4w1fq88NJiVpzvrQQeQfNnnjjfKMIN7dCGAEarTs/highest.mp4"></background-video>
+</div>
+```
+```
+.container {
+  display: grid;
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+```
+```
+import '@videojs/html/media/background-video';
+```
+
+## API Reference
+
+### Attributes
+
+Attribute
+
+Description
+
+`src`
+
+URL of a video the browser can play directly, such as an MP4 or WebM file.
+
+`nomuted`
+
+Opt out of muted playback. By default the video is muted.
+
+`noloop`
+
+Opt out of looped playback. By default the video loops.
+
+`noautoplay`
+
+Opt out of autoplay. By default the video autoplays.
+
+### CSS Custom Properties
+
+Variable
+
+Default
+
+Description
+
+`–media-object-fit`
+
+`inherit`
+
+Controls how the video fits its container.
+
+`–media-object-position`
+
+`50% 50%`
+
+Controls the position of the video within its container.