@videojs/html 10.2.0 → 10.4.0

package/docs/guides/google-analytics.md

@@ -0,0 +1,199 @@
+# Track video telemetry with Google Analytics 4
+
+Track video engagement, progress milestones, and playback interactions by adding the Google Analytics extension to a player
+
+Google Analytics 4 (GA4) Enhanced Measurement tracks video engagement and viewer interaction. Add the Google Analytics [extension](./architecture.md) to a player and it monitors whichever media that player is playing, automatically dispatching standard GA4 Enhanced Measurement video events and playback interaction events to `window.dataLayer` and `window.gtag`.
+
+Install the extension alongside the framework façade:
+
+```bash
+pnpm add @videojs/html @videojs/google-analytics
+```
+
+**index.html**
+
+```html
+<video-player>
+  <media-container>
+    <video src="https://example.com/video.mp4"></video>
+    <google-analytics></google-analytics>
+  </media-container>
+</video-player>
+<script type="module">
+  import '@videojs/html/video/player';
+  import '@videojs/html/ui/container';
+  import '@videojs/html/extensions/google-analytics';
+
+  document.querySelector('google-analytics').metadata = { video_title: 'My Video' };
+</script>
+```
+
+### Load from a CDN
+
+When loading Video.js from a CDN, include the `extensions/google-analytics.js` script tag:
+
+**index.html**
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn/video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn/extensions/google-analytics.js"></script>
+
+<video-player>
+  <media-container>
+    <video src="https://example.com/video.mp4"></video>
+    <google-analytics></google-analytics>
+  </media-container>
+</video-player>
+<script type="module">
+  document.querySelector('google-analytics').metadata = { video_title: 'My Video' };
+</script>
+```
+
+That’s the entire setup for standard video tracking. The extension renders nothing; place it anywhere inside the player.
+
+> **Note**
+>
+> Google Analytics tracking is opt-in. No media component sends telemetry on its own until you add the extension to the player.
+
+## How events are reported
+
+When Google Tag (`gtag.js`) or Google Tag Manager (GTM) is configured on your site, `window.dataLayer` is available globally. The extension pushes structured event objects into `window.dataLayer`:
+
+```js
+window.dataLayer.push({
+  event: 'video_progress',
+  video_current_time: 30,
+  video_duration: 120,
+  video_percent: 25,
+  video_provider: 'video.js',
+  video_stream_type: 'on-demand',
+  video_title: 'My Video',
+  video_url: 'https://example.com/video.mp4',
+  visible: true,
+});
+```
+
+If `window.gtag` is defined, the extension also calls `window.gtag('event', event, params)` with the same parameters. If you use a custom data layer array on `window`, specify its property name with `dataLayerName` (or `data-layer-name` in HTML).
+
+### GA4 Enhanced Measurement events
+
+The extension dispatches standard GA4 Enhanced Measurement video events:
+
+- `video_start`: Dispatched when playback begins for the first time or starts at `currentTime > 0`.
+- `video_progress`: Dispatched when playback crosses 10%, 25%, 50%, and 75% milestones.
+- `video_complete`: Dispatched when the video reaches the end (`ended` event) or loops back to the start.
+
+### Video.js interaction events
+
+In addition to GA4 Enhanced Measurement events, the extension emits player interaction events to measure how viewers engage with controls:
+
+- `play`: Dispatched on first play.
+- `pause`: Dispatched when playback is paused (not triggered during seeking or when ended).
+- `resume`: Dispatched when playback resumes after a pause.
+- `end`: Dispatched when the video finishes.
+- `seek`: Dispatched when scrubbing or seeking completes (bypassed on loop restarts).
+- `mute`: Dispatched when audio is muted or volume drops to 0.
+- `unmute`: Dispatched when audio is unmuted with non-zero volume.
+- `fullscreenEnter`: Dispatched when entering fullscreen.
+- `fullscreenExit`: Dispatched when exiting fullscreen.
+
+## Set stream type
+
+By default, the stream type is inferred from the media (`media.streamType === 'live' ? 'live' : 'on-demand'`). For on-demand videos, duration is known and the extension calculates playback percentage to fire progress milestones at 10%, 25%, 50%, and 75%.
+
+To override or explicitly specify a live stream, pass `video_stream_type: 'live'` in `metadata`:
+
+```html
+<google-analytics></google-analytics>
+<script type="module">
+  const ga = document.querySelector('google-analytics');
+  ga.metadata = { video_title: 'Live Stream', video_stream_type: 'live' };
+</script>
+```
+
+When the effective stream type is `'live'`, milestone progress tracking is bypassed since live streams have unbounded or dynamic duration.
+
+## Disable progress tracking
+
+By default, the extension tracks progress milestones at 10%, 25%, 50%, and 75% for on-demand playback. To turn off milestone progress tracking, set `disableProgress` (or `disable-progress` in HTML):
+
+```html
+<google-analytics disable-progress></google-analytics>
+```
+
+## Set video title
+
+Set `metadata.video_title` on the extension so GA4 gets an explicit title for every media type, including iframe embeds that do not expose a useful DOM `title`.
+
+```html
+<google-analytics></google-analytics>
+<script type="module">
+  const ga = document.querySelector('google-analytics');
+  ga.metadata = { video_title: 'Keynote Presentation' };
+</script>
+```
+
+When `metadata.video_title` is omitted, the extension derives a title in this order: the title the media reports in its content data (Mux, Vimeo, and SoundCloud media report one, for example), then the resolved `video_url`, then `'Untitled Video'`. Do not rely on a `<video title="...">` attribute as your analytics title; set `metadata.video_title` instead.
+
+## Metadata and custom dimensions
+
+Pass `metadata` to set official GA4 video parameters (`video_title`, `video_provider`, `video_url`) and custom dimensions (such as Mux Data compatible names `video_id`, `video_series`, `video_producer`, `video_content_type`, or custom dimensions like `custom_1`):
+
+```html
+<google-analytics></google-analytics>
+<script type="module">
+  const ga = document.querySelector('google-analytics');
+  ga.metadata = {
+    video_title: 'Keynote Presentation',
+    video_series: 'Annual Conference',
+    video_producer: 'Video.js Team',
+    video_id: 'conf_2026_01',
+    custom_1: 'attendee_pro',
+  };
+</script>
+```
+
+### GA4 collection limits
+
+Google Analytics 4 enforces collection limits on event parameters:
+
+- **25 parameters per event**: The extension sends 8 standard parameters (`video_current_time`, `video_duration`, `video_percent`, `video_provider`, `video_stream_type`, `video_title`, `video_url`, and `visible`), leaving room for up to 17 custom dimensions in `metadata`.
+- **Parameter names**: Up to 40 characters in length.
+- **String values**: Up to 100 characters in length.
+
+## Debugging
+
+Enable console logging by setting the `debug` option:
+
+```html
+<google-analytics debug></google-analytics>
+```
+
+When enabled, the extension logs every dispatched event and its parameters:
+
+```plaintext
+[GoogleAnalyticsExtension] Event: "video_start" {video_current_time: 0, video_duration: 120, ...}
+```
+
+You can also provide an `onEvent` callback to intercept dispatched events programmatically:
+
+```html
+<google-analytics></google-analytics>
+<script type="module">
+  const ga = document.querySelector('google-analytics');
+  ga.onEvent = (event, params) => {
+    console.log('Telemetry event:', event, params);
+  };
+</script>
+```
+
+## Related pages
+
+### Components
+
+- [google-analytics](../reference/components/google-analytics.md): Options for the Google Analytics 4 extension that tracks video engagement and playback events
+- [mux-data](../reference/components/mux-data.md): Options for the Mux Data extension that monitors playback quality
+
+### Guides
+
+- [Monitor playback with Mux Data](./mux-data.md): Measure startup time, rebuffering, failures, and watch time by adding the Mux Data extension to a player

package/docs/guides/installation-cdn.md

@@ -30,7 +30,7 @@ npx @videojs/cli agents init
 
 - `project`: Whether to adapt the current project or scaffold a new one. New projects need a named app setup. Values: `new`, `existing`. Default: existing.
 - `preset`: The player configuration and control set. Values: `video`, `audio`, `live-video`, `live-audio`, `background-video`. Default: video.
-- `skin`: The visual skin. Neutral has cleaner surfaces and the same controls as Default. Values: `default`, `neutral`, `compat`, `scaffold`, `none`. Default: default. Applies when preset is not background-video.
+- `skin`: The visual skin. Neutral has cleaner surfaces and the same controls as Default. Compat has plain, unbranded surfaces. Scaffold has minimal styling meant to be restyled. Values: `default`, `neutral`, `compat`, `scaffold`, `none`. Default: default. Applies when preset is not background-video.
 - `media`: The media source or playback adapter. See the preset compatibility map below. Values: `background-video`, `hls-background-video`, `cloudflare`, `dash`, `hls`, `html5-audio`, `html5-video`, `mux-audio`, `mux-background-video`, `mux-video`, `spotify`, `tiktok`, `twitch`, `vimeo`, `youtube`. Default: the selected preset's first compatible media source.
 - `extensions`: A comma-separated list of optional player extensions compatible with the selected player. Pass `none` when no extension is needed. Values: `none`, `google-cast`, `mux-data`. Default: mux-data for Mux media; none otherwise (reported as defaulted).
 - `source-url`: The http:// or https:// media URL placed in the generated player example. Pass `demo` to choose the Video.js demo source for the selected media explicitly. Default: the Video.js demo source for the selected media (reported as defaulted).
@@ -44,7 +44,7 @@ Run the command above without flags to see the corresponding CLI flags for every
 1. **Inspect the project.** Read package.json, framework config, and lockfiles to infer the framework, app setup, and package manager. React installs @videojs/react; HTML, Vue, and Svelte install @videojs/html.
 2. **Choose the starting point.** Use existing when adapting a compatible project. Use new only when the user wants a new app or the intended workspace has no app. Confirm the choice when the workspace and request do not make it clear.
 3. **Choose the player.** Use video unless the request signals another experience: audio, music, or podcasts use audio; a live stream uses live-video or live-audio; a muted, looping decorative video uses background-video. Ask only when those signals conflict.
-4. **Choose the skin.** Use default unless the request asks for a minimal, cleaner, or more subtle look, which uses neutral; both contain the same controls. Use none only when the project builds its own controls. Ask only when those signals conflict.
+4. **Choose the skin.** Use default unless the request signals another look. Use neutral to apply a brand to a finished design, or for a minimal, cleaner, or more subtle look (it was formerly named minimal); it has the same controls as default. Use compat for plain, unbranded controls that blend into content pages, a step above native controls. Use scaffold when the user wants an unbranded foundation to make their own, such as shadcn-style components they restyle; it has the same controls as compat with minimal styling, meant to be restyled rather than used as is. All four support the same browsers. Use none only when the project builds its own controls. Ask only when those signals conflict.
 5. **Choose the media.** Infer the adapter from the source when possible. Mux wins for Mux playback URLs: stream.mux.com/\<playback-id>.m3u8 or a bare playback ID uses mux-video, mux-audio, or mux-background-video rather than hls. Mux static renditions such as .mp4 or .m4a files use html5-video or html5-audio. Other .m3u8 URLs use hls.
 6. **Choose extensions.** Mux Data is included by default for Mux video and audio sources. Add Google Cast when a standard or live video player with a ready-made skin should cast a compatible source. Use none when no extension is needed.
 7. **Choose how to install.** This guide uses CDN scripts for plain HTML. Use an existing page when one is available, and scaffold a minimal Vite app only when no app exists.
@@ -89,7 +89,7 @@ Defaulted options: project, preset, skin, source-url, media, extensions, templat
 ## Reproduce or change these instructions
 
 ```sh
