@joewinke/jatui 0.12.0 → 0.14.0

package/dist/video/audio/graph.js

@@ -0,0 +1,400 @@
+/**
+ * The audio graph (mos-5lzns.31) — the one module under src/lib/video/ that
+ * touches WebAudio. Ported from extension-library `library.js`
+ * (audioEnsure / audioTick / applyAudioSettings / applyQuietAmount).
+ *
+ *   source ─┬─► gain ─► quiet.input … quiet.output ─► limiter ─► trim ─► destination
+ *           └─► analyser   (taps the SOURCE: measure the material, not our
+ *                           own correction, or the loop chases its own tail)
+ *
+ * Quiet listening sits between level and limiter: it shapes TONE, so it acts
+ * on the signal at the level you'll hear, and the limiter is last by
+ * definition. `trim` cancels the limiter's automatic makeup gain (rider.ts
+ * `compressorMakeupDb`), so toggling the limiter moves no level. If the quiet
+ * chain can't build, the graph splices around it — tone is optional; sound
+ * is not.
+ *
+ * `createMediaElementSource` is a ONE-WAY DOOR — the spec has no way back once
+ * an element is routed. The contract is "never a silent player":
+ *
+ * 1. CONTEXT FIRST, ROUTE LAST. The context is created when a feature is on,
+ *    `resume()`d on every gesture, and the element is routed only once
+ *    `ctx.state === 'running'`. A suspended context on a routed element is
+ *    silence; a suspended context on an UNrouted element is nothing at all —
+ *    native audio keeps playing, and the next gesture retries. We never
+ *    consult navigator.userActivation: the context's own state is the truth.
+ * 2. ROUTE ONLY A CORS-CLEAN SOURCE (rider.ts `routeSafety`): blob:/data:, or
+ *    the element has `crossorigin`. A same-origin URL may 302 to storage on
+ *    another origin, and an opaque response routes to zeros.
+ * 3. AFTER ROUTING, WATCH. A later src that is not route-safe, or an analyser
+ *    reading bit-exact zeros for SILENT_AFTER_MS while the element plays
+ *    audibly AND there is positive evidence decoded audio is flowing (a
+ *    rising webkitAudioDecodedByteCount, mozHasAudio, audioTracks), is
+ *    reported as `broken` (`unsafe-src` / `silent`) via `onBroken`. A video
+ *    with no audio track never reads as silent. Both clear if the condition
+ *    clears. Remounting is right for `unsafe-src` (a fresh element); for
+ *    `silent` the host should show a notice and/or turn the audio features
+ *    off for that src — remounting would just loop.
+ * 4. A construction throw is a permanent `broken` (`build-failed`). If it
+ *    happened before the element was taken, the context is closed; if after,
+ *    the source is wired straight to the destination and the context KEPT —
+ *    closing it would silence the routed element.
+ *
+ * Disabled leaves no trace: level off CANCELS scheduled values before setting
+ * 1; the limiter's threshold ramps back to 0 dBFS with its trim to unity; the
+ * quiet chain rests at the identity (amount 0). A graph is never built just
+ * to neutralise it.
+ *
+ * The element itself never enters this module: the component passes `route`,
+ * a closure that calls createMediaElementSource on it.
+ */
+import { amountFor, createQuietChain } from '../advisors/quiet-listening';
+import { AUDIO_FFT_SIZE, AUDIO_TICK_MS, LIMITER, LIMITER_OFF_THRESHOLD, LIMITER_TAU, RIDE_TAU, SILENT_AFTER_MS, clampTarget, gainDb, gateLoud, limiterTrim, rideStep, rmsDb, wantGain } from './rider';
+const defaultEvery = (ms, fn) => {
+    const id = setInterval(fn, ms);
+    return () => clearInterval(id);
+};
+const safely = (fn) => {
+    try {
+        fn();
+    }
+    catch {
+        /* never throw out of the audio path */
+    }
+};
+export function createAudioSession(deps) {
+    let ctx = null;
+    let routed = false;
+    let buildFailed = false;
+    let unsafeSrc = false;
+    let silent = false;
+    let refusedCors = false;
+    let gain = null;
+    let limiter = null;
+    let trim = null;
+    let analyser = null;
+    let quiet = null;
+    let buf = null;
+    let ride = 1;
+    let loud = null;
+    let amount = 0;
+    let levelOn = false;
+    let limiterOn = false;
+    let target = clampTarget(undefined);
+    let stopTimer = null;
+    let lastOpts = null;
+    let anyOnLast = false;
+    let zeroMs = 0;
+    let lastDecoded = null;
+    let lastTime = Number.NaN;
+    let disposed = false;
+    let lastSent = '';
+    let lastBroken = null;
+    const reason = () => buildFailed ? 'build-failed' : routed && unsafeSrc ? 'unsafe-src' : routed && silent ? 'silent' : null;
+    const status = () => reason() ? 'broken' : routed ? 'live' : refusedCors ? 'cors' : 'off';
+    const state = () => ({
+        status: status(),
+        reason: reason(),
+        gainDb: levelOn ? gainDb(ride) : 0,
+        loudDb: loud,
+        quiet: amount
+    });
+    const emit = () => {
+        const s = state();
+        if (s.reason !== lastBroken) {
+            lastBroken = s.reason;
+            if (s.reason)
+                safely(() => deps.onBroken?.(s.reason));
+        }
+        const key = `${s.status}|${s.reason}|${s.gainDb.toFixed(2)}|${s.loudDb?.toFixed(1)}|${s.quiet.toFixed(2)}`;
+        if (key === lastSent)
+            return;
+        lastSent = key;
+        safely(() => deps.onState?.(s));
+    };
+    const now = () => (ctx && Number.isFinite(ctx.currentTime) ? ctx.currentTime : 0);
+    const running = () => !!ctx && (ctx.state === undefined || ctx.state === 'running');
+    const routable = () => {
+        try {
+            return deps.routable();
+        }
+        catch {
+            return 'wait';
+        }
+    };
+    /** Ask the context to start; on success retry whatever is pending. Never loops. */
+    function kick() {
+        if (!ctx || running())
+            return;
+        try {
+            const p = ctx.resume?.();
+            p?.then?.(() => {
+                if (!disposed && running() && lastOpts)
+                    apply(lastOpts);
+            }, () => { });
+        }
+        catch {
+            /* a refused resume just waits for the next gesture */
+        }
+    }
+    function closeCtx() {
+        const c = ctx;
+        ctx = null;
+        safely(() => {
+            const r = c?.close?.();
+            r?.catch?.(() => { });
+        });
+    }
+    /** Route the element and wire the graph. Only ever called with a running context. */
+    function build() {
+        const c = ctx;
+        let source = null;
+        try {
+            source = deps.route(c);
+            routed = true;
+            gain = c.createGain();
+            limiter = c.createDynamicsCompressor();
+            // Built at rest: threshold 0 dBFS, trim unity. configure() ramps them in.
+            limiter.threshold.value = LIMITER_OFF_THRESHOLD;
+            limiter.knee.value = LIMITER.knee;
+            limiter.ratio.value = LIMITER.ratio;
+            limiter.attack.value = LIMITER.attack;
+            limiter.release.value = LIMITER.release;
+            trim = c.createGain();
+            trim.gain.value = 1;
+            analyser = c.createAnalyser();
+            analyser.fftSize = AUDIO_FFT_SIZE;
+            buf = new Float32Array(AUDIO_FFT_SIZE);
+            // The quiet chain degrades to a unity wire or {input:null} on a context
+            // it doesn't recognise — splice around the null case instead of throwing
+            // into the catch below, where the element is already taken.
+            const q = createQuietChain(c);
+            quiet = q.input && q.output ? q : null;
+            source.connect(analyser);
+            source.connect(gain);
+            if (quiet) {
+                gain.connect(quiet.input);
+                quiet.output.connect(limiter);
+            }
+            else {
+                gain.connect(limiter);
+            }
+            limiter.connect(trim);
+            trim.connect(c.destination);
+            stopTimer = (deps.every ?? defaultEvery)(AUDIO_TICK_MS, tick);
+            return true;
+        }
+        catch {
+            buildFailed = true;
+            for (const n of [gain, limiter, trim, analyser])
+                safely(() => n?.disconnect?.());
+            quiet?.dispose();
+            quiet = gain = limiter = trim = analyser = null;
+            if (source) {
+                // The door closed behind us: a partly-built graph is silence. Wire the
+                // source straight out and KEEP the context — plain audio is all
+                // "broken" may mean.
+                safely(() => {
+                    source.disconnect?.();
+                    source.connect(c.destination);
+                });
+            }
+            else {
+                // Never took the element: nothing depends on this context.
+                routed = false;
+                closeCtx();
+            }
+            return false;
+        }
+    }
+    function setLevel(on) {
+        if (on === levelOn)
+            return;
+        levelOn = on;
+        if (on)
+            return;
+        // Hand the level back exactly as it was — cancel first, then set. A ramp
+        // toward 1 would leave a half-faded trace on the param timeline. The
+        // estimate resets too, so re-enabling starts clean, not stale.
+        ride = 1;
+        loud = null;
+        const p = gain?.gain;
+        if (!p)
+            return;
+        try {
+            p.cancelScheduledValues?.(now());
+            if (p.setValueAtTime)
+                p.setValueAtTime(1, now());
+            else
+                p.value = 1;
+        }
+        catch {
+            p.value = 1;
+        }
+    }
+    function setLimiter(on) {
+        if (on === limiterOn || !limiter?.threshold)
+            return;
+        limiterOn = on;
+        const th = on ? LIMITER.threshold : LIMITER_OFF_THRESHOLD;
+        // Ramped, never a .value write, and the trim moves with it so the
+        // compressor's makeup gain never reaches the output.
+        const ramp = (p, v) => {
+            if (!p)
+                return;
+            try {
+                if (p.setTargetAtTime)
+                    p.setTargetAtTime(v, now(), LIMITER_TAU);
+                else
+                    p.value = v;
+            }
+            catch {
+                p.value = v;
+            }
+        };
+        ramp(limiter.threshold, th);
+        ramp(trim?.gain, limiterTrim(th));
+    }
+    function tick() {
+        if (disposed || !routed || buildFailed || !analyser)
+            return;
+        let pb;
+        try {
+            pb = deps.playback();
+        }
+        catch {
+            return;
+        }
+        if (!pb.playing) {
+            lastTime = Number.NaN;
+            return;
+        }
+        try {
+            analyser.getFloatTimeDomainData?.(buf);
+        }
+        catch {
+            return;
+        }
+        // Watchdog: bit-exact zeros while audible, the clock advances AND there is
+        // positive evidence that decoded audio exists and is flowing. A video
+        // with no audio track reads zeros forever and must never be called
+        // "silent" — no evidence, no verdict.
+        const advanced = Number.isFinite(lastTime) && pb.time > lastTime;
+        lastTime = pb.time;
+        const decoded = Number.isFinite(pb.audioDecoded) ? pb.audioDecoded : null;
+        const flowing = decoded !== null
+            ? lastDecoded !== null && decoded > lastDecoded // Chromium: bytes still decoding
+            : pb.audioPresent === true; // Gecko mozHasAudio / WebKit audioTracks
+        lastDecoded = decoded;
+        if (!flowing) {
+            zeroMs = 0;
+            if (silent) {
+                silent = false;
+                emit();
+            }
+        }
+        else if (pb.audible && advanced) {
+            let zero = true;
+            for (let i = 0; i < buf.length; i++) {
+                if (buf[i] !== 0) {
+                    zero = false;
+                    break;
+                }
+            }
+            zeroMs = zero ? zeroMs + AUDIO_TICK_MS : 0;
+            const s = zeroMs >= SILENT_AFTER_MS;
+            if (s !== silent) {
+                silent = s;
+                emit();
+            }
+        }
+        // Rider. Hidden: the estimate holds.
+        if (!levelOn || pb.hidden || !gain?.gain)
+            return;
+        const level = rmsDb(buf);
+        if (level == null)
+            return; // silence carries no vote
+        loud = gateLoud(loud, level);
+        ride = rideStep(ride, wantGain(loud, target));
+        safely(() => gain.gain.setTargetAtTime?.(ride, now(), RIDE_TAU));
+        emit();
+    }
+    function configure(o, q) {
+        setLevel(o.level === true);
+        setLimiter(o.limiter === true);
+        amount = q && quiet ? amountFor(o.muted ? 0 : o.volume, !!o.night, {}) : 0;
+        quiet?.setAmount(amount);
+    }
+    function apply(opts) {
+        if (disposed)
+            return;
+        const o = opts ?? {};
+        lastOpts = o;
+        target = clampTarget(o.target);
+        const q = o.quiet === true;
+        const anyOn = o.level === true || o.limiter === true || q;
+        anyOnLast = anyOn;
+        if (buildFailed)
+            return emit();
+        if (routed) {
+            // The door is shut behind us; all we can do is watch and report.
+            unsafeSrc = routable() === 'cors';
+            configure(o, q);
+            return emit();
+        }
+        // Never create a context — let alone route — just to neutralise it.
+        if (!anyOn) {
+            refusedCors = false;
+            return emit();
+        }
+        const r = routable();
+        refusedCors = r === 'cors';
+        if (r !== 'ok')
+            return emit();
+        if (!ctx) {
+            try {
+                ctx = deps.context();
+                const c = ctx;
+                c.addEventListener?.('statechange', () => {
+                    if (!disposed && ctx === c && running() && !routed && lastOpts)
+                        apply(lastOpts);
+                });
+            }
+            catch {
+                ctx = null;
+                buildFailed = true;
+                return emit();
+            }
+        }
+        if (!running()) {
+            // Suspended: do NOT route. Native audio keeps playing; the resume below
+            // (or the next gesture's) retries.
+            kick();
+            return emit();
+        }
+        if (!build())
+            return emit();
+        configure(o, q);
+        emit();
+    }
+    function gesture() {
+        // All features off: a click is not our business (no context, no apply).
+        if (disposed || buildFailed || !anyOnLast)
+            return;
+        if (ctx && !running())
+            kick();
+        if (!routed && lastOpts)
+            apply(lastOpts);
+    }
+    function dispose() {
+        if (disposed)
+            return;
+        disposed = true;
+        stopTimer?.();
+        stopTimer = null;
+        quiet?.dispose();
+        closeCtx();
+        gain = limiter = trim = analyser = quiet = null;
+    }
+    return { apply, gesture, tick, state, dispose };
+}

