mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-15 22:08:03 +00:00
feat(core): play automation envelopes in preview
Schedules each lane onto the AudioParams behind its knob using native ramps and value curves. Nothing evaluates the envelope per frame: it is handed to the audio thread once, so it stays sample-accurate however busy the main thread is, and the offline render will schedule it the same way. Timing comes from the transport, so an envelope survives seeking into the middle of a clip, a clip that has not started yet, and a playback rate that compresses clip seconds into context seconds. A straight line is only scheduled as a ramp when nothing bends it — no curvature, a linear parameter scale, and no unit mapping. Log-scaled parameters and mapped ones are sampled instead, since a delay knob in milliseconds and a wet/dry pair moving in opposition are not linear in the parameter they drive. Lanes with nowhere to write are skipped rather than reported: a one-pole filter exposes no frequency param, and the worklet effects expose none at all. Editing an envelope mid-playback re-aims it at the live playhead rather than restarting the track. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5
parent
d80cfdeb99
commit
e2153f3d04
@@ -0,0 +1,353 @@
|
||||
// @vitest-environment happy-dom
|
||||
import { describe, expect, it } from "vitest";
|
||||
import {
|
||||
cancelParamLane,
|
||||
scheduleChainAutomation,
|
||||
scheduleParamLane,
|
||||
volumeLane,
|
||||
type AutomationTiming,
|
||||
} from "./audioFxAutomation.js";
|
||||
import type { FxParamTarget } from "./audioFxGraph.js";
|
||||
import type { HfAutomationLane } from "../audioAutomation.js";
|
||||
import type { HfAudioFxChain } from "../audioFx.js";
|
||||
|
||||
/**
|
||||
* happy-dom has no Web Audio. These record what the scheduler asks an
|
||||
* AudioParam to do — the shape of the envelope handed to the audio thread —
|
||||
* which is the part that has to be right; whether Chrome then plays a ramp
|
||||
* accurately is not ours to test.
|
||||
*/
|
||||
type Call =
|
||||
| { op: "set"; value: number; time: number }
|
||||
| { op: "ramp"; value: number; time: number }
|
||||
| { op: "curve"; values: number[]; time: number; duration: number }
|
||||
| { op: "cancel"; time: number }
|
||||
| { op: "hold"; time: number };
|
||||
|
||||
class FakeParam {
|
||||
calls: Call[] = [];
|
||||
value = 0;
|
||||
setValueAtTime(value: number, time: number): void {
|
||||
this.calls.push({ op: "set", value, time });
|
||||
}
|
||||
linearRampToValueAtTime(value: number, time: number): void {
|
||||
this.calls.push({ op: "ramp", value, time });
|
||||
}
|
||||
setValueCurveAtTime(values: Float32Array, time: number, duration: number): void {
|
||||
this.calls.push({ op: "curve", values: Array.from(values), time, duration });
|
||||
}
|
||||
cancelScheduledValues(time: number): void {
|
||||
this.calls.push({ op: "cancel", time });
|
||||
}
|
||||
cancelAndHoldAtTime(time: number): void {
|
||||
this.calls.push({ op: "hold", time });
|
||||
}
|
||||
}
|
||||
|
||||
const fake = (): { target: FxParamTarget; param: FakeParam } => {
|
||||
const param = new FakeParam();
|
||||
return { target: { param: param as unknown as AudioParam }, param };
|
||||
};
|
||||
|
||||
const at = (elapsed = 0, rate = 1, scheduledAt = 10): AutomationTiming => ({
|
||||
scheduledAt,
|
||||
elapsed,
|
||||
rate,
|
||||
});
|
||||
|
||||
const ramp: HfAutomationLane = {
|
||||
target: "volume",
|
||||
points: [
|
||||
{ t: 1, v: 0.2 },
|
||||
{ t: 3, v: 0.8 },
|
||||
],
|
||||
};
|
||||
|
||||
describe("scheduleParamLane", () => {
|
||||
it("seeds the current value, then ramps to each later point", () => {
|
||||
const { target, param } = fake();
|
||||
scheduleParamLane([target], ramp, "linear", at(0));
|
||||
expect(param.calls).toEqual([
|
||||
{ op: "cancel", time: 10 },
|
||||
// Before the first point the envelope holds that point's value.
|
||||
{ op: "set", value: 0.2, time: 10 },
|
||||
{ op: "ramp", value: 0.8, time: 13 },
|
||||
]);
|
||||
});
|
||||
|
||||
it("enters a segment mid-way when the playhead landed inside it", () => {
|
||||
const { target, param } = fake();
|
||||
scheduleParamLane([target], ramp, "linear", at(2));
|
||||
// Half way along a 0.2 → 0.8 ramp.
|
||||
expect(param.calls[1]).toEqual({ op: "set", value: 0.5, time: 10 });
|
||||
expect(param.calls[2]).toEqual({ op: "ramp", value: 0.8, time: 11 });
|
||||
});
|
||||
|
||||
it("holds the last value once the envelope is behind the playhead", () => {
|
||||
const { target, param } = fake();
|
||||
scheduleParamLane([target], ramp, "linear", at(9));
|
||||
expect(param.calls).toEqual([
|
||||
{ op: "cancel", time: 10 },
|
||||
{ op: "set", value: 0.8, time: 10 },
|
||||
]);
|
||||
});
|
||||
|
||||
it("waits for a clip that has not started yet", () => {
|
||||
const { target, param } = fake();
|
||||
scheduleParamLane([target], ramp, "linear", at(-2));
|
||||
// Clip time 1 is three seconds of context time away.
|
||||
expect(param.calls[1]).toEqual({ op: "set", value: 0.2, time: 10 });
|
||||
expect(param.calls[2]).toEqual({ op: "ramp", value: 0.8, time: 15 });
|
||||
});
|
||||
|
||||
it("compresses the envelope by the playback rate", () => {
|
||||
const { target, param } = fake();
|
||||
scheduleParamLane([target], ramp, "linear", at(0, 2));
|
||||
// Clip time 3 arrives after 1.5 s of context time at double speed.
|
||||
expect(param.calls[2]).toEqual({ op: "ramp", value: 0.8, time: 11.5 });
|
||||
});
|
||||
|
||||
it("sets a constant lane once instead of scheduling it", () => {
|
||||
const { target, param } = fake();
|
||||
scheduleParamLane(
|
||||
[target],
|
||||
{
|
||||
target: "volume",
|
||||
points: [
|
||||
{ t: 0, v: 0.4 },
|
||||
{ t: 5, v: 0.4 },
|
||||
],
|
||||
},
|
||||
"linear",
|
||||
at(0),
|
||||
);
|
||||
expect(param.calls).toEqual([
|
||||
{ op: "cancel", time: 10 },
|
||||
{ op: "set", value: 0.4, time: 10 },
|
||||
]);
|
||||
});
|
||||
|
||||
it("samples a curved segment rather than ramping through the bend", () => {
|
||||
const { target, param } = fake();
|
||||
scheduleParamLane(
|
||||
[target],
|
||||
{
|
||||
target: "volume",
|
||||
points: [
|
||||
{ t: 0, v: 0, curve: 1 },
|
||||
{ t: 2, v: 1 },
|
||||
],
|
||||
},
|
||||
"linear",
|
||||
at(0),
|
||||
);
|
||||
const curve = param.calls.find((c) => c.op === "curve");
|
||||
expect(curve).toBeTruthy();
|
||||
if (curve?.op !== "curve") throw new Error("expected a curve");
|
||||
expect(curve.time).toBe(10);
|
||||
expect(curve.duration).toBe(2);
|
||||
expect(curve.values[0]).toBeCloseTo(0, 6);
|
||||
expect(curve.values[curve.values.length - 1]).toBeCloseTo(1, 6);
|
||||
// Curved, so the midpoint is not halfway.
|
||||
expect(curve.values[Math.floor(curve.values.length / 2)]).toBeLessThan(0.4);
|
||||
});
|
||||
|
||||
it("samples a log-scaled sweep, which a linear ramp would get wrong", () => {
|
||||
const { target, param } = fake();
|
||||
scheduleParamLane(
|
||||
[target],
|
||||
{
|
||||
target: "fx.n1.frequency",
|
||||
points: [
|
||||
{ t: 0, v: 200 },
|
||||
{ t: 2, v: 8000 },
|
||||
],
|
||||
},
|
||||
"log",
|
||||
at(0),
|
||||
);
|
||||
const curve = param.calls.find((c) => c.op === "curve");
|
||||
if (curve?.op !== "curve") throw new Error("expected a curve");
|
||||
// Halfway is the geometric mean, not the arithmetic one. The array has an
|
||||
// even length so no sample sits exactly on it; both neighbours bracket it.
|
||||
const half = curve.values.length / 2;
|
||||
const geometric = Math.sqrt(200 * 8000);
|
||||
expect(curve.values[half - 1] ?? 0).toBeLessThan(geometric);
|
||||
expect(curve.values[half] ?? 0).toBeGreaterThan(geometric);
|
||||
expect((curve.values[half] ?? 0) / geometric).toBeCloseTo(1, 1);
|
||||
// A linear ramp would have been at 4100 by now — nowhere near.
|
||||
expect(curve.values[half] ?? 0).toBeLessThan(2000);
|
||||
});
|
||||
|
||||
it("does not seed on top of a curve that starts at the same instant", () => {
|
||||
const { target, param } = fake();
|
||||
scheduleParamLane(
|
||||
[target],
|
||||
{
|
||||
target: "volume",
|
||||
points: [
|
||||
{ t: 0, v: 0, curve: 1 },
|
||||
{ t: 2, v: 1 },
|
||||
],
|
||||
},
|
||||
"linear",
|
||||
at(0),
|
||||
);
|
||||
// A value curve may not overlap another event, so there is no set at 10.
|
||||
expect(param.calls.filter((c) => c.op === "set")).toEqual([]);
|
||||
expect(param.calls[1]?.op).toBe("curve");
|
||||
});
|
||||
|
||||
it("writes every AudioParam behind one knob, each through its own mapping", () => {
|
||||
const wet = new FakeParam();
|
||||
const dry = new FakeParam();
|
||||
scheduleParamLane(
|
||||
[
|
||||
{ param: wet as unknown as AudioParam },
|
||||
{ param: dry as unknown as AudioParam, map: (v) => 1 - v },
|
||||
],
|
||||
{
|
||||
target: "fx.n1.mix",
|
||||
points: [
|
||||
{ t: 0, v: 0.25 },
|
||||
{ t: 4, v: 0.75 },
|
||||
],
|
||||
},
|
||||
"linear",
|
||||
at(0),
|
||||
);
|
||||
expect(wet.calls[1]).toEqual({ op: "set", value: 0.25, time: 10 });
|
||||
// The dry side moves the opposite way. A mapping may be non-linear, so the
|
||||
// segment is sampled rather than ramped.
|
||||
const dryCurve = dry.calls.find((c) => c.op === "curve");
|
||||
if (dryCurve?.op !== "curve") throw new Error("expected a curve");
|
||||
expect(dryCurve.values[0]).toBeCloseTo(0.75, 6);
|
||||
expect(dryCurve.values[dryCurve.values.length - 1]).toBeCloseTo(0.25, 6);
|
||||
});
|
||||
|
||||
it("ignores an empty lane", () => {
|
||||
const { target, param } = fake();
|
||||
scheduleParamLane([target], { target: "volume", points: [] }, "linear", at(0));
|
||||
expect(param.calls).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
describe("cancelParamLane", () => {
|
||||
it("holds the value the envelope had reached rather than snapping back", () => {
|
||||
const { target, param } = fake();
|
||||
cancelParamLane([target], 12);
|
||||
expect(param.calls).toEqual([{ op: "hold", time: 12 }]);
|
||||
});
|
||||
});
|
||||
|
||||
describe("scheduleChainAutomation", () => {
|
||||
const chain: HfAudioFxChain = {
|
||||
version: 1,
|
||||
nodes: [{ type: "peaking", id: "n1", enabled: true, params: {} }],
|
||||
};
|
||||
|
||||
const nodeWith = (automation: Record<string, FxParamTarget[]> | undefined) => [
|
||||
{
|
||||
id: "n1",
|
||||
handle: {
|
||||
input: {} as AudioNode,
|
||||
output: {} as AudioNode,
|
||||
update: () => {},
|
||||
dispose: () => {},
|
||||
automation,
|
||||
},
|
||||
},
|
||||
];
|
||||
|
||||
it("routes a lane to the AudioParam its node exposes", () => {
|
||||
const param = new FakeParam();
|
||||
const nodes = nodeWith({ frequency: [{ param: param as unknown as AudioParam }] });
|
||||
const scheduled = scheduleChainAutomation(
|
||||
{
|
||||
version: 1,
|
||||
lanes: [
|
||||
{
|
||||
target: "fx.n1.frequency",
|
||||
points: [
|
||||
{ t: 0, v: 200 },
|
||||
{ t: 2, v: 8000 },
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
chain,
|
||||
nodes,
|
||||
at(0),
|
||||
);
|
||||
expect(scheduled.length).toBe(1);
|
||||
expect(param.calls.length).toBeGreaterThan(1);
|
||||
});
|
||||
|
||||
it("skips a lane whose node exposes nothing, instead of failing", () => {
|
||||
const scheduled = scheduleChainAutomation(
|
||||
{
|
||||
version: 1,
|
||||
lanes: [
|
||||
{
|
||||
target: "fx.n1.frequency",
|
||||
points: [
|
||||
{ t: 0, v: 200 },
|
||||
{ t: 2, v: 900 },
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
chain,
|
||||
nodeWith(undefined),
|
||||
at(0),
|
||||
);
|
||||
expect(scheduled).toEqual([]);
|
||||
});
|
||||
|
||||
it("skips a lane addressed to a node that is not in the chain", () => {
|
||||
const param = new FakeParam();
|
||||
const scheduled = scheduleChainAutomation(
|
||||
{
|
||||
version: 1,
|
||||
lanes: [
|
||||
{
|
||||
target: "fx.gone.frequency",
|
||||
points: [
|
||||
{ t: 0, v: 200 },
|
||||
{ t: 2, v: 900 },
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
chain,
|
||||
nodeWith({ frequency: [{ param: param as unknown as AudioParam }] }),
|
||||
at(0),
|
||||
);
|
||||
expect(scheduled).toEqual([]);
|
||||
expect(param.calls).toEqual([]);
|
||||
});
|
||||
|
||||
it("leaves the volume lane alone — the transport owns the fader", () => {
|
||||
const param = new FakeParam();
|
||||
const automation = {
|
||||
version: 1,
|
||||
lanes: [
|
||||
{
|
||||
target: "volume",
|
||||
points: [
|
||||
{ t: 0, v: 1 },
|
||||
{ t: 2, v: 0 },
|
||||
],
|
||||
},
|
||||
],
|
||||
};
|
||||
const scheduled = scheduleChainAutomation(
|
||||
automation,
|
||||
chain,
|
||||
nodeWith({ frequency: [{ param: param as unknown as AudioParam }] }),
|
||||
at(0),
|
||||
);
|
||||
expect(scheduled).toEqual([]);
|
||||
expect(volumeLane(automation)?.points.length).toBe(2);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,213 @@
|
||||
/**
|
||||
* Plays automation envelopes through native AudioParam scheduling.
|
||||
*
|
||||
* Nothing here runs per frame. The envelope is handed to the audio thread once,
|
||||
* as ramps and curves, so it stays sample-accurate no matter what the main
|
||||
* thread is doing — and the offline render schedules it the same way, which is
|
||||
* why preview and render agree by construction rather than by tolerance.
|
||||
*/
|
||||
|
||||
import {
|
||||
isConstantLane,
|
||||
resolveAutomationRange,
|
||||
sampleAutomationCurve,
|
||||
sampleAutomationLane,
|
||||
type HfAutomation,
|
||||
type HfAutomationLane,
|
||||
} from "../audioAutomation.js";
|
||||
import { parseAutomationTarget, VOLUME_TARGET } from "../audioAutomation.js";
|
||||
import type { HfAudioFxChain } from "../audioFx.js";
|
||||
import type { FxNodeHandle, FxParamTarget } from "./audioFxGraph.js";
|
||||
|
||||
/** Where the clip sits in context time when its source is scheduled. */
|
||||
export interface AutomationTiming {
|
||||
/** Context time the source was scheduled at. */
|
||||
scheduledAt: number;
|
||||
/** Clip-local seconds already elapsed at that moment; negative before it starts. */
|
||||
elapsed: number;
|
||||
/** Playback rate, which compresses clip seconds into context seconds. */
|
||||
rate: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Sampling density for segments that cannot be expressed as a ramp. Dense
|
||||
* enough that a curve is inaudible from a continuous one, capped so a long
|
||||
* segment cannot allocate without bound.
|
||||
*/
|
||||
const CURVE_POINTS_PER_SEC = 100;
|
||||
const MIN_CURVE_POINTS = 8;
|
||||
const MAX_CURVE_POINTS = 4096;
|
||||
|
||||
const identity = (v: number): number => v;
|
||||
|
||||
type Op =
|
||||
| { kind: "set"; time: number; value: number }
|
||||
| { kind: "ramp"; time: number; value: number }
|
||||
| { kind: "curve"; time: number; duration: number; values: Float32Array };
|
||||
|
||||
/**
|
||||
* A segment is a straight line only when nothing bends it: no curvature on the
|
||||
* point it leaves, a linear parameter scale, and no unit mapping that could be
|
||||
* non-linear. Everything else is sampled.
|
||||
*/
|
||||
function isStraight(
|
||||
curve: number | undefined,
|
||||
scale: "linear" | "log",
|
||||
map: FxParamTarget["map"],
|
||||
): boolean {
|
||||
return !curve && scale === "linear" && !map;
|
||||
}
|
||||
|
||||
function curvePointCount(duration: number): number {
|
||||
const wanted = Math.ceil(duration * CURVE_POINTS_PER_SEC);
|
||||
return Math.min(MAX_CURVE_POINTS, Math.max(MIN_CURVE_POINTS, wanted));
|
||||
}
|
||||
|
||||
/**
|
||||
* One segment of the envelope, as the event that plays it. Returns null when
|
||||
* the segment is already behind the playhead.
|
||||
*/
|
||||
function segmentOp(
|
||||
lane: HfAutomationLane,
|
||||
index: number,
|
||||
scale: "linear" | "log",
|
||||
timing: AutomationTiming,
|
||||
map: FxParamTarget["map"],
|
||||
): Op | null {
|
||||
const { scheduledAt, elapsed, rate } = timing;
|
||||
const apply = map ?? identity;
|
||||
const toCtx = (t: number): number => scheduledAt + (t - elapsed) / rate;
|
||||
const a = lane.points[index]!;
|
||||
const b = lane.points[index + 1]!;
|
||||
|
||||
const toTime = toCtx(b.t);
|
||||
if (toTime <= scheduledAt) return null;
|
||||
const fromTime = Math.max(scheduledAt, toCtx(a.t));
|
||||
const duration = toTime - fromTime;
|
||||
if (duration <= 0) return null;
|
||||
|
||||
if (isStraight(a.curve, scale, map)) {
|
||||
return { kind: "ramp", time: toTime, value: apply(b.v) };
|
||||
}
|
||||
// Sample from wherever the segment is entered, which is mid-segment when the
|
||||
// playhead landed inside it.
|
||||
const count = curvePointCount(duration);
|
||||
const raw = sampleAutomationCurve(lane, Math.max(a.t, elapsed), b.t, count, scale);
|
||||
const values = new Float32Array(count);
|
||||
for (let k = 0; k < count; k += 1) values[k] = apply(raw[k] ?? 0);
|
||||
return { kind: "curve", time: fromTime, duration, values };
|
||||
}
|
||||
|
||||
/** Turn a lane into the events one AudioParam should receive. */
|
||||
function planOps(
|
||||
lane: HfAutomationLane,
|
||||
scale: "linear" | "log",
|
||||
timing: AutomationTiming,
|
||||
map: FxParamTarget["map"],
|
||||
): Op[] {
|
||||
const ops: Op[] = [];
|
||||
for (let i = 0; i + 1 < lane.points.length; i += 1) {
|
||||
const op = segmentOp(lane, i, scale, timing, map);
|
||||
if (op) ops.push(op);
|
||||
}
|
||||
|
||||
// Hold the envelope's value at the moment playback starts. This is what makes
|
||||
// a lane correct before its first point and after its last, and it gives a
|
||||
// following ramp something to ramp from.
|
||||
//
|
||||
// A value curve may not overlap another event, so the seed is dropped when a
|
||||
// curve already begins at that instant — the curve sets the value itself.
|
||||
const first = ops[0];
|
||||
if (!(first?.kind === "curve" && first.time <= timing.scheduledAt)) {
|
||||
ops.unshift({
|
||||
kind: "set",
|
||||
time: timing.scheduledAt,
|
||||
value: (map ?? identity)(sampleAutomationLane(lane, timing.elapsed, scale)),
|
||||
});
|
||||
}
|
||||
return ops;
|
||||
}
|
||||
|
||||
function emit(param: AudioParam, ops: readonly Op[]): void {
|
||||
for (const op of ops) {
|
||||
if (op.kind === "set") param.setValueAtTime(op.value, op.time);
|
||||
else if (op.kind === "ramp") param.linearRampToValueAtTime(op.value, op.time);
|
||||
else param.setValueCurveAtTime(op.values, op.time, op.duration);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Schedule one lane onto every AudioParam behind its knob.
|
||||
*
|
||||
* Existing automation from an earlier schedule is cancelled first, so calling
|
||||
* this again after an edit replaces the envelope rather than layering on it.
|
||||
*/
|
||||
export function scheduleParamLane(
|
||||
targets: readonly FxParamTarget[],
|
||||
lane: HfAutomationLane,
|
||||
scale: "linear" | "log",
|
||||
timing: AutomationTiming,
|
||||
): void {
|
||||
if (lane.points.length === 0) return;
|
||||
for (const target of targets) {
|
||||
target.param.cancelScheduledValues(timing.scheduledAt);
|
||||
if (isConstantLane(lane)) {
|
||||
const value = (target.map ?? identity)(lane.points[0]!.v);
|
||||
target.param.setValueAtTime(value, timing.scheduledAt);
|
||||
continue;
|
||||
}
|
||||
emit(target.param, planOps(lane, scale, timing, target.map));
|
||||
}
|
||||
}
|
||||
|
||||
/** Stop an envelope, leaving the parameter wherever it currently sits. */
|
||||
export function cancelParamLane(targets: readonly FxParamTarget[], from: number): void {
|
||||
for (const target of targets) {
|
||||
// Keep the value the ramp had reached rather than snapping back to the
|
||||
// last explicitly-set one, which would click.
|
||||
if (typeof target.param.cancelAndHoldAtTime === "function") {
|
||||
target.param.cancelAndHoldAtTime(from);
|
||||
} else {
|
||||
target.param.cancelScheduledValues(from);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/** One built effect, paired with the chain node id lanes address it by. */
|
||||
export interface AutomatableNode {
|
||||
id?: string;
|
||||
handle: FxNodeHandle;
|
||||
}
|
||||
|
||||
/**
|
||||
* Schedule every FX lane in an automation set against a built chain.
|
||||
*
|
||||
* Lanes with nowhere to write are skipped rather than reported: a one-pole
|
||||
* filter exposes no frequency param, and a worklet effect exposes none at all.
|
||||
* Returns the targets that were scheduled, so they can be cancelled together.
|
||||
*/
|
||||
export function scheduleChainAutomation(
|
||||
automation: HfAutomation,
|
||||
chain: HfAudioFxChain,
|
||||
nodes: readonly AutomatableNode[],
|
||||
timing: AutomationTiming,
|
||||
): FxParamTarget[] {
|
||||
const byId = new Map(nodes.filter((n) => n.id).map((n) => [n.id as string, n.handle]));
|
||||
const scheduled: FxParamTarget[] = [];
|
||||
for (const lane of automation.lanes) {
|
||||
const parsed = parseAutomationTarget(lane.target);
|
||||
if (!parsed || parsed.kind !== "fx") continue;
|
||||
const targets = byId.get(parsed.nodeId)?.automation?.[parsed.param];
|
||||
if (!targets || targets.length === 0) continue;
|
||||
const range = resolveAutomationRange(lane.target, chain);
|
||||
if (!range) continue;
|
||||
scheduleParamLane(targets, lane, range.scale, timing);
|
||||
scheduled.push(...targets);
|
||||
}
|
||||
return scheduled;
|
||||
}
|
||||
|
||||
/** The track's volume lane, if it has one. */
|
||||
export function volumeLane(automation: HfAutomation): HfAutomationLane | null {
|
||||
return automation.lanes.find((lane) => lane.target === VOLUME_TARGET) ?? null;
|
||||
}
|
||||
@@ -431,6 +431,8 @@ export function buildFxNode(
|
||||
export interface FxChainHandle {
|
||||
input: AudioNode;
|
||||
output: AudioNode;
|
||||
/** Built effects in chain order, carrying the node ids lanes address. */
|
||||
nodes: { id?: string; type: string; handle: FxNodeHandle }[];
|
||||
/** Re-parameterise in place when the shape is unchanged; false if a rebuild is needed. */
|
||||
update(chain: HfAudioFxChain): boolean;
|
||||
dispose(): void;
|
||||
@@ -465,7 +467,7 @@ function shapeOf(chain: HfAudioFxChain): string {
|
||||
export function buildFxChain(ctx: BaseAudioContext, chain: HfAudioFxChain): FxChainHandle {
|
||||
const input = ctx.createGain();
|
||||
const output = ctx.createGain();
|
||||
const handles: { type: string; handle: FxNodeHandle }[] = [];
|
||||
const handles: { id?: string; type: string; handle: FxNodeHandle }[] = [];
|
||||
|
||||
let tail: AudioNode = input;
|
||||
for (const node of chain.nodes) {
|
||||
@@ -473,7 +475,7 @@ export function buildFxChain(ctx: BaseAudioContext, chain: HfAudioFxChain): FxCh
|
||||
const handle = buildFxNode(ctx, node.type, node.params ?? {});
|
||||
tail.connect(handle.input);
|
||||
tail = handle.output;
|
||||
handles.push({ type: node.type, handle });
|
||||
handles.push({ ...(node.id ? { id: node.id } : {}), type: node.type, handle });
|
||||
}
|
||||
tail.connect(output);
|
||||
|
||||
@@ -482,6 +484,7 @@ export function buildFxChain(ctx: BaseAudioContext, chain: HfAudioFxChain): FxCh
|
||||
return {
|
||||
input,
|
||||
output,
|
||||
nodes: handles,
|
||||
update(next) {
|
||||
if (shapeOf(next) !== shape) return false;
|
||||
const active = next.nodes.filter((node) => node.enabled !== false);
|
||||
|
||||
@@ -11,6 +11,18 @@
|
||||
*/
|
||||
|
||||
import { HF_AUDIO_FX_ATTR, parseAudioFxChain, type HfAudioFxChain } from "../audioFx.js";
|
||||
import {
|
||||
HF_AUDIO_AUTOMATION_ATTR,
|
||||
parseAutomation,
|
||||
resolveAutomation,
|
||||
type HfAutomation,
|
||||
} from "../audioAutomation.js";
|
||||
import {
|
||||
cancelParamLane,
|
||||
scheduleChainAutomation,
|
||||
type AutomationTiming,
|
||||
} from "../audio/audioFxAutomation.js";
|
||||
import type { FxParamTarget } from "../audio/audioFxGraph.js";
|
||||
import {
|
||||
audioFxWorkletsReady,
|
||||
buildFxChain,
|
||||
@@ -20,6 +32,24 @@ import {
|
||||
import type { FxChainHandle } from "../audio/audioFxGraph.js";
|
||||
|
||||
const EMPTY: HfAudioFxChain = { version: 1, nodes: [] };
|
||||
const NO_AUTOMATION: HfAutomation = { version: 1, lanes: [] };
|
||||
|
||||
function readAutomation(
|
||||
el: { getAttribute?(name: string): string | null },
|
||||
chain: HfAudioFxChain,
|
||||
): HfAutomation {
|
||||
const raw =
|
||||
(typeof el.getAttribute === "function" ? el.getAttribute(HF_AUDIO_AUTOMATION_ATTR) : null) ??
|
||||
"";
|
||||
if (!raw) return NO_AUTOMATION;
|
||||
try {
|
||||
return resolveAutomation(parseAutomation(raw), chain);
|
||||
} catch {
|
||||
// Unreadable automation plays the track flat rather than silencing it,
|
||||
// matching how an unreadable chain plays dry. The render refuses instead.
|
||||
return NO_AUTOMATION;
|
||||
}
|
||||
}
|
||||
|
||||
function readChain(el: { getAttribute?(name: string): string | null }): {
|
||||
chain: HfAudioFxChain;
|
||||
@@ -38,6 +68,18 @@ function readChain(el: { getAttribute?(name: string): string | null }): {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* An element's automation lanes, bound to whatever chain it carries.
|
||||
*
|
||||
* FX lanes need the chain to resolve their target's range, so they are dropped
|
||||
* for an element with no chain; a volume lane is always readable.
|
||||
*/
|
||||
export function readElementAutomation(el: {
|
||||
getAttribute?(name: string): string | null;
|
||||
}): HfAutomation {
|
||||
return readAutomation(el, readChain(el).chain);
|
||||
}
|
||||
|
||||
/**
|
||||
* Splice an element's FX chain between a decoded source and its gain stage.
|
||||
*
|
||||
@@ -48,12 +90,16 @@ function readChain(el: { getAttribute?(name: string): string | null }): {
|
||||
*
|
||||
* Returns null when the element carries no chain, leaving the original
|
||||
* source-to-gain connection in place.
|
||||
*
|
||||
* With `timing`, the element's automation lanes are scheduled onto the built
|
||||
* effects as AudioParam ramps, and rescheduled when the attribute is edited.
|
||||
*/
|
||||
export function attachElementFxChain(
|
||||
ctx: BaseAudioContext,
|
||||
el: { getAttribute?(name: string): string | null },
|
||||
source: AudioNode,
|
||||
destination: AudioNode,
|
||||
timing?: AutomationTiming,
|
||||
): { dispose(): void } | null {
|
||||
const { chain } = readChain(el);
|
||||
if (chain.nodes.length === 0) {
|
||||
@@ -103,6 +149,31 @@ export function attachElementFxChain(
|
||||
source.connect(handle.input);
|
||||
handle.output.connect(destination);
|
||||
|
||||
let automated: FxParamTarget[] = timing
|
||||
? scheduleChainAutomation(readAutomation(el, chain), chain, handle.nodes, timing)
|
||||
: [];
|
||||
|
||||
/**
|
||||
* Re-aim the envelope at the live playhead. An edit lands mid-playback, so
|
||||
* the clip has advanced past the offset the source was scheduled with.
|
||||
*/
|
||||
const timingNow = (): AutomationTiming | null => {
|
||||
if (!timing) return null;
|
||||
const now = typeof ctx.currentTime === "number" ? ctx.currentTime : timing.scheduledAt;
|
||||
return {
|
||||
scheduledAt: now,
|
||||
elapsed: timing.elapsed + (now - timing.scheduledAt) * timing.rate,
|
||||
rate: timing.rate,
|
||||
};
|
||||
};
|
||||
|
||||
const rescheduleAutomation = (next: HfAudioFxChain): void => {
|
||||
const at = timingNow();
|
||||
if (!at) return;
|
||||
cancelParamLane(automated, at.scheduledAt);
|
||||
automated = scheduleChainAutomation(readAutomation(el, next), next, handle.nodes, at);
|
||||
};
|
||||
|
||||
// Follow the attribute while the source plays, so dragging a knob is heard
|
||||
// without rescheduling the track. Values-only changes re-parameterise the
|
||||
// running graph and land on the next 128-sample quantum; a shape change
|
||||
@@ -116,14 +187,24 @@ export function attachElementFxChain(
|
||||
) {
|
||||
observer = new MutationObserver(() => {
|
||||
const next = readChain(el);
|
||||
if (next.chain.nodes.length > 0) handle.update(next.chain);
|
||||
if (next.chain.nodes.length === 0) return;
|
||||
handle.update(next.chain);
|
||||
// Values pushed by `update` would fight a running envelope, so the lanes
|
||||
// are re-scheduled on top of them from the current playhead.
|
||||
rescheduleAutomation(next.chain);
|
||||
});
|
||||
observer.observe(target, {
|
||||
attributes: true,
|
||||
attributeFilter: [HF_AUDIO_FX_ATTR, HF_AUDIO_AUTOMATION_ATTR],
|
||||
});
|
||||
observer.observe(target, { attributes: true, attributeFilter: [HF_AUDIO_FX_ATTR] });
|
||||
}
|
||||
|
||||
return {
|
||||
dispose: () => {
|
||||
observer?.disconnect();
|
||||
if (automated.length > 0) {
|
||||
cancelParamLane(automated, typeof ctx.currentTime === "number" ? ctx.currentTime : 0);
|
||||
}
|
||||
handle.dispose();
|
||||
},
|
||||
};
|
||||
|
||||
@@ -1,4 +1,10 @@
|
||||
import { attachElementFxChain } from "./audioFx.js";
|
||||
import { attachElementFxChain, readElementAutomation } from "./audioFx.js";
|
||||
import {
|
||||
scheduleParamLane,
|
||||
volumeLane,
|
||||
type AutomationTiming,
|
||||
} from "../audio/audioFxAutomation.js";
|
||||
import { VOLUME_RANGE } from "../audioAutomation.js";
|
||||
import { swallow } from "./diagnostics";
|
||||
import { getDebugSurface } from "./globals.js";
|
||||
|
||||
@@ -57,6 +63,20 @@ function startBoundedSource(
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* The volume lane rides the fader, after the effects — where a DAW puts it,
|
||||
* and the order the render bakes it in.
|
||||
*/
|
||||
function scheduleVolumeLane(
|
||||
el: HTMLMediaElement,
|
||||
gainNode: GainNode,
|
||||
timing: AutomationTiming,
|
||||
): void {
|
||||
const lane = volumeLane(readElementAutomation(el));
|
||||
if (!lane) return;
|
||||
scheduleParamLane([{ param: gainNode.gain }], lane, VOLUME_RANGE.scale, timing);
|
||||
}
|
||||
|
||||
export type ScheduledSource = {
|
||||
el: HTMLMediaElement;
|
||||
sourceNode: AudioBufferSourceNode;
|
||||
@@ -188,15 +208,19 @@ export class WebAudioTransport {
|
||||
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.
|
||||
const fx = attachElementFxChain(this._ctx, el, sourceNode, gainNode);
|
||||
const fx = attachElementFxChain(this._ctx, el, sourceNode, gainNode, timing);
|
||||
gainNode.connect(this._masterGain);
|
||||
|
||||
const elapsed = compositionTime - compositionStart;
|
||||
const scheduledAt = this._ctx.currentTime;
|
||||
scheduleVolumeLane(el, gainNode, timing);
|
||||
|
||||
this._rate = safeRate;
|
||||
this._rateAnchorCtx = scheduledAt;
|
||||
this._rateAnchorComp = compositionTime;
|
||||
|
||||
Reference in New Issue
Block a user