-npx @videojs/cli@10.2.0 agents init --method cdn --framework html --project existing --preset video --skin default --media html5-video --extensions none --source-url https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4 --template none
+npx @videojs/cli@10.4.0 agents init --method cdn --framework html --project existing --preset video --skin default --media html5-video --extensions none --source-url https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4 --template none
 ```
 
 ## Load Video.js
@@ -101,7 +101,7 @@ Add these module scripts to the page head. Module scripts are deferred, so they
 _Merge this into the page `<head>`._
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/video.js"></script>
 ```
 
 ## Add your player

package/docs/guides/installation-shadcn.md

@@ -31,7 +31,7 @@ npx @videojs/cli agents init
 - `framework`: The application framework that will host the player. React installs @videojs/react; HTML, Vue, and Svelte install @videojs/html. Values: `react`, `html`. Default: react.
 - `project`: Whether to adapt the current project or scaffold a new one. New projects need a named app setup. Values: `new`, `existing`. Default: existing.
 - `preset`: The player configuration and control set. Values: `video`, `audio`, `live-video`, `live-audio`. Default: video.
-- `skin`: The visual skin. Neutral has cleaner surfaces and the same controls as Default. Values: `default`, `neutral`, `compat`, `scaffold`. Default: default. Applies when preset is not background-video.
+- `skin`: The visual skin. Neutral has cleaner surfaces and the same controls as Default. Compat has plain, unbranded surfaces. Scaffold has minimal styling meant to be restyled. Values: `default`, `neutral`, `compat`, `scaffold`. Default: default. Applies when preset is not background-video.
 - `media`: The media source or playback adapter. See the preset compatibility map below. Values: `background-video`, `hls-background-video`, `cloudflare`, `dash`, `hls`, `html5-audio`, `html5-video`, `mux-audio`, `mux-background-video`, `mux-video`, `spotify`, `tiktok`, `twitch`, `vimeo`, `youtube`. Default: the selected preset's first compatible media source.
 - `extensions`: A comma-separated list of optional player extensions compatible with the selected player. Pass `none` when no extension is needed. Values: `none`, `google-cast`, `mux-data`. Default: mux-data for Mux media; none otherwise (reported as defaulted).
 - `source-url`: The http:// or https:// media URL placed in the generated player example. Pass `demo` to choose the Video.js demo source for the selected media explicitly. Default: the Video.js demo source for the selected media (reported as defaulted).
