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

package/docs/reference/{seek-indicator.md → components/seek-indicator.md}

@@ -4,17 +4,14 @@ A temporary visual indicator for keyboard and gesture seeking
 
 ## Import
 
-ts
-
-```
+```ts
 import '@videojs/html/ui/seek-indicator';
+import '@videojs/html/ui/seek-indicator-value';
 ```
 
 ## Anatomy
 
-html
-
-```
+```html
 <media-seek-indicator>
   <media-seek-indicator-value></media-seek-indicator-value>
 </media-seek-indicator>
@@ -22,69 +19,33 @@ html
 
 ## Behavior
 
-`SeekIndicator` displays feedback for seek actions emitted by a [`Hotkey`](./hotkey.md) or [`Gesture`](./gesture.md) in the same player `Container`. It does not react to current-time changes or seek commands invoked directly through the player store.
-
-Action
-
-Direction
-
-Value
-
-`seekStep`
+`<media-seek-indicator>` displays feedback for seek actions emitted by a [`<media-hotkey>`](./hotkey.md) or [`<media-gesture>`](./gesture.md) in the same player `<media-container>`. It does not react to current-time changes or seek commands invoked directly through the player store.
 
-The sign of `value` determines `forward` or `backward`
-
-The absolute number of seconds, such as `10s`
-
-`seekToPercent`
-
-The target percentage is compared with the current time
-
-The formatted current time when the action occurred
+| Action | Direction | Value |
+| --- | --- | --- |
+| `seekStep` | The sign of `value` determines `forward` or `backward` | The absolute number of seconds, such as `10s` |
+| `seekToPercent` | The target percentage is compared with the current time | The formatted current time when the action occurred |
 
 Rapid `seekStep` actions in the same direction accumulate while the indicator is open. For example, two 10-second forward actions display `20s`. Changing direction or using `seekToPercent` starts a new display. During a rapid sequence, another full step is not added when it would pass the start or duration boundary.
 
-For `seekToPercent`, pass a percentage from 0 to 100 as `value`. A `Hotkey` with `keys="0-9"` can omit `value`; the pressed digit maps to 0%, 10%, and so on through 90%.
-
-The indicator closes after `closeDelay`, which defaults to 800 milliseconds. React stops rendering the Root after its close transition. The HTML custom element remains in the document with `hidden` until the next handled seek action.
-
-## Styling
-
-Attribute
-
-Values
-
-Description
-
-`data-open`
-
-Present / absent
-
-Present while the indicator is open
-
-`data-direction`
-
-`"forward"` | `"backward"`
+For `seekToPercent`, pass a percentage from 0 to 100 as `value`. A `<media-hotkey>` with `keys="0-9"` can omit `value`; the pressed digit maps to 0%, 10%, and so on through 90%.
 
-Direction of the handled seek
+The indicator closes after `closeDelay`, which defaults to 800 milliseconds.
 
-`data-starting-style`
+The element remains in the document with `hidden` until the next handled seek action.
 
-Present / absent
-
-Present during the open transition
-
-`data-ending-style`
-
-Present / absent
-
-Present during the close transition
+## Styling
 
-Position the Root from `data-direction` and use the transition attributes for entry and exit styles.
+| Attribute | Values | Description |
+| --- | --- | --- |
+| `data-open` | Present / absent | Present while the indicator is open |
+| `data-direction` | `"forward"` \| `"backward"` | Direction of the handled seek |
+| `data-starting-style` | Present / absent | Present during the open transition |
+| `data-ending-style` | Present / absent | Present during the close transition |
 
-css
+Position the root from `data-direction` and use the transition attributes for entry and exit styles.
 
-```
+```css
 media-seek-indicator[data-direction="backward"] {
   left: 1rem;
 }
@@ -101,7 +62,7 @@ media-seek-indicator[data-ending-style] {
 
 ## Accessibility
 
-`SeekIndicator` is visual feedback and does not create a live region. Keep the same seek operation available through keyboard-operable controls, and pair it with [`StatusAnnouncer`](./status-announcer.md) when changes should be announced to screen readers. Do not make `SeekIndicator.Value` a live region because rapid seek input would produce repeated announcements.
+`<media-seek-indicator>` is visual feedback and does not create a live region. Keep the same seek operation available through keyboard-operable controls, and pair it with [`<media-status-announcer>`](./status-announcer.md) when changes should be announced to screen readers. Do not make `<media-seek-indicator-value>` a live region because rapid seek input would produce repeated announcements.
 
 ## Examples
 
@@ -109,15 +70,9 @@ media-seek-indicator[data-ending-style] {
 
 Focus the player, then press the left or right arrow key to seek by ten seconds. Press a digit from 0 through 9 to seek to a percentage of the duration.
 
-Focus the player · ←/→: seek 10s · 0–9: seek to percent
-
-index.html
+**index.html**
 
-index.css
-
-index.ts
-
-```
+```html
 <video-player>
   <media-container class="html-seek-indicator-basic" tabindex="0">
     <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
@@ -131,7 +86,10 @@ index.ts
   </media-container>
 </video-player>
 ```
