feuerwerk/src/core/soundfx/nodes.ts

import type { DeclaredPort } from '../graph/Graph';
import { SOUND_FX_INPUT, SOUND_FX_OUTPUT } from '../graph/nested';
import type { NodeDef, PortDef } from '../graph/NodeRegistry';
import type { PropertyBag } from '../model/Properties';
import type { FlatDef } from '../properties/PropertySchema';

export { SOUND_FX_INPUT, SOUND_FX_OUTPUT };

/** The filter shapes the EQ uses – Web Audio's names, so the player hands them on as they are. */
export type FxFilter = 'lowshelf' | 'peaking' | 'highshelf';

/**
 * One step a voice passes on its way out: a volume, one band of an equalizer, or an echo (#327). An
 * echo's `damping` is already the cutoff of the low-pass in its feedback, in Hz.
 */
export type FxStage =
  | { kind: 'gain'; gain: number }
  | { kind: 'filter'; filter: FxFilter; frequency: number; gain: number; q: number }
  | FxDelay;

export interface FxDelay {
  kind: 'delay';
  time: number;
  feedback: number;
  damping: number;
  mix: number;
  pingPong: boolean;
}

/**
 * Where a way of an instrument's note gets its sound (#331): a file of its own, how loud and how it
 * loops, and whether it ends with the note (`gate`) or plays through. A way of a sound FX has none –
 * it plays the sound the voice was started with. `loopEnd` 0 is the end of the sound.
 */
export interface FxSource {
  file: string;
  volume: number;
  loop: boolean;
  loopStart: number;
  loopEnd: number;
  gate: boolean;
}

/**
 * A sound on its way through the graph: how many semitones it is played up or down, and what it
 * passes, in order. `gain` is a factor, a filter's `gain` is in dB as Web Audio takes it. `shifted`
 * says the way has a Pitch at all – at 0 too, when that comes from a parameter – and so is played
 * by the pitch worklet (#317). Behind a Mix (#316) it is two sounds, `b` making up the share `mix`
 * of what goes on through `stages`.
 */
export type FxChain =
  | { pitch: number; shifted: boolean; stages: readonly FxStage[]; source?: FxSource }
  | { mix: number; a: FxChain; b: FxChain; stages: readonly FxStage[] };

export const DRY: FxChain = { pitch: 0, shifted: false, stages: [] };

/**
 * A number of the graph as the compiler knows it: typed in, or a parameter of the Input that a
 * `Play sound` may hand a value for (#311). `value` is what it is otherwise, and a parameter is held
 * to the row it ends in only once its value is known.
 */
export interface FxAmount {
  value: number;
  param?: string;
  min?: number;
  max?: number;
}

export type FxStagePlan =
  | { kind: 'gain'; db: FxAmount }
  | { kind: 'filter'; filter: FxFilter; frequency: number; gain: FxAmount; q: number }
  | {
      kind: 'delay';
      time: FxAmount;
      feedback: FxAmount;
      damping: FxAmount;
      mix: FxAmount;
      pingPong: boolean;
    };

/** A chain with its parameters still open: compiled once, filled in for every voice by `fxChainOf`. */
export type FxPlan =
  | { pitch: readonly FxAmount[]; stages: readonly FxStagePlan[]; source?: FxSource }
  | { mix: FxAmount; a: FxPlan; b: FxPlan; stages: readonly FxStagePlan[] };

export const EMPTY_PLAN: FxPlan = { pitch: [], stages: [] };

/** Values for the parameters, by name; a name the plan does not have is left out. */
export type FxParams = Readonly<Record<string, number>>;

/** How a voice goes through its sound FX: the plan and the values it starts with, kept so they can change while it plays (#315). */
export interface FxVoice {
  plan: FxPlan;
  params: FxParams;
}

export const DRY_VOICE: FxVoice = { plan: EMPTY_PLAN, params: {} };

/**
 * A node of a sound FX graph (#311). It never runs: `emit` says what it does to the sounds arriving
 * at its audio inputs, by input key, given the numbers at its other inputs and its own settings.
 * Input and Output have no effect.
 */
export interface SoundFxNodeDef extends NodeDef {
  category: 'sound';
  emit(
    sounds: Readonly<Record<string, FxPlan>>,
    amounts: Readonly<Record<string, FxAmount>>,
    settings: PropertyBag,
  ): FxPlan;
}

export function isSoundFxNodeDef(def: NodeDef): def is SoundFxNodeDef {
  return def.category === 'sound' && 'emit' in def;
}