@@ -46,7 +46,7 @@ Run the command above without flags to see the corresponding CLI flags for every
 1. **Inspect the project.** Read package.json, framework config, and lockfiles to infer the framework, app setup, and package manager. React installs @videojs/react; HTML, Vue, and Svelte install @videojs/html.
 2. **Choose the starting point.** Use existing when adapting a compatible project. Use new only when the user wants a new app or the intended workspace has no app. Confirm the choice when the workspace and request do not make it clear.
 3. **Choose the player.** Use video unless the request signals another experience: audio, music, or podcasts use audio; a live stream uses live-video or live-audio; a muted, looping decorative video uses background-video. Ask only when those signals conflict.
-4. **Choose the skin.** Use default unless the request asks for a minimal, cleaner, or more subtle look, which uses neutral; both contain the same controls. Ask only when those signals conflict.
+4. **Choose the skin.** Use default unless the request signals another look. Use neutral to apply a brand to a finished design, or for a minimal, cleaner, or more subtle look (it was formerly named minimal); it has the same controls as default. Use compat for plain, unbranded controls that blend into content pages, a step above native controls. Use scaffold when the user wants an unbranded foundation to make their own, such as shadcn-style components they restyle; it has the same controls as compat with minimal styling, meant to be restyled rather than used as is. All four support the same browsers. Ask only when those signals conflict.
 5. **Choose the media.** Infer the adapter from the source when possible. Mux wins for Mux playback URLs: stream.mux.com/\<playback-id>.m3u8 or a bare playback ID uses mux-video, mux-audio, or mux-background-video rather than hls. Mux static renditions such as .mp4 or .m4a files use html5-video or html5-audio. Other .m3u8 URLs use hls.
 6. **Choose extensions.** Mux Data is included by default for Mux video and audio sources. Add Google Cast when a standard or live video player with a ready-made skin should cast a compatible source. Use none when no extension is needed.
 7. **Choose how to install.** This guide uses Shadcn to copy editable skin source. React uses the React source catalog; plain HTML uses the HTML source catalog. Vue and Svelte use packaged modules.
@@ -94,7 +94,7 @@ Defaulted options: project, preset, skin, source-url, media, extensions, templat
 ## Reproduce or change these instructions
 
 ```sh
-npx @videojs/cli@10.2.0 agents init --method shadcn --framework html --project existing --preset video --skin default --media html5-video --extensions none --source-url https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4 --package-manager pnpm --template vite --styling css
+npx @videojs/cli@10.4.0 agents init --method shadcn --framework html --project existing --preset video --skin default --media html5-video --extensions none --source-url https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4 --package-manager pnpm --template vite --styling css
 ```
 
 ## Configure app aliases

