@banou/media-player 0.9.0 → 0.10.1

package/dist/react/components/skip-chapter.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Offers to jump past an opening or ending, when the chapter under the playhead looks like one.
+ *
+ * The whole feature is this button plus `classifyChapters`, and it is deliberately the weaker half
+ * of the pair: the classifier reads titles written by whoever muxed the file, so it is sometimes
+ * going to be wrong. Making the offer expire, and never acting on its own, is what makes being wrong
+ * cheap. See the classifier for what it matches and the sample it was measured against.
+ */
+export declare const SkipChapter: () => import("@emotion/react/jsx-runtime").JSX.Element | null;
+export default SkipChapter;

package/dist/react/hooks/use-thumbnails.d.ts

@@ -9,4 +9,15 @@ export type UseSeekThumbnailsOptions = {
     /** When omitted the whole file is treated as readable, which is the case for a local file. */
     downloadedRanges?: DownloadedRange[];
 };
-export declare const useSeekThumbnails: ({ publicPath, workerUrl, length, read, downloadedRanges, }: UseSeekThumbnailsOptions) => ThumbnailImage[];
+export type SeekThumbnails = {
+    thumbnails: ThumbnailImage[];
+    /**
+     * Where the viewer is pointing on the seekbar, so that preview is decoded next.
+     *
+     * Stable for the life of the hook, so it can be published to the store once and called from a
+     * pointermove without re-rendering anything. A no-op until the generator boots, and on a source
+     * that brings its own storyboard.
+     */
+    requestThumbnail: (time: number | undefined) => void;
+};
+export declare const useSeekThumbnails: ({ publicPath, workerUrl, length, read, downloadedRanges, }: UseSeekThumbnailsOptions) => SeekThumbnails;

package/dist/react/player.d.ts

