@banou/media-player 0.10.8 → 0.10.10

package/README.md

@@ -89,6 +89,9 @@ reads as a browser bug rather than a missing asset. Serve both.
 
 `libavWorkerUrl` (`libav-wasm/build/worker.js`) is named individually and still copies fine.
 
+`normalizerWorkletUrl` is this package's own `dist/volume-normalizer-worklet.js`, a plain script that
+copies fine or imports as a url; see [the volume normalizer](#the-volume-normalizer).
+
 ### jassub's assets are imported, not copied
 
 jassub 2's worker is an ES module that imports `abslink` and `lfa-ponyfill` by bare specifier plus
@@ -232,6 +235,40 @@ A finger never rests on the control before it presses, so a tap cannot arm it. T
 only where the primary pointer hovers (`(hover: hover) and (pointer: fine)`), and a touch hides it
 until a pointer that hovers moves again.
 
+### The volume normalizer
+
+A "Normalize volume" switch in the settings menu holds the loudness steady, so a music cue comes out no
+louder than the dialogue around it. It is offered once you pass the worklet's url, and it is off until
+the viewer turns it on or you pass `normalizeVolume`:
+
+```tsx
+import normalizerWorkletUrl from '@banou/media-player/volume-normalizer-worklet.js?no-inline&url'
+
+<MediaPlayer
+  {...source}
+  normalizerWorkletUrl={normalizerWorkletUrl}
+  normalizeVolume={saved}
+  onNormalizeVolumeChange={save}
+/>
+```
+
+The player saves nothing, so an app that wants the choice to stick saves what
+`onNormalizeVolumeChange` reports and passes it back.
+
+It is an AudioWorklet that follows EBU short-term loudness (K-weighted, 3 s) and turns the gain down,
+never up, toward -24 LUFS: up to 20 dB, cutting with a 0.25 s time constant and recovering with 1 s. A
+cue is brought within a dialogue's level in about 3 s, and it adds no delay. The url has to be a
+script your origin serves: a page whose CSP says `script-src 'self'` refuses a worklet from a `blob:`
+or `data:` url, and `build.lib` inlines assets as `data:` without `?no-inline`.
+
+The first time it is on, the `<video>` is routed through Web Audio for the rest of its life, because an
+element cannot be handed back; off is a bypass. Routing waits until the AudioContext runs: one that
+autoplay rules hold back resumes on the page's next click, tap or key press, and the video plays as it
+always did until then. WebKit is refused (`createMediaElementSource` in `@banou/ponyfill/web-audio`),
+since a routed element loses its volume and mute there. The refusal comes when routing would, once the
+switch is on and the AudioContext runs: until then the switch reads as available, and from then on it
+reads Unavailable, with the element never routed and playing as it always did.
+
 ## Layout
 
 One package. `src/` is the demo app, `src/lib` is the library it publishes, and the app imports it by

package/dist/audio/volume-normalizer.d.ts

@@ -0,0 +1,37 @@
+/** 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 declare const createVolumeNormalizerNode: (context: BaseAudioContext, workletUrl: string, options?: VolumeNormalizerOptions) => Promise<AudioWorkletNode>;
+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;
+};
+/**
+ * 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 declare const attachVolumeNormalizer: (element: HTMLMediaElement, workletUrl: string, options?: VolumeNormalizerOptions) => VolumeNormalizer;

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export type { DelegatedSelection, DelegatedTracks, ExternalThumbnails, PassThrou
 export { Player, usePlayer } from './react/player';
 export type { PlayerStore } from './react/player';
 export { sourceFeature } from './react/source-feature';
-export type { DownloadedRange, PassThroughControl, PlaybackErrorEntry, SourceState, ViewportBox, } from './react/source-feature';
+export type { DownloadedRange, PassThroughControl, PlaybackErrorEntry, SourceState, ViewportBox, VolumeNormalizerControl, } from './react/source-feature';
 export { useSeekThumbnails } from './react/hooks/use-thumbnails';
 export { usePictureInPicture } from './react/hooks/use-picture-in-picture';
 export { inputToRemuxerInput } from './utils/source';