import { attachElementFxChain, readElementAutomation, scheduleVolume, type ElementFxHandle, type FxAttributes, type VolumeTarget, } from "./audioFx.js"; import { clearParamLane, type AutomationTiming } from "../audio/audioFxAutomation.js"; import { audioGroupOf, readAudioGroupVolume, resolveGroupElement, resolveMasterBusElement, } from "../audioGroups.js"; import { swallow } from "./diagnostics"; import { reportMediaLoadFailure } from "./mediaLoadFailure"; import { createLevelTap, type LevelTap, type StereoLevel } from "./levelTap.js"; import { clampAudioGain } from "../audioGain.js"; import { getDebugSurface } from "./globals.js"; import { readElementPlaybackRate, readElementRateSpec } from "./media.js"; import { rateAt, sourceTimeAt, timeAtSourceTime } from "../speedRamp.js"; import { classifyWebAudioMediaRoute, reportWebAudioMediaRoute } from "./webAudioRoute.js"; import { assetUrl } from "./assetUrl.js"; import { mediaElementTime } from "./mediaClock.js"; import { clampFadesToDuration, fadeGain, readElementFades } from "../audioFade.js"; const MASTER_FX_ATTRS: FxAttributes = { automation: null }; function normalizeRate(rate: number): number { if (!Number.isFinite(rate) || rate <= 0) return 1; return rate; } /** * The render puts every track volume through `clampVolume`, which is * `clampAudioGain` — ceiling MAX_AUDIO_GAIN (+12 dB, ~3.98), not unity. Preview * has to agree or the two diverge on exactly the attribute this bus exists to * honour: an authored `` previewed at 1.0 and * exported at 2.0, up to 6 dB quieter in the audition than in the file, and * 12 dB at the ceiling. Preview was also self-inconsistent — the same * parameter's automation lane is bounded by `VOLUME_RANGE.max`, which IS * MAX_AUDIO_GAIN, so an envelope could reach 3.98 where the static fader could * not pass 1.0. `clampAudioGain` still floors at 0, so a negative value cannot * invert polarity in preview while rendering silent. Compositions are * hand-authorable, so out-of-range values do not need a slider to be reachable. */ function clampGroupVolume(volume: number): number { return clampAudioGain(volume); } /** * Breadcrumb for the per-element-mute handoff: the transport just claimed a track * that was audibly playing through the HTMLMedia fallback. Quiet unless * `__hfDebug` — a hook for diagnosing the race if it ever regresses. */ function logFallbackHandoff(el: HTMLMediaElement, priorMuted: boolean): void { if (priorMuted || el.paused || !getDebugSurface().__hfDebug) return; // eslint-disable-next-line no-console -- intentional debug surface console.debug( "[hyperframes] webAudioTransport claimed fallback-playing element:", el.currentSrc || el.getAttribute("src") || "", ); } /** * Start a buffer source, bounding it to the clip's authored window * (`data-duration`) so a trimmed clip stops at its edge instead of running the * buffer to the source file's natural end. `remaining`, the third `start()` arg, * is the rest of the clip from the offset in buffer seconds. An infinite * `clipDuration` plays unbounded (legacy behavior). * * Returns false when the playhead is already past the clip end (nothing to * play); the caller should discard the source. */ function startBoundedSource( node: AudioBufferSourceNode, opts: { elapsed: number; mediaStart: number; scheduledAt: number; globalRate: number; mediaRate: number; clipDuration: number; headCut: number; }, ): boolean { const { elapsed, mediaStart, scheduledAt, globalRate, mediaRate, clipDuration, headCut } = opts; const hasBound = Number.isFinite(clipDuration) && clipDuration > 0; const from = Math.max(elapsed, headCut, 0); const remaining = (clipDuration - from) * mediaRate; if (hasBound && remaining <= 0) return false; const when = from > elapsed ? scheduledAt + (from - elapsed) / globalRate : 0; if (hasBound) node.start(when, from * mediaRate + mediaStart, remaining); else node.start(when, from * mediaRate + mediaStart); return true; } type BookedFades = { node: GainNode; rebook(timing: AutomationTiming): void }; /** * The clip's `data-fade-in` / `data-fade-out` booked on their own gain on the audio clock, from where the clip starts * sounding (`from`, clip seconds). A per-tick volume write is 50 ms apart, coarser than a fade: stepped, the clip * starts and stops at full level and clicks at every cut. Null when the clip has no fade, or a fade-out with no end * to book it against, which the per-tick volume keeps. */ function bookedFades( ctx: AudioContext, el: HTMLMediaElement, timing: AutomationTiming, from: number, clipDuration: number, ): BookedFades | null { const fades = clampFadesToDuration(readElementFades(el), clipDuration); if (fades.fadeIn <= 0 && fades.fadeOut <= 0) return null; if (fades.fadeOut > 0 && !Number.isFinite(clipDuration)) return null; const node = ctx.createGain(); const gain = node.gain; const level = (clipSeconds: number) => fadeGain(clipSeconds, clipDuration, fades); const book = (t: AutomationTiming) => { const start = Math.max(from, t.elapsed); const at = (clipSeconds: number) => t.scheduledAt + Math.max(0, clipSeconds - t.elapsed) / t.rate; gain.value = level(start); gain.setValueAtTime(level(start), at(start)); if (fades.fadeIn > start) gain.linearRampToValueAtTime(level(fades.fadeIn), at(fades.fadeIn)); if (fades.fadeOut > 0) { const hold = clipDuration - fades.fadeOut; if (hold > start && hold > fades.fadeIn) gain.setValueAtTime(level(hold), at(hold)); gain.linearRampToValueAtTime(0, at(clipDuration)); } }; book(timing); return { node, rebook: (t) => { gain.cancelScheduledValues(0); book(t); }, }; } // Clip gain, FX, then the volume lane on its own gain ahead of `gainNode` (all but the lane // rewritten every tick); the FX handle re-aims the lane on rate changes and edits. function attachClipStages( ctx: AudioContext, el: HTMLMediaElement, source: AudioNode, gainNode: GainNode, timing: AutomationTiming, span: { from: number; clipDuration: number }, ): { fx: ElementFxHandle | null; laneNode: GainNode; clipGainNode: GainNode; fades: BookedFades | null; } { const laneNode = ctx.createGain(); laneNode.connect(gainNode); const clipGainNode = ctx.createGain(); const fades = bookedFades(ctx, el, timing, span.from, span.clipDuration); if (fades) source.connect(fades.node); (fades?.node ?? source).connect(clipGainNode); const fx = attachElementFxChain(ctx, el, clipGainNode, laneNode, timing, undefined, { param: laneNode.gain, gain: () => readAudioGroupVolume(el), gainAhead: true, }); return { fx, laneNode, clipGainNode, fades }; } type ScheduledSourceBase = { el: HTMLMediaElement; gainNode: GainNode; /** The clip's volume lane, between its FX and `gainNode`; unity when it has none. */ laneNode: GainNode; /** `data-volume` as clip gain, between the source and its FX. */ clipGainNode: GainNode; /** FX chain spliced between source and gain, when the element carries one. */ fx?: ElementFxHandle | null; /** The clip's fades booked on the audio clock, between the source and its clip gain; absent without a fade. */ fades?: BookedFades | null; /** Stops re-aiming the lane and fades at a routed element's own position. */ unfollow?: () => void; /** A routed element's first stage: unity except while `seekUnderDip` hides a seek. */ dipNode?: GainNode; dipping?: boolean; compositionStart: number; mediaStart: number; scheduledAt: number; priorMuted: boolean; priorVolume: number; mediaPlaybackRate: number; // The clip had a finite window, so start() was given a fixed duration in // buffer-sample seconds. That bound can't be rescaled in place on a rate // change — callers must stopAll()+reschedule (see hasBoundedActiveSources). bounded: boolean; }; export type ScheduledSource = ScheduledSourceBase & ( | { sourceKind: "buffer"; sourceNode: AudioBufferSourceNode } | { sourceKind: "media-element"; sourceNode: MediaElementAudioSourceNode } ); function isBufferSource( source: ScheduledSource, ): source is ScheduledSourceBase & { sourceKind: "buffer"; sourceNode: AudioBufferSourceNode } { return source.sourceKind === "buffer"; } const decodeKey = (el: HTMLMediaElement): string | null => { const src = el.currentSrc || el.getAttribute("src"); if (!src) return null; try { return assetUrl(src); } catch { return src; } }; const DIP_SECONDS = 0.015; /** A dipped seek comes back up when the element lands, or when it can no longer land. */ const DIP_END_EVENTS = ["seeked", "error", "emptied", "abort"] as const; /** Where a routed element starts sounding or jumps; a pause needs nothing, no audio flows until `playing`. */ const FOLLOWED_EVENTS = ["playing", "seeked", "ratechange"] as const; // A pause to scrub or a reschedule mid-play keeps the output awake; a real idle lets it sleep. const IDLE_SUSPEND_MS = 10000; const SHORT_DECODE_SECONDS = 0.25; const DECODE_BUDGET_BYTES = 256 * 1024 * 1024; const ASSUMED_CHANNELS = 2; const BYTES_PER_SAMPLE = 4; export class WebAudioTransport { private _ctx: AudioContext | null = null; private _bufferCache = new Map(); private _decoding = new Map>(); private _pendingDecodeBytes = new Map(); private _failedSrcs = new Set(); private _mediaElementSources = new WeakMap(); private _handedOver = new Set(); private _activeSources: ScheduledSource[] = []; private _masterGain: GainNode | null = null; /** Where the master bus chain lands; the program meter taps here. */ private _busOut: GainNode | null = null; /** The chain on the composition root, built on first schedule and kept for the session. */ private _master: { fx: ElementFxHandle | null; generation: number } | null = null; /** Preview volume and mute. Downstream of `_masterGain`; meters tap the program. */ private _monitorGain: GainNode | null = null; private _masterVolume = 1; private _masterMuted = false; // One shared bus per group id, lazily built the first time a member of that // group is scheduled. Lives for the session (mirrors `_masterGain`'s own // lifecycle) rather than being torn down on every `stopAll()`, so replaying // a group does not rebuild its chain; only `destroy()` disposes these. private _groups = new Map< string, { input: GainNode; /** Where the bus meets master; the level meter taps here. */ output: GainNode; /** False once the group's element is gone from the document. */ isPresent(): boolean; /** Post-FX fader: `data-volume` times the volume lane. */ fader: GainNode; muteGain: GainNode; /** Kept so `setRate` can re-aim this bus's FX automation, the way it does * every source's — its docblock claims it already did. */ fx: ElementFxHandle | null; /** Play generation the current envelopes were booked against. */ generation: number; reanchor(timing: AutomationTiming): void; dispose(): void; } >(); // Level taps exist only between `startMetering()` and `stopMetering()`. private _metering = false; private _masterTap: LevelTap | null = null; private _groupTaps = new Map(); // Composition-time reference frame: at AudioContext time `_rateAnchorCtx`, // composition time was `_rateAnchorComp`, and time has been advancing at // `_rate` composition-seconds per wallclock-second since. private _rateAnchorCtx = 0; private _rateAnchorComp = 0; private _rate = 1; private _paused = true; private _playGeneration = 0; // A running context renders silence nonstop, so a paused transport keeps it // suspended unless a captured track is sounding on the idle route (scrub). private _playingCaptured = new Set(); private _suspendPending = false; private _restTimer: ReturnType | null = null; async init(): Promise { try { this._ctx = new AudioContext(); this._ctx.onstatechange = () => this.rest(); this._masterGain = this._ctx.createGain(); this._busOut = this._ctx.createGain(); this._monitorGain = this._ctx.createGain(); this._masterGain.connect(this._busOut); this._busOut.connect(this._monitorGain); this._monitorGain.connect(this._ctx.destination); this.applyMasterGain(); if (this._metering) this.attachMasterTap(); return true; } catch { return false; } } private async wake(): Promise { if (!this._ctx || (this._ctx.state === "running" && !this._suspendPending)) return; this._suspendPending = false; await this._ctx.resume(); } private rest(): void { if (this._restTimer !== null) clearTimeout(this._restTimer); this._restTimer = null; if (!this._ctx || this._ctx.state !== "running" || this._suspendPending) return; this._restTimer = setTimeout(() => { this._restTimer = null; this.suspendIfIdle(); }, IDLE_SUSPEND_MS); } private suspendIfIdle(): void { // `paused` is the truth; the load algorithm clears it without a "pause" event. for (const el of this._playingCaptured) if (el.paused) this._playingCaptured.delete(el); if (!this._ctx || !this._paused || this._suspendPending || this._playingCaptured.size > 0) return; this._suspendPending = true; this._ctx.suspend().catch((err) => { this._suspendPending = false; swallow("webAudioTransport.suspend", err); }); } get context(): AudioContext | null { return this._ctx; } getTime(): number { if (!this._ctx || this._paused) return -1; return this._rateAnchorComp + (this._ctx.currentTime - this._rateAnchorCtx) * this._rate; } /** Drops decoded audio no listed element still points at. A playing source holds its own buffer. */ releaseDecodedExcept(els: readonly HTMLMediaElement[]): void { const live = new Set(els.map(decodeKey)); for (const src of [...this._bufferCache.keys()]) { if (!live.has(src)) this._bufferCache.delete(src); } } /** One fetch and decode per source at a time: a play and a seek scheduling together share it. */ decodeAudioElement(el: HTMLMediaElement): Promise { const src = decodeKey(el); if (!src) return Promise.resolve(null); const pending = this._decoding.get(src); if (pending) return pending; this._pendingDecodeBytes.set(src, this.estimateDecodedBytes(el.duration)); const decoding = this.fetchAndDecode(src, el).finally(() => { this._decoding.delete(src); this._pendingDecodeBytes.delete(src); }); this._decoding.set(src, decoding); return decoding; } fitsDecodeBudget(el: HTMLMediaElement): boolean { const src = decodeKey(el); if (!src) return false; if (this._bufferCache.has(src) || this._decoding.has(src)) return true; if (!Number.isFinite(el.duration)) return false; return this.decodedBytes() + this.estimateDecodedBytes(el.duration) <= DECODE_BUDGET_BYTES; } private estimateDecodedBytes(seconds: number): number { const rate = this._ctx?.sampleRate ?? 48000; if (!Number.isFinite(seconds)) return 0; return seconds * rate * ASSUMED_CHANNELS * BYTES_PER_SAMPLE; } private decodedBytes(): number { let bytes = 0; for (const buffer of this._bufferCache.values()) bytes += buffer.length * buffer.numberOfChannels * BYTES_PER_SAMPLE; for (const pending of this._pendingDecodeBytes.values()) bytes += pending; return bytes; } private async fetchAndDecode(src: string, el: HTMLMediaElement): Promise { if (this._bufferCache.has(src)) return this._bufferCache.get(src)!; if (this._failedSrcs.has(src)) return null; if (!this._ctx) return null; // Fetch the bytes. A network error or non-OK status (e.g. a 404 for an // asset that simply has not been uploaded yet) is TRANSIENT — return null // WITHOUT blacklisting, so the next play/seek generation retries once the // asset becomes available. (Previously these were added to `_failedSrcs`, // which is never cleared, permanently silencing a merely-late track.) let arrayBuffer: ArrayBuffer; try { // `no-store`: a retry must actually re-request the asset — not replay a // cached 404/stale response from the failed attempt that we chose not to // blacklist. const response = await fetch(src, { cache: "no-store" }); if (!response.ok) { swallow("webAudioTransport.fetch", new Error(`${response.status} ${src}`)); reportMediaLoadFailure(el, "fetch", response.status); return null; } arrayBuffer = await response.arrayBuffer(); } catch (err) { swallow("webAudioTransport.fetch", err); reportMediaLoadFailure(el, "fetch", null); return null; } // A decode failure means the bytes themselves are unusable (corrupt or an // unsupported codec) — that IS permanent, so blacklist to avoid re-decoding // the same bad payload on every generation. try { const audioBuffer = await this._ctx.decodeAudioData(arrayBuffer); // A file whose container timescale disagrees with its stream decodes short; its element plays it whole. if ( Number.isFinite(el.duration) && el.duration - audioBuffer.duration > SHORT_DECODE_SECONDS ) { this._failedSrcs.add(src); return null; } this._bufferCache.set(src, audioBuffer); return audioBuffer; } catch (err) { this._failedSrcs.add(src); swallow("webAudioTransport.decode", err); reportMediaLoadFailure(el, "decode", null, arrayBuffer.byteLength); return null; } } startGeneration(): number { this._playGeneration += 1; return this._playGeneration; } currentGeneration(): number { return this._playGeneration; } /** * The element's cached MediaElementAudioSourceNode, building it on first use * — or `null` when this element must not be captured at all. * * That second outcome is the whole point. `createMediaElementSource` cannot * report that it produced a silent node: over a CORS-cross-origin resource * the Web Audio spec asks the node for SILENCE rather than an exception, so * the caller's `try/catch` never fires and the composition plays through * with no audio and no error (#3458). The call also permanently reroutes the * element away from its native output, so the question has to be settled * before it, and there is no undo afterwards. * * `init.ts` routes on the same verdict before ever calling in, and * `AudioRow.tsx`'s standalone preview player classifies over its own * throwaway `AudioContext` before its own `createMediaElementSource` call — * this method is A enforcement point, not THE enforcement point; every * caller that can reach `createMediaElementSource` is expected to classify * first. What this method DOES own is the cache below: `_mediaElementSources` * is keyed by element identity, not by asset, so a cache hit alone says * nothing about the element's CURRENT resource. Reclassifying on every call * — cache hit included — means a `src` mutation an outer caller missed (a * pooled element swapped from a same-origin clip to a cross-origin one * without going through a fresh generation) can't leave a stale * `web-audio` verdict silently attached to the new resource. */ private acquireMediaElementSource(el: HTMLMediaElement): MediaElementAudioSourceNode | null { const cached = this._mediaElementSources.get(el); if (cached) { // The node itself doesn't change identity on a src swap, but its // eligibility can: the Web Audio spec's tainted-origin check runs // against the element's CURRENT underlying resource, not the one that // was current when the node was built. A same-origin-to-cross-origin // mutation on this element would otherwise keep returning the old // (now-silent) node forever — `destroy()` was the only thing that ever // cleared this cache, so a long-lived element that changed sources // stayed silenced for the rest of the session (the R2 finding this // block exists to close). The node is still a one-way door — it can't // be un-created, and the element's native output is gone either way — // so disconnecting it just stops it feeding a graph that no longer // matches the asset; the caller falls back to the decode-only path. const route = classifyWebAudioMediaRoute(el); if (route.kind !== "web-audio") { try { cached.disconnect(); } catch { // Already torn down. } this._mediaElementSources.delete(el); reportWebAudioMediaRoute(el, route); return null; } return cached; } if (!this._ctx) return null; const route = classifyWebAudioMediaRoute(el); if (route.kind !== "web-audio") { reportWebAudioMediaRoute(el, route); return null; } const sourceNode = this._ctx.createMediaElementSource(el); this._mediaElementSources.set(el, sourceNode); if (!el.paused) this._playingCaptured.add(el); el.addEventListener("play", () => { this._playingCaptured.add(el); void this.wake(); }); const stopped = () => { this._playingCaptured.delete(el); this.rest(); }; el.addEventListener("pause", stopped); el.addEventListener("emptied", stopped); return sourceNode; } /** * Route the browser's pitch-preserving HTMLMediaElement transport through the * same FX, automation, element-gain, and master graph used by final audio. * The media element remains the source-time/rate owner; Web Audio is strictly * downstream and therefore never resamples it for Studio global speed. */ async scheduleMediaElementPlayback( el: HTMLMediaElement, compositionStart: number, mediaStart: number, compositionTime: number, volume: number, generation: number, rate = 1, clipDuration = Number.POSITIVE_INFINITY, ): Promise { if (!this._ctx || !this._masterGain) return null; if (generation !== this._playGeneration) return null; try { await this.wake(); if (generation !== this._playGeneration) return null; const sourceNode = this.acquireMediaElementSource(el); if (!sourceNode) return null; sourceNode.disconnect(); const safeRate = normalizeRate(rate); const gainNode = this._ctx.createGain(); gainNode.gain.value = volume; const scheduledAt = this._ctx.currentTime; const elapsed = compositionTime - compositionStart; const timing: AutomationTiming = { scheduledAt, elapsed, rate: safeRate }; // The group bus, not master, for a member — same as the decoded-buffer // path. This transport is the PRIMARY one for audio (the decode path is // its fallback), so routing it at master would have left every grouped // track bypassing the bus whose whole premise is that a group is one // signal. gainNode.connect( this.resolveDestination(el, scheduledAt, compositionTime, safeRate) ?? this._masterGain, ); const dipNode = this._ctx.createGain(); sourceNode.connect(dipNode); const { fx, laneNode, clipGainNode, fades } = attachClipStages( this._ctx, el, dipNode, gainNode, timing, { from: Math.max(elapsed, 0), clipDuration }, ); this._rate = safeRate; this._rateAnchorCtx = scheduledAt; this._rateAnchorComp = compositionTime; const scheduled: ScheduledSource = { fx, fades, dipNode, el, sourceNode, sourceKind: "media-element", gainNode, laneNode, clipGainNode, compositionStart, mediaStart, scheduledAt, priorMuted: el.muted, priorVolume: el.volume, mediaPlaybackRate: readElementPlaybackRate(el), bounded: false, unfollow: this.followElement(el, compositionStart, mediaStart, fx, fades), }; // Chrome applies HTMLMediaElement.volume before MediaElementAudioSource. // Keep that upstream stage at unity so the existing downstream gain is // the single owner of author × user volume and automation. el.volume = 1; this._activeSources.push(scheduled); this._paused = false; return scheduled; } catch (err) { swallow("webAudioTransport.mediaElementSource", err); return null; } } /** * A routed element keeps its own time: it starts late, is seeked and is steered by rate. Its lane and fades were * booked against the context clock, so each time it starts or moves they are re-aimed at where it actually is. */ private followElement( el: HTMLMediaElement, compositionStart: number, mediaStart: number, fx: ElementFxHandle | null, fades: BookedFades | null, ): () => void { const retime = () => { if (el.paused || !this._ctx) return; const spec = readElementRateSpec(el); let source = el.currentTime - mediaStart; const loopLength = el.duration - mediaStart; // A looping element's position wraps: it is on the pass nearest where the transport expects it. if (el.loop && loopLength > 0) { const expected = sourceTimeAt(spec, this.getTime() - compositionStart); source += Math.round((expected - source) / loopLength) * loopLength; } const elapsed = timeAtSourceTime(spec, source); const rate = el.playbackRate / rateAt(spec, elapsed); // Stopped at rate 0, or with no position yet: no audio moves, so there is nothing to aim at. if (!(rate > 0) || !Number.isFinite(elapsed)) return; const timing: AutomationTiming = { scheduledAt: this._ctx.currentTime, elapsed, rate }; fx?.retime(timing); fades?.rebook(timing); }; for (const type of FOLLOWED_EVENTS) el.addEventListener(type, retime); return () => { for (const type of FOLLOWED_EVENTS) el.removeEventListener(type, retime); }; } /** * Seek a sounding routed element under a short gain dip: down, seek, and back up once it has landed, so the jump * is neither a click nor a tempo change. False when the element is not routed and has no dip to hide it under. */ seekUnderDip(el: HTMLMediaElement, target: number): boolean { const source = this._activeSources.find((s) => s.el === el && s.sourceKind === "media-element"); const ctx = this._ctx; if (!ctx || !source?.dipNode) return false; if (source.dipping) return true; source.dipping = true; const gain = source.dipNode.gain; const ramp = (to: number) => { const now = ctx.currentTime; gain.cancelScheduledValues(now); gain.setValueAtTime(gain.value, now); gain.linearRampToValueAtTime(to, now + DIP_SECONDS); }; const rise = () => { for (const type of DIP_END_EVENTS) el.removeEventListener(type, rise); source.dipping = false; ramp(1); }; ramp(0); setTimeout(() => { // A stop or a new pass in the meantime owns the element now. if (!this._activeSources.includes(source)) return; for (const type of DIP_END_EVENTS) el.addEventListener(type, rise); try { // Where the element would be by now had it been on time. el.currentTime = mediaElementTime(target + DIP_SECONDS * el.playbackRate); } catch (err) { swallow("webAudioTransport.seekUnderDip", err); rise(); } }, DIP_SECONDS * 1000); return true; } /** * The gain a grouped member's signal should land on, building it on first * use. A group's clock is COMPOSITION time (design doc §1.3) — it has no * `data-start`, and a missing start parses as 0, which is exactly * composition time — so its chain and volume lane are scheduled once here * against that zero-offset timing, not the member's own clip-local timing. * A group id with no matching `` element still gets a bus * (flat, no chain) so a hand-authored `data-audio-group` degrades to a * plain sum rather than losing the member's audio. */ private groupInput(groupId: string, doc: Document, timing: AutomationTiming): GainNode | null { const existing = this._groups.get(groupId); if (existing) { // The bus outlives `stopAll()` on purpose, so a replay or a seek reuses // this graph — but its envelopes were committed to the FIRST pass's // absolute context times. Left alone they hold their last value forever, // which for a fade-out is silence for the rest of the session. Re-anchor // once per play generation, not once per member scheduled. if (existing.generation !== this._playGeneration) { // Stamped only on success, and isolated: this runs inside // `schedulePlayback`, whose catch turns any throw into `return null` — // i.e. a bus problem would silently drop the MEMBER from the pass. And // stamping first would consume the generation, so no later member of // the same group would retry and the bus would keep the previous pass's // envelopes: finding 11 unfixed on exactly the pass that failed. try { existing.reanchor(timing); existing.generation = this._playGeneration; } catch (err) { swallow("webAudioTransport.groupReanchor", err); } } return existing.input; } if (!this._ctx || !this._masterGain) return null; const input = this._ctx.createGain(); // Stable point the FX chain (or, when there's none, the dry passthrough — // see `attachElementFxChain`'s `detach()`) always lands on before master, // regardless of whether a chain is attached/detached/rebuilt later. The // mute gain splices in BEFORE `output`, between the FX chain and here. const output = this._ctx.createGain(); output.connect(this._masterGain); // Tag-checked, and re-resolved on every reanchor below rather than frozen: // a bus whose element does not exist yet (studio group creation, or a // sub-composition that loads later) kept the `getAttribute: () => null` // stub for the whole session, so its fader, chain and mute never reached // preview while the export honoured all three. const resolveEl = (): Element | null => resolveGroupElement(doc, groupId); const groupEl = resolveEl(); const muteGain = this._ctx.createGain(); muteGain.gain.value = groupEl?.hasAttribute("data-hidden") ? 0 : 1; muteGain.connect(output); // The group's fader, POST-FX: `data-volume` is the static position and the // volume lane, scaled by it, rides it, which is where a DAW puts it and the // order the render bakes it in. Scheduling it // on `input` instead put the fader ahead of the effects, so any nonlinear // group effect — a compressor, the Giant preset — previewed differently // than it rendered. const fader = this._ctx.createGain(); fader.gain.value = clampGroupVolume(readAudioGroupVolume(groupEl)); fader.connect(muteGain); const faderLane: VolumeTarget = { param: fader.gain, gain: () => readAudioGroupVolume(resolveEl()), }; const fx = attachElementFxChain( this._ctx, groupEl ?? { getAttribute: () => null }, input, fader, timing, undefined, groupEl ? faderLane : undefined, ); this._groups.set(groupId, { input, output, isPresent: () => resolveEl() !== null, fader, muteGain, fx, generation: this._playGeneration, reanchor: (at: AutomationTiming) => { // Cleared BEFORE the value write, and unconditionally: a scheduled envelope // outranks a `.value` write, so a deleted lane's ramps would keep the param. clearParamLane([{ param: fader.gain }]); // Re-resolved, not the element captured at build time — see `resolveEl`. const live = resolveEl(); fader.gain.value = clampGroupVolume(readAudioGroupVolume(live)); muteGain.gain.value = live?.hasAttribute("data-hidden") ? 0 : 1; fx?.reanchor(at); // The handle books the fader from the element the bus was built with. if (live && live !== groupEl) scheduleVolume(faderLane, readElementAutomation(live), at); }, dispose: () => { try { fx?.dispose(); input.disconnect(); fader.disconnect(); muteGain.disconnect(); output.disconnect(); } catch { // Already torn down. } }, }); this.attachGroupTap(groupId, output); return input; } startMetering(): void { this._metering = true; this.attachMasterTap(); for (const [id, group] of this._groups) this.attachGroupTap(id, group.output); } stopMetering(): void { this._metering = false; this._masterTap?.dispose(); this._masterTap = null; for (const tap of this._groupTaps.values()) tap.dispose(); this._groupTaps.clear(); } readLevels(): { master: StereoLevel; groups: Record } { const groups: Record = {}; for (const [id, tap] of this._groupTaps) { if (this._groups.get(id)?.isPresent()) groups[id] = tap.read(); } return { master: this._masterTap?.read() ?? { l: 0, r: 0 }, groups }; } private attachMasterTap(): void { if (this._ctx && this._masterGain && !this._masterTap) { this._masterTap = createLevelTap(this._ctx, this._busOut ?? this._masterGain); } } private attachGroupTap(id: string, output: GainNode): void { if (this._metering && this._ctx && !this._groupTaps.has(id)) { this._groupTaps.set(id, createLevelTap(this._ctx, output)); } } /** * Group mute, preview side — a separate gain from `input`'s volume fader * so a mute toggle never fights `scheduleVolume`'s ramps on the * same param (the same hazard the design doc flags for §2.1). A no-op * until the group has an active member: at that point `groupInput` reads * the element's own `data-hidden` for its initial value, so there is * nothing to catch up on here. */ setGroupMuted(groupId: string, muted: boolean): void { const group = this._groups.get(groupId); if (!group) return; try { group.muteGain.gain.value = muted ? 0 : 1; } catch (err) { swallow("webAudioTransport.setGroupMuted", err); } } /** * The master bus chain, between the sum of every clip and group and the monitor. * A seek re-anchors it once per play generation; no root yet is retried next schedule. */ private ensureMasterBus(doc: Document, timing: AutomationTiming): void { if (!this._ctx || !this._masterGain || !this._busOut) return; if (this._master) { if (this._master.generation === this._playGeneration) return; try { this._master.fx?.reanchor(timing); this._master.generation = this._playGeneration; } catch (err) { swallow("webAudioTransport.masterReanchor", err); } return; } const root = resolveMasterBusElement(doc); if (!root) return; this._masterGain.disconnect(this._busOut); const fx = attachElementFxChain( this._ctx, root, this._masterGain, this._busOut, timing, MASTER_FX_ATTRS, ); this._master = { fx, generation: this._playGeneration }; } /** Master, unless `el` belongs to a group — then that group's bus (built on * first use, per `groupInput`). */ private resolveDestination( el: HTMLMediaElement, scheduledAt: number, compositionTime: number, safeRate: number, ): GainNode | null { if (!this._masterGain) return null; const groupTiming: AutomationTiming = { scheduledAt, elapsed: compositionTime, rate: safeRate }; this.ensureMasterBus(el.ownerDocument, groupTiming); const groupId = audioGroupOf(el); if (!groupId) return this._masterGain; return this.groupInput(groupId, el.ownerDocument, groupTiming) ?? this._masterGain; } /** * The graph goes with it. Splicing alone left the FX handle alive and then * UNREACHABLE — `stopAll()` disposes by walking `_activeSources`, which the * splice just emptied of this entry. Every clip that finished naturally * leaked its MutationObserver for the session, and each one still answered * later `data-fx-chain` edits by rebuilding a whole graph (impulse response, * chorus/phaser oscillators started and never stopped) around a dead * source. Not disposed when the index is already -1: `stopAll()` has * already done it, and `stop()` is what fired this event. */ private handleSourceEnded( sourceNode: AudioBufferSourceNode, scheduled: ScheduledSource, el: HTMLMediaElement, priorMuted: boolean, ): void { const idx = this._activeSources.indexOf(scheduled); if (idx === -1) return; this._activeSources.splice(idx, 1); el.muted = priorMuted; try { sourceNode.disconnect(); scheduled.fx?.dispose(); scheduled.fades?.node.disconnect(); scheduled.clipGainNode.disconnect(); scheduled.laneNode.disconnect(); scheduled.gainNode.disconnect(); } catch { // Already torn down. } if (this._activeSources.length === 0) this._paused = true; } // Pre-existing size (110 lines before this diff, which shrank it to under // 95 via two extractions — see `handleSourceEnded`/`resolveDestination`); // the remainder is inherently sequential graph-wiring, not a nested // decision tree, and further splitting would cost more readability than it // buys. Same call the B2 step took on `TimelineLogicalRow`. // fallow-ignore-next-line complexity async schedulePlayback( el: HTMLMediaElement, buffer: AudioBuffer, compositionStart: number, mediaStart: number, readCompositionTime: () => number, volume: number, generation: number, rate = 1, clipDuration = Number.POSITIVE_INFINITY, windowStart = compositionStart, ): Promise { if (!this._ctx || !this._masterGain) return null; if (generation !== this._playGeneration) return null; try { await this.wake(); if (generation !== this._playGeneration) return null; // Read after the wake: the clock kept running while the context resumed. const compositionTime = readCompositionTime(); const safeRate = normalizeRate(rate); const mediaRate = readElementPlaybackRate(el); const sourceRate = safeRate * mediaRate; const sourceNode = this._ctx.createBufferSource(); sourceNode.buffer = buffer; sourceNode.playbackRate.value = sourceRate; const gainNode = this._ctx.createGain(); gainNode.gain.value = volume; const elapsed = compositionTime - compositionStart; const scheduledAt = this._ctx.currentTime; const timing: AutomationTiming = { scheduledAt, elapsed, rate: safeRate }; // Splice the element's FX chain between the decoded source and its gain, // so effects see the raw signal and volume automation rides on their // output — the same order the offline render uses. Preview and render run // the identical graph builders, so what is heard here is what is written. gainNode.connect( this.resolveDestination(el, scheduledAt, compositionTime, safeRate) ?? this._masterGain, ); const headCut = windowStart - compositionStart; const { fx, laneNode, clipGainNode, fades } = attachClipStages( this._ctx, el, sourceNode, gainNode, timing, { from: Math.max(elapsed, headCut, 0), clipDuration }, ); this._rate = safeRate; this._rateAnchorCtx = scheduledAt; this._rateAnchorComp = compositionTime; if ( !startBoundedSource(sourceNode, { elapsed, mediaStart, scheduledAt, globalRate: safeRate, mediaRate, clipDuration, headCut, }) ) { // Playhead already past the clip end — discard the nodes we built. sourceNode.disconnect(); fx?.dispose(); fades?.node.disconnect(); clipGainNode.disconnect(); laneNode.disconnect(); gainNode.disconnect(); return null; } const priorMuted = el.muted; el.muted = true; logFallbackHandoff(el, priorMuted); const scheduled: ScheduledSource = { fx, fades, el, sourceNode, sourceKind: "buffer", gainNode, laneNode, clipGainNode, compositionStart, mediaStart, scheduledAt, priorMuted, priorVolume: el.volume, mediaPlaybackRate: mediaRate, bounded: Number.isFinite(clipDuration) && clipDuration > 0, }; this._activeSources.push(scheduled); this._paused = false; sourceNode.addEventListener("ended", () => this.handleSourceEnded(sourceNode, scheduled, el, priorMuted), ); return scheduled; } catch (err) { swallow("webAudioTransport.schedule", err); return null; } } /** Drops the routed element's source once a decoded buffer plays in its place; it stays silent until a stop. */ releaseRouted(el: HTMLMediaElement): void { const routed = this._activeSources.find((s) => s.el === el && s.sourceKind === "media-element"); if (!routed) return; this._activeSources.splice(this._activeSources.indexOf(routed), 1); this.dispose(routed, false); this._handedOver.add(el); } /** A decoded buffer plays what an element carried: it cannot hold pitch through a speed change. */ hasHandedOverSources(): boolean { return this._activeSources.some((s) => isBufferSource(s) && this._handedOver.has(s.el)); } /** * Rebases the composition-time reference frame before swapping rate so * `getTime()` stays continuous across the change. Sources scheduled to * start in the future keep their original wallclock start time — callers * that need rate-correct future starts should `stopAll()` and reschedule. * * Each decoded source's FX automation is re-aimed too. Lanes are committed to * absolute context times when the source is scheduled, so bumping only * `playbackRate` left every automated parameter running its original plan * over audio moving at a different speed. The `stopAll()`+reschedule recovery * in the runtime is no help here: it only fires for bounded sources, and a * project-level music bed with no `data-duration` is unbounded, so it never * recovered at all. */ setRate(rate: number): boolean { const safeRate = normalizeRate(rate); if (safeRate === this._rate) return false; if (this._ctx && !this._paused) { this._rateAnchorComp = this.getTime(); this._rateAnchorCtx = this._ctx.currentTime; } this._rate = safeRate; // A routed element is not touched: its rate change re-aims its own lane and fades (`followElement`). for (const source of this._activeSources) { if (!isBufferSource(source)) continue; try { source.sourceNode.playbackRate.value = safeRate * source.mediaPlaybackRate; source.fx?.setRate(safeRate); if (this._ctx && !this._paused) source.fades?.rebook({ scheduledAt: this._ctx.currentTime, elapsed: this.getTime() - source.compositionStart, rate: safeRate, }); } catch (err) { swallow("webAudioTransport.setRate", err); } } this.setBusRate(safeRate); return true; } // Group buses and the master bus are not in `_activeSources` — they outlive it — so // their FX automation needs re-aiming too, or a rate change leaves their envelopes // running the old plan over audio at the new speed. private setBusRate(rate: number): void { const buses = [...this._groups.values(), ...(this._master ? [this._master] : [])]; for (const bus of buses) { try { bus.fx?.setRate(rate); } catch (err) { swallow("webAudioTransport.setRate.bus", err); } } } // A bounded source's wall-clock duration was baked into start()'s duration // arg at its original rate; a later rate change can't rescale it in place, so // the caller must stopAll()+reschedule to keep trimmed clips ending on time. hasBoundedActiveSources(): boolean { return this._activeSources.some((s) => isBufferSource(s) && s.bounded); } stopAll(): void { for (const source of this._activeSources) this.dispose(source); this._activeSources = []; this.reconnectHandedOver(); this._paused = true; this._playGeneration += 1; this.rest(); } private reconnectHandedOver(): void { for (const el of this._handedOver) { try { if (this._ctx) this._mediaElementSources.get(el)?.connect(this._ctx.destination); } catch (err) { swallow("webAudioTransport.reconnectHandedOver", err); } } this._handedOver.clear(); } /** Stops what plays from media gone from the page, without sending it to the destination as a stop does. */ releaseDetached(): void { this._activeSources = this._activeSources.filter((source) => { if (source.el.isConnected) return true; this.dispose(source, false); return false; }); } private dispose(source: ScheduledSource, keepsSounding = true): void { source.unfollow?.(); try { if (isBufferSource(source)) source.sourceNode.stop(); source.sourceNode.disconnect(); source.fx?.dispose(); source.fades?.node.disconnect(); source.dipNode?.disconnect(); source.clipGainNode.disconnect(); source.laneNode.disconnect(); source.gainNode.disconnect(); } catch { // already stopped } if (isBufferSource(source)) source.el.muted = source.priorMuted; else { source.el.volume = source.priorVolume; // Captured, it has no native output; outside a play it sounds through the destination. if (this._ctx && keepsSounding) source.sourceNode.connect(this._ctx.destination); } } setVolume(volume: number): void { this._masterVolume = Math.max(0, Math.min(1, volume)); this.applyMasterGain(); } /** * The per-element gain carries the clip's AUTHOR gain, which reaches * MAX_AUDIO_GAIN — so it is clamped against that ceiling, not the spec's * [0,1]. `setVolume` above is the opposite case and stays spec-clamped: the * user's master volume is a fader, not a gain. * * Clamping this one at unity capped every static above-unity `data-volume` on * the preview path while the render honoured it — the exact preview/render * divergence this ceiling exists to close. Automation lanes hid it, because * they schedule ramps onto the param directly and never pass through here. */ setElementVolume( el: HTMLMediaElement, volume: number, clipGain = 1, unfadedVolume = volume, ): void { for (const source of this._activeSources) { if (source.el !== el) continue; try { if (source.sourceKind === "media-element") source.el.volume = 1; source.gainNode.gain.value = clampAudioGain(source.fades ? unfadedVolume : volume); source.clipGainNode.gain.value = clampAudioGain(clipGain); } catch (err) { swallow("webAudioTransport.setElementVolume", err); } } } setMuted(muted: boolean): void { this._masterMuted = muted; this.applyMasterGain(); } private applyMasterGain(): void { if (this._monitorGain) this._monitorGain.gain.value = this._masterMuted ? 0 : this._masterVolume; } ownsClock(): boolean { return !this._paused && this._activeSources.some(isBufferSource); } /** Whether the transport currently plays THIS element (the runtime mutes it to * avoid double audio; an unclaimed track stays audible). */ ownsElement(el: HTMLMediaElement): boolean { return !this._paused && this._activeSources.some((s) => s.el === el && isBufferSource(s)); } /** Whether this element's native signal currently flows through the WebAudio graph. */ routesElement(el: HTMLMediaElement): boolean { return !this._paused && this._activeSources.some((source) => source.el === el); } destroy(): void { this.stopAll(); this.stopMetering(); for (const group of this._groups.values()) group.dispose(); this._groups.clear(); this._master?.fx?.dispose(); this._master = null; this._bufferCache.clear(); this._failedSrcs.clear(); this._mediaElementSources = new WeakMap(); this._playingCaptured.clear(); this._suspendPending = false; if (this._restTimer !== null) clearTimeout(this._restTimer); this._restTimer = null; if (this._ctx) { try { void this._ctx.close(); } catch { // ignore } } this._ctx = null; this._masterGain = null; this._busOut = null; this._monitorGain = null; this._masterVolume = 1; this._masterMuted = false; } }