package/docs/guides/installation-svelte.md

@@ -30,7 +30,7 @@ npx @videojs/cli agents init
 
 - `project`: Whether to adapt the current project or scaffold a new one. New projects need a named app setup. Values: `new`, `existing`. Default: existing.
 - `preset`: The player configuration and control set. Values: `video`, `audio`, `live-video`, `live-audio`, `background-video`. Default: video.
-- `skin`: The visual skin. Neutral has cleaner surfaces and the same controls as Default. Values: `default`, `neutral`, `compat`, `scaffold`, `none`. Default: default. Applies when preset is not background-video.
+- `skin`: The visual skin. Neutral has cleaner surfaces and the same controls as Default. Compat has plain, unbranded surfaces. Scaffold has minimal styling meant to be restyled. Values: `default`, `neutral`, `compat`, `scaffold`, `none`. Default: default. Applies when preset is not background-video.
 - `media`: The media source or playback adapter. See the preset compatibility map below. Values: `background-video`, `hls-background-video`, `cloudflare`, `dash`, `hls`, `html5-audio`, `html5-video`, `mux-audio`, `mux-background-video`, `mux-video`, `spotify`, `tiktok`, `twitch`, `vimeo`, `youtube`. Default: the selected preset's first compatible media source.
 - `extensions`: A comma-separated list of optional player extensions compatible with the selected player. Pass `none` when no extension is needed. Values: `none`, `google-cast`, `mux-data`. Default: mux-data for Mux media; none otherwise (reported as defaulted).
 - `source-url`: The http:// or https:// media URL placed in the generated player example. Pass `demo` to choose the Video.js demo source for the selected media explicitly. Default: the Video.js demo source for the selected media (reported as defaulted).
@@ -44,7 +44,7 @@ Run the command above without flags to see the corresponding CLI flags for every
 1. **Inspect the project.** Read package.json, framework config, and lockfiles to infer the framework, app setup, and package manager. React installs @videojs/react; HTML, Vue, and Svelte install @videojs/html.
 2. **Choose the starting point.** Use existing when adapting a compatible project. Use new only when the user wants a new app or the intended workspace has no app. Confirm the choice when the workspace and request do not make it clear.
 3. **Choose the player.** Use video unless the request signals another experience: audio, music, or podcasts use audio; a live stream uses live-video or live-audio; a muted, looping decorative video uses background-video. Ask only when those signals conflict.
-4. **Choose the skin.** Use default unless the request asks for a minimal, cleaner, or more subtle look, which uses neutral; both contain the same controls. Use none only when the project builds its own controls. Ask only when those signals conflict.
+4. **Choose the skin.** Use default unless the request signals another look. Use neutral to apply a brand to a finished design, or for a minimal, cleaner, or more subtle look (it was formerly named minimal); it has the same controls as default. Use compat for plain, unbranded controls that blend into content pages, a step above native controls. Use scaffold when the user wants an unbranded foundation to make their own, such as shadcn-style components they restyle; it has the same controls as compat with minimal styling, meant to be restyled rather than used as is. All four support the same browsers. Use none only when the project builds its own controls. Ask only when those signals conflict.
 5. **Choose the media.** Infer the adapter from the source when possible. Mux wins for Mux playback URLs: stream.mux.com/\<playback-id>.m3u8 or a bare playback ID uses mux-video, mux-audio, or mux-background-video rather than hls. Mux static renditions such as .mp4 or .m4a files use html5-video or html5-audio. Other .m3u8 URLs use hls.
 6. **Choose extensions.** Mux Data is included by default for Mux video and audio sources. Add Google Cast when a standard or live video player with a ready-made skin should cast a compatible source. Use none when no extension is needed.
 7. **Choose how to install.** This guide uses packaged modules, which need a bundler. Match the package manager to the project lockfile. For an existing HTML site without a build step, use CDN scripts instead.
@@ -90,13 +90,13 @@ Defaulted options: project, preset, skin, source-url, media, extensions, templat
 ## Reproduce or change these instructions
 
 ```sh
-npx @videojs/cli@10.2.0 agents init --method packaged --framework svelte --project existing --preset video --skin default --media html5-video --extensions none --source-url https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4 --package-manager pnpm --template vite
+npx @videojs/cli@10.4.0 agents init --method packaged --framework svelte --project existing --preset video --skin default --media html5-video --extensions none --source-url https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4 --package-manager pnpm --template vite
 ```
 
 ## Install the packages
 
 ```bash
-pnpm add @videojs/html@10.2.0
+pnpm add @videojs/html@10.4.0
 ```
 
 ## Add your player

package/docs/guides/installation-vue.md

@@ -30,7 +30,7 @@ npx @videojs/cli agents init
 
 - `project`: Whether to adapt the current project or scaffold a new one. New projects need a named app setup. Values: `new`, `existing`. Default: existing.
 - `preset`: The player configuration and control set. Values: `video`, `audio`, `live-video`, `live-audio`, `background-video`. Default: video.
