@banou/media-player 0.10.9 → 0.10.11

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

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+export declare const useVolumeNormalizer: (video: HTMLVideoElement | null, workletUrl: string | undefined, enabled: boolean) => {
+    refused: boolean;
+};

package/dist/react/player.d.ts

@@ -22,6 +22,7 @@ export declare const Player: import("@videojs/react").CreatePlayerResult<import(
     passThroughPictureInPicture: import("./source-feature").PassThroughControl | null;
     pictureInPictureMode: import("../engine").PictureInPictureMode | null;
     burnedInSubtitles: boolean;
+    volumeNormalizer: import("./source-feature").VolumeNormalizerControl | null;
     requestSeek?: (time: number) => void;
     playbackError: unknown;
     playbackErrors: import("./source-feature").PlaybackErrorEntry[];

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

@@ -90,6 +90,13 @@ export type PassThroughControl = {
     /** Leaves picture in picture through the media. */
     exit: () => void;
 };
+/** The settings menu's volume normalizer switch, for a player that offers one (see `normalizeVolume`). */
+export type VolumeNormalizerControl = {
+    enabled: boolean;
+    /** False once the engine refused to route the element, which then plays exactly as it did. */
+    available: boolean;
+    setEnabled: (enabled: boolean) => void;
+};
 /**
  * Everything about the source that the chrome reads, carried on the player store next to the built-in
  * playback state so a component never has to know which of two channels owns a field.
@@ -194,6 +201,8 @@ export type SourceState = {
     pictureInPictureMode: PictureInPictureMode | null;
     /** Burn-in only. True while the composite is the picture on screen. */
     burnedInSubtitles: boolean;
+    /** null when the player offers no volume normalizer: a media it does not own, or no `normalizerWorkletUrl`. */
+    volumeNormalizer: VolumeNormalizerControl | null;
     /**
      * Move the playhead, letting the pipeline get the data there first.
      *
@@ -337,6 +346,8 @@ export declare const sourceFeature: import("@videojs/react").PlayerFeature<{
     pictureInPictureMode: PictureInPictureMode | null;
     /** Burn-in only. True while the composite is the picture on screen. */
     burnedInSubtitles: boolean;
+    /** null when the player offers no volume normalizer: a media it does not own, or no `normalizerWorkletUrl`. */
+    volumeNormalizer: VolumeNormalizerControl | null;
     /**
      * Move the playhead, letting the pipeline get the data there first.
      *

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

@@ -136,6 +136,30 @@ export type MediaPlayerLocalOptions = CommonOptions & MediaPlayerSource & {
     thumbnailRead?: (offset: number, size: number) => Promise<ArrayBuffer>;
     /** Off entirely. A second wasm worker during pipeline boot is worth avoiding on a slow source. */
     thumbnailsEnabled?: boolean;
+    /**
+     * Where this package's `volume-normalizer-worklet.js` is served, a plain script to copy or import as a url
+     * (`@banou/media-player/volume-normalizer-worklet.js?no-inline&url` with vite). Without it the settings menu
+     * offers no volume normalizer.
+     *
+     * A url and not a blob, because a page whose CSP says `script-src 'self'` refuses a worklet module from a
+     * `blob:` or `data:` url, and `build.lib` inlines an asset as `data:` unless told otherwise.
+     */
+    normalizerWorkletUrl?: string;
+    /**
+     * The settings menu's "Normalize volume" switch: holds the loudness steady, so a music cue is turned down to
+     * the dialogue around it. Off by default. The player keeps the switch's state from here and from the viewer's
+     * clicks; nothing is saved, so an app that wants it to stick saves what `onNormalizeVolumeChange` reports and
+     * passes it back.
+     *
+     * 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
+     * the video plays as before meanwhile. Where the engine refuses the routing (WebKit), it does so when routing
+     * would happen, once the switch is on and the context runs: the switch reads Unavailable from then on, and
+     * the element is never routed.
+     */
+    normalizeVolume?: boolean;
+    /** The viewer flipped the switch. */
+    onNormalizeVolumeChange?: (normalizeVolume: boolean) => void;
 };
 /**
  * A media the caller owns and the player only drives.

package/dist/volume-normalizer-worklet.js

@@ -0,0 +1,162 @@
+/*
+ * The volume normalizer's AudioWorkletProcessor, served to the browser as it is written: plain script, no imports,
+ * nothing a bundler has to touch. Holds EBU short-term loudness (K-weighted, ITU-R BS.1770, gated) at a target by
+ * turning the gain down, never up, so it needs no limiter and adds no delay.
+ *
+ * processorOptions, every one optional:
+ *   targetLufs      -24   short-term loudness held, typical anime dialogue
+ *   enabled         true  false starts it bypassed
+ *   inputGainDb     0     gain already applied upstream (the element's volume), judged without
+ *
+ * Port messages: `{ enabled }` bypasses or engages with a 50 ms crossfade, `{ inputGainDb }` follows the volume,
+ * `{ reset: 'seek' }` empties the loudness window, so the new position is judged on its own while the gain holds
+ * until three blocks have refilled it, and `{ reset: 'source' }` also returns the gain to 0 dB, because nothing
+ * heard so far says anything about a new file.
+ */
+
+const BLOCK_SECONDS = 0.1
+const WINDOW_SECONDS = 3
+const MAX_CUT_DB = 20
+// time constants of a cut and of a recovery
+const ATTACK_SECONDS = 0.25
+const RELEASE_SECONDS = 1
+// 100 ms blocks quieter than this are left out, so a pause holds the gain
+const GATE_LUFS = -50
+
+// ITU-R BS.1770 K-weighting at any sample rate, in the bilinear form libebur128 uses
+const kWeighting = (rate) => {
+  let f0 = 1681.974450955533
+  const G = 3.999843853973347
+  let Q = 0.7071752369554196
+  let K = Math.tan(Math.PI * f0 / rate)
+  const Vh = Math.pow(10, G / 20)
+  const Vb = Math.pow(Vh, 0.4996667741545416)
+  let a0 = 1 + K / Q + K * K
+  const shelf = [
+    (Vh + Vb * K / Q + K * K) / a0, 2 * (K * K - Vh) / a0, (Vh - Vb * K / Q + K * K) / a0,
+    2 * (K * K - 1) / a0, (1 - K / Q + K * K) / a0,
+  ]
+  f0 = 38.13547087602444
+  Q = 0.5003270373238773
+  K = Math.tan(Math.PI * f0 / rate)
+  a0 = 1 + K / Q + K * K
+  const highpass = [1, -2, 1, 2 * (K * K - 1) / a0, (1 - K / Q + K * K) / a0]
+  return { shelf, highpass }
+}
+
+// BS.1770 channel weights in WAVE order: the LFE counts for nothing, the surrounds for +1.5 dB
+const channelWeight = (index, count) => count >= 6 ? [1, 1, 1, 0, 1.41, 1.41, 1.41, 1.41][index] ?? 1 : 1
+
+class VolumeNormalizer extends AudioWorkletProcessor {
+  constructor({ processorOptions = {} } = {}) {
+    super()
+    const option = (key, fallback) => typeof processorOptions[key] === 'number' ? processorOptions[key] : fallback
+    this.target = option('targetLufs', -24)
+    this.enabled = processorOptions.enabled !== false
+    this.mix = this.enabled ? 1 : 0
+    this.inputPower = Math.pow(10, option('inputGainDb', 0) / 10)
+
+    this.coefficients = kWeighting(sampleRate)
+    this.filterState = []
+    this.blockLength = Math.round(sampleRate * BLOCK_SECONDS)
+    this.blockFill = 0
+    this.blockSum = 0
+    // mean square of each block in the window, or -1 for a block the gate left out
+    this.blocks = new Float64Array(Math.round(WINDOW_SECONDS / BLOCK_SECONDS)).fill(-1)
+    this.blockIndex = 0
+    this.desiredDb = 0
+    this.gainDb = 0
+    this.appliedGain = 1
+    this.energy = new Float32Array(128)
+
+    this.port.onmessage = ({ data }) => {
+      if (typeof data?.enabled === 'boolean') this.enabled = data.enabled
+      if (typeof data?.inputGainDb === 'number') this.inputPower = Math.pow(10, data.inputGainDb / 10)
+      if (data?.reset === 'seek' || data?.reset === 'source') {
+        this.blocks.fill(-1)
+        this.blockSum = 0
+        this.blockFill = 0
+      }
+      if (data?.reset === 'source') {
+        this.desiredDb = 0
+        this.gainDb = 0
+      }
+    }
+  }
+
+  closeBlock() {
+    const meanSquare = this.blockSum / this.blockLength / this.inputPower
+    this.blocks[this.blockIndex] = -0.691 + 10 * Math.log10(meanSquare) >= GATE_LUFS ? meanSquare : -1
+    this.blockIndex = (this.blockIndex + 1) % this.blocks.length
+    this.blockSum = 0
+    this.blockFill = 0
+
+    let sum = 0
+    let active = 0
+    for (const block of this.blocks) {
+      if (block >= 0) { sum += block; active++ }
+    }
+    // fewer than three blocks with anything in them is a pause, and the gain holds where it is
+    if (active < 3) return
+    const level = -0.691 + 10 * Math.log10(sum / active)
+    this.desiredDb = Math.max(-MAX_CUT_DB, Math.min(0, this.target - level))
+  }
+
+  process(inputs, outputs) {
+    const input = inputs[0]
+    const output = outputs[0]
+    const frames = output[0].length
+    const channels = input.length
+    if (channels === 0) {
+      for (const channel of output) channel.fill(0)
+      return true
+    }
+
+    if (this.energy.length < frames) this.energy = new Float32Array(frames)
+    const energy = this.energy
+    energy.fill(0, 0, frames)
+    const [b0, b1, b2, a1, a2] = this.coefficients.shelf
+    const [c0, c1, c2, d1, d2] = this.coefficients.highpass
+    for (let c = 0; c < channels; c++) {
+      const weight = channelWeight(c, channels)
+      if (!this.filterState[c]) this.filterState[c] = new Float64Array(4)
+      if (weight === 0) continue
+      const state = this.filterState[c]
+      let s1 = state[0], s2 = state[1], t1 = state[2], t2 = state[3]
+      const x = input[c]
+      for (let i = 0; i < frames; i++) {
+        const v = x[i]
+        const y = b0 * v + s1
+        s1 = b1 * v - a1 * y + s2
+        s2 = b2 * v - a2 * y
+        const z = c0 * y + t1
+        t1 = c1 * y - d1 * z + t2
+        t2 = c2 * y - d2 * z
+        energy[i] += weight * z * z
+      }
+      state[0] = s1; state[1] = s2; state[2] = t1; state[3] = t2
+    }
+    for (let i = 0; i < frames; i++) {
+      this.blockSum += energy[i]
+      if (++this.blockFill === this.blockLength) this.closeBlock()
+    }
+
+    const seconds = frames / sampleRate
+    const tau = this.desiredDb < this.gainDb ? ATTACK_SECONDS : RELEASE_SECONDS
+    this.gainDb += (this.desiredDb - this.gainDb) * (1 - Math.exp(-seconds / tau))
+    const crossfade = seconds / 0.05
+    this.mix += Math.max(-crossfade, Math.min(crossfade, (this.enabled ? 1 : 0) - this.mix))
+    const from = this.appliedGain
+    const to = Math.pow(10, this.gainDb * this.mix / 20)
+    this.appliedGain = to
+    const step = (to - from) / frames
+    for (let c = 0; c < output.length; c++) {
+      const x = input[c] ?? input[0]
+      const y = output[c]
+      for (let i = 0; i < frames; i++) y[i] = x[i] * (from + step * (i + 1))
+    }
+    return true
+  }
+}
+
+registerProcessor('banou-volume-normalizer', VolumeNormalizer)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@banou/media-player",
-  "version": "0.10.9",
+  "version": "0.10.11",
   "description": "A video player for containers and codecs the browser cannot play natively, remuxed on the fly",
   "type": "module",
   "main": "dist/index.js",
