instruments.js

import {
  getAttackInstabilityOscillator,
  getNoiseOscillator,
  getVarianceOscillator,
  getVibratoVarianceGain,
} from "./sources.js";

export class InstrumentPreset {
  group = "Miscellaneous";

  /** @type {OscillatorPreset[]} the oscillators that create the sound of the instrument. */
  oscillators = [];

  /** a `timeConstant` for how long the note takes to "fade in"; values below ~0.008 hurt a bit */
  attack = 0.008;
  /** a `timeConstant` for how long before the note reaches the `sustain` level after finishing its `attack` */
  decay = 0.0;
  /** how loud the note after it has fully decayed */
  sustain = 0.0;
  /** a `timeConstant` for how long the note takes to "fade out" */
  release = 0.0;

  /** @type {number} determines how strongly the oscillator's dynamics respond to different velocities */
  velocitySensitivity = 1.0;

  /** @type {OscillatorType} the type of the oscillator used for vibrato and attackInstability */
  vibratoType = "triangle";

  /** @type {number} how much vibrato should affect the note frequency (in cents) */
  vibratoEffectOnPitch = 0.0;
  /** @type {number} how much vibrato should affect volume (in gain) */
  vibratoEffectOnVolume = 0.0;
  /** @type {number} amount of brass instrument style initial note vibration: causes the "braaap" */
  attackInstability = 0.0;

  /** @type {number} detunes oscillator by this many cents * velocity */
  attackDetune = 0.0;
  /** @type {number=} a `timeConstant` for how long `attackDetune` should occur, defaults to `attack` */
  attackDetuneDuration = undefined;

  /** @type {number} detunes oscillators by this many cents over time, using a low frequency oscillator */
  pitchVariance = 0.0;

  // Values mostly from these sources:
  // http://hyperphysics.phy-astr.gsu.edu/hbase/Music/orchins.html
  // https://alexiy.nl/eq_chart/
  // https://www.soundonsound.com/techniques/practical-bowed-string-synthesis
  // https://euphonics.org/5-3-signature-modes-and-formants/
  // https://sengpielaudio.com/VowelDiagram.htm
  /** @type {number} applies to a lowpass filter at this frequency */
  lowPassFrequency = 4186.009 * 1.059463;
  /** @type {number} applies a highpass filter at this frequency */
  highPassFrequency = 27.5 * 0.943874;

  /** @type {number} the resonance or "Q factor" of the lowpass filter */
  lowPassQ = Math.SQRT1_2;
  /** @type {number} the resonance or "Q factor" of the highpass filter */
  highPassQ = Math.SQRT1_2;

  /** @type {FormantFilterPreset[]} */
  formants = [];

  /**
   * @param {Partial<Omit<InstrumentPreset, "oscillators" | "formants">> & {oscillators?: Partial<OscillatorPreset>[], formants?: Partial<FormantFilterPreset>[]}} instrumentProps
   */
  constructor({ oscillators, formants, ...props }) {
    Object.assign(this, props);

    if (oscillators) {
      for (const oscillator of oscillators) {
        this.oscillators.push(new OscillatorPreset(oscillator));
      }
    }

    if (formants) {
      for (const formant of formants) {
        this.formants.push(new FormantFilterPreset(formant));
      }
    }
  }
}

/** A `peaking` filter applied to the instrument to shape its timbre. The instrument's overall volume will be automatically lowered to compensate. */
export class FormantFilterPreset {
  frequency = 440;
  Q = 2.456424;
  gain = 1.618;

  constructor(/** @type {Partial<FormantFilterPreset>} */ props) {
    Object.assign(this, props);
  }
}

export class OscillatorPreset {
  /** @type {OscillatorType | "noise"} */
  type = "custom";
  /** @type {PeriodicWaveOptions["imag"]=} used for custom oscillators */
  imag = undefined;
  /** @type {PeriodicWaveOptions["real"]=} used for custom oscillators */
  real = undefined;
  /** @type {number} base volume of the oscillator */
  gain = 1.0;

  /** @type {InstrumentPreset["attack"]=} */
  attack = undefined;
  /** @type {InstrumentPreset["decay"]=} */
  decay = undefined;
  /** @type {InstrumentPreset["sustain"]=} */
  sustain = undefined;
  /** @type {InstrumentPreset["release"]=} */
  release = undefined;

  /** @type {InstrumentPreset["velocitySensitivity"]=} */
  velocitySensitivity = undefined;
  /** @type {number} determines how much of the oscillator's gain is impacted by velocity */
  velocityImpactOnGain = 0.236;

