feat(player): show example captions text on style change

packages/react/src/components/layouts/default/audio-layout.tsx

@@ -14,13 +14,13 @@ import {
 import { useMediaContext } from '../../../hooks/use-media-context';
 import { useMediaState } from '../../../hooks/use-media-state';
 import { createComputed } from '../../../hooks/use-signals';
-import { Captions } from '../../ui/captions';
 import * as Controls from '../../ui/controls';
 import { useLayoutName } from '../utils';
 import { DefaultLayoutContext, i18n, useDefaultLayoutContext } from './context';
 import { createDefaultMediaLayout, type DefaultLayoutProps } from './media-layout';
 import {
   DefaultCaptionButton,
+  DefaultCaptions,
   DefaultChaptersMenu,
   DefaultControlsSpacer,
   DefaultMuteButton,
@@ -111,7 +111,7 @@ function AudioLayout() {
   const slots = useDefaultAudioLayoutSlots();
   return (
     <>
-      <Captions className="vds-captions" />
+      <DefaultCaptions />
       <Controls.Root className="vds-controls">
         <Controls.Group className="vds-controls-group">
           {slot(slots, 'seekBackwardButton', <DefaultSeekButton backward tooltip="top start" />)}

packages/react/src/components/layouts/default/font-menu.tsx

@@ -278,22 +278,38 @@ function DefaultFontSettingSubmenu({
     return i18n(translations, label);
   }, [value, radioOptions]);
 
-  const onChange = React.useCallback((newValue: string) => {
-    setValue(newValue);
-    localStorage.setItem(`vds-player:${key}`, newValue);
-    player?.el?.style.setProperty(
-      `--media-user-${cssVarName}`,
-      getCssVarValue?.(newValue, player) ?? newValue,
-    );
-  }, []);
+  const update = React.useCallback(
+    (newValue: string) => {
+      setValue(newValue);
+      localStorage.setItem(`vds-player:${key}`, newValue);
+      player?.el?.style.setProperty(
+        `--media-user-${cssVarName}`,
+        getCssVarValue?.(newValue, player) ?? newValue,
+      );
+    },
+    [player],
+  );
+
+  const notify = React.useCallback(() => {
+    player?.dispatchEvent(new Event('vds-font-change'));
+  }, [player]);
+
+  const onChange = React.useCallback(
+    (newValue: string) => {
+      update(newValue);
+      notify();
+    },
+    [update, notify],
+  );
 
   const onReset = React.useCallback(() => {
     setValue(defaultValue);
-  }, []);
+    notify();
+  }, [notify]);
 
   React.useEffect(() => {
     const savedValue = localStorage.getItem(`vds-player:${key}`);
-    if (savedValue) onChange(savedValue);
+    if (savedValue) update(savedValue);
 
     resets.all.add(onReset);
     return () => {

packages/react/src/components/layouts/default/shared-layout.tsx

@@ -24,6 +24,7 @@ import { MuteButton } from '../../ui/buttons/mute-button';
 import { PIPButton } from '../../ui/buttons/pip-button';
 import { PlayButton } from '../../ui/buttons/play-button';
 import { SeekButton } from '../../ui/buttons/seek-button';
+import { Captions } from '../../ui/captions';
 import { ChapterTitle } from '../../ui/chapter-title';
 import * as Menu from '../../ui/menu';
 import * as AudioGainSlider from '../../ui/sliders/audio-gain-slider';
@@ -301,6 +302,18 @@ function DefaultSeekButton({
 DefaultSeekButton.displayName = 'DefaultSeekButton';
 export { DefaultSeekButton };
 
+/* -------------------------------------------------------------------------------------------------
+ * DefaultCaptions
+ * -----------------------------------------------------------------------------------------------*/
+
+function DefaultCaptions() {
+  const exampleText = useDefaultLayoutWord('Captions look like this');
+  return <Captions className="vds-captions" exampleText={exampleText} />;
+}
+
+DefaultCaptions.displayName = 'DefaultCaptions';
+export { DefaultCaptions };
+
 /* -------------------------------------------------------------------------------------------------
  * DefaultVolumeSlider
  * -----------------------------------------------------------------------------------------------*/

packages/react/src/components/layouts/default/video-layout.tsx

@@ -1,7 +1,6 @@
 import * as React from 'react';
 
 import { useMediaState } from '../../../hooks/use-media-state';
-import { Captions } from '../../ui/captions';
 import * as Controls from '../../ui/controls';
 import { Gesture } from '../../ui/gesture';
 import * as Spinner from '../../ui/spinner';
@@ -13,6 +12,7 @@ import { createDefaultMediaLayout, type DefaultLayoutProps } from './media-layou
 import {
   DefaultAirPlayButton,
   DefaultCaptionButton,
+  DefaultCaptions,
   DefaultChaptersMenu,
   DefaultChapterTitle,
   DefaultControlsSpacer,
@@ -24,7 +24,6 @@ import {
   DefaultSettingsMenu,
   DefaultTimeInfo,
   DefaultTimeSlider,
-  DefaultTitle,
   DefaultVolumeSlider,
 } from './shared-layout';
 import {
@@ -101,7 +100,7 @@ function DefaultVideoLargeLayout() {
         />
       ) : null}
       {slot(slots, 'bufferingIndicator', <DefaultBufferingIndicator />)}
-      {slot(slots, 'captions', <Captions className="vds-captions" />)}
+      {slot(slots, 'captions', <DefaultCaptions />)}
       <Controls.Root className="vds-controls">
         <Controls.Group className="vds-controls-group">
           {slot(slots, 'topControlsGroupStart', null)}
@@ -160,7 +159,7 @@ function DefaultVideoSmallLayout() {
     <>
       <DefaultVideoGestures />
       {slot(slots, 'bufferingIndicator', <DefaultBufferingIndicator />)}
-      {slot(slots, 'captions', <Captions className="vds-captions" />)}
+      {slot(slots, 'captions', <DefaultCaptions />)}
       <Controls.Root className="vds-controls">
         <Controls.Group className="vds-controls-group">
           {slot(slots, 'topControlsGroupStart', null)}

packages/vidstack/mangle.json

@@ -794,5 +794,12 @@
   "_getARIAValueMin": "Pn",
   "_onAudioGainChange": "Nn",
   "_watchAudioGain": "On",
-  "_isSliderActive": "Qn"
+  "_isSliderActive": "Qn",
+  "_createCueDisplayElement": "Tn",
+  "_createCueElement": "Un",
+  "_hideExample": "Vn",
+  "_hideExampleTimer": "Rn",
+  "_onFontStyleChange": "Wn",
+  "_removeExample": "Sn",
+  "_showExample": "Xn"
 }

packages/vidstack/player/styles/default/captions.css

@@ -39,6 +39,23 @@
   visibility: hidden;
 }
 
+.vds-captions[data-example] {
+  opacity: 1 !important;
+  visibility: visible !important;
+}
+
+:where([data-view-type='video'] .vds-captions [data-part='cue-display'][data-example]) {
+  --cue-text-align: center;
+  --cue-width: 100%;
+  --cue-top: 90%;
+  --cue-left: 0%;
+}
+
+:where([data-view-type='audio'] .vds-captions [data-part='cue-display']) {
+  --cue-width: 100%;
+  position: relative !important;
+}
+
 /*
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  * VTT Cues

packages/vidstack/src/components/layouts/default/translations.ts

@@ -58,7 +58,8 @@ export type DefaultLayoutWord =
   | 'Unmute'
   | 'Volume'
   | 'White'
-  | 'Yellow';
+  | 'Yellow'
+  | 'Captions look like this';
 
 export type DefaultLayoutTranslations = {
   [word in DefaultLayoutWord]: string;

packages/vidstack/src/components/player.ts

@@ -38,7 +38,6 @@ import {
   type MediaPlayerState,
   type MediaStateAccessors,
   type MediaStore,
-  type RemotePlaybackType,
 } from '../core';
 import { MEDIA_ATTRIBUTES, mediaAttributes } from '../core/api/media-attrs';
 import { mediaContext, type MediaContext } from '../core/api/media-context';

packages/vidstack/src/components/ui/captions/captions.ts

@@ -1,5 +1,5 @@
 import { Component, effect, peek, scoped } from 'maverick.js';
-import { listenEvent } from 'maverick.js/std';
+import { listenEvent, setAttribute } from 'maverick.js/std';
 import type { CaptionsRenderer } from 'media-captions';
 
 import { useMediaContext, type MediaContext } from '../../../core/api/media-context';
@@ -14,6 +14,10 @@ export interface CaptionsProps {
    * - right-to-left (rtl)
    */
   textDir: 'ltr' | 'rtl';
+  /**
+   * The text to be displayed when an example caption is being shown.
+   */
+  exampleText: string;
 }
 
 /**
@@ -25,6 +29,7 @@ export interface CaptionsProps {
 export class Captions extends Component<CaptionsProps> {
   static props: CaptionsProps = {
     textDir: 'ltr',
+    exampleText: 'Captions look like this.',
   };
 
   private _media!: MediaContext;
@@ -44,6 +49,9 @@ export class Captions extends Component<CaptionsProps> {
   }
 
   protected override onConnect(el: HTMLElement) {
+    const player = this._media.player;
+    if (player) listenEvent(player, 'vds-font-change', this._onFontStyleChange.bind(this));
+
     if (this._renderer) {
       effect(this._watchViewType.bind(this));
       return;
@@ -108,15 +116,22 @@ export class Captions extends Component<CaptionsProps> {
   private _onCueChange() {
     this.el!.textContent = '';
 
+    if (this._hideExampleTimer >= 0) {
+      this._removeExample();
+    }
+
     const { realCurrentTime, textTrack } = this._media.$state,
+      { renderVTTCueString } = this._lib,
       time = peek(realCurrentTime),
       activeCues = peek(textTrack)!.activeCues;
 
-    const { renderVTTCueString } = this._lib;
     for (const cue of activeCues) {
-      const cueEl = document.createElement('div');
-      cueEl.setAttribute('data-part', 'cue');
+      const displayEl = this._createCueDisplayElement(),
+        cueEl = this._createCueElement();
+
       cueEl.innerHTML = renderVTTCueString(cue, time);
+
+      displayEl.append(cueEl);
       this.el!.append(cueEl);
     }
   }
@@ -144,7 +159,67 @@ export class Captions extends Component<CaptionsProps> {
 
   private _watchMediaTime() {
     if (this._isHidden()) return;
-    const { realCurrentTime } = this._media.$state;
+
+    const { realCurrentTime, textTrack } = this._media.$state;
     this._renderer.currentTime = realCurrentTime();
+
+    if (this._hideExampleTimer >= 0 && textTrack()?.activeCues[0]) {
+      this._removeExample();
+    }
+  }
+
+  private _onFontStyleChange() {
+    if (this._hideExampleTimer >= 0) {
+      this._hideExample();
+      return;
+    }
+
+    const { textTrack } = this._media.$state;
+
+    if (!textTrack()?.activeCues[0]) {
+      this._showExample();
+    } else {
+      this._renderer?.update(true);
+    }
+  }
+
+  private _showExample() {
+    const display = this._createCueDisplayElement();
+    setAttribute(display, 'data-example', '');
+
+    const cue = this._createCueElement();
+    setAttribute(cue, 'data-example', '');
+    cue.textContent = this.$props.exampleText();
+
+    display?.append(cue);
+    this.el?.append(display);
+
+    this.el?.setAttribute('data-example', '');
+
+    this._hideExample();
+  }
+
+  private _hideExampleTimer = -1;
+  private _hideExample() {
+    window.clearTimeout(this._hideExampleTimer);
+    this._hideExampleTimer = window.setTimeout(this._removeExample.bind(this), 2500);
+  }
+
+  private _removeExample() {
+    this.el?.removeAttribute('data-example');
+    if (this.el?.querySelector('[data-example]')) this.el.textContent = '';
+    this._hideExampleTimer = -1;
+  }
+
+  private _createCueDisplayElement() {
+    const el = document.createElement('div');
+    setAttribute(el, 'data-part', 'cue-display');
+    return el;
+  }
+
+  private _createCueElement() {
+    const el = document.createElement('div');
+    setAttribute(el, 'data-part', 'cue');
+    return el;
   }
 }

packages/vidstack/src/core/api/player-events.ts

@@ -19,6 +19,8 @@ export interface MediaPlayerEvents
   'media-player-connect': MediaPlayerConnectEvent;
   /* @internal */
   'find-media-player': FindMediaPlayerEvent;
+  /* @internal */
+  'vds-font-change': Event;
 }
 
 /**

packages/vidstack/src/elements/define/layouts/default/audio-layout.ts

@@ -16,6 +16,7 @@ import {
 import { $signal } from '../../../lit/directives/signal';
 import {
   DefaultCaptionButton,
+  DefaultCaptions,
   DefaultChaptersMenu,
   DefaultChapterTitle,
   DefaultControlsSpacer,
@@ -30,7 +31,7 @@ import {
 
 export function DefaultAudioLayout() {
   return [
-    html`<media-captions class="vds-captions"></media-captions>`,
+    DefaultCaptions(),
     html`
       <media-controls class="vds-controls">
         <media-controls-group class="vds-controls-group">

packages/vidstack/src/elements/define/layouts/default/font-menu.ts

@@ -211,6 +211,11 @@ function DefaultFontSettingMenu({
 
   function onReset() {
     onValueChange(defaultValue);
+    notify();
+  }
+
+  function notify() {
+    player.dispatchEvent(new Event('vds-font-change'));
   }
 
   function onOpen() {
@@ -230,6 +235,7 @@ function DefaultFontSettingMenu({
           options: radioOptions,
           onChange({ detail: value }) {
             onValueChange(value);
+            notify();
           },
         })}
       </media-menu-items>

packages/vidstack/src/elements/define/layouts/default/shared-layout.ts

@@ -222,6 +222,16 @@ export function DefaultSeekButton({
   `;
 }
 
+export function DefaultCaptions() {
+  const { translations } = useDefaultLayoutContext();
+  return html`
+    <media-captions
+      class="vds-captions"
+      .exampleText=${$i18n(translations, 'Captions look like this')}
+    ></media-captions>
+  `;
+}
+
 export function DefaultVolumeSlider({ orientation }: { orientation?: SliderOrientation } = {}) {
   const { translations } = useDefaultLayoutContext(),
     $label = $i18n(translations, 'Volume');