@banou/media-player 0.10.21 → 0.10.22

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

@@ -1,3 +1,4 @@
+import type { PlaybackOutput } from '../../engine';
 import type { MediaPlayerLocalOptions } from '../video-player';
 /**
  * Owns the engine for the life of a source: start, teardown, and every piece of state the pipeline
@@ -5,4 +6,4 @@ import type { MediaPlayerLocalOptions } from '../video-player';
  */
 export declare const usePlayback: (video: HTMLVideoElement | null, subtitles: HTMLElement | null, 
 /** null when the media is remote: there are no bytes, so there is no pipeline to run. */
-options: MediaPlayerLocalOptions | null) => void;
+options: MediaPlayerLocalOptions | null, onOutput?: (output: PlaybackOutput) => void) => void;

package/dist/react/hooks/use-volume-normalizer.d.ts

@@ -1,12 +1,16 @@
 import type { LoudnessSource } from '../../audio/loudness-analysis';
+import type { PlaybackTap } from '../../audio/playback-tap';
 /**
  * Normalizes the element's volume while `enabled`. Nothing is built until it first is, and turning it off
  * afterwards bypasses rather than unroutes, since an element cannot be handed back. `refused` is true once the
  * engine turned the element down, which leaves it playing exactly as before.
  *
  * With a `source`, the file is also analysed ahead of the playhead while it is on, reading only the byte `ranges`
- * given (all of them when undefined).
+ * given (all of them when undefined), or with a `tap`, from the audio playback remuxed.
  */
