@banou/media-player 0.10.20 → 0.10.22

package/README.md

@@ -44,6 +44,10 @@ const source = await inputToRemuxerInput({ url: 'https://example.com/episode.mkv
 const source = await inputToRemuxerInput({ length, read })
 ```
 
+A URL's source comes back with `readsDownload: true`, which the player takes beside `read` and `size`: each read of
+it is a download, so the volume normalizer then analyses the audio playback fetched rather than fetching the file
+again.
+
 `usePlayer` reads and drives playback state from anywhere inside a `MediaPlayer`. It is the only hook
 the chrome uses: the built-in video.js state and this player's own source state (tracks, thumbnails,
 indexes, readiness) live on one store, so there is no second context to reach for.
@@ -89,8 +93,8 @@ 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).
+`normalizerWorkletUrl` is this package's own `dist/volume-normalizer-worklet.js`, one plain module with no imports
+that copies fine or imports as a url; see [the volume normalizer](#the-volume-normalizer).
 
 ### jassub's assets are imported, not copied
 
@@ -241,9 +245,9 @@ 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`:
+A "Normalize volume" switch in the settings menu keeps the file's own normal level and turns down what goes well over
+it, so a sudden blast comes out near the dialogue and the dialogue is left as it was. It is offered once you pass the
+worklet's url, and it is on unless the viewer turns it off or you pass `normalizeVolume={false}`:
 
 ```tsx
 import normalizerWorkletUrl from '@banou/media-player/volume-normalizer-worklet.js?no-inline&url'
@@ -251,27 +255,35 @@ import normalizerWorkletUrl from '@banou/media-player/volume-normalizer-worklet.
 <MediaPlayer
   {...source}
   normalizerWorkletUrl={normalizerWorkletUrl}
-  normalizeVolume={saved}
+  normalizeVolume={saved ?? true}
   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.
+The player saves nothing, so an app that wants the choice to stick saves what `onNormalizeVolumeChange` reports and
+passes it back.
+
+It works in two stages. A worker reads the file a second time, through `thumbnailRead` when you pass one and only
+within `downloadedRanges` (for a source that `readsDownload` it reads nothing and takes the audio playback fetched,
+about 30 s ahead of the playhead), decodes its audio with WebCodecs, learns the file's normal level (the median 400 ms
+loudness) and computes a cut with unlimited lookahead, so a cut starts before a spike: every 10 ms of the output is
+held to 10 LU over the normal level and every 50 ms to 8 LU. It analyses what is near the playhead first and then the
+rest of the file, keeping only 1 ms loudness readings, never the audio. Wherever that analysis has not reached the
+playhead, and for a track this browser's WebCodecs cannot decode, an AudioWorklet plays a live stage: a 100 ms detector
+that cuts what goes 5 LU over the level heard so far, and the 10 ms loudness held to 10 LU over it, seen 10 ms ahead.
+Neither stage ever boosts. The sound plays 10 ms behind the picture, on or off, once routed.
+
+The url names one file that is both the worklet and the worker's script, so it has to be a script your origin serves:
+a page whose CSP says `script-src 'self'` refuses a worklet or a worker from a `blob:` or `data:` url, and
+`build.lib` inlines assets as `data:` without `?no-inline`. A worker must also be same-origin, so serve it from the
+page's own origin.
+
+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
 

package/dist/audio/loudness-analysis.d.ts

@@ -0,0 +1,38 @@
+import type { PlaybackTap } from './playback-tap';
+/** The file the analysis reads, the same one playback plays. */
+export type LoudnessSource = {
+    read: (offset: number, size: number) => Promise<ArrayBuffer>;
+    length: number;
+    publicPath: string;
+    libavWorkerUrl: string;
+    /** The input stream index of the audio track playing. */
+    audioStreamIndex: number;
+};
+export type LoudnessAnalysis = {
+    /**
+     * Which bytes can be read without waiting on a download, as [start, end) pairs; undefined when all of them can.
+     * Nothing outside them is asked of the source.
+     */
+    update: (ranges?: [number, number][]) => void;
+    stop: () => void;
+};
+/**
+ * Analyses `source` ahead of the playhead with a second remuxer, in the worker the normalizer's script starts, and
+ * hands the worklet behind `node` the cut it computes. It reads only what `update` says is there, analyses what is
+ * 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 declare const startLoudnessAnalysis: ({ node, element, scriptUrl, source }: {
+    node: AudioWorkletNode;
+    element: HTMLMediaElement;
+    scriptUrl: string;
+    source: LoudnessSource | {
+        tap: PlaybackTap;
+        audioStreamIndex: number;
+    };
+}) => LoudnessAnalysis;

package/dist/audio/playback-tap.d.ts

@@ -0,0 +1,11 @@
+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 declare const createPlaybackTap: () => PlaybackTap;

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

@@ -1,6 +1,8 @@
-/** The worklet's processorOptions, read once when the node is made; its header has the defaults. */
+/**
+ * The worklet's processorOptions, read once when the node is made: `enabled` false starts it bypassed, and
+ * `inputGainDb` is the gain already applied upstream (the element's volume), which loudness is judged without.
+ */
 export type VolumeNormalizerOptions = {
-    targetLufs?: number;
     enabled?: boolean;
     inputGainDb?: number;
 };

package/dist/engine/index.d.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';
 export { createThumbnailGenerator } from './thumbnails';

package/dist/engine/index.js

@@ -1,2 +1,2 @@
-import { a as e, c as t, d as n, f as r, i, l as a, n as o, o as s, r as c, s as l, t as u, u as d } from "../engine-C4Gj_4zs.js";
+import { a as e, c as t, d as n, f as r, i, l as a, n as o, o as s, r as c, s as l, t as u, u as d } from "../engine-Cr_7OImR.js";
 export { i as DEFAULT_BUFFER_SIZE, e as MediaElementError, a as SUBTITLES_OFF, u as createPictureInPicture, d as createSubtitleRenderer, c as createThumbnailGenerator, n as getTimeRanges, s as isMediaElementError, o as pictureInPictureMode, l as startPlayback, t as terminateRemuxer, r as updateSourceBuffer };

package/dist/engine/playback.d.ts

@@ -21,6 +21,26 @@ export type MediaChapter = {
     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;
     /**
@@ -49,6 +69,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 = {
     destroy: () => void;