@banou/media-player 0.10.20 → 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,8 +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), or with a `tap`, from the audio playback remuxed.
  */
-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 | {
+    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 = {
@@ -134,11 +140,13 @@ 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`, 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. */
@@ -153,10 +161,14 @@ 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; 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
@@ -165,7 +177,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;
 };
 /**

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;