mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
* fix(core): a decoded buffer's handover leaves the routed element silent * fix(core): a handed-over element sounds again when playback stops
1271 lines
49 KiB
TypeScript
1271 lines
49 KiB
TypeScript
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;
|
||
}
|
||
}
|