mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-16 14:27:26 +00:00
531 lines
18 KiB
TypeScript
531 lines
18 KiB
TypeScript
/**
|
|
* Builds the Web Audio graph for an FX chain, one builder per `web` id in the
|
|
* core registry.
|
|
*
|
|
* Every node exposes `update`, so turning a dial re-parameterises the running
|
|
* graph instead of rebuilding it. That is the whole point of previewing in the
|
|
* browser: an AudioParam change lands on the next 128-sample render quantum,
|
|
* about 2.7 ms at 48 kHz, so the knob-to-ear loop is immediate.
|
|
*/
|
|
|
|
import {
|
|
getAudioFxDef,
|
|
normalizeAudioFxParams,
|
|
type HfAudioFxChain,
|
|
type HfAudioFxParamValues,
|
|
} from "../audioFx.js";
|
|
import { audioFxWorkletsReady, ensureAudioFxWorklets } from "./audioFxWorklets.js";
|
|
|
|
/**
|
|
* Deterministic reverb impulse, shared by both engines so the browser and the
|
|
* render convolve the identical response. Exponentially-decaying noise with a
|
|
* one-pole lowpass standing in for air absorption; the PRNG is seeded from the
|
|
* parameters so the same room always produces the same tail.
|
|
*/
|
|
export function synthesizeReverbImpulse(
|
|
sampleRate: number,
|
|
size: number,
|
|
damping: number,
|
|
): Float32Array {
|
|
const seconds = 0.6 + Math.max(0, Math.min(1, size)) * 2.6;
|
|
const length = Math.max(1, Math.floor(sampleRate * seconds));
|
|
const out = new Float32Array(length);
|
|
// Seed from the parameters: same room, same tail, on every machine.
|
|
let seed = (Math.round(size * 1000) * 2654435761 + Math.round(damping * 1000) * 40503) >>> 0;
|
|
const rand = (): number => {
|
|
seed = (seed * 1664525 + 1013904223) >>> 0;
|
|
return (seed / 0xffffffff) * 2 - 1;
|
|
};
|
|
const cutoff = Math.max(0.001, 1 - Math.max(0, Math.min(1, damping)));
|
|
let lp = 0;
|
|
let energy = 0;
|
|
for (let i = 0; i < length; i++) {
|
|
lp += cutoff * (rand() - lp);
|
|
const sample = lp * Math.pow(1 - i / length, 2.5);
|
|
out[i] = sample;
|
|
energy += sample * sample;
|
|
}
|
|
// Scale to unit energy. A ConvolverNode applies the impulse's gain whole (the
|
|
// graph sets `normalize = false` so the room is deterministic rather than
|
|
// browser-defined), and this impulse is decaying noise whose raw energy runs
|
|
// to +33 dB at the default size — loud enough that simply adding a Reverb
|
|
// clipped the mix. Normalising here keeps the wet knob meaning what it says
|
|
// and keeps preview and render identical, since both convolve this buffer.
|
|
const norm = Math.sqrt(energy);
|
|
if (norm > 0) {
|
|
for (let i = 0; i < length; i++) out[i] = (out[i] ?? 0) / norm;
|
|
}
|
|
return out;
|
|
}
|
|
|
|
/**
|
|
* Where an automation lane writes when it drives one knob.
|
|
*
|
|
* A knob is not always one AudioParam. A wet/dry mix is two gains moving in
|
|
* opposition, and a knob in milliseconds drives a delay time in seconds, so
|
|
* each target carries its own mapping out of the knob's declared unit.
|
|
*/
|
|
export interface FxParamTarget {
|
|
param: AudioParam;
|
|
map?: (value: number) => number;
|
|
}
|
|
|
|
export interface FxNodeHandle {
|
|
input: AudioNode;
|
|
output: AudioNode;
|
|
update(params: HfAudioFxParamValues): void;
|
|
/**
|
|
* AudioParams behind the knobs the registry marks `automatable`, keyed by
|
|
* parameter key. Absent for a node whose values cannot be scheduled.
|
|
*/
|
|
automation?: Record<string, FxParamTarget[]>;
|
|
dispose(): void;
|
|
}
|
|
|
|
type Builder = (ctx: BaseAudioContext, p: HfAudioFxParamValues) => FxNodeHandle;
|
|
|
|
const n = (v: number | string | undefined): number => (typeof v === "number" ? v : Number(v ?? 0));
|
|
|
|
/** Milliseconds on the knob, seconds on the AudioParam. */
|
|
const msToSec = (v: number): number => v / 1000;
|
|
|
|
/** A wet/dry pair: the dry side is whatever the wet side is not. */
|
|
function mixTargets(wet: AudioParam, dry: AudioParam): FxParamTarget[] {
|
|
return [{ param: wet }, { param: dry, map: (v) => 1 - v }];
|
|
}
|
|
|
|
/** Linear crossfade: dry falls as wet rises, in lockstep. */
|
|
function setWetDryMix(wet: GainNode, dry: GainNode, mix: number): void {
|
|
wet.gain.value = mix;
|
|
dry.gain.value = 1 - mix;
|
|
}
|
|
|
|
/** A node that is its own input and output and has nothing to tear down. */
|
|
function simple(
|
|
node: AudioNode,
|
|
update: (p: HfAudioFxParamValues) => void,
|
|
automation?: Record<string, FxParamTarget[]>,
|
|
): FxNodeHandle {
|
|
return { input: node, output: node, update, automation, dispose: () => node.disconnect() };
|
|
}
|
|
|
|
/**
|
|
* Filter types whose Q a BiquadFilterNode actually reads. The spec leaves it
|
|
* unused for shelving filters, so the registry offers no shelf Q and the graph
|
|
* must expose none either — the exposure invariant would otherwise advertise an
|
|
* AudioParam for a knob nobody can set.
|
|
*/
|
|
const USES_Q: ReadonlySet<BiquadFilterType> = new Set(["peaking", "highpass", "lowpass"]);
|
|
|
|
/** dB on the knob, a linear multiplier on the AudioParam. */
|
|
const dbToLinear = (db: number): number => Math.pow(10, db / 20);
|
|
|
|
/**
|
|
* A plain level stage.
|
|
*
|
|
* Every other gain in the registry sits on a BiquadFilterNode, whose `gain`
|
|
* param is already in dB. A GainNode's is a linear multiplier, so both the
|
|
* initial value and anything an automation lane schedules have to be converted —
|
|
* which is what `FxParamTarget.map` is for.
|
|
*/
|
|
const gainStage: Builder = (ctx, p) => {
|
|
const g = ctx.createGain();
|
|
const apply = (v: HfAudioFxParamValues): void => {
|
|
g.gain.value = dbToLinear(n(v.gain));
|
|
};
|
|
apply(p);
|
|
return simple(g, apply, { gain: [{ param: g.gain, map: dbToLinear }] });
|
|
};
|
|
|
|
function biquad(type: BiquadFilterType, useGain: boolean): Builder {
|
|
return (ctx, p) => {
|
|
const f = ctx.createBiquadFilter();
|
|
f.type = type;
|
|
const apply = (v: HfAudioFxParamValues): void => {
|
|
f.frequency.value = n(v.frequency);
|
|
if (v.q !== undefined) f.Q.value = n(v.q);
|
|
if (useGain) f.gain.value = n(v.gain);
|
|
};
|
|
apply(p);
|
|
return simple(f, apply, {
|
|
frequency: [{ param: f.frequency }],
|
|
...(USES_Q.has(type) ? { q: [{ param: f.Q }] } : {}),
|
|
...(useGain ? { gain: [{ param: f.gain }] } : {}),
|
|
});
|
|
};
|
|
}
|
|
|
|
/**
|
|
* FFmpeg's highpass/lowpass take a pole count; Web Audio's biquad is always
|
|
* two-pole, so one-pole is built from raw coefficients via IIRFilterNode.
|
|
* Changing the pole count changes the node type, so the chain rebuilds rather
|
|
* than updates — handled by the caller comparing structural signatures.
|
|
*/
|
|
function onePoleBuilder(kind: "highpass" | "lowpass"): Builder {
|
|
return (ctx, p) => {
|
|
const k = Math.tan((Math.PI * n(p.frequency)) / ctx.sampleRate);
|
|
const node =
|
|
kind === "highpass"
|
|
? ctx.createIIRFilter([1 / (1 + k), -1 / (1 + k)], [1, (k - 1) / (k + 1)])
|
|
: ctx.createIIRFilter([k / (1 + k), k / (1 + k)], [1, (k - 1) / (k + 1)]);
|
|
// IIRFilterNode coefficients are immutable; the caller rebuilds on change.
|
|
// Nothing here is schedulable either, so a frequency lane on a one-pole
|
|
// filter has nowhere to write — the scheduler skips what is not exposed.
|
|
return simple(node, () => {});
|
|
};
|
|
}
|
|
|
|
function workletBuilder(processor: string): Builder {
|
|
return (ctx, p) => {
|
|
const node = new AudioWorkletNode(ctx, processor, { processorOptions: { ...p } });
|
|
return {
|
|
input: node,
|
|
output: node,
|
|
update: (v) => node.port.postMessage({ ...v }),
|
|
dispose: () => node.disconnect(),
|
|
};
|
|
};
|
|
}
|
|
|
|
/** Curves matching asoftclip's shapes, sampled once per parameter change. */
|
|
const CURVES: Record<string, (x: number) => number> = {
|
|
tanh: Math.tanh,
|
|
atan: (x) => (2 / Math.PI) * Math.atan((Math.PI / 2) * x),
|
|
cubic: (x) => (Math.abs(x) >= 1 ? Math.sign(x) : x - x ** 3 / 3),
|
|
exp: (x) => Math.sign(x) * (1 - Math.exp(-Math.abs(x))),
|
|
alg: (x) => x / Math.sqrt(1 + x * x),
|
|
quintic: (x) => (Math.abs(x) >= 1 ? Math.sign(x) : x - x ** 5 / 5),
|
|
sin: (x) => (Math.abs(x) >= 1 ? Math.sign(x) : Math.sin((Math.PI / 2) * x)),
|
|
erf: (x) => Math.tanh(1.20211 * x),
|
|
hard: (x) => Math.max(-1, Math.min(1, x)),
|
|
};
|
|
|
|
const waveshaper: Builder = (ctx, p) => {
|
|
const ws = ctx.createWaveShaper();
|
|
const preGain = ctx.createGain();
|
|
const postGain = ctx.createGain();
|
|
preGain.connect(ws).connect(postGain);
|
|
const apply = (v: HfAudioFxParamValues): void => {
|
|
const shape = CURVES[String(v.type)] ?? Math.tanh;
|
|
const threshold = Math.pow(10, n(v.threshold) / 20);
|
|
const SIZE = 8192;
|
|
const curve = new Float32Array(SIZE);
|
|
for (let i = 0; i < SIZE; i++) {
|
|
const x = (i / (SIZE - 1)) * 2 - 1;
|
|
curve[i] = shape(x / Math.max(1e-6, threshold)) * threshold;
|
|
}
|
|
ws.curve = curve;
|
|
ws.oversample = n(v.oversample) >= 4 ? "4x" : n(v.oversample) >= 2 ? "2x" : "none";
|
|
postGain.gain.value = Math.pow(10, n(v.output) / 20);
|
|
};
|
|
apply(p);
|
|
return {
|
|
input: preGain,
|
|
output: postGain,
|
|
update: apply,
|
|
// The curve itself is rebuilt wholesale, but the make-up gain after it is
|
|
// an ordinary AudioParam.
|
|
automation: { output: [{ param: postGain.gain, map: (v) => Math.pow(10, v / 20) }] },
|
|
dispose: () => {
|
|
preGain.disconnect();
|
|
ws.disconnect();
|
|
postGain.disconnect();
|
|
},
|
|
};
|
|
};
|
|
|
|
const delayFeedback: Builder = (ctx, p) => {
|
|
const input = ctx.createGain();
|
|
const out = ctx.createGain();
|
|
const dl = ctx.createDelay(5);
|
|
const fb = ctx.createGain();
|
|
const wet = ctx.createGain();
|
|
const dry = ctx.createGain();
|
|
input.connect(dl);
|
|
dl.connect(fb);
|
|
fb.connect(dl);
|
|
dl.connect(wet).connect(out);
|
|
input.connect(dry).connect(out);
|
|
const apply = (v: HfAudioFxParamValues): void => {
|
|
dl.delayTime.value = Math.min(5, n(v.time) / 1000);
|
|
fb.gain.value = n(v.feedback);
|
|
setWetDryMix(wet, dry, n(v.mix));
|
|
};
|
|
apply(p);
|
|
return {
|
|
input,
|
|
output: out,
|
|
update: apply,
|
|
automation: {
|
|
time: [{ param: dl.delayTime, map: (v) => Math.min(5, msToSec(v)) }],
|
|
feedback: [{ param: fb.gain }],
|
|
mix: mixTargets(wet.gain, dry.gain),
|
|
},
|
|
dispose: () => [input, out, dl, fb, wet, dry].forEach((x) => x.disconnect()),
|
|
};
|
|
};
|
|
|
|
const chorusLfo: Builder = (ctx, p) => {
|
|
const input = ctx.createGain();
|
|
const out = ctx.createGain();
|
|
const dl = ctx.createDelay(0.5);
|
|
const lfo = ctx.createOscillator();
|
|
const depth = ctx.createGain();
|
|
const wet = ctx.createGain();
|
|
const dry = ctx.createGain();
|
|
lfo.connect(depth).connect(dl.delayTime);
|
|
input.connect(dl).connect(wet).connect(out);
|
|
input.connect(dry).connect(out);
|
|
lfo.start();
|
|
const apply = (v: HfAudioFxParamValues): void => {
|
|
dl.delayTime.value = n(v.delay) / 1000;
|
|
depth.gain.value = n(v.depth) / 1000;
|
|
lfo.frequency.value = n(v.speed);
|
|
setWetDryMix(wet, dry, n(v.mix));
|
|
};
|
|
apply(p);
|
|
return {
|
|
input,
|
|
output: out,
|
|
update: apply,
|
|
automation: {
|
|
delay: [{ param: dl.delayTime, map: msToSec }],
|
|
depth: [{ param: depth.gain, map: msToSec }],
|
|
speed: [{ param: lfo.frequency }],
|
|
mix: mixTargets(wet.gain, dry.gain),
|
|
},
|
|
dispose: () => {
|
|
try {
|
|
lfo.stop();
|
|
} catch {
|
|
/* already stopped */
|
|
}
|
|
[input, out, dl, depth, wet, dry].forEach((x) => x.disconnect());
|
|
},
|
|
};
|
|
};
|
|
|
|
const PHASER_STAGES = 6;
|
|
|
|
const allpassPhaser: Builder = (ctx, p) => {
|
|
const input = ctx.createGain();
|
|
const out = ctx.createGain();
|
|
// aphaser's in_gain/out_gain trim the signal entering and leaving the effect.
|
|
// Wiring them to the wet and dry legs instead made "Input" mute the dry path
|
|
// and let the two defaults sum above unity, so inserting a phaser raised the
|
|
// track level.
|
|
const inTrim = ctx.createGain();
|
|
const outTrim = ctx.createGain();
|
|
const lfo = ctx.createOscillator();
|
|
const depth = ctx.createGain();
|
|
const wet = ctx.createGain();
|
|
const dry = ctx.createGain();
|
|
const stages: BiquadFilterNode[] = [];
|
|
input.connect(inTrim);
|
|
let node: AudioNode = inTrim;
|
|
for (let i = 0; i < PHASER_STAGES; i++) {
|
|
const ap = ctx.createBiquadFilter();
|
|
ap.type = "allpass";
|
|
ap.Q.value = 0.7071;
|
|
depth.connect(ap.frequency);
|
|
node.connect(ap);
|
|
node = ap;
|
|
stages.push(ap);
|
|
}
|
|
lfo.connect(depth);
|
|
// aphaser's type 0 is triangular, 1 sinusoidal. The builder never set this, so
|
|
// the declared default ("Triangular") was silently a sine. An OscillatorNode
|
|
// has no triangle-with-the-same-phase primitive to switch to, so triangle is
|
|
// the node's own "triangle" type.
|
|
lfo.start();
|
|
node.connect(wet).connect(outTrim);
|
|
inTrim.connect(dry).connect(outTrim);
|
|
outTrim.connect(out);
|
|
const apply = (v: HfAudioFxParamValues): void => {
|
|
// aphaser sweeps around a centre derived from its delay; mirror the range
|
|
// rather than the exact curve, and let the parity harness score it.
|
|
const centre = 1000 / Math.max(0.1, n(v.delay));
|
|
for (const ap of stages) ap.frequency.value = centre;
|
|
depth.gain.value = centre * n(v.decay);
|
|
lfo.frequency.value = n(v.speed);
|
|
lfo.type = String(v.type) === "1" ? "sine" : "triangle";
|
|
inTrim.gain.value = n(v.in_gain);
|
|
outTrim.gain.value = n(v.out_gain);
|
|
// Summed at unity: the sweep is the effect, not a blend control.
|
|
wet.gain.value = 1;
|
|
dry.gain.value = 1;
|
|
};
|
|
apply(p);
|
|
return {
|
|
input,
|
|
output: out,
|
|
update: apply,
|
|
// `delay` and `decay` set the sweep centre, which feeds every stage's
|
|
// frequency at once — not one knob, one param — so they stay unautomated.
|
|
automation: {
|
|
speed: [{ param: lfo.frequency }],
|
|
in_gain: [{ param: dry.gain }],
|
|
out_gain: [{ param: wet.gain }],
|
|
},
|
|
dispose: () => {
|
|
try {
|
|
lfo.stop();
|
|
} catch {
|
|
/* already stopped */
|
|
}
|
|
[input, out, inTrim, outTrim, depth, wet, dry, ...stages].forEach((x) => x.disconnect());
|
|
},
|
|
};
|
|
};
|
|
|
|
const convolver: Builder = (ctx, p) => {
|
|
const input = ctx.createGain();
|
|
const out = ctx.createGain();
|
|
const conv = ctx.createConvolver();
|
|
const wet = ctx.createGain();
|
|
const dry = ctx.createGain();
|
|
conv.normalize = false;
|
|
input.connect(conv).connect(wet).connect(out);
|
|
input.connect(dry).connect(out);
|
|
let lastKey = "";
|
|
const apply = (v: HfAudioFxParamValues): void => {
|
|
const key = `${n(v.size)}:${n(v.damping)}`;
|
|
if (key !== lastKey) {
|
|
// Same generator the render uses, so both convolve the identical tail.
|
|
const ir = synthesizeReverbImpulse(ctx.sampleRate, n(v.size), n(v.damping));
|
|
const buf = ctx.createBuffer(1, ir.length, ctx.sampleRate);
|
|
buf.getChannelData(0).set(ir);
|
|
conv.buffer = buf;
|
|
lastKey = key;
|
|
}
|
|
wet.gain.value = n(v.wet);
|
|
dry.gain.value = n(v.dry);
|
|
};
|
|
apply(p);
|
|
return {
|
|
input,
|
|
output: out,
|
|
update: apply,
|
|
// Size and damping regenerate the impulse response, so only the wet/dry
|
|
// balance is schedulable.
|
|
automation: { wet: [{ param: wet.gain }], dry: [{ param: dry.gain }] },
|
|
dispose: () => [input, out, conv, wet, dry].forEach((x) => x.disconnect()),
|
|
};
|
|
};
|
|
|
|
const BUILDERS: Record<string, Builder> = {
|
|
"gain-node": gainStage,
|
|
"biquad-peaking": biquad("peaking", true),
|
|
"biquad-lowshelf": biquad("lowshelf", true),
|
|
"biquad-highshelf": biquad("highshelf", true),
|
|
"biquad-highpass": biquad("highpass", false),
|
|
"biquad-lowpass": biquad("lowpass", false),
|
|
"worklet-compressor": workletBuilder("hf-compressor"),
|
|
"worklet-limiter": workletBuilder("hf-limiter"),
|
|
"worklet-gate": workletBuilder("hf-gate"),
|
|
"worklet-bitcrush": workletBuilder("hf-bitcrush"),
|
|
waveshaper,
|
|
"delay-feedback": delayFeedback,
|
|
"chorus-lfo": chorusLfo,
|
|
"allpass-phaser": allpassPhaser,
|
|
convolver,
|
|
};
|
|
|
|
/** Effect ids whose Web Audio node needs a worklet module registered first. */
|
|
export function chainNeedsWorklets(chain: HfAudioFxChain): boolean {
|
|
return chain.nodes.some((node) => getAudioFxDef(node.type)?.web.startsWith("worklet-") ?? false);
|
|
}
|
|
|
|
export function buildFxNode(
|
|
ctx: BaseAudioContext,
|
|
type: string,
|
|
params: HfAudioFxParamValues,
|
|
): FxNodeHandle {
|
|
const def = getAudioFxDef(type);
|
|
if (!def) throw new Error(`Unknown effect type: ${type}`);
|
|
const resolved = normalizeAudioFxParams(type, params);
|
|
// One-pole is a different node type, not a different parameter value.
|
|
if ((type === "highpass" || type === "lowpass") && String(resolved.poles) === "1") {
|
|
return onePoleBuilder(type)(ctx, resolved);
|
|
}
|
|
const builder = BUILDERS[def.web];
|
|
if (!builder) throw new Error(`No Web Audio builder for ${def.web}`);
|
|
return builder(ctx, resolved);
|
|
}
|
|
|
|
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;
|
|
}
|
|
|
|
/**
|
|
* A signature of everything that changes the graph's *shape* rather than its
|
|
* parameter values. When this is unchanged an update can just push new values
|
|
* into the running nodes; when it changes, the caller rebuilds.
|
|
*/
|
|
function shapeOf(chain: HfAudioFxChain): string {
|
|
return chain.nodes
|
|
.filter((node) => node.enabled !== false)
|
|
.map((node) => {
|
|
const p = normalizeAudioFxParams(node.type, node.params);
|
|
const poles = p.poles !== undefined ? `:${p.poles}` : "";
|
|
// A one-pole filter is an IIRFilterNode whose coefficients are fixed at
|
|
// construction, so its cutoff cannot be pushed into the running graph.
|
|
// Carrying the frequency here makes a cutoff change rebuild instead of
|
|
// being pushed into a no-op updater — which is what let preview keep
|
|
// filtering at the old frequency while the render used the new one.
|
|
const fixedFreq = String(p.poles) === "1" ? `@${p.frequency}` : "";
|
|
return `${node.type}${poles}${fixedFreq}`;
|
|
})
|
|
.join("|");
|
|
}
|
|
|
|
/**
|
|
* Build the whole chain in series. Returns a handle whose `input`/`output` can
|
|
* be spliced into any graph; an empty chain yields a pass-through.
|
|
*/
|
|
export function buildFxChain(ctx: BaseAudioContext, chain: HfAudioFxChain): FxChainHandle {
|
|
const input = ctx.createGain();
|
|
const output = ctx.createGain();
|
|
const handles: { id?: string; type: string; handle: FxNodeHandle }[] = [];
|
|
|
|
let tail: AudioNode = input;
|
|
for (const node of chain.nodes) {
|
|
if (node.enabled === false) continue;
|
|
const handle = buildFxNode(ctx, node.type, node.params ?? {});
|
|
tail.connect(handle.input);
|
|
tail = handle.output;
|
|
handles.push({ ...(node.id ? { id: node.id } : {}), type: node.type, handle });
|
|
}
|
|
tail.connect(output);
|
|
|
|
let shape = shapeOf(chain);
|
|
|
|
return {
|
|
input,
|
|
output,
|
|
nodes: handles,
|
|
update(next) {
|
|
if (shapeOf(next) !== shape) return false;
|
|
const active = next.nodes.filter((node) => node.enabled !== false);
|
|
active.forEach((node, i) => {
|
|
handles[i]?.handle.update(normalizeAudioFxParams(node.type, node.params));
|
|
});
|
|
shape = shapeOf(next);
|
|
return true;
|
|
},
|
|
dispose() {
|
|
for (const { handle } of handles) handle.dispose();
|
|
input.disconnect();
|
|
output.disconnect();
|
|
},
|
|
};
|
|
}
|
|
|
|
export { audioFxWorkletsReady, ensureAudioFxWorklets };
|