-```
+
+**index.css**
+
+```css
 .html-seek-indicator-basic {
   position: relative;
 }
@@ -213,186 +171,50 @@ index.ts
   font-variant-numeric: tabular-nums;
 }
 ```
-```
+
+**index.ts**
+
+```ts
 import '@videojs/html/video/player';
+import '@videojs/html/ui/container';
 import '@videojs/html/ui/hotkey';
 import '@videojs/html/ui/seek-indicator';
+import '@videojs/html/ui/seek-indicator-value';
 ```
 
 ## API Reference
 
-### 
-
-media-seek-indicator
+### media-seek-indicator
 
 #### Props
 
-Prop
-
-Type
-
-Default
-
-Details
-
-`closeDelay`
-
-`number`
-
-`—`
-
-▸
-
-Attribute
-
-`close-delay`
-
-Description
-
-Delay in milliseconds before the indicator closes.
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `closeDelay` (attribute `close-delay`) | `number` | — | Delay in milliseconds before the indicator closes. |
 
 #### State
 
 State is reflected as data attributes for CSS styling.
 
-Property
-
-Type
-
-Details
-
-`transitionStarting`
-
-`boolean`
-
-▸
-
-Description
-
-Whether the open transition is in progress.
-
-`transitionEnding`
-
-`boolean`
-
-▸
-
-Description
-
-Whether the close transition is in progress.
-
-`open`
-
-`boolean`
-
-▸
-
-Description
-
-Whether the indicator is open.
-
-`generation`
-
-`number`
-
-▸
-
-Description
-
-Increments each time a seek input action updates the indicator.
-
-`direction`
-
-`'forward' | 'backward' | null`
-
-▸
-
-Description
-
-Direction of the seek, or `null` when the target does not change the current time.
-
-`count`
-
-`number`
-
-▸
-
-Description
-
-Number of same-direction seek steps accumulated in the current display.
-
-`seekTotal`
-
-`number`
-
-▸
-
-Description
-
-Absolute number of seconds accumulated from seek-step actions.
-
-`value`
-
-`string | null`
-
-▸
-
-Description
-
-Accumulated seek-step label, or `null` for percentage seeks.
-
-`currentTime`
-
-`string`
-
-▸
-
-Description
-
-Formatted current time captured when the input action occurred.
+| Property | Type | Description |
+| --- | --- | --- |
+| `transitionStarting` | `boolean` | Whether the open transition is in progress. |
+| `transitionEnding` | `boolean` | Whether the close transition is in progress. |
+| `open` | `boolean` | Whether the indicator is open. |
+| `generation` | `number` | Increments each time a seek input action updates the indicator. |
+| `direction` | `'forward' \| 'backward' \| null` | Direction of the seek, or `null` when the target does not change the current time. |
+| `count` | `number` | Number of same-direction seek steps accumulated in the current display. |
+| `seekTotal` | `number` | Absolute number of seconds accumulated from seek-step actions. |
+| `value` | `string \| null` | Accumulated seek-step label, or `null` for percentage seeks. |
+| `currentTime` | `string` | Formatted current time captured when the input action occurred. |
 
 #### Data attributes
 
