@joewinke/jatui 0.12.0 → 0.14.0

package/dist/components/VideoPlayer.svelte

@@ -15,6 +15,10 @@
 	export type { VideoMarker } from '../video/band/markers';
 	// mos-5lzns.33 — night dimming.
 	export type { NightMode, NightWindow } from '../video/night/clock';
+	// mos-5lzns.31 — audio graph.
+	export type { AudioState, AudioStatus, AudioBrokenReason } from '../video/audio/graph';
+	// mos-5lzns.32 — rate composer (smart speed, speaker pace, skip ad reads).
+	export type { VideoAdSpan, RateReport } from '../video/rate';
 </script>
 
 <script lang="ts">
@@ -135,7 +139,25 @@
 	import { dragCancel, dragEnd, dragMove, dragStart, type DragState } from '../video/band/drag';
 	import { createBandLayerCache } from '../video/band/memo';
 	import { BAND_KEYS, PLAYER_KEYS, chapterJump, FRAME_STEP_SEC } from '../video/keys';
-	import { composeRate, formatSpeedLabel, stepRate } from '../video/rate';
+	import {
+		adMaxStep,
+		adSkipTarget,
+		adviseRate,
+		advisorsActive,
+		composeRate,
+		formatSpeedLabel,
+		normalizeAdSpans,
+		RATE_TICK_MS,
+		shouldWriteRate,
+		silenceMapFor,
+		smartSpeedLabel,
+		speakerRateMap,
+		stepRate,
+		toRateSegments,
+		toRateTurns,
+		type RateReport,
+		type VideoAdSpan
+	} from '../video/rate';
 	import { readTimeParam, WRITE_THROTTLE_MS, writeTimeParam } from '../video/deepLink';
 	import {
 		biasCells,
@@ -157,6 +179,13 @@
 		type NightFrame,
 		type NightState
 	} from '../video/night/track';
+	import {
+		createAudioSession,
+		routeSafety,
+		AUDIO_TARGET_DEFAULT,
+		type AudioBrokenReason,
+		type AudioState
+	} from '../video/audio';
 
 	let {
 		src,
@@ -214,6 +243,18 @@
 		strobeGuard = true,
 		onNightModeChange = undefined,
 		onNightBlind = undefined,
+		loudness = undefined,
+		loudnessTarget = AUDIO_TARGET_DEFAULT,
+		quietListening = undefined,
+		limiter = undefined,
+		onAudioState = undefined,
+		onAudioBroken = undefined,
+		smartSpeed = false,
+		speakerPace = false,
+		speakerRates = null,
+		adSpans = null,
+		skipAds = false,
+		onRateChange = undefined,
 		class: className = ''
 	}: {
 		src: string;
@@ -350,6 +391,78 @@
 		onNightModeChange?: (mode: NightMode) => void;
 		/** Frame readback was refused (CORS-tainted canvas) — night fell back to a fixed level. */
 		onNightBlind?: () => void;
+		/**
+		 * Audio graph (mos-5lzns.31) — all three default OFF (absent = the
+		 * feature does not exist on this player and nothing is ever routed).
+		 *
+		 * `loudness`: a gated RMS meter rides the gain slowly toward
+		 * `loudnessTarget` (dBFS, −30…−12, default −20) so a whispered video and
+		 * a blaring one arrive at the same level; clamped 0.3–1.35×, it rescues a
+		 * quiet mix by a few dB and never becomes an amplifier.
+		 * `quietListening`: loudness-compensated tone that rises as the volume
+		 * drops (and sits a little on while night is armed).
+		 * `limiter`: catches peaks above −3 dBFS that the slow rider can't.
+		 *
+		 * ⚠ Routing into WebAudio is permanent for the element, and a source
+		 * that isn't CORS-clean routes to SILENCE. So the player routes only
+		 * when the src is blob:/data: or `crossorigin` is set ("anonymous" /
+		 * "use-credentials", with the server answering Access-Control-Allow-
+		 * Origin) — a same-origin URL is NOT enough, since it may redirect to
+		 * storage on another origin. Anything else is refused and plays
+		 * unprocessed (`status: 'cors'`). It also waits for the AudioContext to
+		 * be `running` (a user gesture); until then native audio plays.
+		 *
+		 * After routing it cannot be undone, so the player reports
+		 * `status: 'broken'` and calls `onAudioBroken(reason)`:
+		 * · 'unsafe-src' — the src later changed to one that isn't route-safe
+		 *   (or `crossorigin` was removed). Remount the player (a fresh element)
+		 *   for that source.
+		 * · 'silent' — bit-exact silence for 4s while the video plays audibly
+		 *   AND the browser shows decoded audio flowing (a video with no audio
+		 *   track never fires). Show a notice and/or turn the audio features
+		 *   off for that src — do NOT remount; it would loop.
+		 * · 'build-failed' — construction threw: plain audio for the session.
+		 */
+		loudness?: boolean;
+		loudnessTarget?: number;
+		quietListening?: boolean;
+		limiter?: boolean;
+		/** Graph status + the rider's live gain (≤5×/s while matching acts). */
+		onAudioState?: (state: AudioState) => void;
+		/** Entered `broken`: 'build-failed' | 'unsafe-src' | 'silent' (see above). */
+		onAudioBroken?: (reason: AudioBrokenReason) => void;
+		/**
+		 * Rate composer (mos-5lzns.32): `rate = base × speaker × silence`. The
+		 * speed readout only ever reports `base` — the rate a human chose — so it
+		 * keeps saying `1×` while a gap is taken at 2.2×. Every advisor is off by
+		 * default and collapses to 1 until its data arrives: off, the element
+		 * plays at exactly `base`.
+		 *
+		 * Smart speed: run the silences between sentences at 2.2×, found off the
+		 * `waveform` envelope. Speech stays at `base`.
+		 */
+		smartSpeed?: boolean;
+		/**
+		 * Per-speaker pace: level everyone to the median words-per-minute,
+		 * measured from the diarised `transcript` + `speakers`. Ad reads and
+		 * gaps between turns play at `base`.
+		 */
+		speakerPace?: boolean;
+		/**
+		 * Hand-set speaker rates keyed by speaker NAME (the legend's display
+		 * name). They always beat measured ones, and like them apply only while
+		 * `speakerPace` is on — off means off. Range 0.0625–16.
+		 */
+		speakerRates?: Record<string, number> | null;
+		/** Host-detected ad reads. Merged with any `ad: true` speaker turns. */
+		adSpans?: VideoAdSpan[] | null;
+		/**
+		 * Skip ad reads: when playback runs into an ad span it jumps to its end
+		 * (the OSD says so). A seek that lands inside an ad is honoured.
+		 */
+		skipAds?: boolean;
+		/** The composed rate changed (real change only). `base` is what the UI shows. */
+		onRateChange?: (report: RateReport) => void;
 		class?: string;
 	} = $props();
 
