feat(media): one sound at a time across route videos, radio and audio tracks

Playing a route video pauses the header radio and the audio tracks, and
playing either of those pauses the video (site.mediaExclusivePlayback,
default true). A route video with video.muted plays only the picture and
stays out of the rule.

- shared/lib/media-playback: page-wide playback arbiter (moved from
  features/audio-player, which re-exports it)
- features/video-playback: per-source controllers (YouTube IFrame Player
  API, Vimeo postMessage protocol, native media, generic iframe focus),
  embed playback params and useVideoPlayback
- content containers: shared header text, card title/description, frame
  props and container style; md-container renders one branch
- route-builders: shared text and frame defaults (output unchanged)
- docs: README "Media playback", functionalities pages (en/pt/es),
  frontend README; e2e/media-playback.spec.ts

Author: Vidigal-code

README.md

@@ -22,6 +22,7 @@ It does **not** generate `index.html` or `index.js`.
 - [Scripts](#scripts)
 - [URL Routes and Query Parameters](#url-routes-and-query-parameters)
 - [Video routes](#video-routes)
+- [Media playback](#media-playback)
 - [Authorized Routes](#authorized-routes)
 - [CLI Options](#cli-options)
 - [AI CLI (interactive docs generator)](#ai-cli-interactive-docs-generator)
@@ -559,6 +560,46 @@ Route definition in `gitpagedocs/docs/versions/0.0.7/config.json`:
 }
 ```
 
+## Media playback
+
+Only one sound plays at a time. With `site.mediaExclusivePlayback` (default `true` in
+`gitpagedocs/config.json`):
+
+| Starts playing | Is paused |
+| --- | --- |
+| a route video | the header radio and the audio tracks |
+| the header radio | the route video and the audio tracks |
+| an audio track | the route video and the header radio |
+
+How each video source is followed and paused:
+
+| Source (`video.videoType`) | Detects play | Pauses |
+| --- | --- | --- |
+| `youtube` | official YouTube IFrame Player API (`enablejsapi=1`, state `PLAYING`) | `pauseVideo()` |
+| `vimeo` | Vimeo player `postMessage` protocol (`play` event) | `pause` method |
+| `mp4`, `webm`, `ogg`, … (native) | the element's `play` event | `pause()` |
+| any other embed (`tiktok`, `instagram`, …) | focus moving into the player | reloads the embed |
+
+Customizing:
+
+- **Video with the picture only** — set `"muted": true` in a route's `video` object. The video starts
+  without sound (YouTube `mute=1`, Vimeo `muted=1`, native `muted`) and stays out of the rule, so it
+  can run while the radio or an audio track explains it:
+
+  ```json
+  {
+    "id": 5,
+    "video": {
+      "videoType": { "en": "youtube" },
+      "pathVideo": { "en": "r8jQ9hVA2qs" },
+      "muted": true
+    }
+  }
+  ```
+
+- **No rule at all** — `"mediaExclusivePlayback": false` in `site` lets every player run freely (the
+  radio and the audio tracks still pause each other, as before).
+
 ## Authorized Routes
 
 Route authorization is configured per version in:

cli/builders/route-builders.mjs

@@ -1,21 +1,49 @@
 /** Build route objects for md, html, and video content types */
 
+/** Title/description styling every content route starts from (key order is part of the output). */
+const ROUTE_TEXT_DEFAULTS = {
+  titleCss: "font-size: 1.85rem; font-weight: 700;",
+  titleDarkCss: "font-size: 1.85rem; font-weight: 700; color: var(--text);",
+  titleLightCss: "font-size: 1.85rem; font-weight: 700; color: var(--text);",
+  titlePosition: "center",
+  titleIsVisible: true,
+  descriptionCss: "font-size: 1.2rem; font-weight: 500;",
+  descriptionDarkCss: "font-size: 1.2rem; font-weight: 500; color: var(--text-secondary);",
+  descriptionLightCss: "font-size: 1.2rem; font-weight: 500; color: var(--text-secondary);",
+  descriptionPosition: "center",
+  descriptionIsVisible: true,
+};
+
+/** Container frame settings every content route starts from. */
+const ROUTE_FRAME_DEFAULTS = {
+  fullscreenEnabled: true,
+  marginTop: "",
+  marginBottom: "",
+  blockLink: true,
+};
+
+/** Each default key, taking the option value when it is set. */
+function withDefaults(defaults, options) {
+  return Object.fromEntries(
+    Object.entries(defaults).map(([key, value]) => [key, options[key] === undefined ? value : options[key]]),
+  );
+}
+
+/** A single value becomes the same value for every language. */
+function perLanguage(value) {
+  return typeof value === "string" ? { pt: value, en: value, es: value } : value;
+}
+
+/** Copies only the fields that are set. */
+function assignDefined(target, fields) {
+  for (const [key, value] of Object.entries(fields)) {
+    if (value !== undefined) target[key] = value;
+  }
+  return target;
+}
+
 export function buildMdRoute(versionId, routeId, pathByLang, titles, descriptions, options = {}) {
   const {
-    titleCss = "font-size: 1.85rem; font-weight: 700;",
-    titleDarkCss = "font-size: 1.85rem; font-weight: 700; color: var(--text);",
-    titleLightCss = "font-size: 1.85rem; font-weight: 700; color: var(--text);",
-    titlePosition = "center",
-    titleIsVisible = true,
-    descriptionCss = "font-size: 1.2rem; font-weight: 500;",
-    descriptionDarkCss = "font-size: 1.2rem; font-weight: 500; color: var(--text-secondary);",
-    descriptionLightCss = "font-size: 1.2rem; font-weight: 500; color: var(--text-secondary);",
-    descriptionPosition = "center",
-    descriptionIsVisible = true,
-    fullscreenEnabled = true,
-    marginTop = "",
-    marginBottom = "",
-    blockLink = true,
     container,
     browseAll = false,
     RouteguideBrand = true,
@@ -30,33 +58,17 @@ export function buildMdRoute(versionId, routeId, pathByLang, titles, description
     id: routeId,
     title: titles ?? { pt: "Documentação", en: "Documentation", es: "Documentación" },
     description: descriptions ?? { pt: "Descrição da página", en: "Page description", es: "Descripción de la página" },
-    titleCss,
-    titleDarkCss,
-    titleLightCss,
-    titlePosition,
-    titleIsVisible,
-    descriptionCss,
-    descriptionDarkCss,
-    descriptionLightCss,
-    descriptionPosition,
-    descriptionIsVisible,
+    ...withDefaults(ROUTE_TEXT_DEFAULTS, options),
     path: pathByLang,
-    fullscreenEnabled,
-    marginTop,
-    marginBottom,
-    blockLink,
+    ...withDefaults(ROUTE_FRAME_DEFAULTS, options),
     container,
     browseAll,
     RouteguideBrand,
     RouteGuideSpeciFicbrand,
     RouteguideBrandPosition,
     RouteguideBrandContainerTop,
   };
-  if (container !== undefined) out.container = container;
-  if (audio !== undefined) out.audio = audio;
-  if (authorization !== undefined) out.authorization = authorization;
-  if (hierarchyPage !== undefined) out.hierarchyPage = hierarchyPage;
-  return out;
+  return assignDefined(out, { container, audio, authorization, hierarchyPage });
 }
 
 export function buildHtmlRoute(versionId, routeId, pathByLang, titles, descriptions, options = {}) {
@@ -65,61 +77,25 @@ export function buildHtmlRoute(versionId, routeId, pathByLang, titles, descripti
 }
 
 export function buildVideoRoute(versionId, routeId, videoType, pathVideo, titles, descriptions, options = {}) {
-  const {
-    titleCss = "font-size: 1.85rem; font-weight: 700;",
-    titleDarkCss = "font-size: 1.85rem; font-weight: 700; color: var(--text);",
-    titleLightCss = "font-size: 1.85rem; font-weight: 700; color: var(--text);",
-    titlePosition = "center",
-    titleIsVisible = true,
-    descriptionCss = "font-size: 1.2rem; font-weight: 500;",
-    descriptionDarkCss = "font-size: 1.2rem; font-weight: 500; color: var(--text-secondary);",
-    descriptionLightCss = "font-size: 1.2rem; font-weight: 500; color: var(--text-secondary);",
-    descriptionPosition = "center",
-    descriptionIsVisible = true,
-    fullscreenEnabled = true,
-    marginTop = "",
-    marginBottom = "",
-    blockLink = true,
-    container,
-    browseAll = false,
-    authorization,
-  } = options;
-  const videoTypeByLang = typeof videoType === "string" ? { pt: videoType, en: videoType, es: videoType } : videoType;
-  const pathVideoByLang = typeof pathVideo === "string" ? { pt: pathVideo, en: pathVideo, es: pathVideo } : pathVideo;
+  const { container, browseAll = false, authorization } = options;
   const obj = {
     id: routeId,
     title: titles ?? { pt: "Vídeo", en: "Video", es: "Vídeo" },
     description: descriptions ?? { pt: "Descrição do vídeo", en: "Video description", es: "Descripción del vídeo" },
-    titleCss,
-    titleDarkCss,
-    titleLightCss,
-    titlePosition,
-    titleIsVisible,
-    descriptionCss,
-    descriptionDarkCss,
-    descriptionLightCss,
-    descriptionPosition,
-    descriptionIsVisible,
-    fullscreenEnabled,
-    marginTop,
-    marginBottom,
-    blockLink,
+    ...withDefaults(ROUTE_TEXT_DEFAULTS, options),
+    ...withDefaults(ROUTE_FRAME_DEFAULTS, options),
     browseAll,
-    video: { videoType: videoTypeByLang, pathVideo: pathVideoByLang },
+    video: { videoType: perLanguage(videoType), pathVideo: perLanguage(pathVideo) },
   };
-  if (container !== undefined) obj.container = container;
-  if (authorization !== undefined) obj.authorization = authorization;
-  return obj;
+  return assignDefined(obj, { container, authorization });
 }
 
 export function buildAudioRoute(versionId, routeId, audioType, pathAudio, titles, descriptions, options = {}) {
   const base = buildVideoRoute(versionId, routeId, audioType, pathAudio, titles, descriptions, options);
-  const audioTypeByLang = typeof audioType === "string" ? { pt: audioType, en: audioType, es: audioType } : audioType;
-  const pathAudioByLang = typeof pathAudio === "string" ? { pt: pathAudio, en: pathAudio, es: pathAudio } : pathAudio;
   const { video, ...rest } = base;
   return {
     ...rest,
-    audio: { audioType: audioTypeByLang, pathAudio: pathAudioByLang },
+    audio: { audioType: perLanguage(audioType), pathAudio: perLanguage(pathAudio) },
   };
 }
 

cli/content/docs-en.mjs

@@ -181,6 +181,12 @@ The version config can render a **Source code** container through \`routes-sourc
 - \`ProjectLink\`, \`layoutsConfigPathOficial\`, \`layoutsConfigPath\`
 - Languages: \`site.languages\` (enable/disable each one); UI strings: \`gitpagedocs/langs/<lang>.json\`
 
+## Media playback (one sound at a time)
+
+\`site.mediaExclusivePlayback\` (default \`true\`): playing a route video pauses the radio and the audio tracks, and playing the radio or an audio track pauses the video. It works with YouTube and Vimeo (through their player APIs), native files (\`mp4\`, \`webm\`, …) and any other embed.
+
+To show a video without sound while the radio or an audio track explains it, set \`"muted": true\` in that route's \`video\` object: the video plays only the picture and stays out of the rule. \`"mediaExclusivePlayback": false\` turns the rule off for the whole site.
+
 ## Environment variables
 
 - \`GITPAGEDOCS_REPOSITORY_SEARCH\` – repository search (local)

cli/content/docs-es.mjs

@@ -174,6 +174,12 @@ El config de version puede renderizar un contenedor **Codigo fuente** via \`rout
 - \`ProjectLink\`, \`layoutsConfigPathOficial\`, \`layoutsConfigPath\`
 - Idiomas: \`site.languages\` (activa/desactiva cada uno); textos de la UI: \`gitpagedocs/langs/<lang>.json\`
 
+## Reproduccion de medios (un sonido a la vez)
+
+\`site.mediaExclusivePlayback\` (por defecto \`true\`): reproducir un video de ruta pausa la radio y las pistas de audio, y reproducir la radio o una pista de audio pausa el video. Funciona con YouTube y Vimeo (mediante las APIs de sus reproductores), archivos nativos (\`mp4\`, \`webm\`, …) y cualquier otro embed.
+
+Para mostrar un video sin sonido mientras la radio o una pista de audio lo explica, usa \`"muted": true\` en el objeto \`video\` de la ruta: el video reproduce solo la imagen y queda fuera de la regla. \`"mediaExclusivePlayback": false\` desactiva la regla en todo el sitio.
+
 ## Variables de entorno
 
 - \`GITPAGEDOCS_REPOSITORY_SEARCH\` – busqueda de repositorio (local)

cli/content/docs-pt.mjs

@@ -174,6 +174,12 @@ O config da versao pode renderizar um container **Codigo fonte** via \`routes-so
 - \`ProjectLink\`, \`layoutsConfigPathOficial\`, \`layoutsConfigPath\`
 - Idiomas: \`site.languages\` (liga/desliga cada um); textos da UI: \`gitpagedocs/langs/<lang>.json\`
 
+## Reproducao de midia (um som por vez)
+
+\`site.mediaExclusivePlayback\` (padrao \`true\`): dar play num video de rota pausa o radio e as trilhas de audio, e dar play no radio ou numa trilha de audio pausa o video. Funciona com YouTube e Vimeo (pelas APIs dos players), arquivos nativos (\`mp4\`, \`webm\`, …) e qualquer outro embed.
+
+Para mostrar um video sem som enquanto o radio ou uma trilha de audio o explica, use \`"muted": true\` no objeto \`video\` da rota: o video roda so a imagem e fica fora da regra. \`"mediaExclusivePlayback": false\` desliga a regra no site inteiro.
+
 ## Variaveis de ambiente
 
 - \`GITPAGEDOCS_REPOSITORY_SEARCH\` – busca de repositorio (local)

cli/data/default-site-config.mjs

@@ -138,6 +138,7 @@ export function getDefaultSiteConfig(projectLink, languageToggles = buildLanguag
         audioSequentialPlayback: false,
         audioPopoverHideSource: false,
         audioPopoverShowMinutes: true,
+        mediaExclusivePlayback: true,
         AiChatAutoLockSeconds: 30,
         audioTracks: [
             {

e2e/media-playback.spec.ts

@@ -0,0 +1,54 @@
+import { test, expect, type FrameLocator, type Locator, type Page } from "@playwright/test";
+
+/**
+ * `site.mediaExclusivePlayback` (default true): a route video and the header
+ * "radio" never sound together. The Introduction to Git page shows a YouTube
+ * route video above its markdown; the radio plays through a YouTube embed, so
+ * "radio playing" is observable as its mounted iframe and the video state as
+ * the YouTube player's `playing-mode` / `paused-mode` class. Needs network
+ * access to youtube.com.
+ */
+const VIDEO_PAGE_ID = 5;
+const YOUTUBE_TIMEOUT_MS = 30_000;
+
+const backgroundMedia = 'iframe[title="Background audio"]';
+const routeVideo = '[data-testid="route-video"]';
+
+async function startBackgroundRadio(page: Page): Promise<void> {
+  await page.locator('[data-testid="audio-player-toggle"]:visible').first().click();
+  const option = page.getByTestId("audio-track-option").first();
+  if (await option.isVisible()) await option.click();
+}
+
+function youtubePlayer(page: Page): Locator {
+  const frame: FrameLocator = page.frameLocator(routeVideo);
+  return frame.locator(".html5-video-player");
+}
+
+// Embedded players start from script calls, which headless Chromium blocks without this policy.
+test.use({ launchOptions: { args: ["--autoplay-policy=no-user-gesture-required"] } });
+
+test.describe("media playback", () => {
+  test.beforeEach(async ({ page }) => {
+    await page.setViewportSize({ width: 1280, height: 900 });
+  });
+
+  test("playing the video pauses the radio, and playing the radio pauses the video", async ({ page }) => {
+    await page.goto(`/?menu=en&id=${VIDEO_PAGE_ID}`);
+    // The origin arrives after hydration; then the IFrame API attaches and renames the iframe.
+    await expect(page.locator(routeVideo)).toHaveAttribute("src", /enablejsapi=1&origin=/);
+    await expect(page.locator(routeVideo)).not.toHaveAttribute("title", "Video embed", { timeout: YOUTUBE_TIMEOUT_MS });
+    await expect(youtubePlayer(page)).toBeVisible({ timeout: YOUTUBE_TIMEOUT_MS });
+
+    await startBackgroundRadio(page);
+    await expect(page.locator(backgroundMedia)).toHaveCount(1);
+
+    await page.locator(routeVideo).click();
+    await expect(youtubePlayer(page)).toHaveClass(/playing-mode/, { timeout: YOUTUBE_TIMEOUT_MS });
+    await expect(page.locator(backgroundMedia)).toHaveCount(0);
+
+    await startBackgroundRadio(page);
+    await expect(page.locator(backgroundMedia)).toHaveCount(1);
+    await expect(youtubePlayer(page)).toHaveClass(/paused-mode/, { timeout: YOUTUBE_TIMEOUT_MS });
+  });
+});

frontend/README.md

@@ -32,11 +32,11 @@ frontend/
     |-- page-slices/          # page compositions: docs-route, introduction-guide, source-viewer
     |-- widgets/              # docs-shell, ai-chat-drawer (+ inactivity-lock-dialog), repository-source-browser,
     |                         #   search-shell-header, search-shell-layout, not-found-shell
-    |-- features/             # ask-ai, ai-console, audio-player, docs-access, route-authorization, route-guide,
+    |-- features/             # ask-ai, ai-console, audio-player, video-playback, docs-access, route-authorization, route-guide,
     |                         #   language/theme/version selectors, quick-navigation, repository-search-form,
     |                         #   source-viewer-link, source-viewer-search, source-code-highlight, …
     |-- entities/             # docs (config/content/embed/layouts/theme), source-viewer
-    `-- shared/               # ui (dropdown-selector, selection-dialog, confirm-popup, …), lib, config, api
+    `-- shared/               # ui (dropdown-selector, selection-dialog, confirm-popup, …), lib (media-playback, …), config, api
 ```
 
 FSD import direction is enforced by the root `eslint.config.mjs` (`app → page-slices → widgets → features → entities → shared`).
@@ -71,6 +71,21 @@ When `site.docsAccess.enabled` is set in `gitpagedocs/config.json` (via the `git
 - `GuideHero` enters with Motion variants: rows focus in with a stagger, and the title splits into grapheme glyphs (`model/hero-motion.ts`) that rise in while a visually hidden copy keeps the heading readable as one name. Each row drifts at its own `HERO_PARALLAX.depthPx` as the hero scrolls away.
 - `GuideStory` (`ui/story/`) is a scroll-driven tour placed before the full guide. The section is one viewport tall per chapter and a sticky stage plays one chapter per slice of the page's own scroll (wheel, touch, keyboard and scrollbar keep working). Each chapter's numeral, headline and details move at different depths; the keyframes come from `chapterTimeline` in `model/story.ts` and run through function-form `useTransform` with `interpolate`, because the range form hands opacity to the native scroll timeline, which left the first chapter half visible. A rail jumps to any chapter, a skip link goes straight to the full guide, and with reduced motion the tour still crossfades while CSS pins every layer in place.
 
+## Media playback
+
+`shared/lib/media-playback` holds the page-wide playback arbiter: every player registers a `pause`
+and calls `claim` before it starts, which pauses all the others. The radio and the audio tracks
+(`features/audio-player`) and the route videos (`features/video-playback`) use it, so with
+`site.mediaExclusivePlayback` (default `true`) only one of them sounds at a time.
+
+`features/video-playback` picks a controller per source (`resolveVideoProvider`): the official YouTube
+IFrame Player API attached to the existing iframe (`enablejsapi=1&origin=…`; it falls back to the
+generic rule if the script cannot load), the Vimeo player `postMessage` protocol, the native media
+`play` event, or, for any other embed, focus moving into the iframe (paused by reloading it).
+`useVideoPlayback` wires the controller to the arbiter and rebuilds it when the source changes; the
+page origin comes from `usePageOrigin`, empty in the static render so the exported markup stays
+stable. A route video with `video.muted: true` starts without sound and stays out of the rule.
+
 ## Environment
 
 `.env` (frontend-local; copy from `.env.example`):
@@ -95,6 +110,7 @@ PORT=3100 pnpm run test:e2e         # use an alternate port if 3000 is taken
 - `e2e/ai-console.spec.ts` and `e2e/ai-chat-drawer.spec.ts` verify the password gate, encrypted persistence (no plaintext key in `localStorage`), and reload behavior.
 - `e2e/docs.spec.ts` checks the docs home renders with no horizontal overflow.
 - `e2e/audio-playback.spec.ts` covers the audio route's centered fullscreen view and the mutual exclusion between the route player and the header radio.
+- `e2e/media-playback.spec.ts` plays the YouTube route video over the header radio and back (needs network access to youtube.com).
 - `e2e/introduction-guide.spec.ts` checks the guide's backdrop, reveal and layout across light, dark and white-primary themes.
 
 ## Static export notes

frontend/src/entities/docs/model/types/config.ts

@@ -46,6 +46,12 @@ export interface HierarchyConfig {
 export interface VideoRouteConfig {
   videoType: Record<LanguageCode, string>;
   pathVideo: Record<LanguageCode, string>;
+  /**
+   * Plays only the picture (YouTube, Vimeo and native videos start without sound).
+   * A muted video stays out of `site.mediaExclusivePlayback`, so it can run while
+   * the radio or an audio track explains it. Default false.
+   */
+  muted?: boolean;
   /**
    * Optional WebVTT captions per language. When absent the player still renders a
    * captions <track> pointing at the empty `captions/empty.vtt` shipped with the site.