@banou/media-player 0.10.19 → 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/components/chrome.tsx

@@ -147,6 +147,8 @@ export const Chrome = ({ ref, onVideoRef, onSubtitleRef, overlay, controls, shor
   const lastPointerType = useRef<string>('mouse')
   // where the mouse last was, which is where it still is when nothing has moved
   const pointer = useRef({ x: -1, y: -1 })
+  // a mouse button held down with the mouse still is a drag on the seekbar or the volume, not yet over
+  const pressed = useRef(false)
   const root = useRef<HTMLDivElement | null>(null)
 
   useEffect(() => () => clearTimeout(autoHide.current), [])
@@ -189,9 +191,10 @@ export const Chrome = ({ ref, onVideoRef, onSubtitleRef, overlay, controls, shor
    * and a right click offers the browser's video menu rather than the control's. That is how a link
    * drawn in an overlay stops behaving like a link, which is what this exists to stop.
    *
-   * Only what actually takes pointer events can be hit, so this needs no list of selectors: the
-   * chrome's own layers opt out, an overlay item opts out until an app opts a child back in, and the
-   * picture is excluded here because resting on the picture is exactly when hiding is right.
+   * Only what actually takes pointer events can be hit: the chrome's own layers opt out, and an
+   * overlay item opts out until an app opts a child back in. The picture and the control bar are
+   * excluded here because resting on them is exactly when hiding is right, unless a button is held
+   * on the bar or one of its menus is open, which are still in use.
    *
    * The mouse only. A finger has no resting position, and `elementFromPoint` on the last tap would
    * keep the controls up forever after one press.
@@ -205,7 +208,9 @@ export const Chrome = ({ ref, onVideoRef, onSubtitleRef, overlay, controls, shor
     const { x, y } = pointer.current
     if (!root.current || x < 0) return false
     const hit = document.elementFromPoint(x, y)
-    return !!hit && root.current.contains(hit) && !hit.closest('.video')
+    if (!hit || !root.current.contains(hit) || hit.closest('.video')) return false
+    if (hit.closest('.control-bar')) return pressed.current || !!root.current.querySelector('.control-bar [aria-expanded="true"]')
+    return true
   }
 
   const hideUnlessTheMouseIsOnAControl = () => {
@@ -233,11 +238,20 @@ export const Chrome = ({ ref, onVideoRef, onSubtitleRef, overlay, controls, shor
 
   const onPointerDown = (event: React.PointerEvent<HTMLDivElement>) => {
     lastPointerType.current = event.pointerType
+    pressed.current = true
   }
 
+  const onPointerUp = () => {
+    pressed.current = false
+  }
+
+  const pausedBeforeClick = useRef(true)
+
   // play/pause with a mouse, show or hide the controls with a finger, which has no other way back
-  const onVideoClick = () => {
+  const onVideoClick = (event: React.MouseEvent) => {
     if (lastPointerType.current === 'mouse') {
+      if (event.detail > 1) return
+      pausedBeforeClick.current = player.paused
       player.togglePaused()
       return
     }
@@ -248,6 +262,15 @@ export const Chrome = ({ ref, onVideoRef, onSubtitleRef, overlay, controls, shor
     }
   }
 
+  // The first click toggled playback, so it is put back rather than toggled again: a remote media
+  // reports its pause late, and a second toggle would read it as still playing and pause it twice.
+  const onVideoDoubleClick = () => {
+    if (lastPointerType.current !== 'mouse') return
+    if (pausedBeforeClick.current) player.pause()
+    else void player.play().catch(() => {})
+    void player.toggleFullscreen()
+  }
+
   // relatedTarget alone is not enough: the browser fires mouseout with a null one while the pointer
   // still sits over the video, so a null is confirmed against the pointer's own coordinates.
   const onMouseOut: React.DOMAttributes<HTMLDivElement>['onMouseOut'] = (ev) => {
@@ -266,6 +289,8 @@ export const Chrome = ({ ref, onVideoRef, onSubtitleRef, overlay, controls, shor
       ref={setRoot}
       onPointerMove={onPointerMove}
       onPointerDown={onPointerDown}
+      onPointerUp={onPointerUp}
+      onPointerCancel={onPointerUp}
       onMouseOut={onMouseOut}
       className={hideUI ? 'hide' : ''}
       // focusable, so a click on the picture puts the focus, and with it the shortcuts, inside the player
@@ -294,7 +319,7 @@ export const Chrome = ({ ref, onVideoRef, onSubtitleRef, overlay, controls, shor
           />
         )
         : null}
-      <div className="video" onClick={onVideoClick}>
+      <div className="video" onClick={onVideoClick} onDoubleClick={onVideoDoubleClick}>
         {onVideoRef ? <video ref={onVideoRef} playsInline /> : null}
         {children}
       </div>

package/src/lib/react/components/control-bar.tsx

@@ -308,6 +308,7 @@ export const ControlBar = (
     // Armed, the whole bar takes no pointer events, or the rows around the control would still catch
     // the click at its box. The chrome's layer covers everything but the control meanwhile.
     <div
+      className='control-bar'
       css={style}
       style={{ ...hideUI ? { opacity: '0', pointerEvents: 'none' } : armed ? { pointerEvents: 'none' } : {} }}
     >

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'
       ? {