-- `skin`: The visual skin. Neutral has cleaner surfaces and the same controls as Default. Values: `default`, `neutral`, `compat`, `scaffold`, `none`. Default: default. Applies when preset is not background-video.
+- `skin`: The visual skin. Neutral has cleaner surfaces and the same controls as Default. Compat has plain, unbranded surfaces. Scaffold has minimal styling meant to be restyled. Values: `default`, `neutral`, `compat`, `scaffold`, `none`. Default: default. Applies when preset is not background-video.
 - `media`: The media source or playback adapter. See the preset compatibility map below. Values: `background-video`, `hls-background-video`, `cloudflare`, `dash`, `hls`, `html5-audio`, `html5-video`, `mux-audio`, `mux-background-video`, `mux-video`, `spotify`, `tiktok`, `twitch`, `vimeo`, `youtube`. Default: the selected preset's first compatible media source.
 - `extensions`: A comma-separated list of optional player extensions compatible with the selected player. Pass `none` when no extension is needed. Values: `none`, `google-cast`, `mux-data`. Default: mux-data for Mux media; none otherwise (reported as defaulted).
 - `source-url`: The http:// or https:// media URL placed in the generated player example. Pass `demo` to choose the Video.js demo source for the selected media explicitly. Default: the Video.js demo source for the selected media (reported as defaulted).
@@ -44,7 +44,7 @@ Run the command above without flags to see the corresponding CLI flags for every
 1. **Inspect the project.** Read package.json, framework config, and lockfiles to infer the framework, app setup, and package manager. React installs @videojs/react; HTML, Vue, and Svelte install @videojs/html.
 2. **Choose the starting point.** Use existing when adapting a compatible project. Use new only when the user wants a new app or the intended workspace has no app. Confirm the choice when the workspace and request do not make it clear.
 3. **Choose the player.** Use video unless the request signals another experience: audio, music, or podcasts use audio; a live stream uses live-video or live-audio; a muted, looping decorative video uses background-video. Ask only when those signals conflict.
-4. **Choose the skin.** Use default unless the request asks for a minimal, cleaner, or more subtle look, which uses neutral; both contain the same controls. Use none only when the project builds its own controls. Ask only when those signals conflict.
+4. **Choose the skin.** Use default unless the request signals another look. Use neutral to apply a brand to a finished design, or for a minimal, cleaner, or more subtle look (it was formerly named minimal); it has the same controls as default. Use compat for plain, unbranded controls that blend into content pages, a step above native controls. Use scaffold when the user wants an unbranded foundation to make their own, such as shadcn-style components they restyle; it has the same controls as compat with minimal styling, meant to be restyled rather than used as is. All four support the same browsers. Use none only when the project builds its own controls. Ask only when those signals conflict.
 5. **Choose the media.** Infer the adapter from the source when possible. Mux wins for Mux playback URLs: stream.mux.com/\<playback-id>.m3u8 or a bare playback ID uses mux-video, mux-audio, or mux-background-video rather than hls. Mux static renditions such as .mp4 or .m4a files use html5-video or html5-audio. Other .m3u8 URLs use hls.
 6. **Choose extensions.** Mux Data is included by default for Mux video and audio sources. Add Google Cast when a standard or live video player with a ready-made skin should cast a compatible source. Use none when no extension is needed.
 7. **Choose how to install.** This guide uses packaged modules, which need a bundler. Match the package manager to the project lockfile. For an existing HTML site without a build step, use CDN scripts instead.
@@ -90,13 +90,13 @@ Defaulted options: project, preset, skin, source-url, media, extensions, templat
 ## Reproduce or change these instructions
 
 ```sh
-npx @videojs/cli@10.2.0 agents init --method packaged --framework vue --project existing --preset video --skin default --media html5-video --extensions none --source-url https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4 --package-manager pnpm --template vite
+npx @videojs/cli@10.4.0 agents init --method packaged --framework vue --project existing --preset video --skin default --media html5-video --extensions none --source-url https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4 --package-manager pnpm --template vite
 ```
 
 ## Install the packages
 
 ```bash
-pnpm add @videojs/html@10.2.0
+pnpm add @videojs/html@10.4.0
 ```
 
 ## Register custom elements

package/docs/guides/installation.md

@@ -30,7 +30,7 @@ npx @videojs/cli agents init
 
 - `project`: Whether to adapt the current project or scaffold a new one. New projects need a named app setup. Values: `new`, `existing`. Default: existing.
 - `preset`: The player configuration and control set. Values: `video`, `audio`, `live-video`, `live-audio`, `background-video`. Default: video.
-- `skin`: The visual skin. Neutral has cleaner surfaces and the same controls as Default. Values: `default`, `neutral`, `compat`, `scaffold`, `none`. Default: default. Applies when preset is not background-video.
+- `skin`: The visual skin. Neutral has cleaner surfaces and the same controls as Default. Compat has plain, unbranded surfaces. Scaffold has minimal styling meant to be restyled. Values: `default`, `neutral`, `compat`, `scaffold`, `none`. Default: default. Applies when preset is not background-video.
 - `media`: The media source or playback adapter. See the preset compatibility map below. Values: `background-video`, `hls-background-video`, `cloudflare`, `dash`, `hls`, `html5-audio`, `html5-video`, `mux-audio`, `mux-background-video`, `mux-video`, `spotify`, `tiktok`, `twitch`, `vimeo`, `youtube`. Default: the selected preset's first compatible media source.
 - `extensions`: A comma-separated list of optional player extensions compatible with the selected player. Pass `none` when no extension is needed. Values: `none`, `google-cast`, `mux-data`. Default: mux-data for Mux media; none otherwise (reported as defaulted).
 - `source-url`: The http:// or https:// media URL placed in the generated player example. Pass `demo` to choose the Video.js demo source for the selected media explicitly. Default: the Video.js demo source for the selected media (reported as defaulted).