-Attribute
-
-Type
-
-Details
-
-`data-open`
-
-▸
-
-Description
-
-Present while the indicator is open.
-
-`data-direction`
-
-`'forward' | 'backward' | null`
-
-▸
-
-Description
-
-Direction of the seek as `"forward"` or `"backward"`.
-
-`data-starting-style`
-
-▸
-
-Description
-
-Present during the open transition.
-
-`data-ending-style`
-
-▸
-
-Description
-
-Present during the close transition.
-
-### 
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-open` | — | Present while the indicator is open. |
+| `data-direction` | `'forward' \| 'backward' \| null` | Direction of the seek as `"forward"` or `"backward"`. |
+| `data-starting-style` | — | Present during the open transition. |
+| `data-ending-style` | — | Present during the close transition. |
 
-media-seek-indicator-value
+### media-seek-indicator-value

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

@@ -0,0 +1,161 @@
+# shaka-video
+
+Video element powered by Shaka Player for DASH, HLS, and progressive playback with DRM
+
+> **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.
+
+Choose [Shaka Player](https://github.com/shaka-project/shaka-player) when one media component needs to play DASH, HLS, and progressive files, or when playback requires DRM.
+
+## Import
+
+```bash
+pnpm add @videojs/shaka-video
+```
+
+```ts
+import '@videojs/html/media/shaka-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/shaka-video.js"></script>
+```
+
+## Load a source
+
+`src` takes a manifest URL. DASH, HLS, and progressive files all go through the same property, and Shaka picks the parser from the URL.
+
+```html
+<shaka-video src="https://example.com/manifest.mpd"></shaka-video>
+```
+
+When the URL carries no extension to go on, name the type with `source.type`. That’s what makes an extensionless manifest playable.
+
+```ts
+const video = document.querySelector('shaka-video');
+video.source = { src: 'https://example.com/manifest', type: 'application/dash+xml' };
+```
+
+## Protected content
+
+`source.drm` names your license servers, keyed by [EME key system id](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/requestMediaKeySystemAccess). Name every system you hold a license server for: which one gets negotiated is the browser’s choice.
+
+```ts
+const video = document.querySelector('shaka-video');
+video.source = {
+  src: 'https://example.com/manifest.mpd',
+  drm: {
+    'com.widevine.alpha': { licenseUrl: 'https://example.com/widevine' },
+    'com.apple.fps': {
+      licenseUrl: 'https://example.com/fairplay',
+      serverCertificateUrl: 'https://example.com/fairplay.cer',
+    },
+  },
+};
+```
+
+FairPlay needs a `serverCertificateUrl` unless its CDM is pre-provisioned; Widevine and PlayReady ignore it. `source.drm` takes the same shape as hls.js’s own `drmSystems`, so one object describes DRM for either engine.
+
+For the parts of Shaka’s DRM configuration this doesn’t cover, configure Shaka directly. A `drm.servers` under `source.engine.shaka` replaces `source.drm` rather than merging with it.
+
+## Behavior
+
+- Adaptation stays within renditions no larger than the element rendering them, through Shaka’s `abr.restrictToElementSize`. Override it under `source.engine.shaka`.
+- `preload="none"` defers the load until playback is asked for; `autoplay` or a `play()` counts as asking.
+- `preload="metadata"` loads, then holds Shaka’s buffering goals down to a second until `preload` rises to `auto`.
+- `streamType` is detected from the manifest, so a player skin renders live and on-demand content correctly without being told which it is.
+- Changing `source.engine.shaka` reconfigures the running player in place instead of recreating it.
+
+## Examples
+
+### Basic Usage
+
+**index.html**
+
+```html
+<media-container class="media-container">
+  <shaka-video src="https://dash.akamaized.net/akamai/streamroot/050714/Spring_4Ktest.mpd" autoplay muted playsinline loop></shaka-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/shaka-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 |
+| --- | --- | --- |
+| `stream-type` | `'on-demand' \| 'live' \| 'unknown'` | `'unknown'` |
+
+### Properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `contentData` | `MediaContentData \| undefined` | — | Read-only. |
+| `engine` | `shaka.Player \| null` | — | Read-only. Underlying playback engine — the Shaka `Player` instance, or `null` when the browser cannot run it. An advanced escape hatch for direct engine access; normal playback is driven through this element's own properties and methods. |
+| `error` | `unknown` | — | Read-only. The last playback failure Shaka could not recover from, or `null`. Shaka loads asynchronously, so a manifest that cannot be played fails after `src` was assigned rather than at the assignment; the `error` event is when to read this. A Shaka failure says more about what went wrong than the media element's own `error` does, so it wins while there is one; anything the element failed on by itself still reads through. |
+| `isFullscreen` | `boolean` | — | Read-only. |
+| `isPictureInPicture` | `boolean` | — | Read-only. |
+| `liveEdgeStart` | `number` | — | Read-only. |
+| `preload` | `'' \| 'none' \| 'metadata' \| 'auto'` | `'metadata'` | How much to fetch before playback is asked for, mirroring the media element's own `preload`. Shaka has no split between "know the source" and "buffer it", so this maps onto when and how `engine.load()` runs:<br>- `'auto'` — load immediately with the configured buffering goals.<br>- `'metadata'` — load immediately, holding buffering to about a segment; the configured goals come back on the first play intent.<br>- `'none'` / `''` — hold the load entirely until the first play intent. A play intent is a `play` event, a target that is already playing, or `autoplay` — which the spec lets override `preload` for good reason: with nothing fetched there is nothing whose readiness could ever fire it. Widening (`none` → `auto`) takes effect immediately; narrowing after a load began cannot un-fetch and leaves it alone. |
+| `source` | `{ src?: string; type?: string; drm?: Partial<Record<KeySystem, DrmSystemConfig>>; engine?: ShakaEngineConfig } \| null` | `null` | Structured source: what to play (`src`, an optional `type`) plus how to play it (`drm`, `engine.shaka`). Replacing it re-derives `src`. Shaka takes configuration on a live player, so changing `engine.shaka` re-applies it in place instead of recreating the engine. |
+| `src` | `string` | `''` | |
+| `streamType` | `'on-demand' \| 'live' \| 'unknown'` | `'unknown'` | |
+| `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`, `loop`, `muted`, `paused`, `playbackRate`, `played`, `playsInline`, `poster`, `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`, `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 |
+| --- | --- |
+| `error` | Fired when playback fails in a way Shaka could not recover from. Read `error` for the failure. |
+| `sourcechange` | Fired when `source` changes, either directly or by resolving a new `src`. Read `source` for the new value. |
+| `streamtypechange` | Fired when the detected stream type changes. Read `streamType` for the new value. |
+| `targetlivewindowchange` | Fired when `targetLiveWindow` changes. Read it 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. |