const audioIn: PortDef = { key: 'in', label: 'in', type: 'audio' };
const audioOut: PortDef = { key: 'out', label: 'out', type: 'audio' };

function numberRow(key: string, label: string, min: number, max: number, step: number): FlatDef<'number'> {
  return { key, label, kind: 'number', default: 0, min, max, step };
}

/** An input taking a number: typed in under the key the setting had, or fed from a parameter. */
function numberIn(row: FlatDef<'number'>): PortDef {
  return { key: row.key, label: row.label, type: 'number', field: row };
}

function holdTo(value: number, row: FlatDef<'number'>): number {
  if (!Number.isFinite(value)) return row.default;
  return Math.max(row.min ?? -Infinity, Math.min(row.max ?? Infinity, value));
}

/** The amount at an input, held to its row, so a hand-edited project cannot blow a speaker. */
function held(amount: FxAmount | undefined, row: FlatDef<'number'>): FxAmount {
  if (!amount) return { value: row.default };
  const value = holdTo(amount.value, row);
  if (amount.param === undefined) return { value };
  return { value, param: amount.param, min: row.min, max: row.max };
}

/** Whether an amount does nothing however the sound is played: a typed-in 0. */
const isNone = (amount: FxAmount) => amount.param === undefined && amount.value === 0;

const arriving = (sounds: Readonly<Record<string, FxPlan>>) => sounds.in ?? EMPTY_PLAN;

export function withStages(plan: FxPlan, stages: readonly FxStagePlan[]): FxPlan {
  return stages.length === 0 ? plan : { ...plan, stages: [...plan.stages, ...stages] };
}

/** A pitch is made where the sound is read, so behind a Mix it goes to both sounds. */
export function withPitch(plan: FxPlan, semitones: FxAmount): FxPlan {
  if ('mix' in plan) return { ...plan, a: withPitch(plan.a, semitones), b: withPitch(plan.b, semitones) };
  return { ...plan, pitch: [...plan.pitch, semitones] };
}

/** A parameter of the Input as the nodes it feeds see it. */
export function soundFxParamPort(port: DeclaredPort): PortDef {
  return { key: port.key, label: port.key, type: 'number' };
}

export const SoundFxInput: SoundFxNodeDef = {
  type: SOUND_FX_INPUT,
  label: 'Input',
  category: 'sound',
  description:
    'The sound as the Play sound node starts it, before any effect. Every parameter declared here is a number output with a default; a Play sound can hand in other values through a Sound FX parameters node.',
  inputs: [],
  outputs: [audioOut],
  params: [],
  declaresPorts: 'outputs',
  portKinds: ['number'],
  declaredPort: (port) => soundFxParamPort(port),
  emit: () => EMPTY_PLAN,
};

export const SoundFxOutput: SoundFxNodeDef = {
  type: SOUND_FX_OUTPUT,
  label: 'Output',
  category: 'sound',
  description: 'What is heard: the sound as it arrives here, with every effect on the way.',
  inputs: [audioIn],
  outputs: [],
  params: [],
  emit: arriving,
};

const GAIN = numberRow('gain', 'Gain (dB)', -120, 24, 0.5);

export const SoundFxGain: SoundFxNodeDef = {
  type: 'SoundFxGain',
  label: 'Gain',
  category: 'sound',
  description:
    'Makes the sound louder or quieter, in decibels: 0 leaves it as it is, -6 is about half as loud, +6 twice. Above 0 it can clip.',
  inputs: [audioIn, numberIn(GAIN)],
  outputs: [audioOut],
  params: [],
  emit: (sounds, amounts) => {
    const db = held(amounts.gain, GAIN);
    return withStages(arriving(sounds), isNone(db) ? [] : [{ kind: 'gain', db }]);
  },
};

const SEMITONES = numberRow('semitones', 'Semitones', -64, 64, 0.1);

export const SoundFxPitch: SoundFxNodeDef = {
  type: 'SoundFxPitch',
  label: 'Pitch',
  category: 'sound',
  description:
    'Plays the sound higher or lower, in semitones: 12 is an octave up, 0.5 a quarter tone. The sound keeps its length, also when the pitch changes while it plays. The pitch is made where the sound is read, so an effect before the Pitch acts as if it came after it.',
  inputs: [audioIn, numberIn(SEMITONES)],
  outputs: [audioOut],
  params: [],
  emit: (sounds, amounts) => {
    const semitones = held(amounts.semitones, SEMITONES);
    return isNone(semitones) ? arriving(sounds) : withPitch(arriving(sounds), semitones);
  },
};