  /** @type {InstrumentPreset["vibratoEffectOnPitch"]=} */
  vibratoEffectOnPitch = undefined;
  /** @type {InstrumentPreset["vibratoEffectOnVolume"]=} */
  vibratoEffectOnVolume = undefined;
  /** @type {InstrumentPreset["attackInstability"]=} */
  attackInstability = undefined;

  /** @type {InstrumentPreset["attackDetune"]=} */
  attackDetune = undefined;
  /** @type {InstrumentPreset["attackDetuneDuration"]=} */
  attackDetuneDuration = undefined;

  /** @type {BiquadFilterType} used when `type` is "noise": determines the type of filter used to filter the noise */
  noiseType = "lowpass";
  /** @type {number} used when `type` is "noise": sets the Q factor of the noise filter */
  noiseQ = Math.SQRT1_2;
  /** @type {number} set when the Oscillator is created */
  detune = 0;

  /** lets you modify the pitch before it gets played */
  getPitch(pitch = 440.0, _velocity = 1.0) {
    return pitch;
  }

  /** @param {Partial<OscillatorPreset>} props */
  constructor(props) {
    Object.assign(this, props);
  }
}

export const createInstrument = (/** @type {InstrumentPreset} */ preset, /** @type {AudioContext}*/ audioContext) => {
  const {
    oscillators: oscillatorsInPreset,
    vibratoType,
    formants,
    lowPassQ = Math.SQRT1_2,
    highPassQ = Math.SQRT1_2,
    lowPassFrequency,
    highPassFrequency,
    pitchVariance,
  } = preset;

  // Filters
  // Useful Q values (no idea exactly what they result in):
  // 2nd-order Butterworth: Qp = Math.SQRT1_2
  // 2nd-order Chebyshev (ripple 1 dB): Qp = 0.9565
  // 2nd-order Thomson-Bessel: Qp=0.5773
  // 4th-order Butterworth: Strage 1: Qp=0.5412; stage 2: Qp=1.3065

  const lowPassFilter = new BiquadFilterNode(audioContext, {
    type: "lowpass",
    frequency: lowPassFrequency,
    Q: lowPassQ,
  });

  const highPassFilter = new BiquadFilterNode(audioContext, {
    type: "highpass",
    frequency: highPassFrequency,
    Q: highPassQ,
  });

  const input = lowPassFilter;
  let output = input;
  let maxPeak = 1.0;

  if (formants.length > 0) {
    for (const { frequency, Q = 2.456424, gain = 1.618 } of formants) {
      const formantFilter = new BiquadFilterNode(audioContext, {
        type: "peaking",
        frequency: frequency,
        Q,
        gain,
      });

      output.connect(formantFilter);
      output = formantFilter;

      maxPeak = Math.max(maxPeak, gain);
    }
  }

  output.connect(highPassFilter);
  output = highPassFilter;

  // Vibrato effects
  const vibratoMain = new OscillatorNode(audioContext, {
    type: vibratoType,
    frequency: 0,
  });

  vibratoMain.start(audioContext.currentTime);

  // Variance
  const hasPitchVariance = pitchVariance !== 0.0;
  const varianceOscillator = getVarianceOscillator(audioContext);
  const pitchVarianceGain = hasPitchVariance ? new GainNode(audioContext, { gain: pitchVariance }) : null;
  if (pitchVarianceGain) varianceOscillator.connect(pitchVarianceGain);

  getVibratoVarianceGain(audioContext).connect(vibratoMain.detune);

  // Oscillators
  const oscillators = [];
  const randomisedPhase = Math.random() * 2.0 - 1.0;
  let canVibrato = false;

  for (const {
    type,
    imag,
    real,
    gain,
    attack = preset.attack,
    decay = preset.decay,
    sustain = preset.sustain,
    release = preset.release,
    velocitySensitivity = preset.velocitySensitivity,
    velocityImpactOnGain,
    attackDetune = preset.attackDetune,
    attackDetuneDuration = preset.attackDetuneDuration,
    noiseType,
    noiseQ,
    detune,
    getPitch = passPitchThrough,
    attackInstability = preset.attackInstability,
    vibratoEffectOnPitch = preset.vibratoEffectOnPitch,
    vibratoEffectOnVolume = preset.vibratoEffectOnVolume,
  } of oscillatorsInPreset) {
    const oscillatorNode =
      type === "custom"
        ? new OscillatorNode(audioContext, {
            type,
            periodicWave: new PeriodicWave(audioContext, {
              imag: imag || undefined,
              real: real || imag?.map((v) => v * randomisedPhase),
              disableNormalization: true,
            }),
            frequency: getPitch(440),
            detune,
          })
        : type === "noise"
          ? new BiquadFilterNode(audioContext, {
              type: noiseType,
              frequency: getPitch(440),
              Q: noiseQ,
              detune,
            })
          : new OscillatorNode(audioContext, { type, frequency: getPitch(440) });

    const gainNode = new GainNode(audioContext, { gain: 0 });
    const effectGainNode = new GainNode(audioContext, { gain: 1 });
    const gainTarget = (gain / maxPeak) ** Math.SQRT1_2;

    if (type === "noise") getNoiseOscillator(audioContext).connect(oscillatorNode);
    if (oscillatorNode instanceof OscillatorNode) oscillatorNode.start(audioContext.currentTime);

    // Brass-style attack instability
    let attackInstabilityGain = null;
    if (attackInstability) {
      attackInstabilityGain = new GainNode(audioContext, { gain: 0.0 });
      getAttackInstabilityOscillator(audioContext).connect(attackInstabilityGain).connect(gainNode.gain);
    }

    // Tremolo and/or brightness vibrato
    if (vibratoEffectOnVolume) {
      canVibrato = true;
      const vibratoVolumeGain = new GainNode(audioContext, { gain: vibratoEffectOnVolume });
      vibratoMain.connect(vibratoVolumeGain).connect(effectGainNode.gain);
    }

    // Regular pitch vibrato
    if (vibratoEffectOnPitch) {
      canVibrato = true;
      const vibratoPitchGain = new GainNode(audioContext, { gain: vibratoEffectOnPitch });
      vibratoMain.connect(vibratoPitchGain).connect(oscillatorNode.detune);
    }

    // Connect variances
    if (hasPitchVariance) {
      pitchVarianceGain.connect(oscillatorNode.detune);
    }

    oscillatorNode.connect(gainNode).connect(effectGainNode).connect(input);

    oscillators.push({
      oscillatorNode,
      gainNode,
      effectGainNode,
      gainTarget,
      getPitch,
      attack,
      decay,
      sustain,
      release,
      velocitySensitivity,
      velocityImpactOnGain,
      attackDetune,
      attackDetuneDuration,
      attackInstabilityGain,
      attackInstability,
      vibratoEffectOnPitch,
      vibratoEffectOnVolume,
    });
  }

  const epsilon = 1.0 / audioContext.sampleRate;

  return {
    epsilon,
    oscillators,
    vibratoMain,
    lowPassFilter,
    highPassFilter,
    canVibrato,
    output,
    preset,
    previousStartAt: audioContext.currentTime - epsilon,
    previousEndAt: audioContext.currentTime,
    previousPitch: 440.0,
    previousVelocity: 0.5,
    previousAttack: 0.0,
    previousDecay: 0.0,
  };
};

