@banou/media-player 0.10.9 → 0.10.10

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

@@ -0,0 +1,37 @@
+import type { VolumeNormalizer } from '../../audio/volume-normalizer'
+
+import { useEffect, useRef, useState } from 'react'
+
+import { attachVolumeNormalizer } from '../../audio/volume-normalizer'
+
+/**
+ * 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.
+ */
+export const useVolumeNormalizer = (video: HTMLVideoElement | null, workletUrl: string | undefined, enabled: boolean) => {
+  const handle = useRef<VolumeNormalizer | null>(null)
+  const [refused, setRefused] = useState(false)
+
+  useEffect(() => {
+    if (!video || !workletUrl) return
+    if (enabled && !handle.current) {
+      const attached = attachVolumeNormalizer(video, workletUrl, { enabled })
+      handle.current = attached
+      attached.routed.catch((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)
+        setRefused(true)
+      })
+    }
+    handle.current?.setEnabled(enabled)
+  }, [video, workletUrl, enabled])
+
+  useEffect(() => () => {
+    handle.current?.release()
+    handle.current = null
+  }, [video])
+
+  return { refused }
+}

package/src/lib/react/source-feature.ts

@@ -98,6 +98,14 @@ export type PassThroughControl = {
   exit: () => void
 }
 
+/** The settings menu's volume normalizer switch, for a player that offers one (see `normalizeVolume`). */
+export type VolumeNormalizerControl = {
+  enabled: boolean
+  /** False once the engine refused to route the element, which then plays exactly as it did. */
+  available: boolean
+  setEnabled: (enabled: boolean) => void
+}
+
 /**
  * Everything about the source that the chrome reads, carried on the player store next to the built-in
  * playback state so a component never has to know which of two channels owns a field.
@@ -210,6 +218,9 @@ export type SourceState = {
   /** Burn-in only. True while the composite is the picture on screen. */
   burnedInSubtitles: boolean
 
+  /** null when the player offers no volume normalizer: a media it does not own, or no `normalizerWorkletUrl`. */
+  volumeNormalizer: VolumeNormalizerControl | null
+
   /**
    * Move the playhead, letting the pipeline get the data there first.
    *
@@ -279,6 +290,7 @@ const initialState: SourceState = {
   passThroughPictureInPicture: null,
   pictureInPictureMode: null,
   burnedInSubtitles: false,
+  volumeNormalizer: null,
   playbackError: null,
   playbackErrors: [],
   ready: false,

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

@@ -1,11 +1,11 @@
 /// <reference types="@emotion/react/types/css-prop" />
 import type { ReactNode } from 'react'
 import type { MediaChapter } from '../engine'
-import type { DownloadedRange } from './source-feature'
+import type { DownloadedRange, VolumeNormalizerControl } from './source-feature'
 import type { DelegatedTracks, ExternalThumbnails, PassThroughPictureInPicture, PlayerMedia } from './media'
 import type { ExposePlayerOptions } from '../remote'
 
-import { useEffect, useRef, useState } from 'react'
+import { useEffect, useMemo, useRef, useState } from 'react'
 import { css } from '@emotion/react'
 import { useContainerAttach, useMediaAttach } from '@videojs/react'
 
@@ -14,6 +14,7 @@ import { usePlayback } from './hooks/use-playback'
 import { useSeekThumbnails } from './hooks/use-thumbnails'
 import { usePictureInPicture } from './hooks/use-picture-in-picture'
 import { usePassThroughPictureInPicture } from './hooks/use-pass-through-picture-in-picture'
+import { useVolumeNormalizer } from './hooks/use-volume-normalizer'
 import Chrome from './components/chrome'
 
 /**
@@ -156,6 +157,31 @@ export type MediaPlayerLocalOptions =
     thumbnailRead?: (offset: number, size: number) => Promise<ArrayBuffer>
     /** Off entirely. A second wasm worker during pipeline boot is worth avoiding on a slow source. */
     thumbnailsEnabled?: boolean
+
+    /**
+     * Where this package's `volume-normalizer-worklet.js` is served, a plain script to copy or import as a url
+     * (`@banou/media-player/volume-normalizer-worklet.js?no-inline&url` with vite). Without it the settings menu
+     * offers no volume normalizer.
+     *
+     * A url and not a blob, because a page whose CSP says `script-src 'self'` refuses a worklet module from a
+     * `blob:` or `data:` url, and `build.lib` inlines an asset as `data:` unless told otherwise.
+     */
+    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 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
+     * the video plays as before meanwhile. Where the engine refuses the routing (WebKit), it does so when routing
+     * would happen, once the switch is on and the context runs: the switch reads Unavailable from then on, and
+     * the element is never routed.
+     */
+    normalizeVolume?: boolean
+    /** The viewer flipped the switch. */
+    onNormalizeVolumeChange?: (normalizeVolume: boolean) => void
   }
 
 /**
@@ -258,6 +284,27 @@ 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 onNormalizeVolumeChange = useRef(local?.onNormalizeVolumeChange)
+  onNormalizeVolumeChange.current = local?.onNormalizeVolumeChange
+  const normalizerWorkletUrl = local?.normalizerWorkletUrl
+  const { refused: normalizerRefused } = useVolumeNormalizer(video, normalizerWorkletUrl, normalizeVolume)
+  const volumeNormalizer = useMemo<VolumeNormalizerControl | null>(
+    () => normalizerWorkletUrl && typeof AudioWorkletNode === 'function'
+      ? {
+        enabled: normalizeVolume,
+        available: !normalizerRefused,
+        setEnabled: (enabled) => {
+          setNormalizeVolume(enabled)
+          onNormalizeVolumeChange.current?.(enabled)
+        },
+      }
+      : null,
+    [normalizerWorkletUrl, normalizeVolume, normalizerRefused],
+  )
+
   const { thumbnails: generatedThumbnails, requestThumbnail } = useSeekThumbnails({
     publicPath,
     workerUrl: libavWorkerUrl,
@@ -306,6 +353,10 @@ const PlayerRoot = ({ options, children }: { options: MediaPlayerOptions, childr
     burnedInSubtitles,
   ])
 
+  useEffect(() => {
+    setSourceState({ volumeNormalizer })
+  }, [setSourceState, volumeNormalizer])
+
   // its own effect: it changes on every hover of the control, and nothing else here does
   useEffect(() => {
     setSourceState({ passThroughPictureInPicture })