/** The five bands of the EQ: a shelf at either end and three peaks between them. */
export const EQ_BANDS: readonly { key: string; label: string; filter: FxFilter; frequency: number }[] = [
  { key: 'low', label: '80 Hz', filter: 'lowshelf', frequency: 80 },
  { key: 'lowMid', label: '250 Hz', filter: 'peaking', frequency: 250 },
  { key: 'mid', label: '1 kHz', filter: 'peaking', frequency: 1000 },
  { key: 'highMid', label: '4 kHz', filter: 'peaking', frequency: 4000 },
  { key: 'high', label: '12 kHz', filter: 'highshelf', frequency: 12000 },
];

/** About an octave and a half wide: neighbouring peaks overlap, so no frequency falls between them. */
const PEAK_Q = 1;
const EQ_ROWS = EQ_BANDS.map((band) => numberRow(band.key, band.label, -60, 24, 0.5));

export const SoundFxEq: SoundFxNodeDef = {
  type: 'SoundFxEq',
  label: '5-Band-EQ',
  category: 'sound',
  description:
    'A five-band equalizer: raises or lowers the lows (80 Hz), low mids (250 Hz), mids (1 kHz), high mids (4 kHz) and highs (12 kHz), each in decibels. A band at 0 does nothing.',
  inputs: [audioIn, ...EQ_ROWS.map(numberIn)],
  outputs: [audioOut],
  params: [],
  emit: (sounds, amounts) => {
    const stages: FxStagePlan[] = [];
    EQ_BANDS.forEach((band, i) => {
      const gain = held(amounts[band.key], EQ_ROWS[i]!);
      if (!isNone(gain))
        stages.push({ kind: 'filter', filter: band.filter, frequency: band.frequency, gain, q: PEAK_Q });
    });
    return withStages(arriving(sounds), stages);
  },
};

const MIX = { ...numberRow('mix', 'Mix', 0, 1, 0.01), default: 0.5 };

export const SoundFxMix: SoundFxNodeDef = {
  type: 'SoundFxMix',
  label: 'Mix',
  category: 'sound',
  description:
    'Blends two sounds: at 0 only a is heard, at 1 only b, at 0.5 half of each. Both ways can start at the same Input, each with its own effects, its own Pitch included.',
  inputs: [{ key: 'a', label: 'a', type: 'audio' }, { key: 'b', label: 'b', type: 'audio' }, numberIn(MIX)],
  outputs: [audioOut],
  params: [],
  emit: (sounds, amounts) => {
    const mix = held(amounts.mix, MIX);
    const a = sounds.a ?? EMPTY_PLAN;
    const b = sounds.b ?? EMPTY_PLAN;
    if (mix.param === undefined && mix.value <= 0) return a;
    if (mix.param === undefined && mix.value >= 1) return b;
    return { mix, a, b, stages: [] };
  },
};

/** As long as a delay line is ever made: every voice holds one this long, whatever its time. */
export const DELAY_MAX = 2;
const DELAY_TIME = { ...numberRow('time', 'Time (s)', 0.01, DELAY_MAX, 0.01), default: 0.25 };
/** Never 1: the echoes would never fade, and above it they would grow. */
const DELAY_FEEDBACK = { ...numberRow('feedback', 'Feedback', 0, 0.95, 0.01), default: 0.4 };
const DELAY_DAMPING = { ...numberRow('damping', 'Damping', 0, 1, 0.01), default: 0.3 };
const DELAY_MIX = { ...numberRow('mix', 'Mix', 0, 1, 0.01), default: 0.5 };
const PING_PONG = { key: 'pingPong', label: 'Ping-pong', kind: 'boolean' as const, default: false };

export const SoundFxDelay: SoundFxNodeDef = {
  type: 'SoundFxDelay',
  label: 'Delay',
  category: 'sound',
  description:
    'Echoes the sound: it comes back after "time" seconds, again and again, each echo "feedback" times as loud as the one before. "damping" makes every echo duller than the last, like tape. "mix" is how loud the echoes are next to the sound, which itself stays as it is. With "ping-pong" the echoes take turns left and right. The echoes ring on after the sound ends; a voice lasts until they have faded.',
  inputs: [audioIn, ...[DELAY_TIME, DELAY_FEEDBACK, DELAY_DAMPING, DELAY_MIX].map(numberIn)],
  outputs: [audioOut],
  params: [PING_PONG],
  emit: (sounds, amounts, settings) => {
    const mix = held(amounts.mix, DELAY_MIX);
    if (isNone(mix)) return arriving(sounds);
    return withStages(arriving(sounds), [
      {
        kind: 'delay',
        time: held(amounts.time, DELAY_TIME),
        feedback: held(amounts.feedback, DELAY_FEEDBACK),
        damping: held(amounts.damping, DELAY_DAMPING),
        mix,
        pingPong: settings[PING_PONG.key] === true,
      },
    ]);
  },
};

