@videojs/html 10.3.0 → 10.4.0

package/docs/reference/components/time-slider-markers.md

@@ -0,0 +1,194 @@
+# media-time-slider-markers
+
+Draws a marker on the time slider for each cue on the text tracks a filter matches, such as ad breaks
+
+A part of the [time slider](./time-slider.md) that draws a marker for each cue on the text tracks a filter matches, such as ad breaks, quiz questions, or highlights. Its props, data attributes, and custom properties are listed with the time slider’s other parts.
+
+## Import
+
+```ts
+import '@videojs/html/ui/time-slider-markers';
+```
+
+## Anatomy
+
+```html
+<media-time-slider>
+  <media-slider-track>
+    <media-slider-fill></media-slider-fill>
+  </media-slider-track>
+  <media-time-slider-markers label="ads"></media-time-slider-markers>
+  <media-slider-thumb></media-slider-thumb>
+</media-time-slider>
+```
+
+Each marker is a `<div>`, or a clone of a `<template>` child. The template must contain exactly one HTML root element, and stays in the light DOM.
+
+```html
+<media-time-slider-markers label="ads">
+  <template>
+    <div class="ad-marker"></div>
+  </template>
+</media-time-slider-markers>
+```
+
+## Behavior
+
+The `kind`, `label`, and `language` attributes pick the tracks whose cues are drawn. The `filter` property takes a filter object, a function, or a [track definition](../api/define-text-track.md) instead, and takes priority over the attributes. With neither, nothing is drawn.
+
+Tracks from the media and from the app are drawn alike. While the markers are rendered, the [text cues feature](../api/feature-text-cues.md) reads the tracks they match, so tracks it skips by default work too.
+
+A cue whose end is its start is a point, drawn as a marker with no width and `data-point`. Any other cue is a range, spanning from its start to its end and clamped to the slider. Markers sit on the same span as the slider: from `0` to the media’s duration, or to the end of its seekable range while the duration is unknown. Cues outside that span, and every cue while it’s unknown, aren’t drawn. Markers are ordered by start, then end.
+
+## Styling
+
+| Attribute | Description |
+| --- | --- |
+| `data-active` | Present while the marker’s cue is active. |
+| `data-point` | Present when the cue marks one moment rather than a span. |
+
+Each marker also carries the slider’s data attributes, such as `data-orientation`, and its geometry through:
+
+- `--media-slider-marker-start`
+- `--media-slider-marker-end`
+- `--media-slider-marker-width`, the marker’s size along the slider, `0%` for a point
+
+Markers are unstyled. Position each one from its custom properties, and give points a visible width:
+
+```css
+media-time-slider-markers > div {
+  position: absolute;
+  inset-block: 0;
+  left: var(--media-slider-marker-start);
+  width: var(--media-slider-marker-width);
+  min-width: 4px;
+}
+
+media-time-slider-markers > [data-active] {
+  background: orange;
+}
+```
+
+## Accessibility
+
+The markers render with `aria-hidden="true"`; the slider’s value is what assistive technology reads. When a marker carries meaning a viewer needs, such as an upcoming ad break, convey it another way too.
+
+## Examples
+
+### Basic usage
+
+An app track labeled `ads` holds a point at 8 seconds and a range from 18 to 24 seconds. A marker turns orange while its cue is active.
+
+**index.html**
+
+```html
+<video-player class="html-time-slider-markers-basic">
+  <media-container class="html-time-slider-markers-basic__container">
+    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
+    <media-time-slider class="html-time-slider-markers-basic__slider">
+      <media-slider-track class="html-time-slider-markers-basic__track">
+        <media-slider-fill class="html-time-slider-markers-basic__fill"></media-slider-fill>
+      </media-slider-track>
+      <media-time-slider-markers label="ads" class="html-time-slider-markers-basic__markers">
+        <template>
+          <div class="html-time-slider-markers-basic__marker"></div>
+        </template>
+      </media-time-slider-markers>
+      <media-slider-thumb class="html-time-slider-markers-basic__thumb"></media-slider-thumb>
+    </media-time-slider>
+  </media-container>
+</video-player>
+```
+
+**index.css**
+
+```css
+.html-time-slider-markers-basic__container {
+  position: relative;
+}
+
+.html-time-slider-markers-basic__container video {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+
+.html-time-slider-markers-basic__slider {
+  position: absolute;
+  right: 12px;
+  bottom: 12px;
+  left: 12px;
+  display: flex;
+  align-items: center;
+  height: 20px;
+  cursor: pointer;
+}
+
+.html-time-slider-markers-basic__track,
+.html-time-slider-markers-basic__markers {
+  position: absolute;
+  right: 0;
+  left: 0;
+  height: 4px;
+}
+
+.html-time-slider-markers-basic__track {
+  overflow: hidden;
+  background: rgba(255, 255, 255, 0.3);
+  border-radius: 9999px;
+}
+
+.html-time-slider-markers-basic__fill {
+  position: absolute;
+  inset-block: 0;
+  left: 0;
+  width: var(--media-slider-fill);
+  background: white;
+}
+
+.html-time-slider-markers-basic__marker {
+  position: absolute;
+  inset-block: 0;
+  left: var(--media-slider-marker-start);
+  width: var(--media-slider-marker-width);
+  min-width: 4px;
+  background: #facc15;
+}
+
+.html-time-slider-markers-basic__marker[data-point] {
+  transform: translateX(-50%);
+}
+
+.html-time-slider-markers-basic__marker[data-active] {
+  background: #f97316;
+}
+
+.html-time-slider-markers-basic__thumb {
+  position: absolute;
+  left: var(--media-slider-fill);
+  width: 12px;
+  height: 12px;
+  background: white;
+  border-radius: 50%;
+  transform: translateX(-50%);
+}
+```
+
+**index.ts**
+
+```ts
+import '@videojs/html/video/player';
+import '@videojs/html/ui/container';
+import '@videojs/html/ui/time-slider';
+import '@videojs/html/ui/slider-track';
+import '@videojs/html/ui/slider-fill';
+import '@videojs/html/ui/slider-thumb';
+import '@videojs/html/ui/time-slider-markers';
+
+const player = document.querySelector('video-player');
+
+player?.store.addTextTrack({
+  kind: 'metadata',
+  label: 'ads',
+  cues: [{ startTime: 8 }, { startTime: 18, endTime: 24 }],
+});
+```

