@videojs/html 10.2.0 → 10.4.0

package/docs/guides/timed-metadata.md

@@ -0,0 +1,318 @@
+# Sync content with timed metadata
+
+Show quizzes, product cards, ad markers, chapters, and transcripts in time with playback, from cues in the media or cues your app adds.
+
+Timed metadata is data tied to a span of playback: a quiz question, a product card, an ad break, or a chapter. Video.js reads it as text tracks and cues, the platform objects captions use, whether the cues come from the media or from your app.
+
+## Recommended approach
+
+Define the track with `defineTextTrack()`, add your cues to the player with `player.store.addTextTrack()`, and render the cue `getActiveTextCues()` returns each time the store changes.
+
+**index.html**
+
+```html
+<video-player class="html-timed-metadata-basic">
+  <media-container class="html-timed-metadata-basic__container">
+    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
+    <p class="html-timed-metadata-basic__note">
+      <strong class="html-timed-metadata-basic__title"></strong>
+      <span class="html-timed-metadata-basic__body"></span>
+    </p>
+  </media-container>
+</video-player>
+```
+
+**index.css**
+
+```css
+.html-timed-metadata-basic__container {
+  position: relative;
+}
+
+.html-timed-metadata-basic__container video {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+
+.html-timed-metadata-basic__note {
+  position: absolute;
+  top: 12px;
+  left: 12px;
+  max-width: calc(100% - 24px);
+  padding: 10px 14px;
+  margin: 0;
+  font-size: 0.875rem;
+  line-height: 1.4;
+  color: black;
+  background: rgba(255, 255, 255, 0.85);
+  border-radius: 12px;
+  backdrop-filter: blur(10px);
+}
+
+.html-timed-metadata-basic__note:not([data-active]) {
+  display: none;
+}
+
+.html-timed-metadata-basic__title {
+  display: block;
+}
+```
+
+**index.ts**
+
+```ts
+import '@videojs/html/video/player';
+import '@videojs/html/ui/container';
+import { defineTextTrack, getActiveTextCues } from '@videojs/html';
+
+interface Note {
+  title: string;
+  body: string;
+}
+
+const notesTrack = defineTextTrack<Note>({ kind: 'metadata', label: 'notes' });
+
+const player = document.querySelector('video-player');
+const note = document.querySelector<HTMLElement>('.html-timed-metadata-basic__note');
+const title = note?.querySelector('.html-timed-metadata-basic__title');
+const body = note?.querySelector('.html-timed-metadata-basic__body');
+
+if (player && note && title && body) {
+  player.store.addTextTrack(notesTrack, {
+    cues: [
+      { startTime: 1, endTime: 8, value: { title: 'Timed metadata', body: 'This note is a cue the app added.' } },
+      { startTime: 12, endTime: 19, value: { title: 'Any data', body: 'Each cue carries a value you render.' } },
+      { startTime: 23, endTime: 30, value: { title: 'Any media', body: 'The player holds the track, not the video.' } },
+    ],
+  });
+
+  player.store.subscribe(() => {
+    const [cue] = getActiveTextCues(player.store, notesTrack);
+
+    note.toggleAttribute('data-active', Boolean(cue?.value));
+    title.textContent = cue?.value?.title ?? '';
+    body.textContent = cue?.value?.body ?? '';
+  });
+}
+```
+
+In your app, the cues usually come from your API or CMS. Fetch them and pass them as `cues`, or pass the file’s URL as `src` and the player loads it.
+
+## How it works
+
+A text track has a `kind`, `label`, and `language`, and a list of cues. Each cue spans `startTime` to `endTime`, in seconds, and carries `text`, structured data in `value`, or both. `value` and `type` are named after the platform’s `DataCue`. A cue without an `endTime` is a point, active for one second, except in a chapters track your app adds, where it runs to the next chapter.
+
+`addTextTrack()` adds the track to the player, not the media, so it works with any media, including YouTube and other embeds. The track sits next to the media’s tracks in `textTrackList` with `source: 'app'`.
+
+The [text cues feature](../reference/api/feature-text-cues.md), included in the video, audio, and live presets, reads cues from the media’s `metadata` and `chapters` tracks and from the tracks your app adds, and tracks which cues are active at the current time. Tracks from either place are read the same way.
+
+`defineTextTrack<Note>()` types each cue’s `value`, and works as a filter: reading through it picks the tracks with the same kind, label, and language. A plain filter, such as `{ label: 'notes' }`, works too, but its cues’ `value` is `unknown`.
+
+`player.store.subscribe()` calls back whenever player state changes, and `getActiveTextCues()` returns the cues active at that moment.
+
+Browsers never draw metadata or chapters cues, so the overlay, its styles, and its accessibility are up to your UI.
+
+## Availability and constraints
+
+- Active cues follow `currentTime`, which updates up to about four times a second. Don’t rely on them for frame-accurate timing. A cue that playback passes between two updates still shows up as active once; a cue a seek jumps over doesn’t.
+- `cues` are plain, JSON-serializable data, so a server-rendered page can pass them in. A `src` is fetched only once the player runs on the client, and a cross-origin file needs CORS headers.
+- Browsers load a `<track>` element’s cues only while the track is `showing` or `hidden`. `default` makes a `<track kind="metadata">` `hidden`; without it, the track stays `disabled` and its cues never load.
+- `value` isn’t checked at runtime unless the definition has a schema. See [Check values with a schema](#check-values-with-a-schema).
+
+Like a `<track>` element, an app track stays through source changes until you remove it. When you play a different video, remove its tracks and add the new video’s.
+
+## Common variations
+
+The examples below assume `player` is the `<video-player>` element, as in the recommended approach, and that the elements they update, such as `adBadge`, are queried from your page.
+
+### Read cues from a WebVTT file
+
+Add a `<track kind="metadata">` to the media. Cue text that parses as a JSON object or array becomes the cue’s `value`; any other text stays in `text`.
+
+**notes.vtt**
+
+```text
+WEBVTT
+
+00:00:01.000 --> 00:00:08.000
+{ "title": "Timed metadata", "body": "This note came from a WebVTT file." }
+```
+
+```html
+<video src="video.mp4" playsinline>
+  <track kind="metadata" label="notes" src="/notes.vtt" default />
+</video>
+```
+
+A definition with the same kind and label reads it, so the rendering code from the recommended approach works unchanged. To use the file with media that has no `<track>` support, such as an embed, pass it as `src` when you add the track instead.
+
+### Read metadata from an HLS stream
+
+When hls.js plays a stream, in [`HlsJsVideo`](../reference/components/hlsjs-video.md) and media built on it such as [`MuxVideo`](../reference/components/mux-video.md), it publishes ID3 frames and `EXT-X-DATERANGE` tags as cues on a metadata track. Read them with [`hlsMetadataTrack`](../reference/api/hls-metadata-track.md). Each cue’s `type` tells an ID3 frame from a date range attribute, and narrows its `value`.
+
+```ts
+import { getActiveTextCues, hlsMetadataTrack } from '@videojs/html';
+
+player.store.subscribe(() => {
+  const cues = getActiveTextCues(player.store, hlsMetadataTrack);
+  const inAd = cues.some((cue) => cue.type === 'com.apple.quicktime.HLS' && cue.value?.key === 'X-AD-ID');
+
+  adBadge.hidden = !inAd;
+});
+```
+
+Where the browser plays HLS natively, as Safari does, in-band metadata arrives as `DataCue`s on the browser’s own metadata tracks. Read those with a `{ kind: 'metadata' }` filter.
+
+### Mark cues on the time slider
+
+Add `<media-time-slider-markers>` to the time slider to draw a marker for each cue on the tracks its attributes match, such as the notes from the recommended approach.
+
+```html
+<media-time-slider>
+  <media-slider-track>
+    <media-slider-fill></media-slider-fill>
+  </media-slider-track>
+  <media-time-slider-markers kind="metadata" label="notes"></media-time-slider-markers>
+  <media-slider-thumb></media-slider-thumb>
+</media-time-slider>
+```
+
+A point is a marker with no width, a range spans its cue, and a marker has `data-active` while its cue is active. Markers are unstyled: position each one with its `--media-slider-marker-*` custom properties. See [the markers reference](../reference/components/time-slider-markers.md) for the full styling contract.
+
+### Check values with a schema
+
+Cues from a file or a stream can carry anything. Pass a `schema` to `defineTextTrack()` to check each value where it’s read. Any [Standard Schema](https://standardschema.dev) works, such as one from zod or valibot, and the value type comes from the schema.
+
+```ts
+import { z } from 'zod';
+
+const NoteSchema = z.object({ title: z.string(), body: z.string() });
+
+const notesTrack = defineTextTrack({ kind: 'metadata', label: 'notes', schema: NoteSchema });
+```
+
+Readers skip cues whose value fails the schema, and warn in development. The schema must be synchronous.
+
+### Add chapters
+
+Add a `chapters` track the same way. A chapter’s title is its cue `text`, and a chapter without an `endTime` runs to the next one. When the media has no chapters track of its own, the [time slider](../reference/components/time-slider.md) shows these chapters.
+
+```ts
+player.store.addTextTrack({
+  kind: 'chapters',
+  cues: [
+    { startTime: 0, text: 'Introduction' },
+    { startTime: 95, text: 'Setup' },
+    { startTime: 410, text: 'Wrap-up' },
+  ],
+});
+```
+
+To load a Podcasting 2.0, Apple HLS, or JSON-LD chapters file, pass its converter as `format`, such as `podcastChapters`. Read the current chapter, with any artwork the file gives it, through [`chaptersTrack`](../reference/api/chapters-track.md).
+
+```ts
+import { chaptersTrack, getActiveTextCues, podcastChapters } from '@videojs/html';
+
+player.store.addTextTrack({ kind: 'chapters', src: '/episodes/42/chapters.json', format: podcastChapters });
+
+player.store.subscribe(() => {
+  const [chapter] = getActiveTextCues(player.store, chaptersTrack);
+  currentChapter.textContent = chapter?.text ?? '';
+});
+```
+
+### Show an interactive transcript
+
+A transcript reads captions cues, which the text cues feature skips unless something asks for them.
+
+Call `watchTextCues()` to read them, then render with `getTextCues()` and `getActiveTextCues()`.
+
+```ts
+import { getActiveTextCues, getTextCues } from '@videojs/html';
+
+const captions = { kind: 'captions', language: 'en' } as const;
+// A cue that hasn't changed stays the same object, so it keeps its line.
+const lines = new WeakMap<object, HTMLLIElement>();
+
+player.store.watchTextCues(captions);
+
+player.store.subscribe(() => {
+  const [active] = getActiveTextCues(player.store, captions);
+  const next = getTextCues(player.store, captions).map((cue) => {
+    let line = lines.get(cue);
+
+    if (!line) {
+      const button = document.createElement('button');
+
+      button.type = 'button';
+      button.textContent = cue.text;
+      button.addEventListener('click', () => player.store.seek(cue.startTime));
+
+      line = document.createElement('li');
+      line.append(button);
+      lines.set(cue, line);
+    }
+
+    if (cue.id === active?.id) line.setAttribute('aria-current', 'true');
+    else line.removeAttribute('aria-current');
+
+    return line;
+  });
+
+  // Replace the lines only when they change, so a focused button keeps focus.
+  const current = [...transcript.children];
+
+  if (next.length !== current.length || next.some((line, index) => line !== current[index])) {
+    transcript.replaceChildren(...next);
+  }
+});
+```
+
+The browser loads a `<track>` element’s cues only while captions are on. To show the transcript either way, add the captions track from your app instead of a `<track>` element. The player copies it into the media, so the browser still draws the captions when a viewer turns them on.
+
+```ts
+player.store.addTextTrack({ kind: 'captions', label: 'English', language: 'en', src: '/captions.vtt' });
+```
+
+## Troubleshooting
+
+### No cue is ever active
+
+Confirm that:
+
+- The track is one the text cues feature reads: a `metadata` or `chapters` track that isn’t `disabled`. Give a `<track kind="metadata">` the `default` attribute. For other kinds, read through the hooks or call `watchTextCues()`.
+- Your filter or definition matches the track’s `kind`, `label`, and `language` exactly. `getTextTracks()` lists the tracks the player has.
+- Cue times are in seconds.
+
+### A cue’s value is undefined
+
+Only `metadata` cue text that parses as a JSON object or array becomes `value`; other text stays in `text`. With a schema, cues whose value fails it are skipped, with a warning in development.
+
+### An app track outlives its video
+
+App tracks stay until they’re removed, through source changes. Call the handle’s `remove()`, or the store’s `removeTextTrack()`, before adding the next video’s tracks.
+
+### Cues from a src never load
+
+The file failed to load, often because of a missing CORS header or a wrong URL. The track keeps any cues it already had, and a warning shows in development.
+
+## Related pages
+
+### Components
+
+- [media-time-slider](../reference/components/time-slider.md): A slider component for seeking through media playback time
+- [media-time-slider-markers](../reference/components/time-slider-markers.md): Draws a marker on the time slider for each cue on the text tracks a filter matches, such as ad breaks
+
+### API
+
+- [Text cues](../reference/api/feature-text-cues.md): Cues and active cues from metadata, chapters, and app text tracks
+- [defineTextTrack](../reference/api/define-text-track.md): Define a text track once, with the type of its cue values, to add and read it with
+- [getActiveTextCues](../reference/api/get-active-text-cues.md): The cues active now on the text tracks a filter or track definition matches
+- [getTextCues](../reference/api/get-text-cues.md): Every cue on the text tracks a filter or track definition matches
+- [chaptersTrack](../reference/api/chapters-track.md): A track definition for chapters, and converters that turn chapter JSON formats into cues
+- [hlsMetadataTrack](../reference/api/hls-metadata-track.md): A track definition for the ID3 and EXT-X-DATERANGE metadata hls.js publishes
+
+### Guides
+
+- [Show captions and subtitles](./captions.md): Show captions and subtitles, and let users turn them on and pick a language.
+- [Media sources](./media-sources.md): Set what a media component plays and how its engine plays it with the structured source property

package/docs/guides/ui-components.md

@@ -39,7 +39,7 @@ import '@videojs/html/icons/element';
 
 ### Style components with state
 
-Components add `data-*` attributes to describe their current state. For example, a play button adds `data-paused` while the media is paused. Use those attributes in CSS:
+Components add `data-*` attributes to describe their current state. For example, a play button adds `data-paused` while the media is paused, except while autoplay is pending, when the button shows pause. Use those attributes in CSS:
 
 ```css
 .my-play-button .pause-icon {

package/docs/llms.txt

@@ -1,6 +1,6 @@
 # Video.js v10 — HTML Documentation
 
-> Bundled with `@videojs/html` v10.2.0. Links are relative paths to files in this directory.
+> Bundled with `@videojs/html` v10.4.0. Links are relative paths to files in this directory.
 
 > Install the [Video.js skill](https://github.com/videojs/skills) to help AI coding agents find version-matched pages from this index.
 
@@ -71,6 +71,7 @@ Guides for one player capability each: the recommended setup, how it works, brow
 - [Automatically show and hide controls](./guides/controls.md): Show controls while the user is active, hide them during playback, and toggle them by touch.
 - [Add a poster and loading placeholder](./guides/poster.md): Set the image shown before playback, then add a lightweight placeholder while it loads
 - [Show captions and subtitles](./guides/captions.md): Show captions and subtitles, and let users turn them on and pick a language.
+- [Sync content with timed metadata](./guides/timed-metadata.md): Show quizzes, product cards, ad markers, chapters, and transcripts in time with playback, from cues in the media or cues your app adds.
 - [Add keyboard shortcuts and gestures](./guides/keyboard-shortcuts.md): Add keyboard shortcuts, tap and double-tap gestures, and on-screen feedback for input actions.
 - [Play live streams](./guides/live-streams.md): Play live streams with live-edge tracking, DVR windows, and stream-type detection.
 - [Add a quality selector](./guides/quality.md): Read available renditions, let the engine adapt automatically, and offer manual quality selection.
@@ -82,6 +83,7 @@ Guides for one player capability each: the recommended setup, how it works, brow
 - [Remember user preferences](./guides/user-preferences.md): Save volume and caption preferences, restore them after loading, and adapt the pattern for quality selection.
 - [Add a background video](./guides/background-video.md): Add an accessible background video from an MP4, WebM, HLS, or Mux source
 - [Internationalize the player](./guides/internationalization.md): Translate player labels and announcements: shipped locale packs, custom translations, runtime switching, and server rendering.
+- [Track video telemetry with Google Analytics 4](./guides/google-analytics.md): Track video engagement, progress milestones, and playback interactions by adding the Google Analytics extension to a player
 - [Monitor playback with Mux Data](./guides/mux-data.md): Measure startup time, rebuffering, failures, and watch time by adding the Mux Data extension to a player
 
 ### Migrate
@@ -115,19 +117,19 @@ API reference for the packaged skins each preset ships.
 
 - [video-skin](./reference/components/video-skin.md): The video preset's default skin with the modern, frosted look
 - [video-neutral-skin](./reference/components/video-neutral-skin.md): The video preset's visually lighter skin, closer to a classic control bar
-- [video-compat-skin](./reference/components/video-compat-skin.md): A video skin designed for broader browser compatibility
+- [video-compat-skin](./reference/components/video-compat-skin.md): The video preset's plain, unbranded skin, a polished step above native controls
 - [video-scaffold-skin](./reference/components/video-scaffold-skin.md): A video skin with minimal styling for custom skins
 - [audio-skin](./reference/components/audio-skin.md): The audio preset's default skin with the modern, frosted look
 - [audio-neutral-skin](./reference/components/audio-neutral-skin.md): The audio preset's visually lighter skin, closer to a classic control bar
-- [audio-compat-skin](./reference/components/audio-compat-skin.md): An audio skin designed for broader browser compatibility
+- [audio-compat-skin](./reference/components/audio-compat-skin.md): The audio preset's plain, unbranded skin, a polished step above native controls
 - [audio-scaffold-skin](./reference/components/audio-scaffold-skin.md): An audio skin with minimal styling for custom skins
 - [live-video-skin](./reference/components/live-video-skin.md): The live video preset's default skin, which swaps time controls for a Live button
 - [live-video-neutral-skin](./reference/components/live-video-neutral-skin.md): The live video preset's visually lighter skin, closer to a classic control bar
-- [live-video-compat-skin](./reference/components/live-video-compat-skin.md): A live video skin designed for broader browser compatibility
+- [live-video-compat-skin](./reference/components/live-video-compat-skin.md): The live video preset's plain, unbranded skin, a polished step above native controls
 - [live-video-scaffold-skin](./reference/components/live-video-scaffold-skin.md): A live video skin with minimal styling for custom skins
 - [live-audio-skin](./reference/components/live-audio-skin.md): The live audio preset's default skin, which swaps time controls for a Live button
 - [live-audio-neutral-skin](./reference/components/live-audio-neutral-skin.md): The live audio preset's visually lighter skin, closer to a classic control bar
-- [live-audio-compat-skin](./reference/components/live-audio-compat-skin.md): A live audio skin designed for broader browser compatibility
+- [live-audio-compat-skin](./reference/components/live-audio-compat-skin.md): The live audio preset's plain, unbranded skin, a polished step above native controls
 - [live-audio-scaffold-skin](./reference/components/live-audio-scaffold-skin.md): A live audio skin with minimal styling for custom skins
 - [background-video-skin](./reference/components/background-video-skin.md): The background preset's chrome-less skin for ambient video
 
@@ -138,17 +140,20 @@ API reference for media components that handle streaming protocols and playback.
 - [audio](./reference/components/audio.md): Native audio playback that can provide media to a Video.js player
 - [background-video](./reference/components/background-video.md): Decorative background video element with automatic muting and looping
 - [cloudflare-video](./reference/components/cloudflare-video.md): Video component that plays Cloudflare Stream videos through the Stream player
+- [dailymotion-video](./reference/components/dailymotion-video.md): Video component that plays Dailymotion videos through a Dailymotion player configuration
 - [dash-video](./reference/components/dash-video.md): DASH video element powered by dash.js for adaptive bitrate streaming
 - [hls-audio](./reference/components/hls-audio.md): Audio-only HLS element that plays the audio rendition of an HLS stream
 - [hls-background-video](./reference/components/hls-background-video.md): HLS background video without controls, audio, captions, or adaptive quality
 - [hls-video](./reference/components/hls-video.md): Lightweight HLS video element with minimal bundle size
 - [hlsjs-video](./reference/components/hlsjs-video.md): HLS video element powered by hls.js for adaptive bitrate streaming
+- [mixcloud-audio](./reference/components/mixcloud-audio.md): Audio component that plays Mixcloud shows through the Mixcloud Widget
 - [mux-audio](./reference/components/mux-audio.md): Audio element for Mux-hosted HLS streams
 - [mux-background-video](./reference/components/mux-background-video.md): Mux-specific name for the HLS background video component
 - [mux-video](./reference/components/mux-video.md): Video element for Mux-hosted HLS streams
 - [native-hls-video](./reference/components/native-hls-video.md): HLS video element using the browser's built-in HLS support
 - [playerjs-video](./reference/components/playerjs-video.md): Video component that plays any embed implementing the player.js protocol, such as Mux Player, Gumlet, FrameRate, Livid, Bunny Stream, and Streamable
 - [shaka-video](./reference/components/shaka-video.md): Video element powered by Shaka Player for DASH, HLS, and progressive playback with DRM
+- [soundcloud-audio](./reference/components/soundcloud-audio.md): Audio component that plays SoundCloud tracks and sets through the SoundCloud Widget
 - [spotify-audio](./reference/components/spotify-audio.md): Audio component that plays Spotify tracks, episodes, playlists, and shows through the Spotify embed
 - [tiktok-video](./reference/components/tiktok-video.md): Video component that plays TikTok videos through the TikTok embed player
 - [twitch-video](./reference/components/twitch-video.md): Video component that plays Twitch videos and live channels through the Twitch embed player
@@ -161,6 +166,7 @@ API reference for media components that handle streaming protocols and playback.
 
 API reference for extensions that connect external services to the player.
 
+- [google-analytics](./reference/components/google-analytics.md): Options for the Google Analytics 4 extension that tracks video engagement and playback events
 - [google-cast](./reference/components/google-cast.md): Options for the Google Cast extension that configures the receiver and load request
 - [mux-data](./reference/components/mux-data.md): Options for the Mux Data extension that monitors playback quality
 
@@ -185,6 +191,7 @@ API reference for the slider components that scrub time and adjust volume.
 
 - [media-slider](./reference/components/slider.md): A composable slider component with track, fill, thumb, preview, and value parts
 - [media-time-slider](./reference/components/time-slider.md): A slider component for seeking through media playback time
+- [media-time-slider-markers](./reference/components/time-slider-markers.md): Draws a marker on the time slider for each cue on the text tracks a filter matches, such as ad breaks
 - [media-volume-slider](./reference/components/volume-slider.md): A slider component for controlling media playback volume
 
 ### Menus
@@ -237,7 +244,7 @@ API reference for the icon sets the skins use, available for your own controls.
 
 ## API
 
-API reference for the player factory, presets, store controllers, features, translation tools, and utilities.
+API reference for the player factory, presets, store controllers, features, text tracks, translation tools, and utilities.
 
 Section index: [reference/api/llms.txt](./reference/api/llms.txt).
 
@@ -289,10 +296,22 @@ API reference for the feature modules passed to createPlayer, which provide play
 - [Remote Playback](./reference/api/feature-remote-playback.md): Remote playback state and actions for the player store
 - [Source](./reference/api/feature-source.md): Media source state and actions for the player store
 - [Stream type](./reference/api/feature-stream-type.md): Stream delivery type (live / on-demand) state for the player store
+- [Text cues](./reference/api/feature-text-cues.md): Cues and active cues from metadata, chapters, and app text tracks
 - [Text tracks](./reference/api/feature-text-tracks.md): Subtitles, captions, and chapter track state for the player store
 - [Time](./reference/api/feature-time.md): Playback position and duration state for the player store
 - [Volume](./reference/api/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](./reference/api/define-text-track.md): Define a text track once, with the type of its cue values, to add and read it with
+- [getTextTracks](./reference/api/get-text-tracks.md): The text tracks a filter or track definition matches, from the media or the app
+- [getTextCues](./reference/api/get-text-cues.md): Every cue on the text tracks a filter or track definition matches
+- [getActiveTextCues](./reference/api/get-active-text-cues.md): The cues active now on the text tracks a filter or track definition matches
+- [chaptersTrack](./reference/api/chapters-track.md): A track definition for chapters, and converters that turn chapter JSON formats into cues
+- [hlsMetadataTrack](./reference/api/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/chapters-track.md

@@ -0,0 +1,71 @@
+# chaptersTrack
+
+A track definition for chapters, and converters that turn chapter JSON formats into cues
+
+## Import
+
+```ts
+import { appleHlsChapters, chaptersTrack, jsonLdChapters, podcastChapters } from '@videojs/html';
+```
+
+`chaptersTrack` is a [track definition](./define-text-track.md) for `{ kind: 'chapters' }`. It has no `label`, so it matches every chapters track, from the media and the app alike. A chapter’s title is its cue’s `text`, and its `value` is typed as `ChapterCueValue`, which holds what chapter formats carry beyond a title.
+
+WebVTT chapters carry only a title, so their cues have no `value`. Chapters converted from JSON with the functions below carry one.
+
+| `ChapterCueValue` field | Description |
+| --- | --- |
+| `description` | The chapter’s description. |
+| `url` | A web page for the chapter. |
+| `images` | Images for the chapter, such as artwork or a thumbnail. Each has a `url`, and optionally a `width` and `height` in pixels. |
+| `titles` | The chapter’s titles by language, when the source has several. |
+
+## Usage
+
+**current-chapter.ts**
+
+```ts
+import { chaptersTrack, getActiveTextCues } from '@videojs/html';
+
+const player = document.querySelector('video-player')!;
+const label = document.querySelector('.current-chapter')!;
+
+player.store.subscribe(() => {
+  const [chapter] = getActiveTextCues(player.store, chaptersTrack);
+  label.textContent = chapter?.text ?? '';
+});
+```
+
+## Chapter formats
+
+Each converter takes a file’s text, or JSON you already parsed, and returns cues for a chapters track. Pass one as the `format` of a track with a `src`, and the player converts the file once it loads. Or call it yourself and pass the result as `cues`. Converters skip entries they can’t read; only text that isn’t JSON throws.
+
+```ts
+player.store.addTextTrack({ kind: 'chapters', src: '/episodes/42/chapters.json', format: podcastChapters });
+```
+
+A chapter without an end runs to the next chapter, and the last one to the end of the media.
+
+### `podcastChapters`
+
+Reads a [Podcasting 2.0 JSON chapters](https://github.com/Podcastindex-org/podcast-namespace) file. Each chapter’s `title` becomes the cue text, `startTime` and `endTime` its times, `url` its `url`, and `img` its first image. Chapters marked `toc: false` are left out, since they aren’t meant to be shown.
+
+### `appleHlsChapters`
+
+Reads an Apple HLS chapters file: the JSON an `EXT-X-SESSION-DATA` tag with `DATA-ID="com.apple.hls.chapters"` points to. Each chapter starts at its `start-time` and ends after its `duration`. Its first title becomes the cue text, and every title is kept in `titles` by language. Its `images` keep their `pixel-width` and `pixel-height` as `width` and `height`.
+
+### `jsonLdChapters`
+
+Reads schema.org JSON-LD: a `VideoObject` whose `hasPart` lists `Clip`s, a list of `Clip`s, or one `Clip`. These are the clips Google shows as key moments. Each clip’s `name` becomes the cue text, `startOffset` and `endOffset` its times in seconds, and its `description`, `url`, and first `thumbnailUrl` its value.
+
+```ts
+const jsonLd = document.querySelector('script[type="application/ld+json"]')!.textContent!;
+
+player.store.addTextTrack({ kind: 'chapters', cues: jsonLdChapters(jsonLd) });
+```
+
+## Exports
+
+| Export | Description |
+| --- | --- |
+| `ChapterCueValue` | What a chapter can carry beyond its title. |
+| `ChapterImage` | An image for a chapter: a `url`, and optionally a `width` and `height`. |

package/docs/reference/api/define-text-track.md

@@ -0,0 +1,113 @@
+# defineTextTrack
+
+Define a text track once, with the type of its cue values, to add and read it with
+
+## Import
+
+```ts
+import { defineTextTrack } from '@videojs/html';
+```
+
+`defineTextTrack` returns a track definition: a track’s `kind`, and optionally its `label` and `language`, typed with the `value` its cues carry. A definition works anywhere a text track filter does, matching tracks by kind, label, and language. Reading through it types each cue’s `value`, and adding a track from it checks the cues you pass against that type.
+
+## Usage
+
+Pass the value type as a type parameter. The type isn’t checked at runtime.
+
+```ts
+import { defineTextTrack, getActiveTextCues, type TextCueInit } from '@videojs/html';
+
+interface Quiz {
+  question: string;
+}
+
+const quizTrack = defineTextTrack<Quiz>({ kind: 'metadata', label: 'quiz' });
+
+const player = document.querySelector('video-player')!;
+const cues: TextCueInit<Quiz>[] = await fetch('/api/quiz').then((res) => res.json());
+
+player.store.addTextTrack(quizTrack, { cues });
+
+player.store.subscribe(() => {
+  const [cue] = getActiveTextCues(player.store, quizTrack);
+  console.log(cue?.value?.question);
+});
+```
+
+### Schemas
+
+Pass a `schema` to check values where they’re read. It takes any [Standard Schema](https://standardschema.dev), the validation interface zod, valibot, ArkType, and other libraries implement, and the value type comes from the schema’s output.
+
+```ts
+import { z } from 'zod';
+
+const QuizSchema = z.object({ question: z.string() });
+
+const quizTrack = defineTextTrack({ kind: 'metadata', label: 'quiz', schema: QuizSchema });
+```
+
+Readers skip a cue whose value fails the schema, and warn in development. Each cue is checked once per schema. Schemas must be synchronous; an asynchronous schema fails every value. Adding a track doesn’t run the schema.
+
+### Built-in definitions
+
+[`chaptersTrack`](./chapters-track.md) matches every chapters track and types the values chapter formats carry. [`hlsMetadataTrack`](./hls-metadata-track.md) matches the metadata track hls.js publishes ID3 and `EXT-X-DATERANGE` metadata on.
+
+## Exports
+
+| Export | Description |
+| --- | --- |
+| `TextTrackDefinition` | A track definition. Its type parameter is the cue type it reads. |
+| `TextTrackIdentity` | What identifies a track: `kind`, `label`, and `language`. |
+| `InferTextTrackCue` | The cue type a definition reads, as in `InferTextTrackCue<typeof quizTrack>`. |
+| `InferSchemaOutput` | The value type a schema produces. |
+| `StandardSchemaV1` | The Standard Schema interface a `schema` implements. |
+| `StandardSchemaV1Props` | The properties a Standard Schema carries under its `~standard` key. |
+| `StandardSchemaV1Result` | What a Standard Schema’s `validate` returns. |
+
+## API Reference
+
+### With Schema
+
+`defineTextTrack<Schema extends StandardSchemaV1>(init): TextTrackDefinition<MediaTextCue<InferSchemaOutput<Schema>>>`
+
+Define a text track whose cues carry a `value` checked by a schema, such as one from zod or valibot. Cues whose value fails it are skipped where they're read.
+
+`const quizTrack = defineTextTrack({ kind: 'metadata', label: 'quiz', schema: QuizSchema });`
+
+#### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `init` (required) | `{ kind: 'subtitles' \| 'captions' \| 'descriptions' \| 'chapters' \| 'metadata'; label?: string; language?: string } & { schema: Schema }` | — | The track's kind, and optionally its label and language, with a [Standard Schema](https://standardschema.dev) for its cue values. |
+
+#### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `kind` | `'subtitles' \| 'captions' \| 'descriptions' \| 'chapters' \| 'metadata'` | |
+| `label` | `string \| undefined` | |
+| `language` | `string \| undefined` | |
+| `schema` | `{ ~standard: StandardSchemaV1Props<unknown, Input> } \| undefined` | Checks each cue's `value` where it's read. Cues whose value fails are skipped. |
+
+### With Type
+
+`defineTextTrack<Value = unknown>(init): TextTrackDefinition<MediaTextCue<Value>>`
+
+Define a text track whose cues carry a `value` of a given type. The type is not checked at runtime; pass a `schema` for that.
+
+`const quizTrack = defineTextTrack<Quiz>({ kind: 'metadata', label: 'quiz' });`
+
+#### Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `init` (required) | `{ kind: 'subtitles' \| 'captions' \| 'descriptions' \| 'chapters' \| 'metadata'; label?: string; language?: string }` | — | The track's kind, and optionally its label and language. |
+
+#### Return Value
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `kind` | `'subtitles' \| 'captions' \| 'descriptions' \| 'chapters' \| 'metadata'` | |
+| `label` | `string \| undefined` | |
+| `language` | `string \| undefined` | |
+| `schema` | `{ ~standard: StandardSchemaV1Props<unknown, Input> } \| undefined` | Checks each cue's `value` where it's read. Cues whose value fails are skipped. |