@@ -44,7 +44,7 @@ Run the command above without flags to see the corresponding CLI flags for every
 1. **Inspect the project.** Read package.json, framework config, and lockfiles to infer the framework, app setup, and package manager. React installs @videojs/react; HTML, Vue, and Svelte install @videojs/html.
 2. **Choose the starting point.** Use existing when adapting a compatible project. Use new only when the user wants a new app or the intended workspace has no app. Confirm the choice when the workspace and request do not make it clear.
 3. **Choose the player.** Use video unless the request signals another experience: audio, music, or podcasts use audio; a live stream uses live-video or live-audio; a muted, looping decorative video uses background-video. Ask only when those signals conflict.
-4. **Choose the skin.** Use default unless the request asks for a minimal, cleaner, or more subtle look, which uses neutral; both contain the same controls. Use none only when the project builds its own controls. Ask only when those signals conflict.
+4. **Choose the skin.** Use default unless the request signals another look. Use neutral to apply a brand to a finished design, or for a minimal, cleaner, or more subtle look (it was formerly named minimal); it has the same controls as default. Use compat for plain, unbranded controls that blend into content pages, a step above native controls. Use scaffold when the user wants an unbranded foundation to make their own, such as shadcn-style components they restyle; it has the same controls as compat with minimal styling, meant to be restyled rather than used as is. All four support the same browsers. Use none only when the project builds its own controls. Ask only when those signals conflict.
 5. **Choose the media.** Infer the adapter from the source when possible. Mux wins for Mux playback URLs: stream.mux.com/\<playback-id>.m3u8 or a bare playback ID uses mux-video, mux-audio, or mux-background-video rather than hls. Mux static renditions such as .mp4 or .m4a files use html5-video or html5-audio. Other .m3u8 URLs use hls.
 6. **Choose extensions.** Mux Data is included by default for Mux video and audio sources. Add Google Cast when a standard or live video player with a ready-made skin should cast a compatible source. Use none when no extension is needed.
 7. **Choose how to install.** This guide uses packaged modules, which need a bundler. Match the package manager to the project lockfile. For an existing HTML site without a build step, use CDN scripts instead.
@@ -92,13 +92,13 @@ Defaulted options: project, preset, skin, source-url, media, extensions, templat
 ## Reproduce or change these instructions
 
 ```sh
-npx @videojs/cli@10.2.0 agents init --method packaged --framework html --project existing --preset video --skin default --media html5-video --extensions none --source-url https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4 --package-manager pnpm --template vite
+npx @videojs/cli@10.4.0 agents init --method packaged --framework html --project existing --preset video --skin default --media html5-video --extensions none --source-url https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4 --package-manager pnpm --template vite
 ```
 
 ## Install the packages
 
 ```bash
-pnpm add @videojs/html@10.2.0
+pnpm add @videojs/html@10.4.0
 ```
 
 ## Add your player

package/docs/guides/internationalization.md

@@ -199,8 +199,8 @@ import '@videojs/html/i18n/locales/ja/register';
 CDN locale modules call `registerI18n` on import. Pin every URL to the same version:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/locales/es.js"></script>
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/locales/es.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/video.js"></script>
 ```
 
 Use the same pinned version for your locale pack, `i18n.js`, and player script. Copies loaded in the same window share a registry; matching versions keeps their translation keys and APIs compatible. Import the full locale pack before partial overrides, and register before the player loads to translate the first render:
@@ -208,15 +208,15 @@ Use the same pinned version for your locale pack, `i18n.js`, and player script.
 **my-locale.js**
 
 ```js