/**
  @param {Number} pitch
*/
const passPitchThrough = (pitch = 440.0) => pitch;

export const playInstrument = (
  /** @type {ReturnType<typeof createInstrument>} */ instrument,
  /** @type {number} */ pitch,
  /** @type {number} */ at,
  /** @type {number} */ duration,
  /** @type {number=} */ velocity = undefined,
  /** @type {number=} */ attackMultiplier = undefined,
  /** @type {number=} */ releaseMultiplier = undefined,
  /** @type {number=} */ volume = undefined,
  /** @type {number=} */ vibratoAmount = undefined,
  /** @type {number=} */ vibratoFrequency = undefined,
  /** @type {number=} */ bendToPitch = undefined,
  /** @type {number=} */ pitchBendDelay = undefined,
) => {
  attackInstrument(
    instrument,
    pitch,
    at,
    velocity,
    attackMultiplier,
    volume,
    vibratoAmount,
    vibratoFrequency,
    bendToPitch,
    pitchBendDelay,
    duration,
  );
  releaseInstrument(instrument, at + duration, releaseMultiplier, true);
};

export const attackInstrument = (
  /** @type {ReturnType<typeof createInstrument>} */ instrument,
  /** @type {number} */ pitch,
  /** @type {number} */ at,
  velocity = 0.5,
  attackMultiplier = 1.0,
  volume = 1.0,
  vibratoAmount = 0.0,
  vibratoFrequency = 5.0,
  /** @type {number | undefined} */ bendToPitch = undefined,
  /** @type {number | undefined} */ pitchBendDelay = undefined,
  /** @type {number | undefined} */ pitchBendDuration = undefined,
) => {
  const { oscillators, vibratoMain, canVibrato, epsilon } = instrument;

  // FIXME: these are repeated in attack and release, but don't need to be in play
  const highPitchness = -(1200.0 * Math.log2(27.5 / pitch)) / highPitchnessReference;
  // const lowPitchness = 1.0 - highPitchness;
  const relativePitchness = highPitchness * 2.0 - 1.0;
  const relativeVelocity = velocity * 2.0 - 1.0;

  const dynamicStartAt = Math.max(instrument.output.context.currentTime, at);

  cancelPendingInstrumentEvents(instrument, dynamicStartAt);

  // Tell the oscillators what to do
  let firstAttack = undefined;
  let firstDecay = undefined;

  for (const oscillator of oscillators) {
    const {
      oscillatorNode,
      gainNode,
      gainTarget,
      attack,
      velocitySensitivity,
      velocityImpactOnGain,
      attackDetune,
      attackDetuneDuration = attack,
      getPitch,
      decay,
      sustain,
      attackInstabilityGain,
      attackInstability,
    } = oscillator;

    cancelPendingOscillatorEvents(oscillator, dynamicStartAt);

    // Attack
    const attackDynamics = (1.0 - 0.382 * relativePitchness) * (1.0 - 0.146 * relativeVelocity) * attackMultiplier;

    const dynamicAttack = attack * attackDynamics;
    firstAttack = firstAttack ?? dynamicAttack;

    const gainWithVelocity = gainTarget * (1.0 - velocityImpactOnGain * (1.0 - velocity)) * volume;

    const pitchTarget = getPitch(pitch, velocity);
    oscillatorNode.frequency.setTargetAtTime(pitchTarget, dynamicStartAt, epsilon);
    gainNode.gain.setTargetAtTime(gainWithVelocity, dynamicStartAt, dynamicAttack);

    // Detune attack
    if (attackDetune !== 0.0) {
      oscillatorNode.detune.setTargetAtTime(attackDetune * velocity ** 0.414, dynamicStartAt, epsilon);

      oscillatorNode.detune.setTargetAtTime(0.0, dynamicStartAt + epsilon * 7.0, attackDetuneDuration * attackDynamics);
    }

    // Brass-style attack instability
    if (attackInstability) {
      const attackInstabilityAttack = dynamicAttack * 0.001;
      const attackInstabilityDecaysAt = dynamicStartAt + attackInstabilityAttack * 5.0;
      const attackInstabilityGainDecay = dynamicAttack * 5.0 - (attackInstabilityDecaysAt - dynamicStartAt);

      attackInstabilityGain?.gain.setTargetAtTime(
        attackInstability * (Math.max(0.0, 1.0 - highPitchness) * velocity) ** Math.SQRT1_2,
        dynamicStartAt,
        attackInstabilityAttack,
      );
      attackInstabilityGain?.gain.setTargetAtTime(0.0, attackInstabilityDecaysAt, attackInstabilityGainDecay);
    }

    // Decay and sustain
    if (sustain === 1.0 && decay === 0) continue;

    const decayAt = dynamicStartAt + dynamicAttack * 5.0;
    const decayDynamics = (2.618 - 2.0 * relativePitchness) * (1.0 + 0.618 * velocity * velocitySensitivity);
    const dynamicDecay = decay * decayDynamics;
    firstDecay = firstDecay ?? dynamicDecay;

    gainNode.gain.setTargetAtTime(gainWithVelocity * sustain, decayAt, dynamicDecay);
  }

  firstAttack = firstAttack ?? 0.0;
  firstDecay = firstDecay ?? 0.0;

  // Pitch bend
  if (bendToPitch !== undefined && bendToPitch !== pitch) {
    for (const { getPitch, oscillatorNode } of oscillators) {
      const bendToPitchTarget = getPitch(bendToPitch, velocity);
      const delay = epsilon * 7.0 + firstAttack * 5.0 * (pitchBendDelay ?? 1.0);
      const duration = pitchBendDuration ?? firstAttack + firstDecay;

      oscillatorNode.frequency.setTargetAtTime(bendToPitchTarget, dynamicStartAt + delay, duration - delay / 5.0);
    }
  }

  // Fire up vibrato
  if (canVibrato && vibratoAmount) {
    const vibratoDynamics = (1.0 - 0.382 * relativePitchness) * (1.0 - 0.382 * relativeVelocity);
    vibratoMain.frequency.setTargetAtTime(vibratoFrequency, dynamicStartAt, 0.09 * vibratoDynamics);
  }

  instrument.previousStartAt = dynamicStartAt;
  instrument.previousEndAt = Number.POSITIVE_INFINITY;
  instrument.previousPitch = pitch;
  instrument.previousVelocity = velocity;
  instrument.previousAttack = firstAttack;
  instrument.previousDecay = firstDecay;
};

