@videojs/html 10.2.0 → 10.4.0

package/docs/reference/api/feature-playback-rate.md

@@ -2,7 +2,7 @@
 
 Playback speed state and actions for the player store
 
-Controls speed of playback.
+Controls speed of playback. `playbackRateAvailability` is `unsupported` when the media has no playback rate, such as an embed whose provider takes no speed command.
 
 ## Import
 
@@ -14,23 +14,74 @@ The `audioFeatures` and `videoFeatures` [feature bundles](../../guides/presets.m
 
 ## API Reference
 
+### Configuration
+
+Attributes and matching properties the player element accepts. They exist only while this feature is selected.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `defaultPlaybackRates` (attribute `default-playback-rates`) | `undefined \| null \| readonly number[] \| string` | `[0.5, 0.75, 1, 1.25, 1.5, 1.75, 2]` | Rates the player's controls offer, in the order they cycle through them, unless a control sets its own `rates`. HTML takes a space-separated list, such as `default-playback-rates="0.5 1 1.5 2"`. Missing or empty input restores the defaults. Rates outside the media's range are left out, so YouTube, which plays up to `2`, may offer fewer. |
+
 ### State
 
 | Property | Type | Description |
 | --- | --- | --- |
-| `playbackRates` | `readonly number[]` | Available playback rates. |
 | `playbackRate` | `number` | Current playback rate. |
+| `playbackRateAvailability` | `'available' \| 'unavailable' \| 'unsupported'` | Whether the media can change its playback rate. `unsupported` when the attached media has no `playbackRate` at all, such as an embed whose provider takes no speed command. |
+| `playbackRates` | `readonly number[]` | The default rates that fit the media's range. Set them through the player, not through the store. They are listed even when the media cannot change its rate, so check `playbackRateAvailability` before offering them. |
 
 ### Actions
 
 | Action | Type | Description |
 | --- | --- | --- |
-| `setPlaybackRate` | `(rate: number) => void` | Set the playback rate. |
+| `setPlaybackRate` | `(rate: number) => void` | Set the playback rate, clamped to the rates the media accepts. |
+
+### Playback rates
+
+The player offers `0.5` through `2` in steps of `0.25` unless you set your own list. The [playback rate button](../components/playback-rate-button.md), the [playback rate radio group](../components/playback-rate-radio-group.md), and the `speedUp` and `speedDown` [hotkeys](../../guides/keyboard-shortcuts.md) use this list unless you give one of them its own.
+
+Set the `default-playback-rates` attribute on [`<video-player>`](../components/player.md) to a space-separated list:
+
+```html
+<video-player default-playback-rates="0.5 1 1.25 1.5 2">
+  <media-container>
+    <video src="/video.mp4"></video>
+  </media-container>
+</video-player>
+```
+
+The `defaultPlaybackRates` property also takes an array, such as `player.defaultPlaybackRates = [1, 2]`. Removing the attribute restores the defaults.
+
+The button cycles through the rates in the order you list them, and the menu shows them in that order. `speedUp` and `speedDown` move to the next faster or slower rate whatever the order, and do nothing at the fastest or slowest rate. The player ignores values that aren’t positive numbers, and repeated rates. If nothing usable is left, it falls back to the defaults.
+
+### Rates for one control
+
+To give one control a different list, set `rates` on it. The rest of the player keeps the default list. The control offers these rates as given, even ones outside the media’s range, which play at the nearest end of the range.
+
+```html
+<media-playback-rate-button rates="1 1.5 2"></media-playback-rate-button>
+```
+
+To make the speed hotkeys change speed in fixed steps instead, give `speedUp` and `speedDown` a `value`. A `value` of `0.1` moves from `1` to `1.1`, then `1.2`, and so on.
+
+### Rates outside the list
+
+The media owns the current rate, so it can be one the menu doesn’t offer, such as `1.1` set through the media API or a stepped hotkey. The menu then shows that rate as an extra item, slotted before the next faster rate. Skins set it in italics, and its accessible name is “Custom, 1.1×”. The item goes away once the rate is back on the list. Normal speed (`1`) is added the same way when your list leaves it out, but isn’t marked custom.
+
+### Media range
+
+Each media accepts rates within a range. Browsers play `0.0625` through `16`, YouTube `0.25` through `2`, and Vimeo up to `2`. The player leaves out any `defaultPlaybackRates` outside that range and keeps the rest in your order. If none are left, it offers the defaults within the range and warns in development. `setPlaybackRate` clamps a rate outside the range to the nearest end, and warns in development. That includes `0`, which would stop the picture while the player still reports playback; call `pause()` instead.
+
+`playbackRates` lists rates even for a media that can’t change its rate, so check `playbackRateAvailability` before offering them.
+
+YouTube rounds rates down to a step of `0.05`, so asking for `1.13` plays at `1.1`.
 
 ### Selector
 
 Pass `selectPlaybackRate` to [`PlayerController`](./player-controller.md) to subscribe to playback rate state. Returns `undefined` if the playback rate feature is not configured.
 
+Check `playbackRateAvailability` before showing a playback rate control.
+
 **rate-display.ts**
 
 ```ts

package/docs/reference/api/feature-playback.md

@@ -4,6 +4,8 @@ Play/pause state and actions for the player store
 
 Controls play/pause state and tracks whether playback has started or is stalled.
 
+When the media has `autoplay`, `autoplaying` is true from the moment a source loads until playback starts. It also turns false when the autoplay is refused: browsers don’t announce that, so it shows as the media being able to play through but staying paused, and embeds report it with a `pause` or `error` event. Treat it as playback about to begin: the play button shows pause and the buffering indicator shows while it’s true, and `pause()` cancels it.
+
 ## Import
 
 ```ts
@@ -22,13 +24,15 @@ The `audioFeatures`, `liveAudioFeatures`, `liveVideoFeatures`, and `videoFeature
 | `ended` | `boolean` | Whether playback has reached the end. |
 | `started` | `boolean` | Whether playback has started (played or seeked). |
 | `waiting` | `boolean` | Whether playback is stalled waiting for data. |
+| `autoplay` | `boolean` | Whether the media starts playing on its own once it can. |
+| `autoplaying` | `boolean` | Whether the media is trying to autoplay: `autoplay` is set, and playback hasn't started yet. Clears when playback starts, when `pause()` cancels it, and when the autoplay is refused. Browsers don't announce a refusal, so it shows as the media being able to play through but staying paused; embeds report one with a `pause` or `error` event. Controls treat it as playback that's about to begin. |
 
 ### Actions
 
 | Action | Type | Description |
 | --- | --- | --- |
 | `play` | `() => Promise<void>` | Start playback. Updates `paused` immediately when the media starts. |
-| `pause` | `() => void` | Pause playback. Updates `paused` immediately. |
+| `pause` | `() => void` | Pause playback. Updates `paused` immediately, and cancels a pending autoplay. |
 
 ### Selector
 

package/docs/reference/api/feature-text-cues.md

@@ -0,0 +1,133 @@
+# Text cues
+
+Cues and active cues from metadata, chapters, and app text tracks
+
+Reads the cues of text tracks, from the media and from the app, and tracks which cues are active at the current time. The [timed metadata guide](../../guides/timed-metadata.md) shows how to use it.
+
+`textCues` has one entry per track being read, in `textTrackList` order. Each entry holds the `track` as `textTrackList` lists it, every one of its `cues` ordered by start time, and its `activeCues`. Cues are plain data with an `id`, `startTime`, `endTime`, `text`, and, when the cue carries data, a `value` and a `type`.
+
+By default the feature reads every `metadata` and `chapters` track that isn’t `disabled`, except the `thumbnails` track. `watchTextCues(filter)` adds the tracks a filter matches until the function it returns is called.
+
+Tracks from the media and tracks from the app are read the same way. The [text track feature](./feature-text-tracks.md) lists both in `textTrackList`, and each track’s `source` is `'media'` or `'app'`. Cue changes are kept out of the text track feature, so UI that only lists tracks doesn’t update as cues come and go.
+
+## Import
+
+```ts
+import { textCuesFeature } from '@videojs/html';
+```
+
+The `audioFeatures`, `liveAudioFeatures`, `liveVideoFeatures`, and `videoFeatures` [feature bundles](../../guides/presets.md) include this feature.
+
+## API Reference
+
+### State
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `textCues` | `MediaTrackCues[]` | Cues for the tracks being read: `metadata` and `chapters` tracks that aren't disabled, except the thumbnails track, plus any track a `watchTextCues()` filter matches. In `textTrackList` order. |
+
+### Actions
+
+| Action | Type | Description |
+| --- | --- | --- |
+| `watchTextCues` | `(filter: { kind?: TextTrackKind \| readonly TextTrackKind[]; label?: string; language?: string } \| ((track: MediaTextTrack) => boolean)) => (() => void)` | Read cues for more tracks, such as captions for an interactive transcript. Cues are tracked until the returned function is called. |
+
+### Selector
+
+Pass `selectTextCues` to [`PlayerController`](./player-controller.md) to subscribe to text cue state. Returns `undefined` if the text cues feature is not configured. Outside a custom element, read `player.store.textCues` in a `player.store.subscribe()` callback, or pick cues with [`getActiveTextCues`](./get-active-text-cues.md).
+
+**cue-count.ts**
+
+```ts
+import { createPlayer, UIElement, selectTextCues } from '@videojs/html';
+import { videoFeatures } from '@videojs/html/video';
+
+const { PlayerController } = createPlayer({ features: videoFeatures });
+
+class CueCount extends UIElement {
+  readonly #textCues = new PlayerController(this, selectTextCues);
+}
+```
+
+## Active cues
+
+A cue is active from its `startTime` up to its `endTime`. A cue whose `endTime` equals its `startTime` is a point, and stays active for one second from where it sits, so a seek that lands far past a point never activates it. The rule is the same for tracks from the media and from the app. The one exception is a chapters track the app added: a chapter without an `endTime` runs to the next chapter, and the last one to the end of the media.
+
+Active cues follow the media’s `currentTime` through `timeupdate` and `seeked` events, and a media track’s `cuechange` events. They aren’t frame-accurate. Updates come a few times a second, so fast playback can move past a point, or a short cue, between two of them. A cue that started since the last update counts as active for that update even when it’s already over, so playback never skips one. A seek doesn’t: the cues it jumps over stay inactive.
+
+Cues delivered with a stream can be open-ended. Cue ends are clamped to the media duration once it’s finite.
+
+## Cue values
+
+A cue’s `value` comes from the first of these that applies:
+
+1. The cue’s own `value`. A `DataCue`, such as the ones Safari’s native HLS creates for in-band metadata, carries one, and so do the cues hls.js creates for ID3 and `EXT-X-DATERANGE` metadata. Its `type` says what `value` holds, such as `org.id3`. A type names the shape of `value`, not where it came from, so ID3 carried in an `emsg` box is `org.id3` too.
+2. On a `metadata` track, cue text that parses as a JSON object or array.
+3. Otherwise, the cue has no `value`. Its text is always in `text`.
+
+App cues keep the `value` and `type` they were added with.
+
+A media publishes cues on its text tracks in the platform’s shapes. A `VTTCueLike` carries `text`, like the platform’s `VTTCue`. A `DataCueLike` carries a `value` and, when known, its `type`, like the platform’s `DataCue`. A `TextCueLike` is either one, and a single cue can be both, as the cues hls.js creates are. A custom media writes its cues in these shapes.
+
+## App tracks
+
+`addTextTrack()` and `removeTextTrack()` come from the [text track feature](./feature-text-tracks.md), and are described here. `addTextTrack()` adds a track to the player rather than to the media, so it works with any media, including embeds without text tracks of their own. It takes a [track definition](./define-text-track.md) and its content, or one object describing both, and returns a handle to the track.
+
+```ts
+const player = document.querySelector('video-player')!;
+const quiz = player.store.addTextTrack({ kind: 'metadata', label: 'quiz' });
+
+quiz.addCue({ startTime: 42, value: { question: 'Ready?' } });
+quiz.remove();
+```
+
+The track description takes these fields:
+
+| Field | Description |
+| --- | --- |
+| `kind` | The track kind: `metadata`, `chapters`, `captions`, `subtitles`, or `descriptions`. |
+| `label` | The track label. Defaults to `''`. |
+| `language` | The track language, as a BCP 47 tag. Defaults to `''`. |
+| `cues` | The track’s cues. |
+| `src` | A file to load cues from. The file is fetched once the player attaches to media, so only on the client. Without a `format`, it’s WebVTT, or JSON that is an array of cues or an object with a `cues` array. |
+| `format` | A function that reads the `src` file’s text into cues, such as [`podcastChapters`](./chapters-track.md). It returns an array of cues or an object with a `cues` array, and can return a promise, so a parser for another format, such as SRT, loads only when a file needs it. |
+
+Each cue takes these fields:
+
+| Field | Description |
+| --- | --- |
+| `id` | The cue’s id. When it’s missing or empty, it defaults to an id unique within the track. |
+| `startTime` | Where the cue starts, in seconds. |
+| `endTime` | Where the cue ends, in seconds. Omit it for a point, or, in a chapters track, for a chapter that runs to the next one. |
+| `text` | The cue’s text. Defaults to `''`. |
+| `value` | Structured, JSON-serializable data. |
+| `type` | What `value` holds. |
+
+The handle `addTextTrack()` returns has the track’s `id` in `textTrackList`, and `removed`, which turns `true` once the track is gone. `addCue(cue)` and `removeCue(id)` change its cues, and `remove()` removes it. `removeTextTrack(id)` removes a track the app added; tracks from the media stay.
+
+Like a `<track>` element, an app track stays until it’s removed, through source changes and media swaps. Removing a track stops loading its `src`. A file given as `src` that fails to load leaves the track with the cues it already has.
+
+App tracks start `hidden`. Browsers never draw `metadata` or `chapters` cues. An app `captions` or `subtitles` track is copied into the media, so the browser draws its cues when the track is selected, including in iOS fullscreen where the player’s UI isn’t shown, and the captions menu lists it. The track takes its copy’s mode, so it’s `disabled` until it’s selected and `showing` while it is.
+
+When the media has no chapters track, the text track feature’s `chaptersCues` reads the first chapters track the app added, so the [time slider](../components/time-slider.md) can show its chapters. In the same way, when the media has no thumbnails track, `thumbnailsTrack` reads the first `metadata` track the app added with the label `thumbnails`, such as a storyboard file. Image URLs in its cues resolve against its `src`, as they do for a `<track>` element.
+
+## Exports
+
+| Export | Description |
+| --- | --- |
+| `MediaTrackCues` | One `textCues` entry: a `track`, its `cues`, and its `activeCues`. |
+| `MediaTextCue` | A cue as plain data. Its type parameter types `value`. |
+| `TextCueLike` | A cue on a media’s text track: a `VTTCueLike`, a `DataCueLike`, or both. |
+| `VTTCueLike` | A media cue that carries `text`, like the platform’s `VTTCue`. |
+| `DataCueLike` | A media cue that carries a `value` and its `type`, like the platform’s `DataCue`. |
+| `TextTrackFilter` | Picks tracks by `kind`, `label`, or `language`, or with a function. Each given field must match, and a list of kinds matches any kind in it. |
+| `TextTrackSource` | Where a track came from: `'media'` or `'app'`. |
+| `AddTextTrack` | The type of `addTextTrack()`. |
+| `TextTrackInit` | A track description with its content. |
+| `TextTrackContent` | What a track carries: `cues`, `src`, and `format`. |
+| `TextCueInit` | A cue an app adds. |
+| `TextCueFormat` | A function that reads a file’s text into cues. |
+| `TextCueFormatResult` | What a `TextCueFormat` returns: an array of cues, or an object with a `cues` array. |
+| `TextTrackHandle` | The handle `addTextTrack()` returns. |
+| `InferCueValue` | The `value` type of a cue type. |
+| `MediaTextCuesState` | The state this feature adds to the store. |

package/docs/reference/api/feature-text-tracks.md

@@ -4,9 +4,13 @@ Subtitles, captions, and chapter track state for the player store
 
 Manages subtitles, captions, chapters, and thumbnail tracks.
 
-A default `kind="chapters"` track can also divide the [time slider](../components/time-slider.md) into chapter ranges and label the chapter at the current interaction position.
+`textTrackList` lists the media’s tracks, then the tracks an app adds to the player with this feature’s `addTextTrack()`, described with the [text cues feature](./feature-text-cues.md). Each track’s `source` is `'media'` or `'app'`. An app `captions` or `subtitles` track is copied into the media so the browser can draw it, and it’s selected and listed like the media’s own; its copy isn’t listed separately. Media without text tracks of their own, such as embeds, list only app tracks.
 
-`thumbnailsTrack` is the first `kind="metadata"` track labeled `thumbnails`, or `null` when there is none. Its `crossOrigin` reports the media component’s CORS mode, or `null` when the media is not CORS-enabled. [Thumbnail](../components/thumbnail.md) reads it to fetch sprite sheets the same way the browser fetched the track.
+A default `kind="chapters"` track can also divide the [time slider](../components/time-slider.md) into chapter ranges and label the chapter at the current interaction position. When the media has no chapters track, `chaptersCues` reads the first chapters track the app added instead.
+
+This feature doesn’t track cues as they become active. The text cues feature does, for metadata and chapters tracks and for any track a reader asks for.
+
+`thumbnailsTrack` is the first `kind="metadata"` track labeled `thumbnails`, or `null` when there is none. When the media has none, it’s the first such track the app added, with its `src` as the base for image URLs. Its `crossOrigin` reports the media component’s CORS mode, or `null` when the media is not CORS-enabled. [Thumbnail](../components/thumbnail.md) reads it to fetch sprite sheets the same way the browser fetched the track.
 
 ## Import
 
@@ -14,7 +18,7 @@ A default `kind="chapters"` track can also divide the [time slider](../component
 import { textTrackFeature } from '@videojs/html';
 ```
 
-The `liveVideoFeatures` and `videoFeatures` [feature bundles](../../guides/presets.md) include this feature.
+The `audioFeatures`, `liveAudioFeatures`, `liveVideoFeatures`, and `videoFeatures` [feature bundles](../../guides/presets.md) include this feature.
 
 ## API Reference
 
@@ -22,10 +26,11 @@ The `liveVideoFeatures` and `videoFeatures` [feature bundles](../../guides/prese
 
 | Property | Type | Description |
 | --- | --- | --- |
-| `textTrackList` | `MediaTextTrack[]` | All text tracks available on the media component. |
+| `textTrackList` | `MediaTextTrack[]` | Every text track: the media's, then those the app added through the player. `source` tells them apart. |
 | `subtitlesShowing` | `boolean` | Whether a captions/subtitles track is showing. |
-| `chaptersCues` | `MediaTextCue[]` | Cues from the first `kind="chapters"` track, with cue ends clamped to a finite media duration. |
+| `chaptersCues` | `MediaTextCue[]` | Cues from the media's first `kind="chapters"` track, with cue ends clamped to a finite media duration. When the media has none, cues from the first chapters track the app added, where a chapter without an end runs to the next one and the last to the end of the media. |
 | `thumbnailsTrack` | `{ cues: MediaTextCue[]; src: string \| null; crossOrigin: 'anonymous' \| 'use-credentials' \| null } \| null` | The first thumbnails track, or `null` when there is none. |
+| `addTextTrack` | `{ <Cue extends MediaTextCue>(track: TextTrackDefinition<Cue>, content?: TextTrackContent<InferCueValue<Cue>>): TextTrackHandle<InferCueValue<Cue>>; <Value = unknown>(init: TextTrackInit<Value>): TextTrackHandle<Value> }` | Add a text track from the app. It works on any media, sits next to the media's tracks in `textTrackList`, and its cues are read like theirs. Like a `<track>` element, it stays until it's removed, through source changes and media swaps. |
 
 ### Actions
 
@@ -33,6 +38,7 @@ The `liveVideoFeatures` and `videoFeatures` [feature bundles](../../guides/prese
 | --- | --- | --- |
 | `toggleSubtitles` | `(forceShow?: boolean) => boolean` | Toggle captions/subtitles visibility. Showing enables one caption/subtitle track. A track already showing stays selected. Otherwise, selection prefers the last track shown, then a track matching the browser language, then the first available track. Returns whether a track is showing. |
 | `selectSubtitlesTrack` | `(id: string \| null) => void` | Show the captions/subtitles track with `id`, or turn captions/subtitles off with `null`. |
+| `removeTextTrack` | `(id: string) => void` | Remove a track the app added. Tracks from the media stay. |
 
 ### Selector
 

package/docs/reference/api/get-active-text-cues.md

@@ -0,0 +1,69 @@
+# getActiveTextCues
+
+The cues active now on the text tracks a filter or track definition matches
+
+## Import
+
+```ts
+import { getActiveTextCues } from '@videojs/html';
+```
+
+`getActiveTextCues` returns the cues active at the current time on the tracks a filter or [track definition](./define-text-track.md) matches, from the media and the app alike. Cues from several tracks are merged in time order.
+
+It reads `textCues` from the [text cues feature](./feature-text-cues.md), which describes when a cue is active, so it only finds cues on the tracks that feature reads.
+
+Read through a definition, cues are typed by it. With a schema, cues whose value fails it are skipped.
+
+## Usage
+
+Read the active cues in a `player.store.subscribe()` callback to follow playback:
+
+```ts
+const player = document.querySelector('video-player')!;
+const quiz = document.querySelector<HTMLElement>('.quiz')!;
+
+player.store.subscribe(() => {
+  const [cue] = getActiveTextCues(player.store, quizTrack);
+
+  quiz.hidden = !cue;
+  quiz.textContent = cue?.value?.question ?? '';
+});
+```
+
+## API Reference
+
+### With Definition
+
+`getActiveTextCues<Cue extends MediaTextCue>(source, track): readonly Cue[]`
+
+The cues active now on the tracks a track definition matches, typed by the definition. With a schema, cues whose value fails it are skipped.
+
+`player.store.subscribe(() => { const [question] = getActiveTextCues(player.store, quizTrack); });`
+
+#### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `source` (required) | `{ textCues: readonly MediaTrackCues[] }` | — | State that carries text cues, such as the player store. |
+| `track` (required) | `{ kind: 'subtitles' \| 'captions' \| 'descriptions' \| 'chapters' \| 'metadata'; label?: string; language?: string; schema?: StandardSchemaV1 }` | — | The track definition to read. |
+
+#### Return Value
+
+`readonly Cue[]`
+
+### With Filter
+
+`getActiveTextCues(source, filter?): readonly MediaTextCue[]`
+
+The cues active now on the tracks a filter matches, from the media or the app.
+
+#### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `source` (required) | `{ textCues: readonly MediaTrackCues[] }` | — | State that carries text cues, such as the player store. |
+| `filter` | `{ kind?: TextTrackKind \| readonly TextTrackKind[]; label?: string; language?: string } \| ((track: MediaTextTrack) => boolean)` | — | Picks tracks by kind, label, or language, or with a function. Defaults to every track being read. |
+
+#### Return Value
+
+`readonly MediaTextCue[]`

package/docs/reference/api/get-text-cues.md

@@ -0,0 +1,69 @@
+# getTextCues
+
+Every cue on the text tracks a filter or track definition matches
+
+## Import
+
+```ts
+import { getTextCues } from '@videojs/html';
+```
+
+`getTextCues` returns every cue on the tracks a filter or [track definition](./define-text-track.md) matches, from the media and the app alike. Cues from several tracks are merged in time order.
+
+It reads `textCues` from the [text cues feature](./feature-text-cues.md), so it only finds cues on the tracks that feature reads: `metadata` and `chapters` tracks that aren’t `disabled`, except the `thumbnails` track, and the tracks a `watchTextCues()` filter matches.
+
+Read through a definition, cues are typed by it. With a schema, cues whose value fails it are skipped.
+
+## Usage
+
+To read tracks the feature doesn’t read by default, such as captions for a transcript, watch them first:
+
+```ts
+const player = document.querySelector('video-player')!;
+const captions = { kind: 'captions', language: 'en' } as const;
+
+player.store.watchTextCues(captions);
+
+player.store.subscribe(() => {
+  const cues = getTextCues(player.store, captions);
+  console.log(cues.map((cue) => cue.text));
+});
+```
+
+## API Reference
+
+### With Definition
+
+`getTextCues<Cue extends MediaTextCue>(source, track): readonly Cue[]`
+
+Every cue on the tracks a track definition matches, typed by the definition. With a schema, cues whose value fails it are skipped.
+
+`const questions = getTextCues(player.store, quizTrack);`
+
+#### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `source` (required) | `{ textCues: readonly MediaTrackCues[] }` | — | State that carries text cues, such as the player store. |
+| `track` (required) | `{ kind: 'subtitles' \| 'captions' \| 'descriptions' \| 'chapters' \| 'metadata'; label?: string; language?: string; schema?: StandardSchemaV1 }` | — | The track definition to read. |
+
+#### Return Value
+
+`readonly Cue[]`
+
+### With Filter
+
+`getTextCues(source, filter?): readonly MediaTextCue[]`
+
+Every cue on the tracks a filter matches, from the media or the app.
+
+#### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `source` (required) | `{ textCues: readonly MediaTrackCues[] }` | — | State that carries text cues, such as the player store. |
+| `filter` | `{ kind?: TextTrackKind \| readonly TextTrackKind[]; label?: string; language?: string } \| ((track: MediaTextTrack) => boolean)` | — | Picks tracks by kind, label, or language, or with a function. Defaults to every track being read. |
+
+#### Return Value
+
+`readonly MediaTextCue[]`

package/docs/reference/api/get-text-tracks.md

@@ -0,0 +1,41 @@
+# getTextTracks
+
+The text tracks a filter or track definition matches, from the media or the app
+
+## Import
+
+```ts
+import { getTextTracks } from '@videojs/html';
+```
+
+`getTextTracks` returns the tracks in `textTrackList` that a filter or [track definition](./define-text-track.md) matches, from the media and the app alike. Each track’s `source` says which. The list comes from the [text track feature](./feature-text-tracks.md).
+
+A filter picks tracks by `kind`, `label`, or `language`, or with a function. Each given field must match, and a list of kinds matches any kind in it. Without a filter, `getTextTracks` returns every track.
+
+## Usage
+
+Read the tracks in a `player.store.subscribe()` callback to follow changes:
+
+```ts
+const player = document.querySelector('video-player')!;
+
+player.store.subscribe(() => {
+  const captions = getTextTracks(player.store, { kind: ['captions', 'subtitles'] });
+  console.log(captions.map((track) => track.label));
+});
+```
+
+## API Reference
+
+`getTextTracks(source, filter?): MediaTextTrack[]`
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `source` (required) | `{ textTrackList: readonly MediaTextTrack[] }` | — | State that lists text tracks, such as the player store. |
+| `filter` | `{ kind?: TextTrackKind \| readonly TextTrackKind[]; label?: string; language?: string } \| ((track: MediaTextTrack) => boolean) \| { kind: 'subtitles' \| 'captions' \| 'descriptions' \| 'chapters' \| 'metadata'; label?: string; language?: string; schema?: StandardSchemaV1 }` | `{}` | Picks tracks by kind, label, or language, or with a function. Defaults to every track. |
+
+### Return Value
+
+`MediaTextTrack[]`

package/docs/reference/api/hls-metadata-track.md

@@ -0,0 +1,48 @@
+# hlsMetadataTrack
+
+A track definition for the ID3 and EXT-X-DATERANGE metadata hls.js publishes
+
+## Import
+
+```ts
+import { hlsMetadataTrack } from '@videojs/html';
+```
+
+`hlsMetadataTrack` is a [track definition](./define-text-track.md) for `{ kind: 'metadata', label: 'id3' }`, the track hls.js publishes timed metadata on. Its cues are typed as `HlsMetadataCue`. The [text cues feature](./feature-text-cues.md) reads the track like any other metadata track.
+
+hls.js plays streams in [`HlsJsVideo`](../components/hlsjs-video.md) and the media built on it, such as [`MuxVideo`](../components/mux-video.md), when they play through Media Source Extensions. Where the browser plays HLS natively, as Safari does, in-band metadata arrives as `DataCue`s on the browser’s own metadata tracks instead; read those with a `{ kind: 'metadata' }` filter.
+
+## Cues
+
+Each cue carries one ID3 frame or one `EXT-X-DATERANGE` attribute. Its `type` tells which, and narrows `value`:
+
+| `type` | Source | `value` |
+| --- | --- | --- |
+| `'org.id3'` | An ID3 frame in the stream’s segments, or carried in an `emsg` box. hls.js types the second `https://aomedia.org/emsg/ID3`; the player reads both as `org.id3`. | `Id3Frame`: the frame id as `key`, such as `TXXX` or `PRIV`, its description or owner as `info`, and its `data`. |
+| `'com.apple.quicktime.HLS'` | An `EXT-X-DATERANGE` tag in the playlist. | `HlsDateRangeAttribute`: the attribute name as `key`, such as `CLASS` or `X-AD-ID`, and its `data`. |
+
+A date range’s cues span the range, from its start to its end.
+
+## Usage
+
+**id3.ts**
+
+```ts
+import { getActiveTextCues, hlsMetadataTrack } from '@videojs/html';
+
+const player = document.querySelector('video-player')!;
+
+player.store.subscribe(() => {
+  for (const cue of getActiveTextCues(player.store, hlsMetadataTrack)) {
+    if (cue.type === 'org.id3' && cue.value?.key === 'TXXX') console.log(cue.value.info, cue.value.data);
+  }
+});
+```
+
+## Exports
+
+| Export | Description |
+| --- | --- |
+| `HlsMetadataCue` | A metadata cue from hls.js, typed by its `type`. |
+| `Id3Frame` | An ID3 frame: `key`, `info`, and `data`. |
+| `HlsDateRangeAttribute` | One `EXT-X-DATERANGE` attribute: `key` and `data`. |

package/docs/reference/api/html-create-player.md

@@ -175,7 +175,7 @@ Creates a typed HTML player class and bound controller.
 
 | Parameter | Type | Default | Description |
 | --- | --- | --- | --- |
-| `config` (required) | `{ features: [PlayerFeature<MediaPlaybackState>, PlayerFeature<MediaPlaybackRateState>, PlayerFeature<MediaQualityState>, PlayerFeature<MediaAudioTrackState>, PlayerFeature<MediaVolumeState>, PlayerFeature<MediaTimeState>, PlayerFeature<MediaSourceState>, PlayerFeature<MediaBufferState>, PlayerFeature<MediaFullscreenState>, PlayerFeature<MediaPictureInPictureState>, PlayerFeature<MediaRemotePlaybackState>, PlayerFeature<MediaControlsState>, PlayerFeature<MediaTextTrackState>, PlayerFeature<MediaErrorState>, typeof metadataFeature] }` | — | Player configuration with features. |
+| `config` (required) | `{ features: [PlayerFeature<MediaPlaybackState>, typeof playbackRateFeature, PlayerFeature<MediaQualityState>, PlayerFeature<MediaAudioTrackState>, PlayerFeature<MediaVolumeState>, PlayerFeature<MediaTimeState>, PlayerFeature<MediaSourceState>, PlayerFeature<MediaBufferState>, PlayerFeature<MediaFullscreenState>, PlayerFeature<MediaPictureInPictureState>, PlayerFeature<MediaRemotePlaybackState>, PlayerFeature<MediaControlsState>, typeof textTrackFeature, typeof textCuesFeature, PlayerFeature<MediaErrorState>, typeof metadataFeature] }` | — | Player configuration with features. |
 
 #### Return Value
 
@@ -195,7 +195,7 @@ Creates a typed HTML audio player class and bound controller.
 
 | Parameter | Type | Default | Description |
 | --- | --- | --- | --- |
-| `config` (required) | `{ features: [PlayerFeature<MediaPlaybackState>, PlayerFeature<MediaPlaybackRateState>, PlayerFeature<MediaVolumeState>, PlayerFeature<MediaTimeState>, PlayerFeature<MediaSourceState>, PlayerFeature<MediaBufferState>, PlayerFeature<MediaErrorState>, typeof metadataFeature] }` | — | Player configuration with features. |
+| `config` (required) | `{ features: [PlayerFeature<MediaPlaybackState>, typeof playbackRateFeature, PlayerFeature<MediaVolumeState>, PlayerFeature<MediaTimeState>, PlayerFeature<MediaSourceState>, PlayerFeature<MediaBufferState>, typeof textTrackFeature, typeof textCuesFeature, PlayerFeature<MediaErrorState>, typeof metadataFeature] }` | — | Player configuration with features. |
 
 #### Return Value
 

package/docs/reference/api/llms.txt

@@ -1,6 +1,6 @@
 # Video.js v10 — HTML API
 
-> API reference for the player factory, presets, store controllers, features, translation tools, and utilities. Bundled with `@videojs/html` v10.2.0. Links are relative paths to files in this directory.
+> API reference for the player factory, presets, store controllers, features, text tracks, translation tools, and utilities. Bundled with `@videojs/html` v10.4.0. Links are relative paths to files in this directory.
 
 ## Player
 
@@ -50,10 +50,22 @@ API reference for the feature modules passed to createPlayer, which provide play
 - [Remote Playback](./feature-remote-playback.md): Remote playback state and actions for the player store
 - [Source](./feature-source.md): Media source state and actions for the player store
 - [Stream type](./feature-stream-type.md): Stream delivery type (live / on-demand) state for the player store
+- [Text cues](./feature-text-cues.md): Cues and active cues from metadata, chapters, and app text tracks
 - [Text tracks](./feature-text-tracks.md): Subtitles, captions, and chapter track state for the player store
 - [Time](./feature-time.md): Playback position and duration state for the player store
 - [Volume](./feature-volume.md): Volume level and mute state for the player store
 
+## Text tracks
+
+API reference for reading text tracks and their cues: track definitions and readers.
+
+- [defineTextTrack](./define-text-track.md): Define a text track once, with the type of its cue values, to add and read it with
+- [getTextTracks](./get-text-tracks.md): The text tracks a filter or track definition matches, from the media or the app
+- [getTextCues](./get-text-cues.md): Every cue on the text tracks a filter or track definition matches
+- [getActiveTextCues](./get-active-text-cues.md): The cues active now on the text tracks a filter or track definition matches
+- [chaptersTrack](./chapters-track.md): A track definition for chapters, and converters that turn chapter JSON formats into cues
+- [hlsMetadataTrack](./hls-metadata-track.md): A track definition for the ID3 and EXT-X-DATERANGE metadata hls.js publishes
+
 ## i18n
 
 API reference for translating the player: the i18n elements, controller, and the phrase registry.

package/docs/reference/api/media-capabilities.md

@@ -38,7 +38,7 @@ Each `isMedia*Capable` guard accepts any value and returns `false` for `null`, `
 
 A guard checks that a few members of a capability are present, then narrows to every member of that capability’s contract. The table lists both.
 
-Some media, such as embeds, can’t provide buffered ranges, text tracks, or remote playback, and report a shared empty placeholder in their place. `isMediaBufferCapable`, `isMediaTextTrackCapable`, and `isMediaRemotePlaybackCapable` return `false` for that placeholder.
+Some media can’t provide buffered ranges, text tracks, or remote playback, and return `undefined` from `buffered` and `seekable`, `textTracks`, or `remote` instead. `isMediaBufferCapable`, `isMediaTextTrackCapable`, and `isMediaRemotePlaybackCapable` return `false` for `undefined`. Media that can provide buffered ranges but has none yet, such as an embed before it loads, reports an empty range, so `isMediaBufferCapable` returns `true`. A custom media that extends a built-in one opts out by overriding the getter to return `undefined`.
 
 A guard describes what the media object supports, not its current state. `isMediaErrorCapable` returns `true` while `error` is `null`, and `isMediaVolumeCapable` returns `true` on platforms that ignore volume changes. For current state and availability, such as `volumeAvailability` from the [volume feature](./feature-volume.md), read the player’s [features](../../guides/features.md) instead.
 
@@ -49,13 +49,13 @@ A guard describes what the media object supports, not its current state. `isMedi
 | `isMediaSourceCapable` | `src`, `currentSrc`, `readyState`, `load()` | `src`, `currentSrc`, `readyState`, `preload`, `crossOrigin`, `load()`, `canPlayType()` |
 | `isMediaVolumeCapable` | `volume`, `muted` | `volume`, `muted`, `defaultMuted` |
 | `isMediaPlaybackRateCapable` | `playbackRate` | `playbackRate`, `defaultPlaybackRate` |
-| `isMediaBufferCapable` | `buffered`, `seekable`, neither an empty placeholder | `buffered`, `seekable` |
+| `isMediaBufferCapable` | `buffered`, `seekable`, neither `undefined` | `buffered`, `seekable` |
 | `isMediaErrorCapable` | `error` (`null` counts) | `error` |
-| `isMediaTextTrackCapable` | `textTracks`, not an empty placeholder | `textTracks`, `addTextTrack()` |
+| `isMediaTextTrackCapable` | `textTracks` is not `undefined` | `textTracks`, `addTextTrack()` |
 | `isMediaVideoRenditionCapable` | `videoRenditions` | `videoRenditions` |
 | `isMediaAudioTrackCapable` | `audioTracks` | `audioTracks`, `addAudioTrack()`, `removeAudioTrack()` |
 | `isMediaVideoDimensionsCapable` | `videoWidth`, `videoHeight` | `videoWidth`, `videoHeight` |
-| `isMediaRemotePlaybackCapable` | `remote` is an object, not an empty placeholder | `remote`, `disableRemotePlayback` |
+| `isMediaRemotePlaybackCapable` | `remote` is an object | `remote`, `disableRemotePlayback` |
 | `isMediaStreamTypeCapable` | `streamType` | `streamType` |
 | `isMediaLiveCapable` | `liveEdgeStart`, `targetLiveWindow` | `liveEdgeStart`, `targetLiveWindow` |