-export declare const useVolumeNormalizer: (video: HTMLVideoElement | null, workletUrl: string | undefined, enabled: boolean, source?: LoudnessSource, ranges?: [number, number][]) => {
+export declare const useVolumeNormalizer: (video: HTMLVideoElement | null, workletUrl: string | undefined, enabled: boolean, source?: LoudnessSource | {
+    tap: PlaybackTap;
+    audioStreamIndex: number;
+}, ranges?: [number, number][]) => {
     refused: boolean;
 };

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

@@ -6,13 +6,19 @@ import type { ExposePlayerOptions } from '../remote';
 /**
  * The source, read a range at a time: the player never downloads the whole file. Both fields travel
  * together, so passing one without the other is a type error.
+ *
+ * `readsDownload` marks a source each read of which is a download, a file over HTTP, so the volume normalizer
+ * analyses the audio playback fetched instead of reading the file again. Without it, and with no
+ * `downloadedRanges`, every byte is taken to be readable for free, as a local file's are.
  */
 export type MediaPlayerSource = {
     read: (offset: number, size: number) => Promise<ArrayBuffer>;
     size: number;
+    readsDownload?: boolean;
 } | {
     read?: undefined;
     size?: undefined;
+    readsDownload?: undefined;
 };
 /** Shared by both arms: nothing here depends on who owns the media. */
 type CommonOptions = {
@@ -139,7 +145,8 @@ export type MediaPlayerLocalOptions = CommonOptions & MediaPlayerSource & {
      * They are the same by default so generation shares playback's fetch order. A consumer whose
      * reads are not free wants them apart: a torrent hands this a non-prioritising, fail-fast reader
      * so generating previews cannot steal download order from the bytes playback is blocked on. The
-     * analysis asks it only for bytes inside `downloadedRanges`, and with none given, for the whole file.
+     * analysis asks it only for bytes inside `downloadedRanges`, with none given for the whole file, and for
+     * nothing when the source `readsDownload`.
      */
     thumbnailRead?: (offset: number, size: number) => Promise<ArrayBuffer>;
     /** Off entirely. A second wasm worker during pipeline boot is worth avoiding on a slow source. */
@@ -160,7 +167,8 @@ export type MediaPlayerLocalOptions = CommonOptions & MediaPlayerSource & {
      * `onNormalizeVolumeChange` reports and passes it back.
      *
      * While it is on the file is read a second time, in a worker, as far as `downloadedRanges` allows, to find the
-     * loud parts ahead of the playhead. The sound plays 10 ms behind its input, on or off, once routed.
+     * loud parts ahead of the playhead; a source that `readsDownload` is not read again, and its loud parts are found
+     * in what playback fetched. The sound plays 10 ms behind its input, on or off, once routed.
      *
      * The first time it is on, the element is routed through Web Audio for the rest of its life (off then
      * bypasses). If autoplay rules hold the audio back, that waits for the page's next click, tap or key press, and

package/dist/utils/source.d.ts

@@ -15,12 +15,17 @@ declare const fromUrl: ({ url, length: _length, name, credentials }: {
     length: number;
     name: string | undefined;
     read: (offset: number, size: number) => Promise<ArrayBuffer>;
+    readsDownload: boolean;
 }>;
-/** A source resolved down to what the remuxer needs: a total length and a byte-range reader. */
+/**
+ * A source resolved down to what the remuxer needs: a total length and a byte-range reader, and whether each read
+ * is a download, which the player's `readsDownload` takes.
+ */
 export type RemuxerInput = {
     length: number;
     name?: string;
     read: (offset: number, size: number) => Promise<ArrayBuffer>;
+    readsDownload?: boolean;
 };
 export declare const inputToRemuxerInput: (params: Parameters<typeof fromBlob | typeof fromUrl>[0] | {
     length: number;

package/dist/volume-normalizer-worklet.js

@@ -629,12 +629,15 @@ export const createAnalysis = ({ toWorklet, toPage = () => {} }) => {
 }
 
 /*
- * The worker's side: fragments from a second libav remuxer reading the same file, decoded with WebCodecs.
+ * The worker's side: fragments from a second libav remuxer reading the same file, or from playback's own, decoded with
+ * WebCodecs.
  *
  *   { type: 'port', port }                the worklet's end of a MessageChannel, for the blocks
  *   { type: 'init', data, codec }         the init segment and the codec string MediaSource was given
  *   { type: 'run', run, pts, start }      a run of fragments starts, `pts` added to their times as the SourceBuffer's
- *                                         timestampOffset adds it for playback; `start` for the one from the start
+ *                                         timestampOffset adds it for playback; `start` for the one from the start,
+ *                                         and `join: true` for one whose first fragments went by unseen, which starts
+ *                                         at its first sample
  *   { type: 'fragment', run, data }       answered { type: 'ack', run, spans, end, normal } once its audio is queued
  *                                         for decoding: the analysed seconds, the file's end once known, and the
  *                                         level learned so far in LUFS
@@ -651,6 +654,7 @@ const serve = (scope) => {
   let decoder
   let runId = -1
   let pts = 0
+  let joining = false
   const analysis = createAnalysis({
     toWorklet: (message, transfer) => port?.postMessage(message, transfer),
     toPage: (message) => scope.postMessage(message),
@@ -707,10 +711,16 @@ const serve = (scope) => {
       runId = data.run
       pts = data.pts
       open(runId)
-      analysis.startRun(runId, pts, data.start)
+      joining = !!data.join
+      if (!joining) analysis.startRun(runId, pts, data.start)
     } else if (data.type === 'fragment') {
       if (data.run !== runId || decoder.state !== 'configured') return
-      for (const sample of audioSamplesOf(data.data, track)) {
+      const samples = audioSamplesOf(data.data, track)
+      if (joining && samples.length) {
+        joining = false
+        analysis.startRun(runId, pts + samples[0].time / track.timescale)
+      }
+      for (const sample of samples) {
         const time = pts + sample.time / track.timescale
         stamps.push(time)
         decoder.decode(new EncodedAudioChunk({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@banou/media-player",
-  "version": "0.10.21",
+  "version": "0.10.22",
   "description": "A video player for containers and codecs the browser cannot play natively, remuxed on the fly",
   "type": "module",
   "main": "dist/index.js",
@@ -34,12 +34,12 @@
     "types": "tsc -p tsconfig.lib.json",
     "copy-assets": "shx mkdir -p public && npm run copy-libav",
     "copy-libav": "shx cp node_modules/libav-wasm/build/worker.js public/libav-worker.js && shx cp node_modules/libav-wasm/build/libav.wasm public/libav.wasm && shx cp node_modules/libav-wasm/build/libav-jspi.wasm public/libav-jspi.wasm",
-    "test": "npm run fixtures && vp test run",
+    "test": "npm run copy-assets && npm run fixtures && vp test run",
     "fixtures": "node scripts/fixture.mjs"
   },
   "author": "Banou26",
   "dependencies": {
-    "@banou/ponyfill": "^0.0.10",
+    "@banou/ponyfill": "^0.0.12",
     "@videojs/core": "10.0.0-beta.26",
     "@videojs/react": "10.0.0-beta.26",
     "ass-compiler": "^0.1.16",

package/src/lib/audio/loudness-analysis.ts

@@ -1,3 +1,5 @@
+import type { PlaybackTap } from './playback-tap'
+
 import { makeRemuxer } from 'libav-wasm'
 
 import { terminateRemuxer } from '../engine/playback'
@@ -37,12 +39,16 @@ const CLOCK_MS = 50
  * nearest the playhead first, then the rest of the file, and drops nothing it learned on a seek. Until a stretch is
  * analysed, and for the whole file where this browser's WebCodecs cannot decode the track, the worklet's live stage
  * plays.
+ *
+ * Given a `tap` instead, it reads nothing and analyses the audio playback remuxed for `audioStreamIndex`, which runs
+ * as far ahead of the playhead as playback buffers. It starts at the next fragment playback fetches, so what was
+ * buffered before it attached is not analysed.
  */
 export const startLoudnessAnalysis = ({ node, element, scriptUrl, source }: {
   node: AudioWorkletNode
   element: HTMLMediaElement
   scriptUrl: string
-  source: LoudnessSource
+  source: LoudnessSource | { tap: PlaybackTap, audioStreamIndex: number }
 }): LoudnessAnalysis => {
   let stopped = false
   let ranges: [number, number][] | undefined
@@ -54,14 +60,13 @@ export const startLoudnessAnalysis = ({ node, element, scriptUrl, source }: {
   }
   const changed = () => new Promise<void>((resolve) => wakers.add(resolve))
 
-  const readable = (offset: number, size: number) =>
-    !ranges || ranges.some(([from, to]) => from <= offset && Math.min(offset + size, source.length) <= to)
-  const read = async (offset: number, size: number) => {
-    while (!readable(offset, size)) {
+  const read = async (reader: LoudnessSource, offset: number, size: number) => {
+    const end = Math.min(offset + size, reader.length)
+    while (ranges && !ranges.some(([from, to]) => from <= offset && end <= to)) {
       // given up once the task waiting on it has been aborted, or the analysis stopped
       if (stopped || await new Promise<boolean>((resolve) => waiting.add(resolve))) throw new Error('Cancelled')
     }
-    return source.read(offset, size)
+    return reader.read(offset, size)
   }
   const release = (abandon: boolean) => {
     for (const resolve of [...waiting]) resolve(abandon)
@@ -180,14 +185,14 @@ export const startLoudnessAnalysis = ({ node, element, scriptUrl, source }: {
     await acked
   }
 
-  const loop = async () => {
+  const loop = async (reader: LoudnessSource) => {
     remuxer = await makeRemuxer({
-      publicPath: source.publicPath,
-      workerUrl: source.libavWorkerUrl,
+      publicPath: reader.publicPath,
+      workerUrl: reader.libavWorkerUrl,
       workerOptions: { type: 'module' },
-      length: source.length,
-      read,
-      audioStreamIndex: source.audioStreamIndex,
+      length: reader.length,
+      read: (offset, size) => read(reader, offset, size),
+      audioStreamIndex: reader.audioStreamIndex,
     })
     // stopped while it was being made, which stop() could not end
     if (stopped) return terminateRemuxer(remuxer)
@@ -240,6 +245,30 @@ export const startLoudnessAnalysis = ({ node, element, scriptUrl, source }: {
     remuxer = undefined
   }
 
+  let detach = () => {}
+  const follow = (tap: PlaybackTap, audioStreamIndex: number) => {
+    let open = false
+    const end = (finished: boolean) => {
+      if (open) worker.postMessage({ type: 'end', run, finished })
+      open = false
+    }
+    detach = tap.attach(audioStreamIndex, (output, join) => {
+      if (output.type === 'init') {
+        end(false)
+        const data = output.data.slice(0)
+        worker.postMessage({ type: 'init', data, codec: output.audioMimeType }, [data])
+      } else if (output.type === 'run') {
+        end(false)
+        open = true
+        worker.postMessage({ type: 'run', run: ++run, pts: output.pts, start: !join && output.pts <= 0, join })
+      } else if (output.type === 'end') end(true)
+      else if (open) {
+        const data = output.data.slice(0)
+        worker.postMessage({ type: 'fragment', run, data }, [data])
+      }
+    })
+  }
+
   const stop = () => {
     if (stopped) return
     stopped = true
@@ -250,6 +279,7 @@ export const startLoudnessAnalysis = ({ node, element, scriptUrl, source }: {
     element.removeEventListener('seeking', onSeeking)
     element.removeEventListener('seeked', onTime)
     element.removeEventListener('timeupdate', onTime)
+    detach()
     if (remuxer) terminateRemuxer(remuxer)
     worker.terminate()
     node.port.postMessage({ analysis: null })
@@ -257,11 +287,14 @@ export const startLoudnessAnalysis = ({ node, element, scriptUrl, source }: {
     replies.clear()
   }
 
-  loop().catch((error) => {
-    if (stopped) return
-    console.warn('[media-player] the volume normalizer cannot analyse ahead:', error)
-    stop()
-  })
+  if ('tap' in source) follow(source.tap, source.audioStreamIndex)
+  else {
+    loop(source).catch((error) => {
+      if (stopped) return
+      console.warn('[media-player] the volume normalizer cannot analyse ahead:', error)
+      stop()
+    })
+  }
   playhead()
 
   return {

package/src/lib/audio/playback-tap.ts

@@ -0,0 +1,37 @@
+import type { PlaybackOutput } from '../engine/playback'
+
+/**
+ * Playback's output, for an analysis that reads nothing of its own: `push` takes what playback's remuxer produced,
+ * and `attach` hands a listener what follows for one input audio stream, starting with the last init segment and the
+ * run in progress. `join` marks a run some of whose fragments went by before the listener was attached.
+ */
+export type PlaybackTap = {
+  push: (output: PlaybackOutput) => void
+  attach: (audioStreamIndex: number, listener: (output: PlaybackOutput, join?: boolean) => void) => () => void
+}
+
+export const createPlaybackTap = (): PlaybackTap => {
+  let init: Extract<PlaybackOutput, { type: 'init' }> | undefined
+  let run: { pts: number, begun: boolean } | undefined
+  let listener: { audioStreamIndex: number, take: (output: PlaybackOutput, join?: boolean) => void } | undefined
+  const live = () => listener && init?.audioStreamIndex === listener.audioStreamIndex ? listener : undefined
+  return {
+    push: (output) => {
+      if (output.type === 'init') {
+        init = output
+        run = undefined
+      } else if (output.type === 'run') run = { pts: output.pts, begun: false }
+      else if (output.type === 'fragment' && run) run.begun = true
+      live()?.take(output)
+    },
+    attach: (audioStreamIndex, take) => {
+      const mine = { audioStreamIndex, take }
+      listener = mine
+      if (live() && init) {
+        take(init)
+        if (run) take({ type: 'run', pts: run.pts }, run.begun)
+      }
+      return () => { if (listener === mine) listener = undefined }
+    },
+  }
+}

package/src/lib/audio/volume-normalizer-worklet.js

@@ -629,12 +629,15 @@ export const createAnalysis = ({ toWorklet, toPage = () => {} }) => {
 }
 
 /*
- * The worker's side: fragments from a second libav remuxer reading the same file, decoded with WebCodecs.
+ * The worker's side: fragments from a second libav remuxer reading the same file, or from playback's own, decoded with
+ * WebCodecs.
  *
  *   { type: 'port', port }                the worklet's end of a MessageChannel, for the blocks
  *   { type: 'init', data, codec }         the init segment and the codec string MediaSource was given
  *   { type: 'run', run, pts, start }      a run of fragments starts, `pts` added to their times as the SourceBuffer's
- *                                         timestampOffset adds it for playback; `start` for the one from the start
+ *                                         timestampOffset adds it for playback; `start` for the one from the start,
+ *                                         and `join: true` for one whose first fragments went by unseen, which starts
+ *                                         at its first sample
  *   { type: 'fragment', run, data }       answered { type: 'ack', run, spans, end, normal } once its audio is queued
  *                                         for decoding: the analysed seconds, the file's end once known, and the
  *                                         level learned so far in LUFS
@@ -651,6 +654,7 @@ const serve = (scope) => {
   let decoder
   let runId = -1
   let pts = 0
+  let joining = false
   const analysis = createAnalysis({
     toWorklet: (message, transfer) => port?.postMessage(message, transfer),
     toPage: (message) => scope.postMessage(message),
@@ -707,10 +711,16 @@ const serve = (scope) => {
       runId = data.run
       pts = data.pts
       open(runId)
-      analysis.startRun(runId, pts, data.start)
+      joining = !!data.join
+      if (!joining) analysis.startRun(runId, pts, data.start)
     } else if (data.type === 'fragment') {
       if (data.run !== runId || decoder.state !== 'configured') return
-      for (const sample of audioSamplesOf(data.data, track)) {
+      const samples = audioSamplesOf(data.data, track)
+      if (joining && samples.length) {
+        joining = false
+        analysis.startRun(runId, pts + samples[0].time / track.timescale)
+      }
+      for (const sample of samples) {
         const time = pts + sample.time / track.timescale
         stamps.push(time)
         decoder.decode(new EncodedAudioChunk({

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, MediaChapter, AudioStream } from './playback'
+export type { PlaybackOptions, PlaybackController, PlaybackOutput, MediaIndex, MediaChapter, AudioStream } from './playback'
 
 export { createSubtitleRenderer, SUBTITLES_OFF } from './subtitles'
 export type { SubtitleRenderer, SubtitleRendererOptions, SubtitleStream } from './subtitles'

package/src/lib/engine/playback.ts

@@ -23,6 +23,18 @@ export type MediaIndex = { pos: number, timestamp: number }
  */
 export type MediaChapter = { start: number, end: number, title: string }
 
+/**
+ * What the remuxer produced, in the order it was appended: the init segment and the input audio stream it carries,
+ * a run at load and at every remuxer seek (`pts` is the timestampOffset its fragments are appended at), each
+ * fragment, and the end of the file once read. The buffers are playback's own and may be appended again, so a
+ * consumer copies what it keeps.
+ */
+export type PlaybackOutput =
+  | { type: 'init', data: ArrayBuffer, audioMimeType: string, audioStreamIndex: number }
+  | { type: 'run', pts: number }
+  | { type: 'fragment', data: ArrayBuffer }
+  | { type: 'end' }
+
 export type PlaybackOptions = {
   videoElement: HTMLVideoElement
   /**
@@ -51,6 +63,7 @@ export type PlaybackOptions = {
   onSeek?: (fraction: number) => void
   onSubtitleStreams?: (streams: SubtitleStream[]) => void
   onAudioStreams?: (streams: AudioStream[], selected: number) => void
+  onOutput?: (output: PlaybackOutput) => void
 }
 
 export type PlaybackController = {
@@ -146,7 +159,7 @@ export const startPlayback = async (options: PlaybackOptions): Promise<PlaybackC
     videoElement, subtitleContainer, read, length, publicPath, libavWorkerUrl,
     jassubWorkerUrl, jassubWasmUrl, jassubLegacyWasmUrl, defaultFontUrl, bufferSize = DEFAULT_BUFFER_SIZE,
     audioStreamIndex, onReady, onError, onRecovered, onSeek, onSubtitleStreams,
-    onAudioStreams,
+    onAudioStreams, onOutput,
   } = options
 
   const remuxer = await makeRemuxer({
@@ -253,6 +266,8 @@ export const startPlayback = async (options: PlaybackOptions): Promise<PlaybackC
 
     const { appendBuffer, unbufferRange, updateTimestampOffset, endOfStream } = updateSourceBuffer(sourceBuffer, mediaSource)
     await appendBuffer(metadata.data)
+    onOutput?.({ type: 'init', data: metadata.data, audioMimeType: metadata.info.output.audioMimeType, audioStreamIndex: selectedAudio })
+    onOutput?.({ type: 'run', pts: 0 })
     if (metadata.subtitles?.length) subtitles.pushFragments(metadata.subtitles)
     onReady?.()
 
@@ -400,6 +415,9 @@ export const startPlayback = async (options: PlaybackOptions): Promise<PlaybackC
         if (fragments?.length) subtitles.pushFragments(fragments)
         await updateTimestampOffset(pts)
         if (destroyed || generation !== seekGeneration) return
+        onOutput?.({ type: 'run', pts })
+        if (data.byteLength) onOutput?.({ type: 'fragment', data })
+        if (done) onOutput?.({ type: 'end' })
         if (data.byteLength) {
           await appendBuffer(data)
           trackAppendedEnd()
@@ -458,6 +476,8 @@ export const startPlayback = async (options: PlaybackOptions): Promise<PlaybackC
           if (stale()) return
           if (done) finished = true
           if (fragments?.length) subtitles.pushFragments(fragments)
+          if (data.byteLength) onOutput?.({ type: 'fragment', data })
+          if (done) onOutput?.({ type: 'end' })
           if (!data.byteLength) return
           pending = data
           pendingAttempts = 0

package/src/lib/index.tsx

@@ -43,6 +43,7 @@ export type {
   PictureInPictureController,
   PlaybackController,
   PlaybackOptions,
+  PlaybackOutput,
   SubtitleStream,
   ThumbnailImage,
 } from './engine'

package/src/lib/react/hooks/use-playback.ts

@@ -1,4 +1,4 @@
-import type { PlaybackController } from '../../engine'
+import type { PlaybackController, PlaybackOutput } from '../../engine'
 import type { PlaybackErrorEntry } from '../source-feature'
 import type { MediaPlayerLocalOptions } from '../video-player'
 
@@ -74,6 +74,7 @@ export const usePlayback = (
   subtitles: HTMLElement | null,
   /** null when the media is remote: there are no bytes, so there is no pipeline to run. */
   options: MediaPlayerLocalOptions | null,
+  onOutput?: (output: PlaybackOutput) => void,
 ) => {
   const player = usePlayer()
   // The four asset urls are required on the local arm, so a default only ever applies when options is
@@ -147,6 +148,8 @@ export const usePlayback = (
   onSeekRef.current = options?.onSeek
   const onPlaybackErrorRef = useRef(options?.onPlaybackError)
   onPlaybackErrorRef.current = options?.onPlaybackError
+  const onOutputRef = useRef(onOutput)
+  onOutputRef.current = onOutput
 
   // The store's ids are opaque, but everything this hook writes into it came from libav, so every id
   // that comes back is one of its own stream indices.
@@ -355,6 +358,7 @@ export const usePlayback = (
           onError: fail,
           onRecovered: () => { if (!cancelled) player.setSourceState({ playbackError: null }) },
           onSeek: (fraction) => onSeekRef.current?.(fraction),
+          onOutput: (output) => onOutputRef.current?.(output),
           onSubtitleStreams: (streams) => {
             if (cancelled) return
             player.setSourceState({

package/src/lib/react/hooks/use-volume-normalizer.ts

@@ -1,5 +1,6 @@
 import type { VolumeNormalizer } from '../../audio/volume-normalizer'
 import type { LoudnessSource } from '../../audio/loudness-analysis'
+import type { PlaybackTap } from '../../audio/playback-tap'
 
 import { useEffect, useRef, useState } from 'react'
 
@@ -12,13 +13,13 @@ import { startLoudnessAnalysis } from '../../audio/loudness-analysis'
  * engine turned the element down, which leaves it playing exactly as before.
  *
  * With a `source`, the file is also analysed ahead of the playhead while it is on, reading only the byte `ranges`
- * given (all of them when undefined).
+ * given (all of them when undefined), or with a `tap`, from the audio playback remuxed.
  */
 export const useVolumeNormalizer = (
   video: HTMLVideoElement | null,
   workletUrl: string | undefined,
   enabled: boolean,
-  source?: LoudnessSource,
+  source?: LoudnessSource | { tap: PlaybackTap, audioStreamIndex: number },
   ranges?: [number, number][],
 ) => {
   const handle = useRef<VolumeNormalizer | null>(null)
@@ -53,7 +54,9 @@ export const useVolumeNormalizer = (
   const analysis = useRef<ReturnType<typeof startLoudnessAnalysis> | null>(null)
   const sourceRef = useRef(source)
   sourceRef.current = source
-  const { length, publicPath, libavWorkerUrl, audioStreamIndex } = source ?? {}
+  const { length, publicPath, libavWorkerUrl } = source && 'read' in source ? source : {}
+  const tap = source && 'tap' in source ? source.tap : undefined
+  const audioStreamIndex = source?.audioStreamIndex
   useEffect(() => {
     const current = sourceRef.current
     if (!node || !video || !workletUrl || !enabled || !current) return
@@ -64,7 +67,7 @@ export const useVolumeNormalizer = (
       started.stop()
       analysis.current = null
     }
-  }, [node, video, workletUrl, enabled, length, publicPath, libavWorkerUrl, audioStreamIndex])
+  }, [node, video, workletUrl, enabled, length, publicPath, libavWorkerUrl, audioStreamIndex, tap])
 
   useEffect(() => { analysis.current?.update(ranges) }, [ranges])
 

package/src/lib/react/video-player.tsx

@@ -15,15 +15,20 @@ import { useSeekThumbnails } from './hooks/use-thumbnails'
 import { usePictureInPicture } from './hooks/use-picture-in-picture'
 import { usePassThroughPictureInPicture } from './hooks/use-pass-through-picture-in-picture'
 import { useVolumeNormalizer } from './hooks/use-volume-normalizer'
+import { createPlaybackTap } from '../audio/playback-tap'
 import Chrome from './components/chrome'
 
 /**
  * The source, read a range at a time: the player never downloads the whole file. Both fields travel
  * together, so passing one without the other is a type error.
+ *
+ * `readsDownload` marks a source each read of which is a download, a file over HTTP, so the volume normalizer
+ * analyses the audio playback fetched instead of reading the file again. Without it, and with no
+ * `downloadedRanges`, every byte is taken to be readable for free, as a local file's are.
  */
 export type MediaPlayerSource =
-  | { read: (offset: number, size: number) => Promise<ArrayBuffer>, size: number }
-  | { read?: undefined, size?: undefined }
+  | { read: (offset: number, size: number) => Promise<ArrayBuffer>, size: number, readsDownload?: boolean }
+  | { read?: undefined, size?: undefined, readsDownload?: undefined }
 
 /** Shared by both arms: nothing here depends on who owns the media. */
 type CommonOptions = {
@@ -161,7 +166,8 @@ export type MediaPlayerLocalOptions =
      * They are the same by default so generation shares playback's fetch order. A consumer whose
      * reads are not free wants them apart: a torrent hands this a non-prioritising, fail-fast reader
      * so generating previews cannot steal download order from the bytes playback is blocked on. The
-     * analysis asks it only for bytes inside `downloadedRanges`, and with none given, for the whole file.
+     * analysis asks it only for bytes inside `downloadedRanges`, with none given for the whole file, and for
+     * nothing when the source `readsDownload`.
      */
     thumbnailRead?: (offset: number, size: number) => Promise<ArrayBuffer>
     /** Off entirely. A second wasm worker during pipeline boot is worth avoiding on a slow source. */
@@ -183,7 +189,8 @@ export type MediaPlayerLocalOptions =
      * `onNormalizeVolumeChange` reports and passes it back.
      *
      * While it is on the file is read a second time, in a worker, as far as `downloadedRanges` allows, to find the
-     * loud parts ahead of the playhead. The sound plays 10 ms behind its input, on or off, once routed.
+     * loud parts ahead of the playhead; a source that `readsDownload` is not read again, and its loud parts are found
+     * in what playback fetched. The sound plays 10 ms behind its input, on or off, once routed.
      *
      * The first time it is on, the element is routed through Web Audio for the rest of its life (off then
      * bypasses). If autoplay rules hold the audio back, that waits for the page's next click, tap or key press, and
@@ -250,7 +257,7 @@ const PlayerRoot = ({ options, children }: { options: MediaPlayerOptions, childr
   // local arm and is absent when the media is remote.
   const { title, chapters } = options
   const {
-    size, downloadedRanges, publicPath, libavWorkerUrl, read, thumbnailRead, thumbnailsEnabled,
+    size, downloadedRanges, publicPath, libavWorkerUrl, read, thumbnailRead, thumbnailsEnabled, readsDownload,
   } = local ?? ({} as Partial<MediaPlayerLocalOptions>)
 
   const setMedia = useMediaAttach()
@@ -298,9 +305,12 @@ const PlayerRoot = ({ options, children }: { options: MediaPlayerOptions, childr
     return () => { dropped = true; stop?.() }
   }, [media, !!expose, exposeId, exposeOrigin, exposeChannel])
 
+  // one per file, as `size` is the source's identity everywhere here
+  const tap = useMemo(() => createPlaybackTap(), [size])
+
   // Each of these no-ops on null inputs, which is what a remote arm supplies: it renders no <video>,
   // so there is nothing for them to attach to and nothing to guard at the call site.
-  usePlayback(video, subtitleLayer, local)
+  usePlayback(video, subtitleLayer, local, readsDownload ? tap.push : undefined)
 
   const normalizeVolumeProp = local?.normalizeVolume ?? true
   const [normalizeVolume, setNormalizeVolume] = useState(normalizeVolumeProp)
@@ -315,15 +325,17 @@ const PlayerRoot = ({ options, children }: { options: MediaPlayerOptions, childr
   const hasRead = !!read
   const normalizerSource = useMemo(
     () => hasRead && size && publicPath && libavWorkerUrl && typeof playingAudio === 'number' && playingAudio >= 0
-      ? {
-        read: (offset: number, length: number) => analysisRead.current!(offset, length),
-        length: size,
-        publicPath,
-        libavWorkerUrl,
-        audioStreamIndex: playingAudio,
-      }
+      ? readsDownload
+        ? { tap, audioStreamIndex: playingAudio }
+        : {
+          read: (offset: number, length: number) => analysisRead.current!(offset, length),
+          length: size,
+          publicPath,
+          libavWorkerUrl,
+          audioStreamIndex: playingAudio,
+        }
       : undefined,
-    [hasRead, size, publicPath, libavWorkerUrl, playingAudio],
+    [hasRead, size, publicPath, libavWorkerUrl, playingAudio, readsDownload, tap],
   )
   const normalizerRanges = useMemo(
     () => downloadedRanges?.map(({ startByteOffset, endByteOffset }) => [startByteOffset, endByteOffset] as [number, number]),

package/src/lib/utils/source.ts

@@ -42,14 +42,18 @@ const fromUrl = async (
     if (!response.ok) throw new Error(`The source could not be read: HTTP ${response.status}`)
     return response.arrayBuffer()
   }
-  return { length, name, read }
+  return { length, name, read, readsDownload: true }
 }
 
-/** A source resolved down to what the remuxer needs: a total length and a byte-range reader. */
+/**
+ * A source resolved down to what the remuxer needs: a total length and a byte-range reader, and whether each read
+ * is a download, which the player's `readsDownload` takes.
+ */
 export type RemuxerInput = {
   length: number
   name?: string
   read: (offset: number, size: number) => Promise<ArrayBuffer>
+  readsDownload?: boolean
 }
 
 export const inputToRemuxerInput = async (