-import 'https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/locales/es.js';
-import { registerI18n } from 'https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/i18n.js';
+import 'https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/locales/es.js';
+import { registerI18n } from 'https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/i18n.js';
 
 registerI18n('es', { buttons: { play: 'Reproducir', pause: 'Pausa' } });
 ```
 
 ```html
 <script type="module" src="/my-locale.js"></script>
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/video.js"></script>
 ```
 
 ### Switch locale at runtime

package/docs/guides/keyboard-shortcuts.md

@@ -39,7 +39,7 @@ Declare shortcuts with `<media-hotkey>` and gestures with `<media-gesture>` insi
 
 ## How it works
 
-- `<media-hotkey>` binds keys to player actions: `togglePaused`, `toggleMuted`, `toggleFullscreen`, `toggleSubtitles`, `togglePictureInPicture`, `seekStep`, `volumeStep`, `seekToPercent`, `speedUp`, and `speedDown`. `seekStep` and `volumeStep` use a default step unless you pass a custom `value`. These input actions call the feature actions your components use; for example, `toggleFullscreen` chooses `requestFullscreen` or `exitFullscreen` based on `isFullscreen`.
+- `<media-hotkey>` binds keys to player actions: `togglePaused`, `toggleMuted`, `toggleFullscreen`, `toggleSubtitles`, `togglePictureInPicture`, `seekStep`, `volumeStep`, `seekToPercent`, `speedUp`, and `speedDown`. `seekStep` and `volumeStep` use a default step unless you pass a custom `value`. `speedUp` and `speedDown` move through the player’s playback rates, or step by `value` when you pass one. These input actions call the feature actions your components use; for example, `toggleFullscreen` chooses `requestFullscreen` or `exitFullscreen` based on `isFullscreen`.
 - `<media-gesture>` binds `tap` and `doubletap` to the same actions. Gestures also support `toggleControls`; `seekToPercent` is available only to hotkeys. Scope each binding with `pointer` (`mouse` or `touch`) and `region` (`left`, `center`, `right`). For example, a double tap on the left can rewind while a double tap on the right skips forward.
 - `<media-status-announcer>` announces action results to screen readers. The input indicator components show brief on-screen feedback, such as volume level or captions on and off, the way native players do. The packaged skins include both.
 
@@ -73,6 +73,16 @@ How the container splits into regions depends on which regions you bind for the
 
 For a packaged skin, [add the skin source to your project](./customize-skins.md#style-skin-source) and edit its `<media-hotkey>` declarations. Adding another binding alongside the packaged skin does not replace its bindings. For a custom UI, edit your own `<media-hotkey>` set directly.
 
+### Tap to play on touch
+
+The packaged skins toggle controls on a touch tap, and the center play button starts playback. To play and pause with a tap anywhere on the video instead, bind `togglePaused` in place of `toggleControls` for touch:
+
+```html
+<media-gesture type="tap" action="togglePaused" pointer="touch"></media-gesture>
+```
+
+A tap then pauses playback as well, and taps no longer show or hide the controls.
+
 ### Seek step size
 
 Set the `seekStep` distance with `value`. Match it to your content: 5 seconds for short clips, 15 or 30 seconds for long-form video.

package/docs/guides/llms.txt

@@ -1,6 +1,6 @@
 # Video.js v10 — HTML Guides
 
-> Installation, migration, concepts, playback guides, customization, and tooling for Video.js. Bundled with `@videojs/html` v10.2.0. Links are relative paths to files in this directory.
+> Installation, migration, concepts, playback guides, customization, and tooling for Video.js. Bundled with `@videojs/html` v10.4.0. Links are relative paths to files in this directory.
 
 ## Getting Started
 
@@ -57,6 +57,7 @@ Guides for one player capability each: the recommended setup, how it works, brow
 - [Automatically show and hide controls](./controls.md): Show controls while the user is active, hide them during playback, and toggle them by touch.
 - [Add a poster and loading placeholder](./poster.md): Set the image shown before playback, then add a lightweight placeholder while it loads
 - [Show captions and subtitles](./captions.md): Show captions and subtitles, and let users turn them on and pick a language.
+- [Sync content with timed metadata](./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](./keyboard-shortcuts.md): Add keyboard shortcuts, tap and double-tap gestures, and on-screen feedback for input actions.
 - [Play live streams](./live-streams.md): Play live streams with live-edge tracking, DVR windows, and stream-type detection.
 - [Add a quality selector](./quality.md): Read available renditions, let the engine adapt automatically, and offer manual quality selection.
@@ -68,6 +69,7 @@ Guides for one player capability each: the recommended setup, how it works, brow
 - [Remember user preferences](./user-preferences.md): Save volume and caption preferences, restore them after loading, and adapt the pattern for quality selection.
 - [Add a background video](./background-video.md): Add an accessible background video from an MP4, WebM, HLS, or Mux source
 - [Internationalize the player](./internationalization.md): Translate player labels and announcements: shipped locale packs, custom translations, runtime switching, and server rendering.
+- [Track video telemetry with Google Analytics 4](./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](./mux-data.md): Measure startup time, rebuffering, failures, and watch time by adding the Mux Data extension to a player
 
 ## Migrate

package/docs/guides/media-sources.md

@@ -88,9 +88,12 @@ Engine options live under `source.engine`, **namespaced by engine**. Each key th
 | `engine.vimeo` | [`<vimeo-video>`](../reference/components/vimeo-video.md) | [Vimeo embed parameters](https://developer.vimeo.com/player/sdk/embed) |
 | `engine.youtube` | [`<youtube-video>`](../reference/components/youtube-video.md) | [YouTube player parameters](https://developer.chrome.com/docs/youtube/iframe_api_reference#Parameters) |
 | `engine.cloudflare` | [`<cloudflare-video>`](../reference/components/cloudflare-video.md) | [Stream player parameters](https://developers.cloudflare.com/stream/viewing-videos/using-the-stream-player/) |
+| `engine.soundcloud` | [`<soundcloud-audio>`](../reference/components/soundcloud-audio.md) | [SoundCloud Widget parameters](https://developers.soundcloud.com/docs/api/html5-widget#parameters) |
+| `engine.mixcloud` | [`<mixcloud-audio>`](../reference/components/mixcloud-audio.md) | [Mixcloud Widget options](https://www.mixcloud.com/developers/widget/) |
 | `engine.spotify` | [`<spotify-audio>`](../reference/components/spotify-audio.md) | [Spotify embed options](https://developer.spotify.com/documentation/embeds) |
 | `engine.tiktok` | [`<tiktok-video>`](../reference/components/tiktok-video.md) | [TikTok player parameters](https://developers.tiktok.com/doc/embed-player) |
 | `engine.twitch` | [`<twitch-video>`](../reference/components/twitch-video.md) | [Twitch embed parameters](https://dev.twitch.tv/docs/embed/video-and-clips/) |
+| `engine.dailymotion` | [`<dailymotion-video>`](../reference/components/dailymotion-video.md) | a Player ID and [Dailymotion runtime parameters](https://developers.dailymotion.com/reference/web-sdk-player-runtime-parameters) |
 | `engine.playerJs` | [`<playerjs-video>`](../reference/components/playerjs-video.md) | URL parameters for whichever service serves the embed |
 
 Naming the engine rather than using one generic key matters where an element has more than one to choose from. `<hlsjs-video>` plays through hls.js or through the browser depending on the platform and `preferPlayback`, and only one of them runs — so a single source can describe both paths without either engine reading the other’s options.

package/docs/guides/migrate-from-media-chrome.md

@@ -46,14 +46,14 @@ Before loading Video.js HTML, remove every Media Chrome import and CDN script fr
 For a page without a bundler, load the CDN video preset. It registers the player, the UI elements and icons used in the controller example below, and the `<media-i18n>` element:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/video.js"></script>
 ```
 
 Some elements in the mapping table below need separate bundles. If you use any of these elements, also load its bundle:
 
