@videojs/html 10.3.0 → 10.4.0

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>, typeof playbackRateFeature, 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>, typeof playbackRateFeature, 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.3.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 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. Media that can provide buffered ranges but has none yet, such as an embed before it loads, reports an empty range that is not the placeholder, so `isMediaBufferCapable` returns `true`.
+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` |
 

package/docs/reference/api/player-store.md

@@ -55,12 +55,14 @@ Each feature links to the same entry on its reference page.
 | `toggleControls` | `(forceShow?: boolean) => boolean` | [`controlsFeature`](./feature-controls.md#controls-action-toggleControls) | Toggle controls visibility, or force it with `forceShow`. Returns the new `controlsVisible` value. |
 | `buffered` | `[number, number][]` | [`bufferFeature`](./feature-buffer.md#buffer-state-buffered) | Buffered time ranges as \[start, end\] tuples. |
 | `seekable` | `[number, number][]` | [`bufferFeature`](./feature-buffer.md#buffer-state-seekable) | Seekable time ranges as \[start, end\] tuples. |
-| `textTrackList` | `MediaTextTrack[]` | [`textTrackFeature`](./feature-text-tracks.md#textTrack-state-textTrackList) | All text tracks available on the media component. |
+| `textTrackList` | `MediaTextTrack[]` | [`textTrackFeature`](./feature-text-tracks.md#textTrack-state-textTrackList) | Every text track: the media's, then those the app added through the player. `source` tells them apart. |
 | `subtitlesShowing` | `boolean` | [`textTrackFeature`](./feature-text-tracks.md#textTrack-state-subtitlesShowing) | Whether a captions/subtitles track is showing. |
-| `chaptersCues` | `MediaTextCue[]` | [`textTrackFeature`](./feature-text-tracks.md#textTrack-state-chaptersCues) | Cues from the first `kind="chapters"` track, with cue ends clamped to a finite media duration. |
+| `chaptersCues` | `MediaTextCue[]` | [`textTrackFeature`](./feature-text-tracks.md#textTrack-state-chaptersCues) | 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` | [`textTrackFeature`](./feature-text-tracks.md#textTrack-state-thumbnailsTrack) | 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> }` | [`textTrackFeature`](./feature-text-tracks.md#textTrack-state-addTextTrack) | 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. |
 | `toggleSubtitles` | `(forceShow?: boolean) => boolean` | [`textTrackFeature`](./feature-text-tracks.md#textTrack-action-toggleSubtitles) | 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` | [`textTrackFeature`](./feature-text-tracks.md#textTrack-action-selectSubtitlesTrack) | Show the captions/subtitles track with `id`, or turn captions/subtitles off with `null`. |
+| `removeTextTrack` | `(id: string) => void` | [`textTrackFeature`](./feature-text-tracks.md#textTrack-action-removeTextTrack) | Remove a track the app added. Tracks from the media stay. |
 | `playbackRate` | `number` | [`playbackRateFeature`](./feature-playback-rate.md#playbackRate-state-playbackRate) | Current playback rate. |
 | `playbackRateAvailability` | `'available' \| 'unavailable' \| 'unsupported'` | [`playbackRateFeature`](./feature-playback-rate.md#playbackRate-state-playbackRateAvailability) | 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[]` | [`playbackRateFeature`](./feature-playback-rate.md#playbackRate-state-playbackRates) | 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. |
@@ -88,6 +90,8 @@ Each feature links to the same entry on its reference page.
 | `streamType` | `'on-demand' \| 'live' \| 'unknown'` | [`streamTypeFeature`](./feature-stream-type.md#streamType-state-streamType) | Current stream delivery type. Components use this to show live-specific UI (for example, a live indicator or a "jump to live edge" button) or hide the time display. |
 | `orientationLockType` | `'any' \| 'landscape' \| 'landscape-primary' \| 'landscape-secondary' \| 'natural' \| 'portrait' \| 'portrait-primary' \| 'portrait-secondary'` | [`orientationLockFeature`](./feature-orientation-lock.md#orientationLock-state-orientationLockType) | Screen orientation type locked while fullscreen is active. |
 | `setOrientationLockType` | `(value: 'any' \| 'landscape' \| 'landscape-primary' \| 'landscape-secondary' \| 'natural' \| 'portrait' \| 'portrait-primary' \| 'portrait-secondary' \| null \| undefined) => void` | [`orientationLockFeature`](./feature-orientation-lock.md#orientationLock-action-setOrientationLockType) | Sets the locked orientation type. A missing value, including an empty one, restores the default. |
+| `textCues` | `MediaTrackCues[]` | [`textCuesFeature`](./feature-text-cues.md#textCues-state-textCues) | 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. |
+| `watchTextCues` | `(filter: { kind?: TextTrackKind \| readonly TextTrackKind[]; label?: string; language?: string } \| ((track: MediaTextTrack) => boolean)) => (() => void)` | [`textCuesFeature`](./feature-text-cues.md#textCues-action-watchTextCues) | Read cues for more tracks, such as captions for an interactive transcript. Cues are tracked until the returned function is called. |
 
 ## Features by preset
 
@@ -101,7 +105,7 @@ Each column is a preset's feature bundle. A feature no bundle includes is opt-in
 | [`fullscreenFeature`](./feature-fullscreen.md) | ✓ | – | – | ✓ |
 | [`controlsFeature`](./feature-controls.md) | ✓ | – | – | ✓ |
 | [`bufferFeature`](./feature-buffer.md) | ✓ | ✓ | ✓ | ✓ |
-| [`textTrackFeature`](./feature-text-tracks.md) | ✓ | – | – | ✓ |
+| [`textTrackFeature`](./feature-text-tracks.md) | ✓ | ✓ | ✓ | ✓ |
 | [`playbackRateFeature`](./feature-playback-rate.md) | ✓ | ✓ | – | – |
 | [`pipFeature`](./feature-pip.md) | ✓ | – | – | ✓ |
 | [`errorFeature`](./feature-error.md) | ✓ | ✓ | ✓ | ✓ |
@@ -112,4 +116,5 @@ Each column is a preset's feature bundle. A feature no bundle includes is opt-in
 | [`remotePlaybackFeature`](./feature-remote-playback.md) | ✓ | – | – | ✓ |
 | [`liveFeature`](./feature-live.md) | – | – | ✓ | ✓ |
 | [`streamTypeFeature`](./feature-stream-type.md) | – | – | – | – |
-| [`orientationLockFeature`](./feature-orientation-lock.md) | – | – | – | – |
+| [`orientationLockFeature`](./feature-orientation-lock.md) | – | – | – | – |
+| [`textCuesFeature`](./feature-text-cues.md) | ✓ | ✓ | ✓ | ✓ |

package/docs/reference/api/preset-audio.md

@@ -14,7 +14,7 @@ import '@videojs/html/audio/skin';
 Import `@videojs/html/audio/neutral-skin`, `compat-skin`, or `scaffold-skin` instead for another skin. Or load one [CDN](../../guides/cdn.md) bundle that registers the player and a skin together:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/audio.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/audio.js"></script>
 ```
 
 `audio-neutral.js`, `audio-compat.js`, and `audio-scaffold.js` register the other skins instead, and `audio-player.js` registers `<audio-player>` alone.
@@ -62,6 +62,8 @@ The preset root also exports a `PlayerController` bound to the audio player’s
 | [`timeFeature`](./feature-time.md) | Playback position and duration state for the player store |
 | [`sourceFeature`](./feature-source.md) | Media source state and actions for the player store |
 | [`bufferFeature`](./feature-buffer.md) | Buffered and seekable time range state for the player store |
+| [`textTrackFeature`](./feature-text-tracks.md) | Subtitles, captions, and chapter track state for the player store |
+| [`textCuesFeature`](./feature-text-cues.md) | Cues and active cues from metadata, chapters, and app text tracks |
 | [`errorFeature`](./feature-error.md) | Media error state and actions for the player store |
 | [`metadataFeature`](./feature-metadata.md) | Resolved title and poster values for the player store |
 

package/docs/reference/api/preset-background.md

@@ -15,7 +15,7 @@ import '@videojs/html/background/video';
 Or load the [CDN](../../guides/cdn.md) bundle that registers all three:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/background.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/background.js"></script>
 ```
 
 Unlike the other presets, the background preset has one bundle and no player-only bundle.

package/docs/reference/api/preset-live-audio.md

@@ -14,7 +14,7 @@ import '@videojs/html/live-audio/skin';
 Import `@videojs/html/live-audio/neutral-skin`, `compat-skin`, or `scaffold-skin` instead for another skin. Or load one [CDN](../../guides/cdn.md) bundle that registers the player and a skin together:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/live-audio.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/live-audio.js"></script>
 ```
 
 `live-audio-neutral.js`, `live-audio-compat.js`, and `live-audio-scaffold.js` register the other skins instead, and `live-audio-player.js` registers `<live-audio-player>` alone.
@@ -64,6 +64,8 @@ The preset root also exports a `PlayerController` bound to the live audio player
 | [`timeFeature`](./feature-time.md) | Playback position and duration state for the player store |
 | [`sourceFeature`](./feature-source.md) | Media source state and actions for the player store |
 | [`bufferFeature`](./feature-buffer.md) | Buffered and seekable time range state for the player store |
+| [`textTrackFeature`](./feature-text-tracks.md) | Subtitles, captions, and chapter track state for the player store |
+| [`textCuesFeature`](./feature-text-cues.md) | Cues and active cues from metadata, chapters, and app text tracks |
 | [`errorFeature`](./feature-error.md) | Media error state and actions for the player store |
 | [`liveFeature`](./feature-live.md) | Live edge state for the player store |
 | [`metadataFeature`](./feature-metadata.md) | Resolved title and poster values for the player store |

package/docs/reference/api/preset-live-video.md

@@ -14,7 +14,7 @@ import '@videojs/html/live-video/skin';
 Import `@videojs/html/live-video/neutral-skin`, `compat-skin`, or `scaffold-skin` instead for another skin. Or load one [CDN](../../guides/cdn.md) bundle that registers the player and a skin together:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.3.0/live-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/live-video.js"></script>
 ```
 
 `live-video-neutral.js`, `live-video-compat.js`, and `live-video-scaffold.js` register the other skins instead, and `live-video-player.js` registers `<live-video-player>` alone.
@@ -69,6 +69,7 @@ The preset root also exports a `PlayerController` bound to the live video player
 | [`remotePlaybackFeature`](./feature-remote-playback.md) | Remote playback state and actions for the player store |
 | [`controlsFeature`](./feature-controls.md) | User activity and controls visibility state for the player store |
 | [`textTrackFeature`](./feature-text-tracks.md) | Subtitles, captions, and chapter track state for the player store |
+| [`textCuesFeature`](./feature-text-cues.md) | Cues and active cues from metadata, chapters, and app text tracks |
 | [`errorFeature`](./feature-error.md) | Media error state and actions for the player store |
 | [`liveFeature`](./feature-live.md) | Live edge state for the player store |
 | [`metadataFeature`](./feature-metadata.md) | Resolved title and poster values for the player store |

package/docs/reference/api/preset-video.md

@@ -14,7 +14,7 @@ import '@videojs/html/video/skin';
 Import `@videojs/html/video/neutral-skin`, `compat-skin`, or `scaffold-skin` instead for another skin. Or load one [CDN](../../guides/cdn.md) bundle that registers the player and a skin together:
 
 ```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>
 ```
 
 `video-neutral.js`, `video-compat.js`, and `video-scaffold.js` register the other skins instead, and `video-player.js` registers `<video-player>` alone.
@@ -69,6 +69,7 @@ The preset root also exports a `PlayerController` bound to the video player’s
 | [`remotePlaybackFeature`](./feature-remote-playback.md) | Remote playback state and actions for the player store |
 | [`controlsFeature`](./feature-controls.md) | User activity and controls visibility state for the player store |
 | [`textTrackFeature`](./feature-text-tracks.md) | Subtitles, captions, and chapter track state for the player store |
+| [`textCuesFeature`](./feature-text-cues.md) | Cues and active cues from metadata, chapters, and app text tracks |
 | [`errorFeature`](./feature-error.md) | Media error state and actions for the player store |
 | [`metadataFeature`](./feature-metadata.md) | Resolved title and poster values for the player store |