Files
hyperframes/packages/core/src/runtime/webAudioTransport.ts
T
Miguel Ángel cb8e02e826 fix(core): a decoded buffer's handover leaves the routed element silent (#7309)
* fix(core): a decoded buffer's handover leaves the routed element silent

* fix(core): a handed-over element sounds again when playback stops
2026-11-06 10:17:47 +00:00

1271 lines
49 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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 `<hf-audio-group data-volume="2">` 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<string, AudioBuffer>();
private _decoding = new Map<string, Promise<AudioBuffer | null>>();
private _pendingDecodeBytes = new Map<string, number>();
private _failedSrcs = new Set<string>();
private _mediaElementSources = new WeakMap<HTMLMediaElement, MediaElementAudioSourceNode>();
private _handedOver = new Set<HTMLMediaElement>();
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<string, LevelTap>();
// 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<HTMLMediaElement>();
private _suspendPending = false;
private _restTimer: ReturnType<typeof setTimeout> | null = null;
async init(): Promise<boolean> {
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<void> {
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<AudioBuffer | null> {
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<AudioBuffer | null> {
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<ScheduledSource | null> {
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 `<hf-audio-group>` 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<string, StereoLevel> } {
const groups: Record<string, StereoLevel> = {};
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<ScheduledSource | null> {
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;
}
}