package/dist/video/audio/rider.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Loudness matching — the pure half (mos-5lzns.31). Ported from
+ * extension-library `library.js` §Loudness matching (audioLevel / audioTick)
+ * and FEATURES.md §Loudness matching; every number below is the extension's.
+ *
+ * Shape: a gated RMS estimate of the programme's LOUD level drives a slow,
+ * asymmetric gain rider toward a target. The graph (./graph.ts) feeds this
+ * module the analyser's time-domain buffer every AUDIO_TICK_MS and lands the
+ * returned ride on the gain param; nothing here touches WebAudio.
+ *
+ * Not true LUFS — no K-weighting, no channel weighting. The thing being
+ * corrected is "this video is louder than the last one", and RMS answers that
+ * honestly at a fraction of the cost.
+ */
+/** How often the rider reads the meter. fftSize 2048 is ~46ms at 44.1kHz. */
+export declare const AUDIO_TICK_MS = 200;
+export declare const AUDIO_FFT_SIZE = 2048;
+/** Where matching aims, dBFS RMS. At −20 an ordinary video is left at ~1.0×. */
+export declare const AUDIO_TARGET_DEFAULT = -20;
+export declare const AUDIO_TARGET_MIN = -30;
+export declare const AUDIO_TARGET_MAX = -12;
+/** Below this RMS a window is silence — it carries no vote about level. */
+export declare const SILENCE_RMS = 0.00001;
+/**
+ * The gate is the whole difference between working and shouting. A 46ms
+ * window of speech runs ~−15 dB, the pause between sentences ~−40; driving
+ * gain off the instantaneous level climbs through every gap and blares the
+ * next word. So the estimate only listens to material within GATE_DB of what
+ * it already believes the loud level to be (EBU R128's relative-gate idea).
+ */
+export declare const GATE_DB = 12;
+/** Rise toward a louder reading quickly … */
+export declare const LOUD_RISE = 0.08;
+/** … and forget a quiet one very slowly (a new video does NOT reset it). */
+export declare const LOUD_FORGET = 0.01;
+/**
+ * The clamp. 1.35 is a deliberate ceiling, not a round number: measured
+ * across the extension's library, target −20 leaves normal material at 1.0×,
+ * lifts a quiet podcast by the full +2.6 dB and pulls a hot one down 10 dB.
+ * Matching may rescue a quiet mix by a few dB; it may NOT become an amplifier.
+ */
+export declare const GAIN_MIN = 0.3;
+export declare const GAIN_MAX = 1.35;
+/**
+ * Asymmetric ride — the opposite way round from night dimming: coming DOWN
+ * off something too loud is quick, going up is slow enough to be inaudible.
+ */
+export declare const RIDE_DOWN = 0.15;
+export declare const RIDE_UP = 0.02;
+/** setTargetAtTime constant the ride lands with, so the param smooths between ticks. */
+export declare const RIDE_TAU = 0.25;
+/**
+ * The limiter — the fast half. High ratio, knee 0, fast attack: it does
+ * nothing until something actually peaks. Off moves the threshold to 0 dBFS
+ * rather than rewiring the graph (rewiring a live graph clicks); the move is
+ * RAMPED (LIMITER_TAU), never a `.value` write.
+ *
+ * Not a straight wire on its own: DynamicsCompressorNode applies automatic
+ * makeup gain (see `compressorMakeupDb`) — ~+1.7 dB at −3 dBFS / 20:1 — so the
+ * graph follows the limiter with a trim GainNode at the inverse. Without the
+ * trim, "limiter on" is a 1.7 dB level jump, which is exactly the kind of
+ * trace a feature must not leave.
+ */
+export declare const LIMITER: Readonly<{
+    threshold: -3;
+    knee: 0;
+    ratio: 20;
+    attack: 0.003;
+    release: 0.25;
+}>;
+export declare const LIMITER_OFF_THRESHOLD = 0;
+/** Ramp constant for limiter threshold/trim moves — under an event, over a click. */
+export declare const LIMITER_TAU = 0.15;
+/**
+ * Silence watchdog: a routed element whose analyser reads EXACT zeros for this
+ * long while it is playing, audible, its clock advancing AND with positive
+ * evidence that decoded audio is flowing is reported as silent — the
+ * signature of a source that became CORS-tainted after routing (the node
+ * outputs zeros, never noise). Without that evidence (no audio track, or a
+ * browser that can't tell us) it never fires. Exact digital silence in a real
+ * track (a muted-mic screen recording) can still trip it, which is why the
+ * report asks for a notice, never a remount.
+ */
+export declare const SILENT_AFTER_MS = 4000;
+/**
+ * Short-term RMS of a time-domain buffer, in dBFS. `null` for silence (below
+ * SILENCE_RMS), an empty buffer or junk — never −Infinity, never NaN.
+ */
+export declare function rmsDb(buf: ArrayLike<number> | null | undefined): number | null;
+/**
+ * One step of the gated loud-level estimate. `loud` null means "no estimate
+ * yet" — the first real reading seeds it. A null/junk `level` (silence) leaves
+ * the estimate exactly where it was.
+ */
+export declare function gateLoud(loud: number | null, level: number | null): number | null;
+/** Clamp a target to the declared range; junk falls back to the default. */
+export declare function clampTarget(target: unknown): number;
+/**
+ * The gain that would put the measured loud level at `target`, clamped to
+ * [GAIN_MIN, GAIN_MAX]. No estimate yet ⇒ 1 (neutral): we never guess.
+ */
+export declare function wantGain(loud: number | null, target: unknown): number;
+/** One asymmetric step of the ride toward `want`. Junk in ⇒ neutral 1. */
+export declare function rideStep(ride: number, want: number): number;
+/** A ride as dB — for readouts. 1 ⇒ 0 dB; junk ⇒ 0. */
+export declare function gainDb(ride: number): number;
+/**
+ * DynamicsCompressorNode's automatic makeup gain, dB, for knee 0 — the Web
+ * Audio spec's "makeup gain" step (as Chromium/WebKit/Gecko implement it):
+ * fullRangeGain = the curve's output for a 0 dBFS input, makeup =
+ * (1 / fullRangeGain) ^ 0.6. For knee 0 the curve at 0 dBFS is
+ * threshold + (0 − threshold) / ratio, so the makeup is
+ * 0.6 × (−threshold) × (1 − 1/ratio): +1.71 dB at −3 dBFS / 20:1, 0 at a
+ * 0 dBFS threshold. Junk ⇒ 0.
+ */
+export declare function compressorMakeupDb(threshold: unknown, ratio: unknown): number;
+/** The trim gain (linear) that cancels a limiter's makeup at this threshold. */
+export declare function limiterTrim(threshold: number): number;
+/**
+ * Can this element's audio be routed through WebAudio without going SILENT?
+ *
+ * A media response that isn't CORS-clean makes a MediaElementAudioSourceNode
+ * output zeros — and routing is a one-way door, so that is silence with no
+ * way back. A same-origin URL is NOT enough: it may 302 to a signed storage
+ * URL on another origin (MardukOS file routes do exactly that), and without
+ * `crossorigin` the redirected response is opaque. So:
+ *
+ * · 'ok'   — blob:/data: (never leave the page's origin), or the element asked
+ *            for a CORS load (`crossorigin` set — the load is then CORS-clean
+ *            or it fails outright, never silently).
+ * · 'wait' — no source yet; nothing to decide.
+ * · 'cors' — anything else: refuse, play unprocessed.
+ */
+export declare function routeSafety(mediaUrl: unknown, crossorigin: unknown): 'ok' | 'wait' | 'cors';