muxinc · AdamJaggard · May 21, 2024 · Apr 23, 2024 · Apr 23, 2024 · Apr 23, 2024
@@ -0,0 +1,55 @@
+import Link from "next/link";
+import Head from 'next/head';
+import { useState } from "react";
+import MuxPlayer from "@mux/mux-player-react";
+import type MuxPlayerElement from "@mux/mux-player";
+
+type Chapter = { startTime: number; endTime: number; value: string; };
+const chapters: Chapter[] = [
+  { startTime: 0, endTime: 3, value: 'Chapter 1' },
+  { startTime: 3, endTime: 6, value: 'Chapter 2' },
+  { startTime: 6, endTime: 9, value: 'Chapter 3' }
+];
+
+
+function MuxPlayerPage() {
+  const [activeChapter, setActiveChapter] = useState<Chapter>(undefined);
+
+  function addChaptersToPlayer(playerEl: MuxPlayerElement) {
+	playerEl.addChapters(chapters);
+  }
+
+  return (
+    <>
+      <Head>
+        <title>&lt;MuxPlayer/&gt; (CuePoints) Demo</title>
+      </Head>
+
+      <MuxPlayer
+        playbackId="23s11nz72DsoN657h4314PjKKjsF2JG33eBQQt6B95I"
+        streamType="on-demand"
+        preload="auto"
+        onLoadedMetadata={({ target }) => {
+          addChaptersToPlayer(target as MuxPlayerElement);
+        }}
+        onChapterChange={({ target }) => {
+          setActiveChapter((target as MuxPlayerElement).activeChapter);
+        }}
+      />
+      <div>
+        <b>Active chapter:</b>
+        <pre style={{
+          backgroundColor: '#888',
+          padding: '10px',
+		  color: '#fff'
+        }}>
+          {activeChapter?.value ?? 'Unset'}
+        </pre>
+      </div>
+      <br />
+      <Link href="/">Browse Elements</Link>
+    </>
+  );
+}
+
+export default MuxPlayerPage;
@@ -4,25 +4,26 @@ function HomePage() {
   return (
     <nav>
       <ul>
-        <li><Link legacyBehavior href="/MuxVideo"><a className="video">&lt;MuxVideo&gt;</a></Link></li>
-        <li><Link legacyBehavior href="/MuxAudio"><a className="audio">&lt;MuxAudio&gt;</a></Link></li>
-        <li><Link legacyBehavior href="/MuxPlayer"><a className="player">&lt;MuxPlayer&gt;</a></Link></li>
-        <li><Link legacyBehavior href="/MuxPlayerPosterSlot"><a className="player">&lt;MuxPlayer&gt;<br/>(poster slot)</a></Link></li>
-        <li><Link legacyBehavior href="/MuxPlayerTheme"><a className="player">&lt;MuxPlayer&gt;<br/>(theme)</a></Link></li>
-        <li><Link legacyBehavior href="/MuxPlayerCuePoints"><a className="player">&lt;MuxPlayer&gt;<br/>(CuePoints)</a></Link></li>
-        <li><Link legacyBehavior href="/MuxPlayerCuePointsMeditate"><a className="player">&lt;MuxPlayer&gt;<br/>(CuePoints + Audio Only)</a></Link></li>
-        <li><Link legacyBehavior href="/MuxPlayerLazy"><a className="player">&lt;MuxPlayer&gt;<br/>(lazy)</a></Link></li>
-        <li><Link legacyBehavior href="/MuxPlayerDynamic"><a className="player">&lt;MuxPlayer&gt;<br/>(Next.js dynamic)</a></Link></li>
-        <li><Link legacyBehavior href="/MuxPlayerLazyDynamic"><a className="player">&lt;MuxPlayer&gt;<br/>(lazy + dynamic)</a></Link></li>
-        <li><Link legacyBehavior href="/MuxPlayerIframe"><a className="player">&lt;MuxPlayer&gt;<br/>(w/o fullscreen)</a></Link></li>
-        <li><Link legacyBehavior href="/MuxPlayerLazyIframe"><a className="player">&lt;MuxPlayer&gt;<br/>(lazy + w/o fullscreen)</a></Link></li>
-        <li><Link legacyBehavior href="/MuxPlayerLazyBlurUp"><a className="player">&lt;MuxPlayer&gt;<br/>(lazy + @mux/blurup)</a></Link></li>
-        <li><Link legacyBehavior href="/MuxUploader"><a className="uploader">&lt;MuxUploader&gt;</a></Link></li>
-        <li><Link legacyBehavior href="/MuxUploaderSeparateComponents"><a className="uploader">&lt;MuxUploader&gt; (Separate Components)</a></Link></li>
-        <li><Link legacyBehavior href="/mux-video"><a className="video">&lt;mux-video&gt;<br/>(Web Component)</a></Link></li>
-        <li><Link legacyBehavior href="/mux-audio"><a className="audio">&lt;mux-audio&gt;<br/>(Web Component)</a></Link></li>
-        <li><Link legacyBehavior href="/mux-player"><a className="player">&lt;mux-player&gt;<br/>(Web Component)</a></Link></li>
-        <li><Link legacyBehavior href="/app-router"><a className="react">App Router</a></Link></li>
+        <li><Link href="/MuxVideo" className="video">&lt;MuxVideo&gt;</Link></li>
+        <li><Link href="/MuxAudio"className="audio">&lt;MuxAudio&gt;</Link></li>
+        <li><Link href="/MuxPlayer" className="player">&lt;MuxPlayer&gt;</Link></li>
+        <li><Link href="/MuxPlayerPosterSlot" className="player"><>&lt;MuxPlayer&gt;<br/>(poster slot)</></Link></li>
+        <li><Link href="/MuxPlayerTheme" className="player"><>&lt;MuxPlayer&gt;<br/>(theme)</></Link></li>
+        <li><Link href="/MuxPlayerCuePoints" className="player"><>&lt;MuxPlayer&gt;<br/>(CuePoints)</></Link></li>
+        <li><Link href="/MuxPlayerCuePointsMeditate" className="player"><>&lt;MuxPlayer&gt;<br/>(CuePoints + Audio Only)</></Link></li>
+        <li><Link href="/MuxPlayerChapters" className="player"><>&lt;MuxPlayer&gt;<br/>(Chapters)</></Link></li>
+        <li><Link href="/MuxPlayerLazy" className="player"><>&lt;MuxPlayer&gt;<br/>(lazy)</></Link></li>
+        <li><Link href="/MuxPlayerDynamic" className="player"><>&lt;MuxPlayer&gt;<br/>(Next.js dynamic)</></Link></li>
+        <li><Link href="/MuxPlayerLazyDynamic" className="player"><>&lt;MuxPlayer&gt;<br/>(lazy + dynamic)</></Link></li>
+        <li><Link href="/MuxPlayerIframe" className="player"><>&lt;MuxPlayer&gt;<br/>(w/o fullscreen)</></Link></li>
+        <li><Link href="/MuxPlayerLazyIframe" className="player"><>&lt;MuxPlayer&gt;<br/>(lazy + w/o fullscreen)</></Link></li>
+        <li><Link href="/MuxPlayerLazyBlurUp" className="player"><>&lt;MuxPlayer&gt;<br/>(lazy + @mux/blurup)</></Link></li>
+        <li><Link href="/MuxUploader" className="uploader"><>&lt;MuxUploader&gt;</></Link></li>
+        <li><Link href="/MuxUploaderSeparateComponents" className="uploader"><>&lt;MuxUploader&gt; (Separate Components)</></Link></li>
+        <li><Link href="/mux-video" className="video"><>&lt;mux-video&gt;<br/>(Web Component)</></Link></li>
+        <li><Link href="/mux-audio" className="audio"><>&lt;mux-audio&gt;<br/>(Web Component)</></Link></li>
+        <li><Link href="/mux-player" className="player"><>&lt;mux-player&gt;<br/>(Web Component)</></Link></li>
+        <li><Link href="/app-router" className="react"><>App Router</></Link></li>
       </ul>
     </nav>
   );

@@ -31,6 +31,7 @@ <h1><a href="/">Elements</a></h1>
         <li><a href="./mux-player.html" class="player">&lt;mux-player&gt;</a></li>
         <li><a href="./mux-player-audio.html" class="player">&lt;mux-player audio&gt;</a></li>
         <li><a href="./mux-player-cuepoints.html" class="player">&lt;mux-player&gt; (cuePoints)</a></li>
+        <li><a href="./mux-player-chapters.html" class="player">&lt;mux-player&gt; (chapters)</a></li>
         <li><a href="./mux-player-renditions.html" class="player">&lt;mux-player&gt; (renditions)</a></li>
         <li><a href="./mux-player-poster-slot.html" class="player">&lt;mux-player&gt; (poster slot)</a></li>
         <li><a href="./mux-player-audio-tracks.html" class="player">&lt;mux-player&gt; (audio tracks)</a></li>

@@ -0,0 +1,127 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta name="viewport" content="width=device-width" />
+    <title>&lt;mux-player&gt; | Chapters</title>
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/water.css@2/out/water.css">
+    <link rel="stylesheet" href="./styles.css">
+    <script type="module" src="./dist/mux-player.js"></script>
+    <style>
+      mux-player {
+        display: block;
+        width: 100%;
+        margin: 1rem 0 2rem;
+        background-color: #000;
+      }
+
+      mux-player:not([audio]) {
+        aspect-ratio: 16 / 9;
+      }
+
+      #chapter-renderer {
+        background-color: #888;
+        color: #fff;
+        padding: 10px;
+      }
+    </style>
+  </head>
+  <body>
+    <header>
+      <div class="left-header">
+        <a class="mux-logo" href="https://www.mux.com/player" target="_blank">
+          <picture>
+            <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/360826/233653989-11cd8603-c20f-4008-8bf7-dc15b743c52b.svg">
+            <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/360826/233653583-50dda726-cbe7-4182-a113-059a91ae83e6.svg">
+            <img alt="Mux Logo" src="https://user-images.githubusercontent.com/360826/233653583-50dda726-cbe7-4182-a113-059a91ae83e6.svg">
+          </picture>
+        </a>
+        <h1><a href="/">Elements</a></h1>
+      </div>
+      <div class="right-header">
+        <a class="github-logo" href="https://github.com/muxinc/elements" target="_blank">
+          <img width="32" height="32" src="./images/github-logo.svg" alt="Github logo">
+        </a>
+      </div>
+    </header>
+
+    <h2>Chapters with explicit end times (with gaps)</h2>
+
+    <mux-player
+      id="playerOne"
+      stream-type="on-demand"
+      playback-id="23s11nz72DsoN657h4314PjKKjsF2JG33eBQQt6B95I"
+      muted
+      preload="auto"
+    ></mux-player>
+    <p>
+      <b>Active Chapter:</b> <pre id="chapter-renderer">Unset</pre>
+    </p>
+    <p>
+      <button onclick="window.playerOne.addChapters([{startTime: 15, endTime: 18, value: 'Extra chapter'}]); this.disabled = true;">Add additional fourth chapter</button>
+    </p>
+
+
+    <h2>Chapters with implicit end times (no gaps, audio UI)</h2>
+
+    <mux-player
+      id="playerTwo"
+      stream-type="on-demand"
+      playback-id="23s11nz72DsoN657h4314PjKKjsF2JG33eBQQt6B95I"
+      muted
+      preload="auto"
+      audio
+    ></mux-player>
+
+    <p>
+      <button onclick="window.playerTwo.addChapters([{startTime: 6, value: 'Chapter 2.5'}]); this.disabled = true;">Add chapter between 2 and 3</button>
+    </p>
+
+    <script>
+      const playerOneEl = document.querySelector('#playerOne');
+      const playerTwoEl = document.querySelector('#playerTwo');
+
+      function addChapterstoPlayerOne() {
+        const chaptersOne = [
+          { startTime: 1, endTime: 3, value: 'Chapter 1' },
+          { startTime: 3, endTime: 6, value: 'Chapter 2 (joined)' },
+          { startTime: 10, endTime: 15, value: 'Chapter 3 (after gap)' }
+        ];
+        playerOneEl.addChapters(chaptersOne);
+
+        console.log('Player one chapters added');
+      }
+
+      function addChapterstoPlayerTwo() {
+        const chaptersTwo = [
+          { startTime: 1, value: 'Chapter 1' },
+          { startTime: 3, value: 'Chapter 2' },
+          { startTime: 10, value: 'Chapter 3 (to the end...)' }
+        ];
+        playerTwoEl.addChapters(chaptersTwo);
+
+        console.log('Player 2 chapters added');
+      }
+
+      function chapterChangeListener() {
+        console.log('Active Chapter', playerOneEl.activeChapter);
+        document.getElementById('chapter-renderer').innerText = playerOneEl.activeChapter.value;
+      }
+
+      playerOneEl.addEventListener('chapterchange', chapterChangeListener);
+
+      // NOTE: Need to wait until the player has loaded metadata before adding chapters!
+      if (playerOneEl.readyState >= 1) {
+        addChapterstoPlayerOne();
+      } else {
+        playerOneEl.addEventListener('loadedmetadata', addChapterstoPlayerOne, { once: true });
+      }
+
+      if (playerTwoEl.readyState >= 1) {
+        addChapterstoPlayerTwo();
+      } else {
+        playerTwoEl.addEventListener('loadedmetadata', addChapterstoPlayerTwo, { once: true });
+      }
+    </script>
+    <a href="../">Browse Elements</a>
+  </body>
+</html>
@@ -19,7 +19,8 @@
       }
 
       #cuepoint-renderer {