@@ -3,8 +3,10 @@ export declare const Player: import("@videojs/react").CreatePlayerResult<import(
     size?: number;
     downloadedRanges?: import("./source-feature").DownloadedRange[];
     indexes: import("..").MediaIndex[];
+    chapters: import("..").MediaChapter[];
     thumbnails: import("..").ThumbnailImage[];
     thumbnailAt?: (time: number) => import("..").ThumbnailImage | undefined;
+    requestThumbnail: (time: number | undefined) => void;
     subtitleTracks: import("./source-feature").TrackChoice[];
     selectedSubtitleTrack: string | number | undefined;
     selectSubtitleTrack: (id: string | number | undefined) => void | Promise<void>;

package/dist/react/source-feature.d.ts

@@ -1,4 +1,4 @@
-import type { MediaIndex, PictureInPictureMode, ThumbnailImage } from '../engine';
+import type { MediaChapter, MediaIndex, PictureInPictureMode, ThumbnailImage } from '../engine';
 /**
  * One row of a track menu, already named.
  *
@@ -70,12 +70,31 @@ export type SourceState = {
     downloadedRanges?: DownloadedRange[];
     /** Keyframe index of the input, which turns a downloaded byte range into a time range. */
     indexes: MediaIndex[];
+    /**
+     * Named spans of the timeline, drawn as segments on the seekbar. Empty when the source has none.
+     *
+     * Ordered by start and non-overlapping, which is what the seekbar assumes. They need not cover the
+     * whole duration: the engine passes on whatever the container declared, and a caller-supplied list
+     * is whatever the caller knows.
+     */
+    chapters: MediaChapter[];
     thumbnails: ThumbnailImage[];
     /**
      * Answers for one time directly, when the source has a storyboard it can index but not enumerate.
      * Falls back to scanning `thumbnails` when absent, which is what the engine's generator fills.
      */
     thumbnailAt?: (time: number) => ThumbnailImage | undefined;
+    /**
+     * Where the pointer is on the seekbar, so the preview under it is generated before the rest.
+     *
+     * Generation otherwise walks the file start to end, so pointing at the last third of a long video
+     * means waiting out everything before it. Called on every pointermove, which is why it is a
+     * callback on the store rather than a piece of state: a hover time held in the store would
+     * re-render every subscriber for each move.
+     *
+     * A no-op on a source that brings its own storyboard, and until the generator has booted.
+     */
+    requestThumbnail: (time: number | undefined) => void;
     /**
      * Both selectors may answer with a promise, and the menu waits on it.
      *
@@ -157,12 +176,31 @@ export declare const sourceFeature: import("@videojs/react").PlayerFeature<{
     downloadedRanges?: DownloadedRange[];
     /** Keyframe index of the input, which turns a downloaded byte range into a time range. */
     indexes: MediaIndex[];
+    /**
+     * Named spans of the timeline, drawn as segments on the seekbar. Empty when the source has none.
+     *
+     * Ordered by start and non-overlapping, which is what the seekbar assumes. They need not cover the
+     * whole duration: the engine passes on whatever the container declared, and a caller-supplied list
+     * is whatever the caller knows.
+     */
+    chapters: MediaChapter[];
     thumbnails: ThumbnailImage[];
     /**
      * Answers for one time directly, when the source has a storyboard it can index but not enumerate.
      * Falls back to scanning `thumbnails` when absent, which is what the engine's generator fills.
      */
     thumbnailAt?: (time: number) => ThumbnailImage | undefined;
+    /**
+     * Where the pointer is on the seekbar, so the preview under it is generated before the rest.
+     *
+     * Generation otherwise walks the file start to end, so pointing at the last third of a long video
+     * means waiting out everything before it. Called on every pointermove, which is why it is a
+     * callback on the store rather than a piece of state: a hover time held in the store would
+     * re-render every subscriber for each move.
+     *
+     * A no-op on a source that brings its own storyboard, and until the generator has booted.
+     */
+    requestThumbnail: (time: number | undefined) => void;
     /**
      * Both selectors may answer with a promise, and the menu waits on it.
      *

package/dist/react/video-player.d.ts

@@ -1,4 +1,5 @@
 import type { ReactNode } from 'react';
+import type { MediaChapter } from '../engine';
 import type { DownloadedRange } from './source-feature';
 import type { DelegatedTracks, ExternalThumbnails, PlayerMedia } from './media';
 import type { ExposePlayerOptions } from '../remote';
@@ -35,6 +36,18 @@ type CommonOptions = {
      */
     title?: string;
     autoplay?: boolean;
+    /**
+     * Named spans of the timeline, drawn as segments on the seekbar.
+     *
+     * Common to both arms rather than remote-only, unlike `thumbnails`. A local file is just as likely
+     * to declare none (mp4 and webm routinely carry no chapters at all), and a caller often knows
+     * chapters the container does not: skip-intro ranges from a metadata API are the usual case. Given
+     * here they WIN over whatever the container declared, and they paint on the first frame rather than
+     * waiting for the pipeline to boot.
+     *
+     * Expected in seconds, ordered by start and non-overlapping. They need not cover the duration.
+     */
+    chapters?: MediaChapter[];
     /**
      * Draw the control bar. Defaults to true.
      *

package/dist/utils/chapters.d.ts

@@ -0,0 +1,37 @@
+import type { MediaChapter } from '../engine';
+/**
+ * Where the bar is broken, as percentages, including the two ends: [0, ...breaks, 100].
+ *
+ * Both edges of every chapter count, so chapters that leave un-named time between them break the
+ * bar on each side of the gap and the un-named span becomes a segment of its own. Returns nothing
+ * when there is no break worth drawing, which is what leaves a file with no chapters, or one whose
+ * single chapter spans the whole picture, rendering exactly as it did before chapters existed.
+ */
+export declare const segmentBounds: (chapters: MediaChapter[], duration: number) => number[];
+/**
+ * A mask painting the segments `keep` accepts, with a gap at every boundary between segments.
+ *
+ * The gap is cut from both sides of a boundary so it stays centred on it, and never from the two
+ * outer edges, where it would shorten the bar rather than divide it.
+ */
+export declare const segmentMask: (bounds: number[], keep: (index: number) => boolean) => string;
+/**
+ * What a chapter is, when its title says plainly enough to offer a skip.
+ *
+ * Only ever a suggestion: the player shows a button for a few seconds and does nothing unless it is
+ * pressed. That is what lets this be generous rather than careful. A chapter wrongly called an
+ * opening costs a button nobody presses, while an opening this fails to recognise costs the feature.
+ *
+ * Every rule below was checked against 192 real files (891 chapter markers, 79 distinct chapter
+ * sequences) rather than guessed, and the counts quoted are from that sample.
+ */
+export type ChapterKind = 'opening' | 'ending';
+/**
+ * What each chapter is, decided across the whole list rather than one title at a time.
+ *
+ * The list is what resolves the hedged words. A file whose chapters read Intro, OP, Episode, ED,
+ * Preview has already said which one the theme is, so its Intro is left alone; one that reads
+ * Episode, Intro, Episode, Credits has not, so its Intro is offered. Both shapes are in the sample,
+ * 13 files and 24 files.
+ */
+export declare const classifyChapters: (chapters: MediaChapter[]) => (ChapterKind | undefined)[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@banou/media-player",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "A video player for containers and codecs the browser cannot play natively, remuxed on the fly",
   "type": "module",
   "main": "dist/index.js",

package/src/lib/engine/index.ts

@@ -1,5 +1,5 @@
 export { startPlayback, terminateRemuxer, MediaElementError, isMediaElementError, DEFAULT_BUFFER_SIZE } from './playback'
-export type { PlaybackOptions, PlaybackController, MediaIndex, AudioStream } from './playback'
+export type { PlaybackOptions, PlaybackController, MediaIndex, MediaChapter, AudioStream } from './playback'
 
 export { createSubtitleRenderer, SUBTITLES_OFF } from './subtitles'
 export type { SubtitleRenderer, SubtitleRendererOptions, SubtitleStream } from './subtitles'

package/src/lib/engine/playback.ts

@@ -11,6 +11,18 @@ export type { AudioStream }
 /** A keyframe index entry: the byte offset a keyframe starts at, and the time it plays at. */
 export type MediaIndex = { pos: number, timestamp: number }
 
+/**
+ * One named span of the timeline, in SECONDS.
+ *
+ * Chapters are not required to tile the duration: a container routinely declares a last chapter that
+ * ends fractionally before the file does, and nothing guarantees the first starts at zero. Anything
+ * drawing them has to treat the gaps as ordinary un-named time rather than assume full cover.
+ *
+ * libav also reports an `index`, dropped here the way `MediaIndex` drops it: array position already
+ * carries it, and a caller supplying their own chapters should not have to number them.
+ */
+export type MediaChapter = { start: number, end: number, title: string }
+
 export type PlaybackOptions = {
   videoElement: HTMLVideoElement
   /**
@@ -55,6 +67,8 @@ export type PlaybackController = {
   selectSubtitleStream: (streamIndex: number | undefined) => void
   /** Keyframe index of the input, which is what maps a downloaded byte range onto the timeline. */
   indexes: MediaIndex[]
+  /** Named spans the container declared, empty when it declared none. */
+  chapters: MediaChapter[]
   duration: number
   videoMimeType: string
   audioMimeType: string
@@ -643,6 +657,7 @@ export const startPlayback = async (options: PlaybackOptions): Promise<PlaybackC
       videoElement,
       selectSubtitleStream: (streamIndex: number | undefined) => subtitles.selectStream(streamIndex),
       indexes: metadata.indexes ?? [],
+      chapters: metadata.chapters ?? [],
       duration: metadata.info.input.duration,
       videoMimeType: metadata.info.output.videoMimeType,
       audioMimeType: metadata.info.output.audioMimeType,

package/src/lib/engine/thumbnails.ts

@@ -29,6 +29,17 @@ const KEYFRAME_TIMEOUT = 10_000
 export type ThumbnailGenerator = {
   /** Report which byte ranges are readable. Called with no argument when the whole file is. */
   update: (ranges?: [number, number][]) => void
+  /**
+   * Where the viewer is pointing, so that preview is decoded next. `undefined` when they stop.
+   *
+   * Only the slot covering `time` jumps the queue, and only for as long as it is still waiting, so
+   * this moves one preview forward rather than re-ordering the run. Everything behind it keeps the
+   * order it was claimed in and carries on the moment the jumped slot is done.
+   *
+   * It cannot interrupt a decode that has already started, so the wait is the tail of the one in
+   * flight and not the whole backlog.
+   */
+  prioritize: (time: number | undefined) => void
   destroy: () => void
 }
 
@@ -68,7 +79,35 @@ export const createThumbnailGenerator = async (options: ThumbnailGeneratorOption
 
     let thumbnails: ThumbnailImage[] = []
     let destroyed = false
-    let queue = Promise.resolve()
+
+    /*
+     * Slots claimed for decoding but not yet started, in the order they were claimed.
+     *
+     * A promise chain used to be this queue, which fixed the running order at the moment each slot
+     * was chained on and left nothing a hover could reach: the preview under the pointer waited
+     * behind every slot already queued, which on a long file is the rest of the run. The order is
+     * the same, it is just held somewhere a pick can look into.
+     */
+    const pending: Slot[] = []
+    let running = false
+    /** Where the pointer is on the seekbar, or undefined when it is off it. */
+    let priorityTime: number | undefined
+
+    /*
+     * The slot to decode next: the one under the pointer when it is still waiting, else the oldest claim.
+     *
+     * Requiring the slot to COVER the time is what keeps this a single jump rather than a re-sort
+     * around the cursor. Once that slot is decoded nothing covers the pointer any more, so the very
+     * next pick is the oldest claim again and the sequential walk carries on where it left off.
+     */
+    const nextIndex = () => {
+      const at = priorityTime
+      if (at !== undefined) {
+        const hit = pending.findIndex(({ timestamp, endTime }) => timestamp <= at && at < endTime)
+        if (hit >= 0) return hit
+      }
+      return 0
+    }
 
     // the slider assumes a gapless storyboard, so gaps get sentinels the UI hides
     const emit = () => {
@@ -88,29 +127,44 @@ export const createThumbnailGenerator = async (options: ThumbnailGeneratorOption
       onThumbnails(display)
     }
 
-    const generate = (slot: Slot) => {
-      slot.done = true
-      queue = queue
-        .then(async () => {
-          if (destroyed) return
-          const png = await Promise.race([
-            remuxer.readKeyframe(slot.timestamp),
-            new Promise<never>((_, reject) => setTimeout(() => reject(new Error('timed out')), KEYFRAME_TIMEOUT)),
-          ])
-          const bitmap = await createImageBitmap(new Blob([png], { type: 'image/png' }))
-          const canvas = new OffscreenCanvas(width, Math.max(1, Math.round(bitmap.height * (width / bitmap.width))))
-          canvas.getContext('2d')!.drawImage(bitmap, 0, 0, canvas.width, canvas.height)
-          bitmap.close()
-          const blob = await canvas.convertToBlob({ type: 'image/webp', quality: 0.7 })
-          if (destroyed) return
-          thumbnails = [...thumbnails, { url: URL.createObjectURL(blob), startTime: slot.timestamp, endTime: slot.endTime }]
-            .sort((a, b) => a.startTime - b.startTime)
-          emit()
-        })
+    const decode = async (slot: Slot) => {
+      if (destroyed) return
+      const png = await Promise.race([
+        remuxer.readKeyframe(slot.timestamp),
+        new Promise<never>((_, reject) => setTimeout(() => reject(new Error('timed out')), KEYFRAME_TIMEOUT)),
+      ])
+      const bitmap = await createImageBitmap(new Blob([png], { type: 'image/png' }))
+      const canvas = new OffscreenCanvas(width, Math.max(1, Math.round(bitmap.height * (width / bitmap.width))))
+      canvas.getContext('2d')!.drawImage(bitmap, 0, 0, canvas.width, canvas.height)
+      bitmap.close()
+      const blob = await canvas.convertToBlob({ type: 'image/webp', quality: 0.7 })
+      if (destroyed) return
+      thumbnails = [...thumbnails, { url: URL.createObjectURL(blob), startTime: slot.timestamp, endTime: slot.endTime }]
+        .sort((a, b) => a.startTime - b.startTime)
+      emit()
+    }
+
+    // one decode at a time, because there is one wasm worker behind them all
+    const pump = () => {
+      if (running || destroyed || !pending.length) return
+      const slot = pending.splice(nextIndex(), 1)[0]!
+      running = true
+      void decode(slot)
         .catch(() => {
           slot.attempts += 1
+          // left claimable again, so a later `update` retries it
           slot.done = slot.attempts >= MAX_ATTEMPTS
         })
+        .finally(() => {
+          running = false
+          pump()
+        })
+    }
+
+    const claim = (slot: Slot) => {
+      slot.done = true
+      pending.push(slot)
+      pump()
     }
 
     emit()
@@ -120,11 +174,16 @@ export const createThumbnailGenerator = async (options: ThumbnailGeneratorOption
         if (destroyed) return
         for (const slot of slots) {
           if (slot.done) continue
-          if (!ranges || ranges.some(([from, to]) => from <= slot.startByte && slot.endByte <= to)) generate(slot)
+          if (!ranges || ranges.some(([from, to]) => from <= slot.startByte && slot.endByte <= to)) claim(slot)
         }
       },
+      prioritize: (time) => {
+        if (destroyed) return
+        priorityTime = time
+      },
       destroy: () => {
         destroyed = true
+        pending.length = 0
         for (const t of thumbnails) URL.revokeObjectURL(t.url)
         thumbnails = []
         terminateRemuxer(remuxer)

package/src/lib/index.tsx

@@ -35,6 +35,7 @@ export type { RemuxerInput } from './utils/source'
 // The engine is also published on its own subpath for consumers that want the pipeline with no React.
 export type {
   AudioStream,
+  MediaChapter,
   MediaIndex,
   PictureInPictureController,
   PlaybackController,

package/src/lib/react/components/chrome.tsx

@@ -8,6 +8,7 @@ import { usePlayer } from '../player'
 import { Overlay } from './overlay'
 import ControlBar from './control-bar'
 import BurnInHint from './burn-in-hint'
+import SkipChapter from './skip-chapter'
 
 const AUTO_HIDE_DELAY = 3_000
 
@@ -233,6 +234,7 @@ export const Chrome = ({ ref, onVideoRef, onSubtitleRef, overlay, controls, chil
       {controls === false ? null : <ControlBar />}
       {/* Not tied to `hideUI`: it says what to do next, and it is on screen for nine seconds. */}
       <BurnInHint />
+      <SkipChapter />
       <div className="video" onClick={onVideoClick}>
         {onVideoRef ? <video ref={onVideoRef} playsInline /> : null}
         {children}

package/src/lib/react/components/progress-bar.tsx

@@ -7,6 +7,8 @@ import { css } from '@emotion/react'
 import { usePlayer } from '../player'
 import { useDragValue } from '../hooks/use-drag-value'
 import { fonts } from '../../utils/fonts'
+import { formatTime } from '../../utils/time'
+import { segmentBounds, segmentMask } from '../../utils/chapters'
 
 const style = css`
   position: relative;
@@ -41,6 +43,37 @@ const style = css`
     }
   }
 
+  /*
+   * One copy of the track per mask, stacked.
+   *
+   * The rest track paints every segment except the one under the pointer, the focus track paints only that one and
+   * is the only element that grows. Both are full bar width, which is what keeps every percentage
+   * and every scaleX inside them meaning exactly what it meant before chapters existed: the gaps are
+   * cut by a mask, not by resizing anything.
+   *
+   * The mask sits HERE and never on .loaded-part or .play. Those two carry a scaleX, and a mask
+   * travels with its element's transform, so a gap drawn on them would slide with the fill.
+   */
+  .track {
+    position: absolute;
+    inset: 0;
+    /* never a hit target: .padding is the only one, and a second would break the drag gesture and
+       fire a bubbling mouseout at every boundary crossing */
+    pointer-events: none;
+  }
+
+  /*
+   * The segment under the pointer, on TOP of the growth the whole bar already got.
+   *
+   * Measured off YouTube's live player, hovering one chapter of five: every other segment goes 4px
+   * to 6px, and the one under the pointer goes to 10px. Both grow about the bar's centre line, so
+   * the emphasised segment bulges above and below its neighbours rather than sitting on them. 6 x
+   * 1.667 is 10, and the 1.5 the layers inside already carry gets this track from 4 to exactly that.
+   */
+  .track.focus {
+    transform: scaleY(1.667);
+  }
+
 
   .background-bar {
     position: absolute;
@@ -64,6 +97,23 @@ const style = css`
     text-shadow: 0 0 4px rgba(0, 0, 0, 1);
     ${fonts.bMedium.bold}
 
+    gap: calc(.6 * var(--mp-unit));
+
+    /*
+     * The chapter under the pointer, next to the time, which is where the reference puts it.
+     *
+     * It is the one part of this pill whose width the player does not control, so it is capped and
+     * ellipsised rather than allowed to push the box outside the picture. The cap and the clamp that
+     * positions the pill are set together on the element, since a centred box can only be kept
+     * inside the bar if the clamp knows its half width.
+     */
+    .chapter-title {
+      overflow: hidden;
+      text-overflow: ellipsis;
+      min-width: 0;
+      font-weight: normal;
+    }
+
     position: absolute;
     /* Anchored on its bottom edge rather than its top: now that it has a background its height
        follows the font size, and a top-anchored box would grow downward into the track. */
@@ -194,12 +244,26 @@ export const ProgressBar = () => {
   const indexes = usePlayer((state) => state.indexes)
   const thumbnails = usePlayer((state) => state.thumbnails)
   const thumbnailAt = usePlayer((state) => state.thumbnailAt)
+  const requestThumbnail = usePlayer((state) => state.requestThumbnail)
+  const chapters = usePlayer((state) => state.chapters)
 
   const progressBarRef = useRef<HTMLDivElement>(null)
 
   const [seekFraction, setSeekFraction] = useState<number | undefined>(undefined)
   const [progressBarHoverTime, setProgressBarOverTime] = useState<number | undefined>(undefined)
 
+  /*
+   * Move the preview and the generator's next pick together.
+   *
+   * The frame under the pointer is both the one drawn and the one worth decoding first, and every
+   * place that opens or closes the preview goes through here so the two can never disagree. The
+   * request is a bare assignment inside the generator, so a pointermove costs nothing extra.
+   */
+  const showPreviewAt = (time: number | undefined) => {
+    setProgressBarOverTime(time)
+    requestThumbnail(time)
+  }
+
   // onChange reports a bare fraction, so the device that opened the gesture is recorded on press
   const dragPointerType = useRef<string | undefined>(undefined)
 
@@ -235,7 +299,7 @@ export const ProgressBar = () => {
     }
     setSeekFraction(fraction)
     if (dragPointerType.current === 'mouse') return
-    setProgressBarOverTime(fraction * duration)
+    showPreviewAt(fraction * duration)
   }
 
   const { dragging, handlers } = useDragValue({ ref: progressBarRef, onChange: onSeekDrag })
@@ -269,7 +333,7 @@ export const ProgressBar = () => {
     pressFraction.current = undefined
     // a lifted finger leaves nothing over the bar, so the preview it opened closes with it
     if (ev.pointerType === 'mouse') return
-    setProgressBarOverTime(undefined)
+    showPreviewAt(undefined)
   }
 
   // offsetX is relative to whichever child is under the pointer, and a captured pointer has none
@@ -281,12 +345,12 @@ export const ProgressBar = () => {
   }
 
   const onProgressBarOver: DOMAttributes<HTMLDivElement>['onMouseMove'] = (ev) => {
-    setProgressBarOverTime(timeAtClientX(ev.clientX))
+    showPreviewAt(timeAtClientX(ev.clientX))
   }
 
   const hideProgressBarTime = () => {
     if (!progressBarRef.current) return
-    setProgressBarOverTime(undefined)
+    showPreviewAt(undefined)
   }
 
   // duration is 0 until metadata lands, which is never a divisor
@@ -313,17 +377,6 @@ export const ProgressBar = () => {
     [duration, indexes.length, downloadedRanges?.map(({ startByteOffset, endByteOffset }) => `${startByteOffset}/${endByteOffset}`).join(',')]
   )
 
-  const cusorTimeString = useMemo(() => {
-    if (!progressBarHoverTime || progressBarHoverTime < 0) return undefined
-    const hours = Math.floor(progressBarHoverTime! / 3600)
-    const minutes = Math.floor((progressBarHoverTime! - hours * 3600) / 60)
-    const seconds = Math.floor(progressBarHoverTime! - hours * 3600 - minutes * 60)
-    const hoursString =
-      hours > 0
-        ? `${hours}:`
-        : ''
-    return `${hoursString}${minutes < 10 ? '0' : ''}${minutes}:${seconds < 10 ? '0' : ''}${seconds}`
-  }, [progressBarHoverTime])
 
   /*
    * Follow the pointer while it is actually moving, and NOT on the press itself.
@@ -346,6 +399,38 @@ export const ProgressBar = () => {
       : currentTime / duration
   }, [duration, currentTime])
 
+  const bounds = useMemo(() => segmentBounds(chapters, duration), [chapters, duration])
+  const segmented = bounds.length > 0
+
+  /*
+   * Which segment the pointer is in, or -1.
+   *
+   * Compared against `undefined` rather than tested for truth: a hover at exactly time zero is a
+   * real hover, and the falsy check used elsewhere in this file silently drops it.
+   */
+  const focusedSegment = useMemo(() => {
+    if (!segmented || progressBarHoverTime === undefined || !duration) return -1
+    const at = (progressBarHoverTime / duration) * 100
+    const found = bounds.findIndex((from, i) => i < bounds.length - 1 && at >= from && at < bounds[i + 1]!)
+    // past the last boundary the pointer is in the final segment, which no `at < to` test catches
+    return found >= 0 ? found : bounds.length - 2
+  }, [segmented, bounds, progressBarHoverTime, duration])
+
+  const restMask = useMemo(
+    () => segmented ? segmentMask(bounds, (i) => i !== focusedSegment) : undefined,
+    [segmented, bounds, focusedSegment],
+  )
+  const focusMask = useMemo(
+    () => focusedSegment >= 0 ? segmentMask(bounds, (i) => i === focusedSegment) : undefined,
+    [bounds, focusedSegment],
+  )
+
+  /** The chapter the pointer is over. Absent while it is over un-named time between chapters. */
+  const hoveredChapter = useMemo(() => {
+    if (progressBarHoverTime === undefined) return undefined
+    return chapters.find(({ start, end }) => start <= progressBarHoverTime && progressBarHoverTime < end)
+  }, [chapters, progressBarHoverTime])
+
   // an empty url is a gap sentinel, so it renders nothing
   const thumbnail = useMemo(() => {
     if (!progressBarHoverTime) return undefined
@@ -359,41 +444,71 @@ export const ProgressBar = () => {
     )
   }, [thumbnails, thumbnailAt, progressBarHoverTime])
 
+  /*
+   * The whole track, drawn once per mask.
+   *
+   * Every layer inside is full bar width whichever mask it carries, so the loaded parts' percentage
+   * offsets and both scaleX transforms keep meaning what they meant before chapters existed. Only
+   * what is painted differs.
+   */
+  const track = (variant: 'focus' | undefined, mask: string | undefined) => (
+    <div
+      className={variant ? `track ${variant}` : 'track'}
+      style={mask ? { maskImage: mask } : undefined}
+    >
+      <div className="background-bar" />
+      {/* bar showing the currently loaded progress */}
+      <div className="loaded">
+        {loadedParts}
+      </div>
+      {/* bar displaying the current playback progress */}
+      <div className="play-container">
+        <div className="play" style={{ transform: `scaleX(${scaleX})` }}></div>
+      </div>
+    </div>
+  )
+
   return (
     <div
       css={style}
       ref={progressBarRef}
-      className={dragging ? 'progress-bar dragging' : 'progress-bar'}
+      className={[
+        'progress-bar',
+        dragging ? 'dragging' : '',
+        segmented ? 'segmented' : '',
+      ].filter(Boolean).join(' ')}
       onMouseMove={onProgressBarOver}
       onMouseOut={hideProgressBarTime}
     >
-      <div className="background-bar" />
+      {track(undefined, restMask)}
       {
         progressBarHoverTime
           ? (
             <div
               className="cursor-time"
               /* the inset grew with the pill: content sized and centred, its half width is now the
-                 padding plus the text, so the old 18px let a filled box hang past both ends */
-              style={{ left: `clamp(calc(3 * var(--mp-unit)), ${timePercentage(progressBarHoverTime)}%, calc(100% - calc(3 * var(--mp-unit))))` }}
+                 padding plus the text, so the old 18px let a filled box hang past both ends. With a
+                 chapter title the box is wider again and capped, so the clamp switches to half that
+                 cap, which is the only width a centred box can be kept inside the bar by. */
+              style={{
+                left: hoveredChapter
+                  ? `clamp(var(--thumbnail-half), ${timePercentage(progressBarHoverTime)}%, calc(100% - var(--thumbnail-half)))`
+                  : `clamp(calc(3 * var(--mp-unit)), ${timePercentage(progressBarHoverTime)}%, calc(100% - calc(3 * var(--mp-unit))))`,
+                maxWidth: hoveredChapter ? 'var(--thumbnail-width)' : undefined,
+              }}
             >
-              {cusorTimeString}
+              <span className="cursor-time-value">{formatTime(progressBarHoverTime)}</span>
+              {hoveredChapter ? <span className="chapter-title">{hoveredChapter.title}</span> : undefined}
             </div>
           )
           : undefined
       }
       <div className="progress"></div>
-      {/* bar showing the currently loaded progress */}
-      <div className="loaded">
-        {loadedParts}
-      </div>
       {/* bar to show when hovering to potentially seek */}
       <div className="hover"></div>
-      {/* bar displaying the current playback progress */}
-      <div className='play-container'>
-        <div className="play" style={{ transform: `scaleX(${scaleX})` }}></div>
-      </div>
-      <div className="chapters"></div>
+      {/* the segment under the pointer, drawn taller. Sits after the flat track so it paints over
+          it, and before .padding so it never takes the press. */}
+      {focusMask ? track('focus', focusMask) : undefined}
       <div className="scrubber"></div>
       <div
         className="padding"