/** Where damping 0 leaves the echoes and damping 1 takes them: evenly in octaves between. */
const UNDAMPED_HZ = 20000;
const DAMPED_HZ = 500;

export function dampingCutoff(damping: number): number {
  return UNDAMPED_HZ * (DAMPED_HZ / UNDAMPED_HZ) ** Math.max(0, Math.min(1, damping));
}

export const SOUND_FX_NODES: readonly SoundFxNodeDef[] = [
  SoundFxInput,
  SoundFxOutput,
  SoundFxGain,
  SoundFxPitch,
  SoundFxEq,
  SoundFxMix,
  SoundFxDelay,
];

/** An amount with the value handed in for its parameter, held to its row; a 0 there does nothing. */
function amountOf(amount: FxAmount, params: FxParams): number {
  const given = amount.param !== undefined ? params[amount.param] : undefined;
  if (given === undefined || !Number.isFinite(given)) return amount.value;
  return Math.max(amount.min ?? -Infinity, Math.min(amount.max ?? Infinity, given));
}

/** A stage fed by a parameter stays at 0 as well: a value handed in later has to find it there. */
function stagesOf(plan: FxPlan, params: FxParams): FxStage[] {
  const stages: FxStage[] = [];
  for (const stage of plan.stages) {
    if (stage.kind === 'gain') {
      const db = amountOf(stage.db, params);
      if (db !== 0 || stage.db.param !== undefined) stages.push({ kind: 'gain', gain: 10 ** (db / 20) });
      continue;
    }
    if (stage.kind === 'delay') {
      stages.push({
        kind: 'delay',
        time: amountOf(stage.time, params),
        feedback: amountOf(stage.feedback, params),
        damping: dampingCutoff(amountOf(stage.damping, params)),
        mix: amountOf(stage.mix, params),
        pingPong: stage.pingPong,
      });
      continue;
    }
    const gain = amountOf(stage.gain, params);
    if (gain !== 0 || stage.gain.param !== undefined) stages.push({ ...stage, gain });
  }
  return stages;
}

/**
 * The chain one voice is sent along: the plan with every parameter filled in. Its shape depends on
 * the plan alone, never on the values, so the values of a playing voice can change in place (#315).
 */
export function fxChainOf(plan: FxPlan, params: FxParams = {}): FxChain {
  const stages = stagesOf(plan, params);
  if (!('mix' in plan)) {
    const pitch = plan.pitch.reduce((sum, amount) => sum + amountOf(amount, params), 0);
    const chain = { pitch, shifted: plan.pitch.length > 0, stages };
    return plan.source ? { ...chain, source: plan.source } : chain;
  }
  return {
    mix: amountOf(plan.mix, params),
    a: fxChainOf(plan.a, params),
    b: fxChainOf(plan.b, params),
    stages,
  };
}

/** Whether a plan can ring on after its sources end (#324): it has an echo somewhere. */
export function fxRings(plan: FxPlan): boolean {
  if (plan.stages.some((stage) => stage.kind === 'delay')) return true;
  return 'mix' in plan && (fxRings(plan.a) || fxRings(plan.b));
}

/** How far below the sound a tail has to fall to count as gone: -60 dB. */
const SILENT = 1e-3;

/**
 * How many seconds a chain rings on after its sources end (#324), at the values it has now: until
 * its last echo is 60 dB below the sound. Damping only makes echoes quieter, so it is left out and
 * the tail is never too short. Echoes behind each other add up, two ways of a Mix take the longer.
 */
export function fxTailOf(chain: FxChain): number {
  const ways = 'mix' in chain ? Math.max(fxTailOf(chain.a), fxTailOf(chain.b)) : 0;
  return chain.stages.reduce((sum, stage) => sum + (stage.kind === 'delay' ? delayTail(stage) : 0), ways);
}

/** The echo `k` is `mix * feedback^(k-1)` as loud as the sound; the last one still heard sets the tail. */
function delayTail({ time, feedback, mix }: FxDelay): number {
  if (!(mix >= SILENT) || !(time > 0)) return 0;
  const echoes = feedback > 0 ? 1 + Math.floor(Math.log(SILENT / mix) / Math.log(feedback)) : 1;
  return echoes * time;
}