package/docs/reference/components/time-slider.md

@@ -50,6 +50,8 @@ Add `<media-time-slider-chapters>` to divide the slider track into sections. Eac
 
 The required template must contain exactly one HTML root element. It remains in the light DOM and is cloned for each normalized chapter range. When no chapter cues are available, it is cloned once as a full-width, cue-less range.
 
+To draw a marker for each cue on a text track, such as an ad break, add the markers element, documented on its own page as [media-time-slider-markers](./time-slider-markers.md).
+
 ## Behavior
 
 Displays and controls the current playback position. Dragging the slider seeks the media. The fill level reflects `currentTime / duration` as a percentage, and the buffer level shows how much media has been buffered.
@@ -483,6 +485,18 @@ Clones a light-DOM template once per normalized chapter range.
 
 The required template must contain exactly one HTML root element. When no chapter cues are available, the template is cloned once for a full-duration range.
 
+### media-time-slider-markers
+
+Draws a marker on the time slider for each cue on the text tracks a filter matches, such as ad breaks. Pick tracks with the `kind`, `label`, and `language` attributes, or with the `filter` property; with neither, nothing is drawn. The store reads the matching tracks while the element is connected, so tracks it doesn't read by default work too.
+
+Each marker clones the light-DOM template, which must contain exactly one HTML root element, or is a `<div>` without one. Markers are decorative: the slider's own value is what assistive technology reads.
+
+#### Data attributes
+
+| Attribute | Description |
+| --- | --- |
+| `data-seeking` | Present when a seek operation is in progress. |
+
 ### media-slider-buffer
 
 Displays the buffered range on the slider track.

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

@@ -17,7 +17,7 @@ import '@videojs/html/media/twitch-video';
 Or load it from the [CDN](../../guides/cdn.md):
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/media/twitch-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/media/twitch-video.js"></script>
 ```
 
 ## Load a source

package/docs/reference/components/video-compat-skin.md

@@ -13,7 +13,7 @@ import '@videojs/html/video/compat-skin';
 The import registers the skin and every UI element it composes. The [CDN](../../guides/cdn.md) player bundle registers this skin together with its player:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/video-compat.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/video-compat.js"></script>
 ```
 
 ## Anatomy