-- `media-seek-button`: `https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/ui/seek-button.js`
-- `media-playback-rate-button`: `https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/ui/playback-rate-button.js`
-- `media-thumbnail`: `https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/ui/thumbnail.js`
+- `media-seek-button`: `https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/ui/seek-button.js`
+- `media-playback-rate-button`: `https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/ui/playback-rate-button.js`
+- `media-thumbnail`: `https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/ui/thumbnail.js`
 
 Load each with `<script type="module" src="…"></script>`. See [CDN](./cdn.md) for individual component bundles.
 

package/docs/guides/migrate-from-mux-player.md

@@ -68,9 +68,9 @@ The examples keep a playback ID, analytics metadata, and a poster from two secon
 From the CDN, load the video [preset](./presets.md), the Mux media, and analytics:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/video.js"></script>
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/media/mux-video.js"></script>
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/extensions/mux-data.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/media/mux-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/extensions/mux-data.js"></script>
 
 <video-player content-title="Test VOD">
   <video-skin style="aspect-ratio: 16 / 9">
@@ -288,7 +288,7 @@ Choose the smallest customization that meets your existing UI requirements: a pa
 
 ### Level 1: pick a skin
 
-Video.js has three packaged skins. The Default skin groups settings in a menu. The Neutral skin has a compact layout like a classic player control bar. The Compat skin uses plain surfaces and basic controls for broader browser support. All three bring controls, tooltips, captions, keyboard shortcuts, touch gestures, and a settings menu that appears when there’s something to put in it. See [Skins](./skins.md).
+Video.js has four packaged skins. The Default skin groups settings in a menu. The Neutral skin has a compact layout like a classic player control bar. The Compat skin has plain, unbranded surfaces with large play and seek buttons in the center. The Scaffold skin has Compat’s controls with minimal styling, as a starting point for your own design. All four bring controls, tooltips, captions, keyboard shortcuts, touch gestures, and a settings menu that appears when there’s something to put in it. See [Choose a skin](./skins.md#choose-a-skin).
 
 ### Level 2: restyle it
 
@@ -421,8 +421,8 @@ Mux Player switches to live controls automatically. In Video.js, choose the live
 Register the live preset and Mux media. From the CDN:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/live-video.js"></script>
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/media/mux-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/live-video.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/media/mux-video.js"></script>
 
 <live-video-player>
   <live-video-skin>
@@ -452,7 +452,7 @@ Use [`createPlayer`](../reference/api/html-create-player.md) to build a player e
 The live skin already includes a live button. If you build your own controls, use that same component and style it to match your app. It keeps track of whether playback is live and returns viewers to the newest available point in the stream.
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.2.0/ui/live-button.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.4.0/ui/live-button.js"></script>
 
 <media-live-button class="station-live-button">On air</media-live-button>
 ```
@@ -502,7 +502,7 @@ The video skins include a settings menu with the available quality, audio-track,
 | Quality | [Quality radio group](../reference/components/quality-radio-group.md) | Lets a viewer pick the video quality. Use `source.playback.maxResolution` to cap the stream’s available resolution; it does not force playback at that resolution. |
 | Audio tracks | [Audio track radio group](../reference/components/audio-track-radio-group.md) | For multi-language audio. |
 | Captions | [Captions radio group](../reference/components/captions-radio-group.md) | Rendered by the browser. |
-| Speed | [Playback rate radio group](../reference/components/playback-rate-radio-group.md) | The rates are a fixed set — `0.2`, `0.5`, `0.7`, `1`, `1.2`, `1.5`, `1.7`, `2` — and you can’t choose your own yet ([#1404](https://github.com/videojs/v10/issues/1404)). |
+| Speed | [Playback rate radio group](../reference/components/playback-rate-radio-group.md) | The rates default to `0.5` through `2` in steps of `0.25`. Set `defaultPlaybackRates` on the player, or `rates` on the radio group, to choose your own; see the [playback rate feature](../reference/api/feature-playback-rate.md). |
 
 When enabling captions without a previous selection in this player instance, `toggleSubtitles()` prefers a track matching `navigator.language`, then falls back to the first available caption or subtitle track. For an authored track that should show on load, add `default`. See [Show captions and subtitles](./captions.md).
 
@@ -575,7 +575,7 @@ Video.js has no Program Date Time (PDT) helpers such as `getStartDate()` or `cur
 
 Check these limitations against your required features:
 
-- The two packaged skins do not reproduce Mux Player’s themes, and there is no runtime theme switch. Plan skin customization when preserving a theme such as `classic`.
+- The packaged skins do not reproduce Mux Player’s themes, and there is no runtime theme switch. Plan skin customization when preserving a theme such as `classic`.
 - Lazy loading (`loading="viewport|page"`) has no equivalent.
 - The controls auto-hide delay isn’t configurable ([#1728](https://github.com/videojs/v10/issues/1728)). For always-visible controls, set `visibility="always"` on the controls component in a custom layout or installed skin source.
 - Player preferences such as volume, captions language, speed, and quality are not persisted automatically ([#944](https://github.com/videojs/v10/issues/944)). Mux users can set `source.playback.defaultSubtitlesLang` so the HLS playlist sets the default subtitle language. For application-managed persistence, follow [Remember user preferences](./user-preferences.md).