-        background-color: lightgray;
+        background-color: #888;
+        color: #fff;
         padding: 10px;
       }
     </style>

@@ -124,6 +124,7 @@ export type MuxPlayerProps = {
   onError?: GenericEventListener<MuxPlayerElementEventMap['error']>;
   onCuePointChange?: GenericEventListener<MuxPlayerElementEventMap['cuepointchange']>;
   onCuePointsChange?: GenericEventListener<MuxPlayerElementEventMap['cuepointschange']>;
+  onChapterChange?: GenericEventListener<MuxPlayerElementEventMap['chapterchange']>;
 } & Partial<MuxMediaPropTypes> &
   Partial<VideoApiAttributes>;
 
@@ -178,6 +179,7 @@ const usePlayer = (
     onError,
     onCuePointChange,
     onCuePointsChange,
+    onChapterChange,
     metadata,
     tokens,
     paused,
@@ -244,6 +246,7 @@ const usePlayer = (
   useEventCallbackEffect('error', ref, onError);
   useEventCallbackEffect('cuepointchange', ref, onCuePointChange);
   useEventCallbackEffect('cuepointschange', ref, onCuePointsChange);
+  useEventCallbackEffect('chapterchange', ref, onChapterChange);
   return [remainingProps];
 };
 

@@ -63,7 +63,8 @@
 | --------- | -------------------------------------------------------------------------------------------------------------------- |
 | `play()`  | Identical to the [native `play()` method](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/play).   |
 | `pause()` | Identical to the [native `pause()` method](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/pause). |
-| `addCuePoints()` | Add an array of metadata CuePoints of "shape" `{ time: number; value: any; }` to the Mux Player instance for the current media |
+| `addCuePoints()` | Add an array of CuePoints with the shape `{ startTime: number; endTime?: number, value: any; }` to the Mux Player instance |
+| `addChapters()` | Add an array of chapters with the shape `{ startTime: number; endTime?: number, value: string; }` to the Mux Player instance |
 | `getStartDate()` | Will return a Date that matches the earliest PDT in your stream. Identical to [native `getStartDate()` method](https://html.spec.whatwg.org/multipage/media.html#dom-media-getstartdate), if exists. |
 |
 
@@ -138,8 +139,10 @@
 | `storyboardSrc`                              | `string` (URL)                                                                                                                        | Full URL string for the storyboard asset. Setting this will override the storyboard URL derived from the playback ID.                                                                                                                                                                                                                                                                                                                                             | `undefined`                      |
 | `tokens`                                       | `object`\*                                                                                                                      | An object for setting all signed URL tokens with the signature `{ playback: string; thumbnail: string; storyboard: string; }`. If any `*token` properties or `*-token` attributes are set, they will take precedence.                                                                                                                                                                            | `undefined`                      |
 | `textTracks`                                   | [`TextTrackList`](https://developer.mozilla.org/en-US/docs/Web/API/TextTrackList)                                               | Identical to the [native `textTracks` property](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/textTracks)                                                                                                                                                                                                                                                                    | (empty `TextTrackList` instance) |
-| `cuePoints` <sub><sup>Read only</sup></sub> | `Array<{ time: number; value: any; }>` | The array of CuePoints for the current media, added via `addCuePoints(cuePoints)`. | `[]` |
-| `activeCuePoint` <sub><sup>Read only</sup></sub> | `{ time: number; value: any; }` | The current active CuePoint, determined based on the player's `currentTime`. | `undefined` |
+| `cuePoints` <sub><sup>Read only</sup></sub> | `Array<{ startTime: number; endTime?: number, value: any; }>` | The array of CuePoints for the current media, added via `addCuePoints(cuePoints)`. | `[]` |
+| `chapters` <sub><sup>Read only</sup></sub> | `Array<{ startTime: number; endTime?: number, value: string; }>` | The array of Chapters for the current media, added via `addChapters(chapters)`. | `[]` |
+| `activeCuePoint` <sub><sup>Read only</sup></sub> | `{ startTime: number; endTime?: number, value: any; }` | The current active CuePoint, determined based on the player's `currentTime`. | `undefined` |
+| `activeChapter` <sub><sup>Read only</sup></sub> | `{ startTime: number; endTime?: number, value: string; }` | The current active Chapter, determined based on the player's `currentTime`. | `undefined` |
 
 <!-- UNDOCUMENTED
 // NEW STREAM TYPE VALUES
@@ -181,6 +184,7 @@
 | `volumechange`   | Identical to the native [`volumechange` event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/volumechange_event)     |
 | `waiting`        | Identical to the native [`waiting` event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/waiting_event)               |
 | `cuepointchange` | Similar to the native `TextTrack` [`cuechange` event](https://developer.mozilla.org/en-US/docs/Web/API/TextTrack/cuechange_event), only the event's `detail` will be the `activeCuePoint` |
+| `chapterchange` | Similar to the native `TextTrack` [`cuechange` event](https://developer.mozilla.org/en-US/docs/Web/API/TextTrack/cuechange_event), only the event's `detail` will be the `activeChapter` |
 
 # CSS Variables
 

@@ -231,6 +231,7 @@ const DEFAULT_EXTRA_PLAYLIST_PARAMS = { redundant_streams: true };
 export interface MuxPlayerElementEventMap extends HTMLVideoElementEventMap {
   cuepointchange: CustomEvent<{ time: number; value: any }>;
   cuepointschange: CustomEvent<Array<{ time: number; value: any }>>;
+  chapterchange: CustomEvent<{ startTime: number; endTime: number; value: string }>;
 }
 
 interface MuxPlayerElement
@@ -1507,6 +1508,26 @@ class MuxPlayerElement extends VideoApiElement implements MuxPlayerElement {
     return this.media?.cuePoints ?? [];
   }
 
+  addChapters(chapters: { startTime: number; endTime: number; value: string }[]) {
+    this.#init();
+
+    // NOTE: This condition should never be met. If it is, there is a bug (CJP)
+    if (!this.media) {
+      logger.error('underlying media element missing when trying to addChapters. chapters will not be added.');
+      return;
+    }
+
+    return this.media?.addChapters(chapters);
+  }
+
+  get activeChapter() {
+    return this.media?.activeChapter;
+  }
+
+  get chapters() {
+    return this.media?.chapters ?? [];
+  }
+
   getStartDate() {
     return this.media?.getStartDate();
   }

@@ -100,6 +100,7 @@
       --media-preview-border-radius: 5px;
       --media-text-color: var(--_text-color);
       --media-control-hover-background: transparent;
+      --media-preview-chapter-text-shadow: none;
       color: var(--_accent-color);
       padding: 0 6px;
     }
@@ -272,7 +273,9 @@
       paint-order: stroke;
       stroke: rgba(102, 102, 102, 1);
       stroke-width: 0.3px;
-      text-shadow: 0 0 2px rgb(0 0 0 / 0.25), 0 0 6px rgb(0 0 0 / 0.25);
+      text-shadow:
+        0 0 2px rgb(0 0 0 / 0.25),
+        0 0 6px rgb(0 0 0 / 0.25);
     }
 
     .center-controls media-play-button {