@@ -18,6 +18,7 @@
       "types": "./dist/remote/index.d.ts",
       "import": "./dist/remote/index.js"
     },
+    "./volume-normalizer-worklet.js": "./dist/volume-normalizer-worklet.js",
     "./package.json": "./package.json"
   },
   "files": [
@@ -31,7 +32,7 @@
     "dev": "npm run copy-assets && vp dev --port 4560",
     "build": "shx rm -rf build/ && npm run copy-assets && vp build",
     "preview": "vp preview",
-    "build-lib": "shx rm -rf dist/ && vp build -c vite.lib.config.ts && npm run types",
+    "build-lib": "shx rm -rf dist/ && vp build -c vite.lib.config.ts && shx cp src/lib/audio/volume-normalizer-worklet.js dist/ && npm run types",
     "prepublishOnly": "npm run build-lib",
     "types": "tsc -p tsconfig.lib.json",
     "copy-assets": "shx mkdir -p public && npm run copy-libav",
@@ -41,6 +42,7 @@
   },
   "author": "Banou26",
   "dependencies": {
+    "@banou/ponyfill": "^0.0.10",
     "@videojs/core": "10.0.0-beta.26",
     "@videojs/react": "10.0.0-beta.26",
     "ass-compiler": "^0.1.16",

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

@@ -0,0 +1,162 @@
+/*
+ * The volume normalizer's AudioWorkletProcessor, served to the browser as it is written: plain script, no imports,
+ * nothing a bundler has to touch. Holds EBU short-term loudness (K-weighted, ITU-R BS.1770, gated) at a target by
+ * turning the gain down, never up, so it needs no limiter and adds no delay.
+ *
+ * processorOptions, every one optional:
+ *   targetLufs      -24   short-term loudness held, typical anime dialogue
+ *   enabled         true  false starts it bypassed
+ *   inputGainDb     0     gain already applied upstream (the element's volume), judged without
+ *
+ * Port messages: `{ enabled }` bypasses or engages with a 50 ms crossfade, `{ inputGainDb }` follows the volume,
+ * `{ reset: 'seek' }` empties the loudness window, so the new position is judged on its own while the gain holds
+ * until three blocks have refilled it, and `{ reset: 'source' }` also returns the gain to 0 dB, because nothing
+ * heard so far says anything about a new file.
+ */
+
+const BLOCK_SECONDS = 0.1
+const WINDOW_SECONDS = 3
+const MAX_CUT_DB = 20
+// time constants of a cut and of a recovery
+const ATTACK_SECONDS = 0.25
+const RELEASE_SECONDS = 1
+// 100 ms blocks quieter than this are left out, so a pause holds the gain
+const GATE_LUFS = -50
+
+// ITU-R BS.1770 K-weighting at any sample rate, in the bilinear form libebur128 uses
+const kWeighting = (rate) => {
+  let f0 = 1681.974450955533
+  const G = 3.999843853973347
+  let Q = 0.7071752369554196
+  let K = Math.tan(Math.PI * f0 / rate)
+  const Vh = Math.pow(10, G / 20)
+  const Vb = Math.pow(Vh, 0.4996667741545416)
+  let a0 = 1 + K / Q + K * K
+  const shelf = [
+    (Vh + Vb * K / Q + K * K) / a0, 2 * (K * K - Vh) / a0, (Vh - Vb * K / Q + K * K) / a0,
+    2 * (K * K - 1) / a0, (1 - K / Q + K * K) / a0,
+  ]
+  f0 = 38.13547087602444
+  Q = 0.5003270373238773
+  K = Math.tan(Math.PI * f0 / rate)
+  a0 = 1 + K / Q + K * K
+  const highpass = [1, -2, 1, 2 * (K * K - 1) / a0, (1 - K / Q + K * K) / a0]
+  return { shelf, highpass }
+}
+
+// BS.1770 channel weights in WAVE order: the LFE counts for nothing, the surrounds for +1.5 dB
+const channelWeight = (index, count) => count >= 6 ? [1, 1, 1, 0, 1.41, 1.41, 1.41, 1.41][index] ?? 1 : 1
+
+class VolumeNormalizer extends AudioWorkletProcessor {
+  constructor({ processorOptions = {} } = {}) {
+    super()
+    const option = (key, fallback) => typeof processorOptions[key] === 'number' ? processorOptions[key] : fallback
+    this.target = option('targetLufs', -24)
+    this.enabled = processorOptions.enabled !== false
+    this.mix = this.enabled ? 1 : 0
+    this.inputPower = Math.pow(10, option('inputGainDb', 0) / 10)
+
+    this.coefficients = kWeighting(sampleRate)
+    this.filterState = []
+    this.blockLength = Math.round(sampleRate * BLOCK_SECONDS)
+    this.blockFill = 0
+    this.blockSum = 0
+    // mean square of each block in the window, or -1 for a block the gate left out
+    this.blocks = new Float64Array(Math.round(WINDOW_SECONDS / BLOCK_SECONDS)).fill(-1)
+    this.blockIndex = 0
+    this.desiredDb = 0
+    this.gainDb = 0
+    this.appliedGain = 1
+    this.energy = new Float32Array(128)
+
+    this.port.onmessage = ({ data }) => {
+      if (typeof data?.enabled === 'boolean') this.enabled = data.enabled
+      if (typeof data?.inputGainDb === 'number') this.inputPower = Math.pow(10, data.inputGainDb / 10)
+      if (data?.reset === 'seek' || data?.reset === 'source') {
+        this.blocks.fill(-1)
+        this.blockSum = 0
+        this.blockFill = 0
+      }
+      if (data?.reset === 'source') {
+        this.desiredDb = 0
+        this.gainDb = 0
+      }
+    }
+  }
+
+  closeBlock() {
+    const meanSquare = this.blockSum / this.blockLength / this.inputPower
+    this.blocks[this.blockIndex] = -0.691 + 10 * Math.log10(meanSquare) >= GATE_LUFS ? meanSquare : -1
+    this.blockIndex = (this.blockIndex + 1) % this.blocks.length
+    this.blockSum = 0
+    this.blockFill = 0
+
+    let sum = 0
+    let active = 0
+    for (const block of this.blocks) {
+      if (block >= 0) { sum += block; active++ }
+    }
+    // fewer than three blocks with anything in them is a pause, and the gain holds where it is
+    if (active < 3) return
+    const level = -0.691 + 10 * Math.log10(sum / active)
+    this.desiredDb = Math.max(-MAX_CUT_DB, Math.min(0, this.target - level))
+  }
+
+  process(inputs, outputs) {
+    const input = inputs[0]
+    const output = outputs[0]
+    const frames = output[0].length
+    const channels = input.length
+    if (channels === 0) {
+      for (const channel of output) channel.fill(0)
+      return true
+    }
+
+    if (this.energy.length < frames) this.energy = new Float32Array(frames)
+    const energy = this.energy
+    energy.fill(0, 0, frames)
+    const [b0, b1, b2, a1, a2] = this.coefficients.shelf
+    const [c0, c1, c2, d1, d2] = this.coefficients.highpass
+    for (let c = 0; c < channels; c++) {
+      const weight = channelWeight(c, channels)
+      if (!this.filterState[c]) this.filterState[c] = new Float64Array(4)
+      if (weight === 0) continue
+      const state = this.filterState[c]
+      let s1 = state[0], s2 = state[1], t1 = state[2], t2 = state[3]
+      const x = input[c]
+      for (let i = 0; i < frames; i++) {
+        const v = x[i]
+        const y = b0 * v + s1
+        s1 = b1 * v - a1 * y + s2
+        s2 = b2 * v - a2 * y
+        const z = c0 * y + t1
+        t1 = c1 * y - d1 * z + t2
+        t2 = c2 * y - d2 * z
+        energy[i] += weight * z * z
+      }
+      state[0] = s1; state[1] = s2; state[2] = t1; state[3] = t2
+    }
+    for (let i = 0; i < frames; i++) {
+      this.blockSum += energy[i]
+      if (++this.blockFill === this.blockLength) this.closeBlock()
+    }
+
+    const seconds = frames / sampleRate
+    const tau = this.desiredDb < this.gainDb ? ATTACK_SECONDS : RELEASE_SECONDS
+    this.gainDb += (this.desiredDb - this.gainDb) * (1 - Math.exp(-seconds / tau))
+    const crossfade = seconds / 0.05
+    this.mix += Math.max(-crossfade, Math.min(crossfade, (this.enabled ? 1 : 0) - this.mix))
+    const from = this.appliedGain
+    const to = Math.pow(10, this.gainDb * this.mix / 20)
+    this.appliedGain = to
+    const step = (to - from) / frames
+    for (let c = 0; c < output.length; c++) {
+      const x = input[c] ?? input[0]
+      const y = output[c]
+      for (let i = 0; i < frames; i++) y[i] = x[i] * (from + step * (i + 1))
+    }
+    return true
+  }
+}
+
+registerProcessor('banou-volume-normalizer', VolumeNormalizer)

package/src/lib/audio/volume-normalizer.ts

@@ -0,0 +1,147 @@
+import { createMediaElementSource } from '@banou/ponyfill/web-audio'
+
+/** The worklet's processorOptions, read once when the node is made; its header has the defaults. */
+export type VolumeNormalizerOptions = {
+  targetLufs?: number
+  enabled?: boolean
+  inputGainDb?: number
+}
+
+/** The worklet at `workletUrl`, as a node. A context takes the module once: make a node per context. */
+export const createVolumeNormalizerNode = async (
+  context: BaseAudioContext,
+  workletUrl: string,
+  options: VolumeNormalizerOptions = {},
+) => {
+  await context.audioWorklet.addModule(workletUrl)
+  return new AudioWorkletNode(context, 'banou-volume-normalizer', {
+    // with one input, one output and no outputChannelCount, the output follows the input's channels
+    channelCountMode: 'max',
+    processorOptions: options,
+  })
+}
+
+export type VolumeNormalizer = {
+  context: AudioContext
+  /** Settles once the element is routed, which waits for the context to run. Rejects if it never can be. */
+  routed: Promise<AudioWorkletNode>
+  /** Engage or bypass. A routed element stays routed: it cannot be handed back. */
+  setEnabled: (enabled: boolean) => void
+  /**
+   * For an element going away. One still in the document has its context suspended, and attaching it again resumes
+   * it. One out of the document is gone for good, so its context is closed.
+   */
+  release: () => void
+}
+
+const attached = new WeakMap<HTMLMediaElement, VolumeNormalizer & { wake: () => void }>()
+
+const running = (context: AudioContext) => new Promise<void>((resolve, reject) => {
+  const check = () => {
+    if (context.state !== 'running' && context.state !== 'closed') return
+    context.removeEventListener('statechange', check)
+    if (context.state === 'running') resolve()
+    else reject(new DOMException('The AudioContext closed before it ran', 'InvalidStateError'))
+  }
+  context.addEventListener('statechange', check)
+  check()
+})
+
+/**
+ * Routes `element` through the normalizer, once for its whole life, and returns the same handle on every later
+ * call. Measured 2026-10-11 in Chrome 153, Firefox 151 and WebKit 26.5:
+ *
+ * - An element routed into a context that autoplay rules hold suspended goes silent (Firefox, WebKit) or stops
+ *   advancing (Chrome). So nothing is routed until the context runs; until then the element plays as it always did,
+ *   and the next pointerdown, pointerup or keydown resumes the context.
+ * - Chrome and WebKit refuse a second source for one element, and Chrome stops a playing element whose context is
+ *   closed, so the context is closed only once the element has left the document, and off is a bypass in the same
+ *   graph.
+ * - Chrome and Firefox apply the element's volume before the graph, so the worklet is told the volume and judges
+ *   loudness without it: otherwise a viewer at 25% would read as a quiet episode and nothing would be cut.
+ * - WebKit loses the volume and mute once routed, so `@banou/ponyfill` refuses it and `routed` rejects with a
+ *   `NotSupportedError` before the element is touched. That refusal comes once the context runs, the moment routing
+ *   would happen: telling WebKit apart any earlier would take sniffing here.
+ */
+export const attachVolumeNormalizer = (
+  element: HTMLMediaElement,
+  workletUrl: string,
+  options: VolumeNormalizerOptions = {},
+): VolumeNormalizer => {
+  const existing = attached.get(element)
+  if (existing) {
+    existing.wake()
+    return existing
+  }
+
+  const context = new AudioContext()
+  let enabled = options.enabled !== false
+  let node: AudioWorkletNode | undefined
+  let released = false
+  const inputGainDb = () => 20 * Math.log10(Math.max(element.volume, 1e-6))
+
+  const document = element.ownerDocument
+  const resume = () => { if (context.state === 'suspended') context.resume().catch(() => {}) }
+  const listen = (on: boolean) => {
+    // a mouse activates on pointerdown, a touch or a pen only on pointerup
+    for (const type of ['pointerdown', 'pointerup', 'keydown']) {
+      if (on) document.addEventListener(type, resume, true)
+      else document.removeEventListener(type, resume, true)
+    }
+  }
+  const follow = () => {
+    const suspended = !released && context.state === 'suspended'
+    listen(suspended)
+    // Suspended by something else once routed: Chrome freezes the element and Firefox plays it silent until the
+    // context runs, and the page's activation already allows a resume.
+    if (suspended && node) resume()
+  }
+  context.addEventListener('statechange', follow)
+  follow()
+
+  const routed = (async () => {
+    const created = await createVolumeNormalizerNode(context, workletUrl, { ...options, enabled, inputGainDb: inputGainDb() })
+    await running(context)
+    const source = createMediaElementSource(context, element)
+    created.port.postMessage({ enabled, inputGainDb: inputGainDb() })
+    source.connect(created).connect(context.destination)
+    element.addEventListener('volumechange', () => created.port.postMessage({ inputGainDb: inputGainDb() }))
+    // the 3 s window describes where the playhead was, and a new file owes nothing to the last one's cut
+    element.addEventListener('seeking', () => created.port.postMessage({ reset: 'seek' }))
+    element.addEventListener('emptied', () => created.port.postMessage({ reset: 'source' }))
+    node = created
+    return created
+  })()
+  routed.catch(() => {
+    released = true
+    listen(false)
+    // never routed, so closing it cannot touch the element
+    context.close().catch(() => {})
+  })
+
+  const handle = {
+    context,
+    routed,
+    setEnabled: (value: boolean) => {
+      enabled = value
+      node?.port.postMessage({ enabled })
+    },
+    release: () => {
+      released = true
+      listen(false)
+      // Chrome keeps a context that is not closed alive, with its worklet node, for the life of the page
+      if (!element.isConnected) {
+        attached.delete(element)
+        context.close().catch(() => {})
+      } else if (context.state === 'running') context.suspend().catch(() => {})
+    },
+    wake: () => {
+      if (context.state === 'closed') return
+      released = false
+      resume()
+      follow()
+    },
+  }
+  attached.set(element, handle)
+  return handle
+}

package/src/lib/engine/playback.ts

@@ -304,8 +304,12 @@ export const startPlayback = async (options: PlaybackOptions): Promise<PlaybackC
       const ct = videoElement.currentTime
       const pre = tight ? PRE_EVICT_TIGHT : PRE_EVICT
       const post = tight ? POST_EVICT_TIGHT : POST_EVICT
-      for (const { start, end } of getTimeRanges(sourceBuffer)) {
-        if (start < ct + pre) await unbufferRange(start, ct + pre)
+      const ranges = getTimeRanges(sourceBuffer)
+      // From 0, never from the reported start: once a group is removed, Firefox 151 reports the start
+      // 1 ms after the keyframe it still holds, so a remove from there keeps that frame for good
+      // (measured 2026-10-11).
+      if (ranges.length && ranges[0].start < ct + pre) await unbufferRange(0, ct + pre)
+      for (const { end } of ranges) {
         if (end > ct + post) await unbufferRange(ct + post, end)
       }
     }

package/src/lib/index.tsx

@@ -26,7 +26,7 @@ export type { PlayerStore } from './react/player'
 // only hook the chrome needs.
 export { sourceFeature } from './react/source-feature'
 export type {
-  DownloadedRange, PassThroughControl, PlaybackErrorEntry, SourceState, ViewportBox,
+  DownloadedRange, PassThroughControl, PlaybackErrorEntry, SourceState, ViewportBox, VolumeNormalizerControl,
 } from './react/source-feature'
 
 export { useSeekThumbnails } from './react/hooks/use-thumbnails'