@@ -600,25 +713,236 @@
 		if (videoEl) videoEl.currentTime = t;
 	}
 
-	// ── Speed ───────────────────────────────────────────────────────────────
+	// ── Speed + rate composer (video/rate/*, mos-5lzns.32) ──────────────────
+	// rate = base × speaker × silence. `base` is the only rate a human chose
+	// and the only one the OSD reports; the advisors multiply into the APPLIED
+	// rate from their own 120ms loop, which runs only while one of them (or ad
+	// skipping) can act. Off, every factor is 1 and the element plays at
+	// exactly `base` — the contract in video/rate/compose.ts.
+	const rateTurns = $derived(toRateTurns(speakers));
+	const rateSegments = $derived(toRateSegments(transcript));
+	const rateAdvisors = $derived({
+		speakerRates: speakerPace
+			? speakerRateMap({ turns: rateTurns, segments: rateSegments, manual: speakerRates, measure: true })
+			: null,
+		turns: rateTurns,
+		silence: smartSpeed ? silenceMapFor(waveform, effectiveDuration) : null
+	});
+	const adRanges = $derived(skipAds ? normalizeAdSpans(adSpans, speakers) : []);
+	const rateLoopOn = $derived(advisorsActive(rateAdvisors) || adRanges.length > 0);
+	/** Playing in a visible tab — the only time the 120ms loop has anything to do. */
+	let rateRunning = $state(false);
+	// Plain (non-reactive): written and read inside one tick.
+	let rateSpeaker = 1;
+	let rateSilence = 1;
 	/**
-	 * Apply the base rate. No advisors exist yet (mos-5lzns.32 fills the
-	 * speaker/silence ones) — composeRate collapses them to 1, so today this is
-	 * exactly `base`. When they land, the composer multiplies and this keeps
-	 * reporting `base` on the OSD — the contract in video/rate.ts.
+	 * `ratechange` events this component still owes itself: every write that
+	 * changes the value fires exactly one. Anything beyond them is a human (the
+	 * native speed menu) — even one that picks the very value we last wrote.
 	 */