const highPitchnessReference = 1200.0 * Math.log2(4186.009 / 27.5);

export const releaseInstrument = (
  /** @type {ReturnType<typeof createInstrument>} */ instrument,
  /** @type {number} */ endAt,
  releaseMultiplier = 1.0,
  releaseEarly = true,
) => {
  const { oscillators, vibratoMain } = instrument;

  const pitch = instrument.previousPitch;
  const velocity = instrument.previousVelocity;

  const highPitchness = -(1200.0 * Math.log2(27.5 / pitch)) / highPitchnessReference;
  // const lowPitchness = 1.0 - highPitchness;

  const relativePitchness = highPitchness * 2.0 - 1.0;
  const relativeVelocity = velocity * 2.0 - 1.0;

  let firstEndAt;
  let firstRelease;

  // FIXME: duplicate work here, ugh
  for (const oscillator of oscillators) {
    const { release } = oscillator;

    const releaseDynamics = (1.0 - 0.382 * relativePitchness) * (1.0 + 0.382 * relativeVelocity);
    const dynamicRelease = release * releaseDynamics * releaseMultiplier;

    const dynamicEndAt = releaseEarly
      ? Math.max(
          instrument.output.context.currentTime,
          instrument.previousStartAt + 0.764 * (endAt - instrument.previousStartAt),
          endAt - dynamicRelease * 0.618,
        )
      : endAt;

    firstEndAt = firstEndAt ?? dynamicEndAt;
    firstRelease = firstRelease ?? dynamicRelease;
  }

  for (const oscillator of oscillators) {
    const { gainNode, release, attackInstabilityGain, velocitySensitivity } = oscillator;

    const releaseDynamics =
      (1.0 - 0.236 * relativePitchness) * (1.0 + 0.382 * velocity * velocitySensitivity) * releaseMultiplier;
    const dynamicRelease = release * releaseDynamics;
    const vibratoGainRelease = dynamicRelease * 0.09;

    cancelPendingOscillatorEvents(oscillator, firstEndAt);

    gainNode.gain.setTargetAtTime(0.0, firstEndAt, dynamicRelease);
    attackInstabilityGain?.gain.setTargetAtTime(0.0, firstEndAt, vibratoGainRelease);
  }

  cancelPendingInstrumentEvents(instrument, firstEndAt);

  const vibratoDynamics = (1.0 - 0.382 * relativePitchness) * (1.0 - 0.382 * relativeVelocity);
  vibratoMain.frequency.setTargetAtTime(0.0, firstEndAt, 0.013 * vibratoDynamics);

  instrument.previousEndAt = releaseEarly ? firstEndAt : endAt + firstRelease * 0.236;
};

const cancelPendingInstrumentEvents = (
  /** @type {ReturnType<typeof createInstrument>} */ instrument,
  /** @type {number} */ at,
) => {
  const { vibratoMain } = instrument;
  vibratoMain.frequency.cancelScheduledValues(at);
};

const cancelPendingOscillatorEvents = (
  /** @type {ReturnType<typeof createInstrument>["oscillators"][0]} */ oscillator,
  /** @type {number} */ at,
) => {
  const { oscillatorNode, gainNode, attackInstabilityGain } = oscillator;

  oscillatorNode.frequency.cancelScheduledValues(at);
  oscillatorNode.detune.cancelScheduledValues(at);
  gainNode.gain.cancelScheduledValues(at);

  attackInstabilityGain?.gain.cancelScheduledValues(at);
};

/**
  @param {ReturnType<typeof createInstrument>} instrument
*/
export const destroyInstrument = (instrument) => {
  for (const key in instrument) {
    const value = instrument[key]; // FIXME: as keyof typeof instrument

    if (Array.isArray(value)) {
      for (const child of value) {
        child.stop?.();
        child.disconnect?.();
      }
    } else {
      value.stop?.();
      value.disconnect?.();
    }
  }
};