@banou/media-player 0.10.20 → 0.10.21

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

@@ -1,8 +1,10 @@
 import { createMediaElementSource } from '@banou/ponyfill/web-audio'
 
-/** 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
 }
@@ -106,7 +108,7 @@ export const attachVolumeNormalizer = (
     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
+    // the live detector describes where the playhead was, and a new file owes nothing to the last one's level
     element.addEventListener('seeking', () => created.port.postMessage({ reset: 'seek' }))
     element.addEventListener('emptied', () => created.port.postMessage({ reset: 'source' }))
     node = created

package/src/lib/react/hooks/use-volume-normalizer.ts

@@ -1,24 +1,38 @@
 import type { VolumeNormalizer } from '../../audio/volume-normalizer'
+import type { LoudnessSource } from '../../audio/loudness-analysis'
 
 import { useEffect, useRef, useState } from 'react'
 
 import { attachVolumeNormalizer } from '../../audio/volume-normalizer'
+import { startLoudnessAnalysis } 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 const useVolumeNormalizer = (video: HTMLVideoElement | null, workletUrl: string | undefined, enabled: boolean) => {
+export const useVolumeNormalizer = (
+  video: HTMLVideoElement | null,
+  workletUrl: string | undefined,
+  enabled: boolean,
+  source?: LoudnessSource,
+  ranges?: [number, number][],
+) => {
   const handle = useRef<VolumeNormalizer | null>(null)
   const [refused, setRefused] = useState(false)
+  const [node, setNode] = useState<AudioWorkletNode | null>(null)
 
   useEffect(() => {
     if (!video || !workletUrl) return
     if (enabled && !handle.current) {
       const attached = attachVolumeNormalizer(video, workletUrl, { enabled })
       handle.current = attached
-      attached.routed.catch((error) => {
+      attached.routed.then((routed) => {
+        if (handle.current === attached) setNode(routed)
+      }, (error) => {
         // released first, which closes a context that had not run yet: nothing was refused
         if (handle.current !== attached) return
         console.warn('[media-player] the volume normalizer is unavailable:', error)
@@ -31,7 +45,28 @@ export const useVolumeNormalizer = (video: HTMLVideoElement | null, workletUrl:
   useEffect(() => () => {
     handle.current?.release()
     handle.current = null
+    setNode(null)
   }, [video])
 
+  const rangesRef = useRef(ranges)
+  rangesRef.current = ranges
+  const analysis = useRef<ReturnType<typeof startLoudnessAnalysis> | null>(null)
+  const sourceRef = useRef(source)
+  sourceRef.current = source
+  const { length, publicPath, libavWorkerUrl, audioStreamIndex } = source ?? {}
+  useEffect(() => {
+    const current = sourceRef.current
+    if (!node || !video || !workletUrl || !enabled || !current) return
+    const started = startLoudnessAnalysis({ node, element: video, scriptUrl: workletUrl, source: current })
+    started.update(rangesRef.current)
+    analysis.current = started
+    return () => {
+      started.stop()
+      analysis.current = null
+    }
+  }, [node, video, workletUrl, enabled, length, publicPath, libavWorkerUrl, audioStreamIndex])
+
+  useEffect(() => { analysis.current?.update(ranges) }, [ranges])
+
   return { refused }
 }

package/src/lib/react/video-player.tsx

@@ -156,11 +156,12 @@ export type MediaPlayerLocalOptions =
     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. */
@@ -176,10 +177,13 @@ export type MediaPlayerLocalOptions =
      */
     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
@@ -188,7 +192,7 @@ export type MediaPlayerLocalOptions =
      * 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
   }
 
@@ -298,13 +302,37 @@ const PlayerRoot = ({ options, children }: { options: MediaPlayerOptions, childr
   // so there is nothing for them to attach to and nothing to guard at the call site.
   usePlayback(video, subtitleLayer, local)
 
-  const normalizeVolumeProp = local?.normalizeVolume
-  const [normalizeVolume, setNormalizeVolume] = useState(!!normalizeVolumeProp)
-  useEffect(() => { setNormalizeVolume(!!normalizeVolumeProp) }, [normalizeVolumeProp])
+  const normalizeVolumeProp = local?.normalizeVolume ?? true
+  const [normalizeVolume, setNormalizeVolume] = useState(normalizeVolumeProp)
+  useEffect(() => { setNormalizeVolume(normalizeVolumeProp) }, [normalizeVolumeProp])
   const onNormalizeVolumeChange = useRef(local?.onNormalizeVolumeChange)
   onNormalizeVolumeChange.current = local?.onNormalizeVolumeChange
   const normalizerWorkletUrl = local?.normalizerWorkletUrl
-  const { refused: normalizerRefused } = useVolumeNormalizer(video, normalizerWorkletUrl, normalizeVolume)
+  // the background reader, through a ref: a streaming consumer passes a fresh closure several times a second
+  const analysisRead = useRef(thumbnailRead ?? read)
+  analysisRead.current = thumbnailRead ?? read
+  const playingAudio = usePlayer((state) => state.selectedAudioTrack)
+  const hasRead = !!read
+  const normalizerSource = useMemo(
+    () => hasRead && size && publicPath && libavWorkerUrl && typeof playingAudio === 'number' && playingAudio >= 0
+      ? {
+        read: (offset: number, length: number) => analysisRead.current!(offset, length),
+        length: size,
+        publicPath,
+        libavWorkerUrl,
+        audioStreamIndex: playingAudio,
+      }
+      : undefined,
+    [hasRead, size, publicPath, libavWorkerUrl, playingAudio],
+  )
+  const normalizerRanges = useMemo(
+    () => downloadedRanges?.map(({ startByteOffset, endByteOffset }) => [startByteOffset, endByteOffset] as [number, number]),
+    // a streaming consumer changes the array identity every tick, so compare contents
+    [downloadedRanges?.map(({ startByteOffset, endByteOffset }) => `${startByteOffset}-${endByteOffset}`).join(',')],
+  )
+  const { refused: normalizerRefused } = useVolumeNormalizer(
+    video, normalizerWorkletUrl, normalizeVolume, normalizerSource, normalizerRanges,
+  )
   const volumeNormalizer = useMemo<VolumeNormalizerControl | null>(
     () => normalizerWorkletUrl && typeof AudioWorkletNode === 'function'
       ? {