Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
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 { createLevelTap, type LevelTap, type StereoLevel } from "./levelTap.js";
import { clampAudioGain } from "../audioGain.js";
import { getDebugSurface } from "./globals.js";
import { readElementPlaybackRate } from "./media.js";
import { classifyWebAudioMediaRoute, reportWebAudioMediaRoute } from "./webAudioRoute.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;
}
// 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,
): { fx: ElementFxHandle | null; laneNode: GainNode; clipGainNode: GainNode } {
const laneNode = ctx.createGain();
laneNode.connect(gainNode);
const clipGainNode = ctx.createGain();
source.connect(clipGainNode);
const fx = attachElementFxChain(ctx, el, clipGainNode, laneNode, timing, undefined, {
param: laneNode.gain,
gain: () => readAudioGroupVolume(el),
gainAhead: true,
});
return { fx, laneNode, clipGainNode };
}
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;
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";
}
// A pause to scrub or a reschedule mid-play keeps the output awake; a real idle lets it sleep.
const IDLE_SUSPEND_MS = 10000;
export class WebAudioTransport {
private _ctx: AudioContext | null = null;
private _bufferCache = new Map<string, AudioBuffer>();
private _failedSrcs = new Set<string>();
private _mediaElementSources = new WeakMap<HTMLMediaElement, MediaElementAudioSourceNode>();
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;
}
async decodeAudioElement(el: HTMLMediaElement): Promise<AudioBuffer | null> {
const src = el.currentSrc || el.getAttribute("src");
if (!src) return 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}`));
return null;
}
arrayBuffer = await response.arrayBuffer();
} catch (err) {
swallow("webAudioTransport.fetch", err);
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);
this._bufferCache.set(src, audioBuffer);
return audioBuffer;
} catch (err) {
this._failedSrcs.add(src);
swallow("webAudioTransport.decode", err);
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,
): 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 { fx, laneNode, clipGainNode } = attachClipStages(
this._ctx,
el,
sourceNode,
gainNode,
timing,
);
this._rate = safeRate;
this._rateAnchorCtx = scheduledAt;
this._rateAnchorComp = compositionTime;
const scheduled: ScheduledSource = {
fx,
el,
sourceNode,
sourceKind: "media-element",
gainNode,
laneNode,
clipGainNode,
compositionStart,
mediaStart: _mediaStart,
scheduledAt,
priorMuted: el.muted,
priorVolume: el.volume,
mediaPlaybackRate: readElementPlaybackRate(el),
bounded: false,
};
// 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;
}
}
/**
* 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.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 { fx, laneNode, clipGainNode } = attachClipStages(
this._ctx,
el,
sourceNode,
gainNode,
timing,
);
this._rate = safeRate;
this._rateAnchorCtx = scheduledAt;
this._rateAnchorComp = compositionTime;
if (
!startBoundedSource(sourceNode, {
elapsed,
mediaStart,
scheduledAt,
globalRate: safeRate,
mediaRate,
clipDuration,
headCut: windowStart - compositionStart,
})
) {
// Playhead already past the clip end — discard the nodes we built.
sourceNode.disconnect();
fx?.dispose();
clipGainNode.disconnect();
laneNode.disconnect();
gainNode.disconnect();
return null;
}
const priorMuted = el.muted;
el.muted = true;
logFallbackHandoff(el, priorMuted);
const scheduled: ScheduledSource = {
fx,
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;
}
}
/**
* 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 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;
for (const source of this._activeSources) {
try {
if (isBufferSource(source)) {
source.sourceNode.playbackRate.value = safeRate * source.mediaPlaybackRate;
}
source.fx?.setRate(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) {
try {
if (isBufferSource(source)) source.sourceNode.stop();
source.sourceNode.disconnect();
source.fx?.dispose();
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) source.sourceNode.connect(this._ctx.destination);
}
}
this._activeSources = [];
this._paused = true;
this._playGeneration += 1;
this.rest();
}
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): void {
const safeVolume = clampAudioGain(volume);
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 = safeVolume;
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;
}
}