+	let rateSelfWrites = 0;
+	let reportedBase = Number.NaN;
+	let reportedRate = Number.NaN;
+	/** Last playhead sample while playing; null after a seek/pause ⇒ never an ad skip. */
+	let adPrev: number | null = null;
+	let adPrevAt = 0;
+
 	function applyRate() {
 		const v = videoEl;
 		if (!v) return;
-		const { rate } = composeRate(baseRate, 1, 1);
+		const { rate } = composeRate(baseRate, rateSpeaker, rateSilence);
 		// Only real changes are written — playbackRate is a live audio parameter.
-		if (v.playbackRate !== rate) v.playbackRate = rate;
+		if (shouldWriteRate(v.playbackRate, rate, baseRate)) {
+			rateSelfWrites++;
+			v.playbackRate = rate;
+		}
+		if (baseRate !== reportedBase || rate !== reportedRate) {
+			reportedBase = baseRate;
+			reportedRate = rate;
+			onRateChange?.({ base: baseRate, speaker: rateSpeaker, silence: rateSilence, rate });
+		}
 	}
 	function stepSpeed(direction: 1 | -1) {
 		baseRate = stepRate(baseRate, direction);
 		applyRate();
 		flashOsd(formatSpeedLabel(baseRate));
 	}
+	function rateTick() {
+		const v = videoEl;
+		if (!v) return;
+		const t = v.currentTime || 0;
+		if (v.paused || v.seeking || adRanges.length === 0) adPrev = null;
+		else {
+			const now = performance.now();
+			const hop = adSkipTarget(adPrev, t, adRanges, adMaxStep(now - adPrevAt, v.playbackRate));
+			adPrevAt = now;
+			adPrev = t;
+			if (hop) {
+				adPrev = null;
+				seekTo(hop.to);
+				flashOsd(`Skipped ad · ${formatDuration(hop.to - hop.from)}`);
+				return;
+			}
+		}
+		const a = adviseRate(baseRate, t, rateAdvisors);
+		rateSpeaker = a.speaker;
+		rateSilence = a.silence;
+		applyRate();
+	}
+	$effect(() => {
+		const v = videoEl;
+		if (!v) return;
+		rateSelfWrites = 0;
+		const syncRunning = () => {
+			const on = !v.paused && !v.ended && !document.hidden;
+			if (rateRunning !== on) rateRunning = on;
+		};
+		const onSeeking = () => (adPrev = null);
+		// A paused scrub re-advises once, so the frame you land on already
+		// carries its rate when play resumes (the loop itself is stopped).
+		const onSeeked = () => {
+			if (rateLoopOn && !rateRunning) rateTick();
+		};
+		// A rate this component didn't write came from a human (the native
+		// controls' speed menu): it becomes the new base, so the advisors keep
+		// multiplying on top of it instead of fighting it.
+		const onNativeRate = () => {
+			if (rateSelfWrites > 0) {
+				rateSelfWrites--;
+				return;
+			}
+			const r = v.playbackRate;
+			if (!Number.isFinite(r) || r < 0) return;
+			baseRate = r;
+			applyRate();
+		};
+		syncRunning();
+		for (const ev of ['play', 'pause', 'ended']) v.addEventListener(ev, syncRunning);
+		document.addEventListener('visibilitychange', syncRunning);
+		v.addEventListener('seeking', onSeeking);
+		v.addEventListener('seeked', onSeeked);
+		v.addEventListener('ratechange', onNativeRate);
+		return () => {
+			for (const ev of ['play', 'pause', 'ended']) v.removeEventListener(ev, syncRunning);
+			document.removeEventListener('visibilitychange', syncRunning);
+			v.removeEventListener('seeking', onSeeking);
+			v.removeEventListener('seeked', onSeeked);
+			v.removeEventListener('ratechange', onNativeRate);
+		};
+	});
+	// Armed: advise once now (so the first frame after play is already right),
+	// and off leaves no trace — every factor back to 1, the element to base.
+	$effect(() => {
+		if (!videoEl || !rateLoopOn) return;
+		untrack(rateTick);
+		return () => {
+			untrack(() => {
+				rateSpeaker = 1;
+				rateSilence = 1;
+				adPrev = null;
+				applyRate();
+			});
+		};
+	});
+	// The 120ms loop runs only while armed AND playing in a visible tab —
+	// paused, ended or hidden, there is no rate to steer.
+	$effect(() => {
+		if (!videoEl || !rateLoopOn || !rateRunning) return;
+		const id = setInterval(rateTick, RATE_TICK_MS);
+		untrack(rateTick);
+		return () => {
+			clearInterval(id);
+			adPrev = null;
+		};
+	});
+	// Nothing acts without something the user can see: an advisor announces
+	// itself once on the OSD when it arms (and again only after it disarms).
+	let rateAnnounced = { silence: false, speaker: false };
+	$effect(() => {
+		const { silence, speakerRates: table } = rateAdvisors;
+		const levelled = table ? Object.values(table).filter((r) => r !== 1).length : 0;
+		untrack(() => {
+			if (!silence) rateAnnounced.silence = false;
+			else if (!rateAnnounced.silence) {
+				rateAnnounced.silence = true;
+				const label = smartSpeedLabel(silence);
+				if (label) flashOsd(label);
+			}
+			if (!levelled) rateAnnounced.speaker = false;
+			else if (!rateAnnounced.speaker) {
+				rateAnnounced.speaker = true;
+				flashOsd(`Speaker pace · ${levelled} adjusted`);
+			}
+		});
+	});
+
+	// ── Audio (video/audio/*) ───────────────────────────────────────────────
+	// The session owns the graph and its one-way door; this block only hands
+	// it the element (inside `route`) and re-applies on every input it reads.
+	// Inert until a feature is on: no context, no routing. Gestures anywhere
+	// on the page resume a suspended context and retry a pending route.
+	let audio: ReturnType<typeof createAudioSession> | null = null;
+	$effect(() => {
+		const v = videoEl;
+		if (!v) return;
+		const s = createAudioSession({
+			// The attribute is what will load next; currentSrc lags it until loadstart.
+			routable: () => routeSafety(v.getAttribute('src') || v.currentSrc, v.getAttribute('crossorigin')),
+			context: () => new AudioContext(),
+			route: (ctx) => (ctx as AudioContext).createMediaElementSource(v),
+			playback: () => {
+				const m = v as HTMLVideoElement & {
+					webkitAudioDecodedByteCount?: number;
+					mozHasAudio?: boolean;
+					audioTracks?: { length: number };
+				};
+				return {
+					playing: !v.paused && !v.ended,
+					hidden: document.hidden,
+					audible: !v.muted && v.volume > 0,
+					time: v.currentTime,
+					audioDecoded: typeof m.webkitAudioDecodedByteCount === 'number' ? m.webkitAudioDecodedByteCount : null,
+					audioPresent:
+						typeof m.mozHasAudio === 'boolean' ? m.mozHasAudio : m.audioTracks ? m.audioTracks.length > 0 : null
+				};
+			},
+			onState: (st) => onAudioState?.(st),
+			onBroken: (reason) => onAudioBroken?.(reason)
+		});
+		audio = s;
+		const sync = () => untrack(() => s.apply(audioOpts(v)));
+		const gesture = () => s.gesture();
+		const media = ['volumechange', 'loadstart', 'loadedmetadata'];
+		const gestures = ['pointerdown', 'pointerup', 'keydown', 'touchend'];
+		for (const e of media) v.addEventListener(e, sync);
+		v.addEventListener('play', gesture);
+		for (const e of gestures) window.addEventListener(e, gesture, { capture: true, passive: true });
+		return () => {
+			for (const e of media) v.removeEventListener(e, sync);
+			v.removeEventListener('play', gesture);
+			for (const e of gestures) window.removeEventListener(e, gesture, { capture: true });
+			s.dispose();
+			audio = null;
+		};
+	});
+	function audioOpts(v: HTMLVideoElement) {
+		return {
+			level: loudness === true,
+			target: loudnessTarget,
+			limiter: limiter === true,
+			quiet: quietListening === true,
+			volume: v.volume,
+			muted: v.muted,
+			night: nightArmedNow
+		};
+	}
+	$effect(() => {
+		const v = videoEl;
+		void crossorigin; // a CORS opt-in clears a 'cors' refusal; removing it after routing is 'unsafe-src'
+		void src;
+		const o = v ? audioOpts(v) : null;
+		if (o) untrack(() => audio?.apply(o));
+	});
 
 	// ── Night (video/night/*) ───────────────────────────────────────────────
 	// The modules decide; this block samples the frame and applies the answer