@@ -40,6 +40,10 @@ The skin renders a storyboard preview image while scrubbing the time slider. An
 
 See [Show timeline thumbnail previews](../../guides/thumbnails.md) for complete examples.
 
+## Controls before playback
+
+Before playback starts, the skin shows only the large center play button. The other controls appear once playback starts or the media begins to autoplay. Set `--media-controls-before-start: visible` to show them from the start. See [Customize skins](../../guides/customize-skins.md#set-the-skins-styles).
+
 ## 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](../../guides/customize-skins.md#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

package/docs/reference/components/video-neutral-skin.md

@@ -13,7 +13,7 @@ import '@videojs/html/video/neutral-skin';
 The import registers the skin and every UI element it composes. The [CDN](../../guides/cdn.md) player bundle registers this skin together with its player:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/video-neutral.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/video-neutral.js"></script>
 ```
 
 ## Anatomy
@@ -40,6 +40,10 @@ The skin renders a storyboard preview image while scrubbing the time slider. An
 
 See [Show timeline thumbnail previews](../../guides/thumbnails.md) for complete examples.
 
+## Controls before playback
+
+Before playback starts, the skin shows only the large center play button. The other controls appear once playback starts or the media begins to autoplay. Set `--media-controls-before-start: visible` to show them from the start. See [Customize skins](../../guides/customize-skins.md#set-the-skins-styles).
+
 ## 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](../../guides/customize-skins.md#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

package/docs/reference/components/video-scaffold-skin.md

@@ -13,7 +13,7 @@ import '@videojs/html/video/scaffold-skin';
 The import registers the skin and every UI element it composes. The [CDN](../../guides/cdn.md) player bundle registers this skin together with its player:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/video-scaffold.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/video-scaffold.js"></script>
 ```
 
 ## Usage
@@ -40,6 +40,10 @@ The skin renders a storyboard preview image while scrubbing the time slider. An
 
 See [Show timeline thumbnail previews](../../guides/thumbnails.md) for complete examples.
 
+## Controls before playback
+
+Before playback starts, the skin shows only the large center play button. The other controls appear once playback starts or the media begins to autoplay. Set `--media-controls-before-start: visible` to show them from the start. See [Customize skins](../../guides/customize-skins.md#set-the-skins-styles).
+
 ## 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](../../guides/customize-skins.md#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

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

@@ -13,7 +13,7 @@ import '@videojs/html/video/skin';
 The import registers the skin and every UI element it composes. The [CDN](../../guides/cdn.md) player bundle registers this skin together with its player:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/video.js"></script>
 ```
 
 ## Anatomy
@@ -40,6 +40,10 @@ The skin renders a storyboard preview image while scrubbing the time slider. An
 
 See [Show timeline thumbnail previews](../../guides/thumbnails.md) for complete examples.
 
+## Controls before playback
+
+Before playback starts, the skin shows only the large center play button. The other controls appear once playback starts or the media begins to autoplay. Set `--media-controls-before-start: visible` to show them from the start. See [Customize skins](../../guides/customize-skins.md#set-the-skins-styles).
+
 ## 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](../../guides/customize-skins.md#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

package/docs/reference/components/video.md

@@ -74,4 +74,22 @@ This native video uses a child source, captions track, and browser controls whil
 ```ts
 import '@videojs/html/video/player';
 import '@videojs/html/ui/container';
-```
+```
+
+## API Reference
+
+### Attributes
+
+Accepts the standard `<video>` attributes. See the [MDN `<video>` reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/video): `autoplay`, `controls`, `controlslist`, `crossorigin`, `disablepictureinpicture`, `disableremoteplayback`, `height`, `loop`, `muted`, `playsinline`, `poster`, `preload`, `src`, `width`.
+
+### Properties
+
+Exposes the native media properties. 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`, `height`, `loop`, `mediaKeys`, `muted`, `networkState`, `paused`, `playbackRate`, `played`, `playsInline`, `poster`, `preload`, `preservesPitch`, `readyState`, `remote`, `seekable`, `seeking`, `sinkId`, `src`, `srcObject`, `textTracks`, `videoHeight`, `videoWidth`, `volume`, `width`.
+
+### Methods
+
+Supports the native media methods. See [`HTMLVideoElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) for details: `addTextTrack`, `cancelVideoFrameCallback`, `canPlayType`, `fastSeek`, `getVideoPlaybackQuality`, `load`, `pause`, `play`, `requestPictureInPicture`, `requestVideoFrameCallback`, `setMediaKeys`, `setSinkId`.
+
+### Events
+
+Fires the standard media events: `abort`, `canplay`, `canplaythrough`, `durationchange`, `emptied`, `encrypted`, `ended`, `enterpictureinpicture`, `error`, `leavepictureinpicture`, `loadeddata`, `loadedmetadata`, `loadstart`, `pause`, `play`, `playing`, `progress`, `ratechange`, `resize`, `seeked`, `seeking`, `stalled`, `suspend`, `timeupdate`, `volumechange`, `waiting`, `waitingforkey`.

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

@@ -17,7 +17,7 @@ import '@videojs/html/media/vimeo-video';
 Or load it from the [CDN](../../guides/cdn.md):
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/media/vimeo-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/media/vimeo-video.js"></script>
 ```
 
 ## Load a source
@@ -119,7 +119,6 @@ These attributes configure the embedded media adapter:
 | `muted` | `boolean` | `false` | |
 | `paused` | `boolean` | — | Read-only. |
 | `playbackRate` | `number` | — | |
-| `playbackRateRange` | `{ min: number; max: number }` | — | Read-only. Vimeo plays any rate up to 2, rejects faster ones, and never settles a request slower than the browser allows. |
 | `played` | `{ length: number; start(index: number): number; end(index: number): number }` | — | Read-only. |
 | `playsInline` | `boolean` | `true` | |
 | `poster` | `string` | `''` | |

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

@@ -21,7 +21,7 @@ import '@videojs/html/media/wistia-video';
 Or load it from the [CDN](../../guides/cdn.md):
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/media/wistia-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/media/wistia-video.js"></script>
 ```
 
 ## Load a source

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

@@ -17,7 +17,7 @@ import '@videojs/html/media/youtube-video';
 Or load it from the [CDN](../../guides/cdn.md):
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/media/youtube-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/media/youtube-video.js"></script>
 ```
 
 ## Load a source
@@ -98,7 +98,6 @@ These attributes configure the embedded media adapter:
 | `muted` | `boolean` | `false` | |
 | `paused` | `boolean` | — | Read-only. |
 | `playbackRate` | `number` | — | |
-| `playbackRateRange` | `{ min: number; max: number }` | — | Read-only. YouTube plays any rate from 0.25 to 2, rounded down to a step of 0.05, though `getAvailablePlaybackRates` lists only quarter steps. |
 | `played` | `{ length: number; start(index: number): number; end(index: number): number }` | — | Read-only. |
 | `playsInline` | `boolean` | `true` | |
 | `poster` | `string` | `''` | |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@videojs/html",
-  "version": "10.3.0",
+  "version": "10.4.0",
   "description": "Video.js 10 for HTML, Vue, and Svelte: player custom elements and skins for video and audio",
   "keywords": [
     "audio",
@@ -164,59 +164,59 @@
     "access": "public"
   },
   "dependencies": {
-    "@videojs/core": "10.3.0",
-    "@videojs/element": "10.3.0",
-    "@videojs/media": "10.3.0",
-    "@videojs/native-hls-video": "10.3.0",
-    "@videojs/spf": "10.3.0",
-    "@videojs/store": "10.3.0",
-    "@videojs/utils": "10.3.0"
+    "@videojs/core": "10.4.0",
+    "@videojs/element": "10.4.0",
+    "@videojs/media": "10.4.0",
+    "@videojs/native-hls-video": "10.4.0",
+    "@videojs/spf": "10.4.0",
+    "@videojs/store": "10.4.0",
+    "@videojs/utils": "10.4.0"
   },
   "devDependencies": {
-    "@videojs/cloudflare-video": "10.3.0",
-    "@videojs/dailymotion-video": "10.3.0",
-    "@videojs/dash-video": "10.3.0",
-    "@videojs/google-analytics": "10.3.0",
-    "@videojs/google-cast": "10.3.0",
-    "@videojs/hlsjs-video": "10.3.0",
-    "@videojs/icons": "10.3.0",
-    "@videojs/mixcloud-audio": "10.3.0",
-    "@videojs/mux-audio": "10.3.0",
-    "@videojs/mux-data": "10.3.0",
-    "@videojs/mux-video": "10.3.0",
-    "@videojs/playerjs-video": "10.3.0",
-    "@videojs/shaka-video": "10.3.0",
-    "@videojs/skins": "10.3.0",
-    "@videojs/soundcloud-audio": "10.3.0",
-    "@videojs/spotify-audio": "10.3.0",
-    "@videojs/tiktok-video": "10.3.0",
-    "@videojs/twitch-video": "10.3.0",
-    "@videojs/vimeo-video": "10.3.0",
-    "@videojs/wistia-video": "10.3.0",
-    "@videojs/youtube-video": "10.3.0",
+    "@videojs/cloudflare-video": "10.4.0",
+    "@videojs/dailymotion-video": "10.4.0",
+    "@videojs/dash-video": "10.4.0",
+    "@videojs/google-analytics": "10.4.0",
+    "@videojs/google-cast": "10.4.0",
+    "@videojs/hlsjs-video": "10.4.0",
+    "@videojs/icons": "10.4.0",
+    "@videojs/mixcloud-audio": "10.4.0",
+    "@videojs/mux-audio": "10.4.0",
+    "@videojs/mux-data": "10.4.0",
+    "@videojs/mux-video": "10.4.0",
+    "@videojs/playerjs-video": "10.4.0",
+    "@videojs/shaka-video": "10.4.0",
+    "@videojs/skins": "10.4.0",
+    "@videojs/soundcloud-audio": "10.4.0",
+    "@videojs/spotify-audio": "10.4.0",
+    "@videojs/tiktok-video": "10.4.0",
+    "@videojs/twitch-video": "10.4.0",
+    "@videojs/vimeo-video": "10.4.0",
+    "@videojs/wistia-video": "10.4.0",
+    "@videojs/youtube-video": "10.4.0",
     "happy-dom": "^20.11.1",
     "vite-plus": "1.1.0"
   },
   "peerDependencies": {
-    "@videojs/cloudflare-video": "10.3.0",
-    "@videojs/dailymotion-video": "10.3.0",
-    "@videojs/dash-video": "10.3.0",
-    "@videojs/google-analytics": "10.3.0",
-    "@videojs/google-cast": "10.3.0",
-    "@videojs/hlsjs-video": "10.3.0",
-    "@videojs/mixcloud-audio": "10.3.0",
-    "@videojs/mux-audio": "10.3.0",
-    "@videojs/mux-data": "10.3.0",
-    "@videojs/mux-video": "10.3.0",
-    "@videojs/playerjs-video": "10.3.0",
-    "@videojs/shaka-video": "10.3.0",
-    "@videojs/soundcloud-audio": "10.3.0",
-    "@videojs/spotify-audio": "10.3.0",
-    "@videojs/tiktok-video": "10.3.0",
-    "@videojs/twitch-video": "10.3.0",
-    "@videojs/vimeo-video": "10.3.0",
-    "@videojs/wistia-video": "10.3.0",
-    "@videojs/youtube-video": "10.3.0"
+    "@videojs/cloudflare-video": "10.4.0",
+    "@videojs/dailymotion-video": "10.4.0",
+    "@videojs/dash-video": "10.4.0",
+    "@videojs/google-analytics": "10.4.0",
+    "@videojs/google-cast": "10.4.0",
+    "@videojs/hlsjs-video": "10.4.0",
+    "@videojs/mixcloud-audio": "10.4.0",
+    "@videojs/mux-audio": "10.4.0",
+    "@videojs/mux-data": "10.4.0",
+    "@videojs/mux-video": "10.4.0",
+    "@videojs/playerjs-video": "10.4.0",
+    "@videojs/shaka-video": "10.4.0",
+    "@videojs/soundcloud-audio": "10.4.0",
+    "@videojs/spotify-audio": "10.4.0",
+    "@videojs/tiktok-video": "10.4.0",
+    "@videojs/twitch-video": "10.4.0",
+    "@videojs/vimeo-video": "10.4.0",
+    "@videojs/wistia-video": "10.4.0",
+    "@videojs/youtube-video": "10.4.0"
   },
   "peerDependenciesMeta": {
     "@videojs/cloudflare-video": {