@banou/media-player 0.10.19 → 0.10.21

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

@@ -1,8 +1,12 @@
+import type { LoudnessSource } from '../../audio/loudness-analysis';
 /**
  * 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).
  */
-export declare const useVolumeNormalizer: (video: HTMLVideoElement | null, workletUrl: string | undefined, enabled: boolean) => {
+export declare const useVolumeNormalizer: (video: HTMLVideoElement | null, workletUrl: string | undefined, enabled: boolean, source?: LoudnessSource, ranges?: [number, number][]) => {
     refused: boolean;
 };

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

@@ -134,11 +134,12 @@ export type MediaPlayerLocalOptions = CommonOptions & MediaPlayerSource & {
     /** Byte spans available, painted on the seekbar and informing the thumbnail generator. */
     downloadedRanges?: DownloadedRange[];
     /**
-     * Reader for the thumbnail engine, when it should differ from playback's.
+     * Reader for the thumbnail engine and the volume normalizer's analysis, when it should differ from playback's.
      *
      * 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.
+     * 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.
      */
     thumbnailRead?: (offset: number, size: number) => Promise<ArrayBuffer>;
     /** Off entirely. A second wasm worker during pipeline boot is worth avoiding on a slow source. */
@@ -153,10 +154,13 @@ export type MediaPlayerLocalOptions = CommonOptions & MediaPlayerSource & {
      */
     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 settings menu's "Normalize volume" switch: keeps the file's normal level and turns down what goes well
+     * over it, a loud burst before it starts. On by default; pass false for off. 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.
+     *
+     * 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.
      *
      * 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
@@ -165,7 +169,7 @@ export type MediaPlayerLocalOptions = CommonOptions & MediaPlayerSource & {
      * the element is never routed.
      */
     normalizeVolume?: boolean;
-    /** The viewer flipped the switch. */
+    /** The viewer flipped the switch, to `normalizeVolume`: what an app saves to pass back as `normalizeVolume`. */
     onNormalizeVolumeChange?: (normalizeVolume: boolean) => void;
 };
 /**