package/dist/components/VideoPlayer.svelte.d.ts

@@ -3,11 +3,15 @@ export type { BandAxis, BandState } from '../video/band/axis';
 export type { VideoLumaTrack } from '../video/band/luma';
 export type { VideoMarker } from '../video/band/markers';
 export type { NightMode, NightWindow } from '../video/night/clock';
+export type { AudioState, AudioStatus, AudioBrokenReason } from '../video/audio/graph';
+export type { VideoAdSpan, RateReport } from '../video/rate';
 import type { VideoBookmark, VideoChapter, VideoSpeakerTalkTime, VideoSpeakerTurn, VideoTranscriptSegment, VideoWaveform } from '../video/types';
 import { type BandState } from '../video/band/axis';
 import { type VideoLumaTrack } from '../video/band/luma';
 import { type VideoMarker } from '../video/band/markers';
+import { type RateReport, type VideoAdSpan } from '../video/rate';
 import { type NightMode, type NightWindow } from '../video/night/clock';
+import { type AudioBrokenReason, type AudioState } from '../video/audio';
 type $$ComponentProps = {
     src: string;
     poster?: string | null;
@@ -138,6 +142,78 @@ type $$ComponentProps = {
     onNightModeChange?: (mode: NightMode) => void;
     /** Frame readback was refused (CORS-tainted canvas) — night fell back to a fixed level. */
     onNightBlind?: () => void;
+    /**
+     * Audio graph (mos-5lzns.31) — all three default OFF (absent = the
+     * feature does not exist on this player and nothing is ever routed).
+     *
+     * `loudness`: a gated RMS meter rides the gain slowly toward
+     * `loudnessTarget` (dBFS, −30…−12, default −20) so a whispered video and
+     * a blaring one arrive at the same level; clamped 0.3–1.35×, it rescues a
+     * quiet mix by a few dB and never becomes an amplifier.
+     * `quietListening`: loudness-compensated tone that rises as the volume
+     * drops (and sits a little on while night is armed).
+     * `limiter`: catches peaks above −3 dBFS that the slow rider can't.
+     *
+     * ⚠ Routing into WebAudio is permanent for the element, and a source
+     * that isn't CORS-clean routes to SILENCE. So the player routes only
+     * when the src is blob:/data: or `crossorigin` is set ("anonymous" /
+     * "use-credentials", with the server answering Access-Control-Allow-
+     * Origin) — a same-origin URL is NOT enough, since it may redirect to
+     * storage on another origin. Anything else is refused and plays
+     * unprocessed (`status: 'cors'`). It also waits for the AudioContext to
+     * be `running` (a user gesture); until then native audio plays.
+     *
+     * After routing it cannot be undone, so the player reports
+     * `status: 'broken'` and calls `onAudioBroken(reason)`:
+     * · 'unsafe-src' — the src later changed to one that isn't route-safe
+     *   (or `crossorigin` was removed). Remount the player (a fresh element)
+     *   for that source.
+     * · 'silent' — bit-exact silence for 4s while the video plays audibly
+     *   AND the browser shows decoded audio flowing (a video with no audio
+     *   track never fires). Show a notice and/or turn the audio features
+     *   off for that src — do NOT remount; it would loop.
+     * · 'build-failed' — construction threw: plain audio for the session.
+     */
+    loudness?: boolean;
+    loudnessTarget?: number;
+    quietListening?: boolean;
+    limiter?: boolean;
+    /** Graph status + the rider's live gain (≤5×/s while matching acts). */
+    onAudioState?: (state: AudioState) => void;
+    /** Entered `broken`: 'build-failed' | 'unsafe-src' | 'silent' (see above). */
+    onAudioBroken?: (reason: AudioBrokenReason) => void;
+    /**
+     * Rate composer (mos-5lzns.32): `rate = base × speaker × silence`. The
+     * speed readout only ever reports `base` — the rate a human chose — so it
+     * keeps saying `1×` while a gap is taken at 2.2×. Every advisor is off by
+     * default and collapses to 1 until its data arrives: off, the element
+     * plays at exactly `base`.
+     *
+     * Smart speed: run the silences between sentences at 2.2×, found off the
+     * `waveform` envelope. Speech stays at `base`.
+     */
+    smartSpeed?: boolean;
+    /**
+     * Per-speaker pace: level everyone to the median words-per-minute,
+     * measured from the diarised `transcript` + `speakers`. Ad reads and
+     * gaps between turns play at `base`.
+     */
+    speakerPace?: boolean;
+    /**
+     * Hand-set speaker rates keyed by speaker NAME (the legend's display
+     * name). They always beat measured ones, and like them apply only while
+     * `speakerPace` is on — off means off. Range 0.0625–16.
+     */
+    speakerRates?: Record<string, number> | null;
+    /** Host-detected ad reads. Merged with any `ad: true` speaker turns. */
+    adSpans?: VideoAdSpan[] | null;
+    /**
+     * Skip ad reads: when playback runs into an ad span it jumps to its end
+     * (the OSD says so). A seek that lands inside an ad is honoured.
+     */
+    skipAds?: boolean;
+    /** The composed rate changed (real change only). `base` is what the UI shows. */
+    onRateChange?: (report: RateReport) => void;
     class?: string;
 };
 declare const VideoPlayer: import("svelte").Component<$$ComponentProps, {

package/dist/index.d.ts

@@ -12,7 +12,8 @@ export type { ChapterBlock } from './components/replay/ChapterTimeline.svelte';
 export { default as TranscriptPlayer } from './components/TranscriptPlayer.svelte';
 export type { TranscriptSegment, TranscriptBookmark, TranscriptChapter, TranscriptSpeakerTalkTime, } from './components/TranscriptPlayer.svelte';
 export { default as VideoPlayer } from './components/VideoPlayer.svelte';
-export type { VideoChapter, VideoSpeakerTurn, VideoTranscriptSegment, VideoBookmark, VideoWaveform, VideoSpeakerTalkTime, VideoLumaTrack, VideoMarker, BandState, BandAxis, NightMode, NightWindow, } from './components/VideoPlayer.svelte';
+export type { VideoChapter, VideoSpeakerTurn, VideoTranscriptSegment, VideoBookmark, VideoWaveform, VideoSpeakerTalkTime, VideoLumaTrack, VideoMarker, BandState, BandAxis, NightMode, NightWindow, AudioState, AudioStatus, AudioBrokenReason, VideoAdSpan, RateReport, } from './components/VideoPlayer.svelte';
+export { speakerRateMap, toRateTurns, toRateSegments } from './video/rate';
 export { buildSilenceMap, boostAt, estimateSaving, type SilenceMap, type SilenceWave, type SilenceOpts, type BoostOpts } from './video/advisors/smart-speed';
 export { speakerPace, suggestRates, rateAt, describeRates, type SpeakerPace, type SpeakerPaceRow, type RateMap, type RateTurn, type RateSegment, type SuggestOpts } from './video/advisors/speaker-rate';
 export { snapResume, resumeLabel, type ResumePoint, type ResumeReason, type ResumeCtx, type ResumeOpts } from './video/advisors/resume-point';

package/dist/index.js

@@ -13,6 +13,10 @@ export { default as TranscriptPlayer } from './components/TranscriptPlayer.svelt
 // optional so a bare mp4 still gets the full playback UX. TranscriptPlayer
 // stays exported unchanged — meetings already depends on it.
 export { default as VideoPlayer } from './components/VideoPlayer.svelte';
+// Rate composer (mos-5lzns.32): the same name → rate table the player applies
+// under `speakerPace` (manual beats measured), for a host drawing its own
+// per-speaker speed UI.
+export { speakerRateMap, toRateTurns, toRateSegments } from './video/rate';
 // Pure advisors (mos-5lzns.27): the extension-library self-test modules,
 // ported verbatim. They measure and advise; the player's feature tasks
 // (.31 audio / .32 rate / .34 presence) consume them. qrCanvas is the one

package/dist/video/README.md

@@ -17,17 +17,17 @@ props + callback surfaces.
 | `band.ts` | .28 (done) — extended by **.30** | The timeline band: zoom window (`BandWindow`, `zoomAt`, `followPlayhead`), hit tests (`segmentAt`, `chapterAt`, `biasToSegmentStart`, `nearestBookmark`), and `paintBand` (canvas). .30 adds one-axis arbitration + the light ribbon; its state lives HERE. |
 | `band/` | **.30** (done) | `window.ts` — the zoom-window math (moved out of band.ts, re-exported there; shared by every band layer without an import cycle). `axis.ts` — one-axis four-state arbitration (`resolveAxis`, `BandState`, the churn-guarded microtask `createBandReporter`), `playheadX` (the one "where you are" mapping — ≤0.2px agreement) and `overviewBracket`. `luma.ts` — the light track (`VideoLumaTrack`, the sidecar verbatim) → ribbon (`v² × 0.55`, max-per-interval). `markers.ts` — `VideoMarker` comments (clustered dots) + like heat. |
 | `keys.ts` | .28 (done) | The keyboard map — `PLAYER_KEYS` (the `?` overlay renders it), `chapterJump`, `FRAME_STEP_SEC`. Every key that exists is in the map; a key not in the map doesn't exist. |
-| `rate.ts` | .28 (done) — filled by **.32** | The rate composer contract (`composeRate`, deadband, clamp), the `SPEED_STEPS` staircase, `formatSpeedLabel`. .32 adds the speaker-pace and silence-map advisors — they never write `playbackRate`; they advise. |
+| `rate.ts` + `rate/` | .28 contract — **.32** (done) | `rate.ts` is the barrel. `compose.ts` — the contract (`composeRate`, clamp [0.0625, 16], `shouldWriteRate`'s 0.001 deadband with an exact return to base), the `SPEED_STEPS` staircase, `formatSpeedLabel`. `speaker.ts` — props → `advisors/speaker-rate`; manual rates keyed by NAME always beat measured. `silence.ts` — waveform → `advisors/smart-speed` map + boost + the OSD saving claim. `ads.ts` — `adSpans` ∪ `ad: true` turns; skip only when PLAYBACK runs into an ad, never when a seek lands in one. `tick.ts` — the component's own 120ms loop's one-tick decision. None of them write `playbackRate`; they advise. |
 | `deepLink.ts` | .28 (done) | `?t=` parse/format/read/write (replaceState, throttled, other params preserved). |
 | `settings.ts` | shared — knobs added by .30–.34 | `coerce` (never throws, never junk) + `VIDEO_SETTINGS` registry. A knob lands WITH its reader. |
-| `audio.ts` | **.31** | Loudness matching, quiet listening, limiter — audio-graph contract is in the file header. |
+| `audio.ts` + `audio/` | **.31** (done) | `audio.ts` is the barrel. `rider.ts` — pure: RMS dBFS (silence → null), the 12 dB relative-gated loud estimate (rise 0.08 / forget 0.01), want-gain clamped 0.3–1.35, the asymmetric ride (down 0.15 / up 0.02), limiter constants + `compressorMakeupDb`/`limiterTrim` (DynamicsCompressor's automatic makeup, cancelled by a trim node), `routeSafety` (only blob:/data: or a `crossorigin` load — a same-origin URL may redirect cross-origin and route to SILENCE). `graph.ts` — `createAudioSession`: source → gain → quiet chain → limiter → trim → destination, analyser on the source. Context first, route last: the element is taken only when a feature is on, the source is route-safe and `ctx.state === 'running'` (gestures resume + retry; never navigator.userActivation). After routing it watches: an unsafe src or bit-exact zeros while audibly playing ⇒ `broken` (`unsafe-src` / `silent`) via `onBroken`. A construction throw is a permanent `build-failed` (context closed if the element wasn't taken; kept with source → destination if it was). Level off cancels before it sets; limiter moves are ramped. The element never enters the module — the component passes a `route` closure. |
 | `night.ts` + `night/` | **.33** (done) | `night.ts` is the barrel. `meter.ts` — 32×18 frame bytes → Rec.709 luma + blown share, asymmetric smoothing, bias-light cells from the same bytes. `levels.ts` — luma → brightness/saturation/warmth/vignette off `NIGHT_FLOOR` 0.34, blind fixed level, the light-theme surround. `clock.ts` — local-clock `auto` window + the `N` auto/on/off cycle (no hyprsunset). `track.ts` — prediction (only ever adds dimming), flash intervals, `composeNight` (darker at once, brighter released per tick — never a jump). |
 | `presence.ts` | **.34** | Wind-down (Idle Detection), resume-at-sentence, FLIP open. |
 | `advisors/` | **.27 (done)** | The five extension-library pure advisors, ported verbatim: `smart-speed` (silence map + boost), `speaker-rate` (measured wpm + suggested rates), `resume-point` (sentence-snapping + the label), `quiet-listening` (tone-only chain + `amountFor`), `qr` (ISO 18004 encoder v1–10). Each has its own README row in `advisors/README.md`; the `--self-test` suites live on as vitest in `tests/unit/advisors/` (`npm run test:advisors`). |
 
 Sub-task map: **.30** scrubbing/one-axis/ribbon/markers → `band.ts` (+ its own
 paint layers); **.31** audio graph → `audio.ts`; **.32** rate composer →
-`rate.ts` advisors; **.33** night → `night.ts`; **.34** presence/wind-down →
+`rate.ts` + `rate/`; **.33** night → `night.ts`; **.34** presence/wind-down →
 `presence.ts`. **.27** (landed) ports the advisors themselves — .31's chain
 builder and `amountFor` live in `advisors/quiet-listening`, .32's two advisor
 modules in `advisors/smart-speed` + `advisors/speaker-rate`, .34's snapping in
@@ -44,8 +44,9 @@ feature task.
    the prompt).
 3. **Measuring code is an advisor; the component decides and applies.**
    Modules under `src/lib/video/` read no settings and touch no `<video>`
-   (the audio graph builder is the one exception, and it takes a
-   MediaElementAudioSourceNode, never the element). Knobs arrive as an
+   (the audio graph builder is the one exception: it touches AudioContext,
+   but takes the element only through a `route` closure the component owns
+   — never the element itself). Knobs arrive as an
    `opts` argument; a bad argument returns a safe neutral value rather than
    throwing. This is what keeps every module node-testable under
    `npm run test:unit` (the advisor vitest suites run under

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

@@ -0,0 +1,115 @@
+/** What the host asks for. Booleans are "feature on"; volume/muted/night feed quiet listening's amount. */
+export interface AudioOpts {
+    level: boolean;
+    target?: number;
+    limiter: boolean;
+    quiet: boolean;
+    volume?: number;
+    muted?: boolean;
+    night?: boolean;
+}
+/**
+ * · 'off'    — nothing routed (no feature on, no source yet, or the context is
+ *              still waiting for a gesture to start). Native audio plays.
+ * · 'live'   — routed and processing.
+ * · 'cors'   — a feature is on but the source isn't route-safe: refused,
+ *              audio plays unprocessed. Clears when the source does.
+ * · 'broken' — see `reason`.
+ */
+export type AudioStatus = 'off' | 'live' | 'cors' | 'broken';
+/**
+ * · 'build-failed' — construction threw; plain audio for the session (permanent).
+ * · 'unsafe-src'   — routed, then the src/crossorigin changed to one that is
+ *                    not route-safe: this element may now be SILENT.
+ * · 'silent'       — routed, playing audibly, clock advancing, decoded audio
+ *                    evidently flowing, and the analyser reads bit-exact
+ *                    zeros for SILENT_AFTER_MS. Show a notice / disable the
+ *                    features for this src — do NOT remount (it would loop).
+ */
+export type AudioBrokenReason = 'build-failed' | 'unsafe-src' | 'silent';
+export interface AudioState {
+    status: AudioStatus;
+    /** Why `status` is 'broken'; null otherwise. */
+    reason: AudioBrokenReason | null;
+    /** The rider's current gain, dB (0 when level matching is off or unmeasured). */
+    gainDb: number;
+    /** The gated loud-level estimate, dBFS — null until something has been heard. */
+    loudDb: number | null;
+    /** Quiet listening's current amount, 0..1. */
+    quiet: number;
+}
+interface ParamLike {
+    value: number;
+    setTargetAtTime?(v: number, t: number, tau: number): unknown;
+    setValueAtTime?(v: number, t: number): unknown;
+    cancelScheduledValues?(t: number): unknown;
+}
+interface NodeLike {
+    connect(dest: unknown): unknown;
+    disconnect?(): unknown;
+    gain?: ParamLike;
+    threshold?: ParamLike;
+    knee?: ParamLike;
+    ratio?: ParamLike;
+    attack?: ParamLike;
+    release?: ParamLike;
+    fftSize?: number;
+    getFloatTimeDomainData?(buf: Float32Array): void;
+}
+export interface AudioContextLike {
+    currentTime: number;
+    destination: unknown;
+    /** 'suspended' | 'running' | 'closed' — absent (a test double) reads as running. */
+    state?: string;
+    createGain(): NodeLike;
+    createDynamicsCompressor(): NodeLike;
+    createAnalyser(): NodeLike;
+    createBiquadFilter?(): unknown;
+    resume?(): unknown;
+    close?(): unknown;
+    addEventListener?(type: string, fn: () => void): void;
+}
+export interface AudioPlayback {
+    /** Not paused and not ended. */
+    playing: boolean;
+    /** Tab hidden — the rider holds its estimate. */
+    hidden: boolean;
+    /** Not muted and volume > 0 — silence would be a fault, not a choice. */
+    audible: boolean;
+    /** currentTime, seconds. */
+    time: number;
+    /**
+     * Evidence that the element HAS decoded audio. `audioDecoded`: Chromium's
+     * webkitAudioDecodedByteCount (must be RISING to count); `audioPresent`:
+     * Gecko's mozHasAudio or WebKit's audioTracks.length > 0. null = unknown.
+     * With no positive evidence the silence watchdog never fires.
+     */
+    audioDecoded?: number | null;
+    audioPresent?: boolean | null;
+}
+export interface AudioSessionDeps {
+    /** Is the element's current source route-safe? (rider.ts `routeSafety`) */
+    routable(): 'ok' | 'wait' | 'cors';
+    /** Create the AudioContext. Does NOT touch the element. */
+    context(): AudioContextLike;
+    /** Take the element: createMediaElementSource. The one-way door — called at most once. */
+    route(ctx: AudioContextLike): NodeLike;
+    playback(): AudioPlayback;
+    /** State changes + each rider tick. */
+    onState?(state: AudioState): void;
+    /** Entered `broken` (or its reason changed). */
+    onBroken?(reason: AudioBrokenReason): void;
+    /** Timer seam (tests). Defaults to setInterval/clearInterval. */
+    every?(ms: number, fn: () => void): () => void;
+}
+export interface AudioSession {
+    apply(opts: AudioOpts): void;
+    /** A user gesture (or play): resume the context, retry a pending route. */
+    gesture(): void;
+    /** One watchdog + rider step (the session's own timer calls this; exposed for tests). */
+    tick(): void;
+    state(): AudioState;
+    dispose(): void;
+}
+export declare function createAudioSession(deps: AudioSessionDeps): AudioSession;
+export {};