@blibliki/engine 0.5.1 → 0.9.0

package/src/modules/Delay.ts

@@ -0,0 +1,347 @@
+import { Division, divisionToMilliseconds } from "@blibliki/transport";
+import { Context } from "@blibliki/utils";
+import { EnumProp, ModulePropSchema } from "@/core";
+import { Module, SetterHooks } from "@/core/module/Module";
+import { WetDryMixer } from "@/utils";
+import { ICreateModule, ModuleType } from ".";
+
+export enum DelayTimeMode {
+  short = "short",
+  long = "long",
+}
+
+export type IDelayProps = {
+  time: number; // 0-2000 ms (short) or 0-5000 ms (long)
+  timeMode: DelayTimeMode; // short (2s) or long (5s)
+  sync: boolean; // Enable BPM sync
+  division: Division; // Note division when sync is enabled
+  feedback: number; // 0-0.95 (feedback amount)
+  mix: number; // 0-1 (dry/wet)
+  stereo: boolean; // Enable ping-pong stereo mode
+};
+
+export type IDelay = Module<ModuleType.Delay>;
+
+const NOTE_DIVISIONS: Division[] = [
+  "1/64",
+  "1/48",
+  "1/32",
+  "1/24",
+  "1/16",
+  "1/12",
+  "1/8",
+  "1/6",
+  "3/16",
+  "1/4",
+  "5/16",
+  "1/3",
+  "3/8",
+  "1/2",
+  "3/4",
+  "1",
+  "1.5",
+  "2",
+  "3",
+  "4",
+  "6",
+  "8",
+  "16",
+  "32",
+];
+
+export const delayPropSchema: ModulePropSchema<
+  IDelayProps,
+  {
+    timeMode: EnumProp<DelayTimeMode>;
+    division: EnumProp<Division>;
+  }
+> = {
+  time: {
+    kind: "number",
+    min: 0,
+    max: 5000, // UI max for manual mode (long = 5s)
+    step: 1,
+    label: "Delay Time",
+  },
+  timeMode: {
+    kind: "enum",
+    options: [DelayTimeMode.short, DelayTimeMode.long],
+    label: "Time Mode",
+  },
+  sync: {
+    kind: "boolean",
+    label: "Sync",
+  },
+  division: {
+    kind: "enum",
+    options: NOTE_DIVISIONS,
+    label: "Division",
+  },
+  feedback: {
+    kind: "number",
+    min: 0,
+    max: 0.95,
+    step: 0.01,
+    label: "Feedback",
+  },
+  mix: {
+    kind: "number",
+    min: 0,
+    max: 1,
+    step: 0.01,
+    label: "Mix",
+  },
+  stereo: {
+    kind: "boolean",
+    label: "Stereo",
+  },
+};
+
+const DEFAULT_DELAY_PROPS: IDelayProps = {
+  time: 250,
+  timeMode: DelayTimeMode.short,
+  sync: false,
+  division: "1/4",
+  feedback: 0.3,
+  mix: 0.3,
+  stereo: false,
+};
+
+// ============================================================================
+// Module Class
+// ============================================================================
+
+export default class Delay
+  extends Module<ModuleType.Delay>
+  implements
+    Pick<
+      SetterHooks<IDelayProps>,
+      | "onAfterSetTime"
+      | "onAfterSetTimeMode"
+      | "onAfterSetSync"
+      | "onAfterSetDivision"
+      | "onAfterSetFeedback"
+      | "onAfterSetMix"
+      | "onAfterSetStereo"
+    >
+{
+  // Audio graph nodes
+  declare audioNode: GainNode; // Input node
+  private outputNode!: GainNode; // Final output node
+  private wetDryMixer: WetDryMixer;
+
+  // Mono delay nodes
+  private delayNode: DelayNode;
+  private feedbackGain: GainNode;
+
+  // Stereo ping-pong nodes (created when stereo=true)
+  private delayLeft: DelayNode | null = null;
+  private delayRight: DelayNode | null = null;
+  private feedbackLeft: GainNode | null = null;
+  private feedbackRight: GainNode | null = null;
+  private merger: ChannelMergerNode | null = null;
+
+  constructor(engineId: string, params: ICreateModule<ModuleType.Delay>) {
+    const props = { ...DEFAULT_DELAY_PROPS, ...params.props };
+
+    // Input node
+    const audioNodeConstructor = (context: Context) =>
+      context.audioContext.createGain();
+
+    super(engineId, {
+      ...params,
+      props,
+      audioNodeConstructor,
+    });
+
+    // Set input gain
+    this.audioNode.gain.value = 1;
+
+    // Create WetDryMixer
+    this.wetDryMixer = new WetDryMixer(this.context);
+
+    // Create mono delay graph (default)
+    // Max 179s (Web Audio API limit: must be < 180s / 3 minutes)
+    this.delayNode = this.context.audioContext.createDelay(179);
+    this.feedbackGain = this.context.audioContext.createGain();
+
+    // Connect mono graph initially
+    this.connectMonoGraph();
+
+    // Apply initial parameters
+    this.wetDryMixer.setMix(props.mix);
+    this.feedbackGain.gain.value = props.feedback;
+    this.updateDelayTime();
+
+    // Switch to stereo if needed
+    if (props.stereo) {
+      this.switchToStereo();
+    }
+
+    // Setup BPM listener for sync mode
+    this.setupBPMListener();
+
+    this.registerDefaultIOs("in");
+    this.registerCustomOutput();
+  }
+
+  private setupBPMListener() {
+    this.engine.transport.addPropertyChangeCallback("bpm", () => {
+      if (!this.props.sync) return;
+
+      this.updateDelayTime();
+    });
+  }
+
+  private updateDelayTime() {
+    let timeInSeconds: number;
+
+    if (this.props.sync) {
+      // BPM-based timing
+      const bpm = this.engine.transport.bpm;
+      const timeMs = divisionToMilliseconds(this.props.division, bpm);
+      timeInSeconds = timeMs / 1000;
+    } else {
+      // Manual timing
+      timeInSeconds = this.props.time / 1000;
+    }
+
+    this.delayNode.delayTime.value = timeInSeconds;
+    if (this.delayLeft) this.delayLeft.delayTime.value = timeInSeconds;
+    if (this.delayRight) this.delayRight.delayTime.value = timeInSeconds;
+  }
+
+  private connectMonoGraph() {
+    // Disconnect any existing connections
+    this.disconnectAll();
+
+    // Connect: Input -> WetDryMixer (dry)
+    this.wetDryMixer.connectInput(this.audioNode);
+
+    // Connect: Input -> Delay -> Feedback -> Delay (loop)
+    this.audioNode.connect(this.delayNode);
+    this.delayNode.connect(this.feedbackGain);
+    this.feedbackGain.connect(this.delayNode); // Feedback loop
+
+    // Connect: Delay -> WetDryMixer (wet)
+    this.delayNode.connect(this.wetDryMixer.getWetInput());
+
+    // Output
+    this.outputNode = this.wetDryMixer.getOutput();
+  }
+
+  private switchToStereo() {
+    if (!this.delayLeft) {
+      // Create stereo nodes (max 179s - Web Audio API limit: < 180s)
+      this.delayLeft = this.context.audioContext.createDelay(179);
+      this.delayRight = this.context.audioContext.createDelay(179);
+      this.feedbackLeft = this.context.audioContext.createGain();
+      this.feedbackRight = this.context.audioContext.createGain();
+      this.merger = this.context.audioContext.createChannelMerger(2);
+    }
+
+    // Disconnect mono graph
+    this.disconnectAll();
+
+    // Connect stereo ping-pong graph
+    this.wetDryMixer.connectInput(this.audioNode);
+
+    // Input -> DelayLeft
+    this.audioNode.connect(this.delayLeft);
+
+    // DelayLeft -> Output to left channel
+    this.delayLeft.connect(this.merger!, 0, 0); // Left to channel 0
+
+    // DelayLeft -> FeedbackRight -> DelayRight (ping-pong to right)
+    this.delayLeft.connect(this.feedbackRight!);
+    this.feedbackRight!.connect(this.delayRight!);
+
+    // DelayRight -> Output to right channel
+    this.delayRight!.connect(this.merger!, 0, 1); // Right to channel 1
+
+    // DelayRight -> FeedbackLeft -> DelayLeft (ping-pong back to left)
+    this.delayRight!.connect(this.feedbackLeft!);
+    this.feedbackLeft!.connect(this.delayLeft);
+
+    // Merger -> WetDryMixer (wet)
+    this.merger!.connect(this.wetDryMixer.getWetInput());
+
+    this.outputNode = this.wetDryMixer.getOutput();
+
+    // Sync delay times and feedback gains
+    this.delayLeft.delayTime.value = this.delayNode.delayTime.value;
+    this.delayRight!.delayTime.value = this.delayNode.delayTime.value;
+    this.feedbackLeft!.gain.value = this.feedbackGain.gain.value;
+    this.feedbackRight!.gain.value = this.feedbackGain.gain.value;
+  }
+
+  private disconnectAll() {
+    try {
+      this.audioNode.disconnect();
+      this.delayNode.disconnect();
+      this.feedbackGain.disconnect();
+      if (this.delayLeft) this.delayLeft.disconnect();
+      if (this.delayRight) this.delayRight.disconnect();
+      if (this.feedbackLeft) this.feedbackLeft.disconnect();
+      if (this.feedbackRight) this.feedbackRight.disconnect();
+      if (this.merger) this.merger.disconnect();
+    } catch {
+      // Ignore disconnect errors
+    }
+  }
+
+  private registerCustomOutput() {
+    this.registerAudioOutput({
+      name: "out",
+      getAudioNode: () => this.outputNode,
+    });
+  }
+
+  // ============================================================================
+  // SetterHooks
+  // ============================================================================
+
+  onAfterSetTime = (_value: number) => {
+    if (this.props.sync) return;
+
+    this.updateDelayTime();
+  };
+
+  onAfterSetTimeMode = (value: DelayTimeMode) => {
+    // Clamp time if it exceeds the new mode's maximum
+    const maxTime = value === DelayTimeMode.short ? 2000 : 5000;
+    if (this.props.time > maxTime) {
+      this.props = { time: maxTime };
+    }
+  };
+
+  onAfterSetSync = (_value: boolean) => {
+    this.updateDelayTime();
+  };
+
+  onAfterSetDivision = (_value: Division) => {
+    if (this.props.sync) {
+      this.updateDelayTime();
+    }
+  };
+
+  onAfterSetFeedback = (value: number) => {
+    // Cap at 0.95 to prevent runaway feedback
+    const cappedValue = Math.min(value, 0.95);
+    this.feedbackGain.gain.value = cappedValue;
+    if (this.feedbackLeft) this.feedbackLeft.gain.value = cappedValue;
+    if (this.feedbackRight) this.feedbackRight.gain.value = cappedValue;
+  };
+
+  onAfterSetMix = (value: number) => {
+    this.wetDryMixer.setMix(value);
+  };
+
+  onAfterSetStereo = (value: boolean) => {
+    if (value) {
+      this.switchToStereo();
+    } else {
+      this.connectMonoGraph();
+    }
+  };
+}

package/src/modules/Distortion.ts

@@ -0,0 +1,182 @@
+import { Context } from "@blibliki/utils";
+import { GainNode } from "@blibliki/utils/web-audio-api";
+import { ModulePropSchema } from "@/core";
+import { IModuleConstructor, Module, SetterHooks } from "@/core/module/Module";
+import { IPolyModuleConstructor, PolyModule } from "@/core/module/PolyModule";
+import { WetDryMixer } from "@/utils";
+import { ICreateModule, ModuleType } from ".";
+
+export type IDistortionProps = {
+  drive: number; // 0-10 (controls distortion amount)
+  tone: number; // 200-20000 Hz (lowpass filter cutoff)
+  mix: number; // 0-1 (dry/wet blend)
+};
+
+export type IDistortion = Module<ModuleType.Distortion>;
+
+export const distortionPropSchema: ModulePropSchema<IDistortionProps> = {
+  drive: {
+    kind: "number",
+    min: 0,
+    max: 10,
+    step: 0.1,
+    label: "Drive",
+  },
+  tone: {
+    kind: "number",
+    min: 200,
+    max: 20000,
+    step: 1,
+    exp: 3,
+    label: "Tone",
+  },
+  mix: {
+    kind: "number",
+    min: 0,
+    max: 1,
+    step: 0.01,
+    label: "Mix",
+  },
+};
+
+const DEFAULT_PROPS: IDistortionProps = {
+  drive: 2.0, // Moderate distortion
+  tone: 8000, // Mid-bright tone
+  mix: 1.0, // 100% wet (full effect)
+};
+
+export class MonoDistortion
+  extends Module<ModuleType.Distortion>
+  implements
+    Pick<
+      SetterHooks<IDistortionProps>,
+      "onAfterSetDrive" | "onAfterSetTone" | "onAfterSetMix"
+    >
+{
+  declare audioNode: GainNode; // Input node (inherited from Module)
+  private outputNode: GainNode; // Final output from mixer
+  private inputGain: GainNode; // Drive stage (pre-distortion gain)
+  private waveshaper: WaveShaperNode; // Tanh distortion
+  private filter: BiquadFilterNode; // Post-distortion lowpass filter
+  private wetDryMixer: WetDryMixer; // Wet/dry blending
+
+  constructor(engineId: string, params: ICreateModule<ModuleType.Distortion>) {
+    const props = { ...DEFAULT_PROPS, ...params.props };
+
+    const audioNodeConstructor = (context: Context) =>
+      new GainNode(context.audioContext, { gain: 1 });
+
+    super(engineId, {
+      ...params,
+      audioNodeConstructor,
+      props,
+    });
+
+    // Create audio nodes
+    const audioContext = this.context.audioContext;
+
+    this.inputGain = audioContext.createGain();
+    this.waveshaper = audioContext.createWaveShaper();
+    this.filter = audioContext.createBiquadFilter();
+    this.wetDryMixer = new WetDryMixer(this.context);
+
+    // Configure filter
+    this.filter.type = "lowpass";
+    this.filter.Q.value = 0.707; // Butterworth response (no resonance peak)
+
+    // Connect audio graph
+    // Dry path: Input -> WetDryMixer
+    this.wetDryMixer.connectInput(this.audioNode);
+
+    // Wet path: Input -> InputGain -> WaveShaper -> Filter -> WetDryMixer
+    this.audioNode.connect(this.inputGain);
+    this.inputGain.connect(this.waveshaper);
+    this.waveshaper.connect(this.filter);
+    this.filter.connect(this.wetDryMixer.getWetInput());
+
+    // Output from mixer
+    this.outputNode = this.wetDryMixer.getOutput();
+
+    // Apply initial parameters
+    this.updateInputGain(props.drive);
+    this.updateDistortionCurve(props.drive);
+    this.filter.frequency.value = props.tone;
+    this.wetDryMixer.setMix(props.mix);
+
+    // Register IOs
+    this.registerDefaultIOs("in");
+    this.registerCustomOutput();
+  }
+
+  private registerCustomOutput() {
+    this.registerAudioOutput({
+      name: "out",
+      getAudioNode: () => this.outputNode,
+    });
+  }
+
+  private generateDistortionCurve(drive: number): Float32Array | null {
+    const samples = 65536; // High resolution for smooth distortion
+    const buffer = new ArrayBuffer(samples * Float32Array.BYTES_PER_ELEMENT);
+    const curve: Float32Array = new Float32Array(buffer) as Float32Array;
+
+    for (let i = 0; i < samples; i++) {
+      // Map sample index to input range [-1, 1]
+      const x = (i * 2) / samples - 1;
+
+      // Apply tanh waveshaping with drive scaling
+      // Higher drive values push more of the signal into saturation
+      const driven = x * drive;
+      curve[i] = Math.tanh(driven);
+    }
+
+    return curve;
+  }
+
+  private updateDistortionCurve(drive: number): void {
+    // @ts-expect-error - TypeScript strict mode issue with Float32Array<ArrayBufferLike> vs Float32Array<ArrayBuffer>
+    this.waveshaper.curve = this.generateDistortionCurve(drive);
+  }
+
+  private updateInputGain(drive: number): void {
+    // Exponential scaling: each increment doubles the gain
+    // drive=0 -> 1x, drive=1 -> 2x, drive=2 -> 4x, ..., drive=10 -> 1024x
+    this.inputGain.gain.value = Math.pow(2, drive);
+  }
+
+  onAfterSetDrive: SetterHooks<IDistortionProps>["onAfterSetDrive"] = (
+    value,
+  ) => {
+    this.updateInputGain(value);
+    this.updateDistortionCurve(value);
+  };
+
+  onAfterSetTone: SetterHooks<IDistortionProps>["onAfterSetTone"] = (value) => {
+    this.filter.frequency.value = value;
+  };
+
+  onAfterSetMix: SetterHooks<IDistortionProps>["onAfterSetMix"] = (value) => {
+    this.wetDryMixer.setMix(value);
+  };
+}
+
+export default class PolyDistortion extends PolyModule<ModuleType.Distortion> {
+  constructor(
+    engineId: string,
+    params: IPolyModuleConstructor<ModuleType.Distortion>,
+  ) {
+    const props = { ...DEFAULT_PROPS, ...params.props };
+    const monoModuleConstructor = (
+      engineId: string,
+      params: IModuleConstructor<ModuleType.Distortion>,
+    ) => Module.create(MonoDistortion, engineId, params);
+
+    super(engineId, {
+      ...params,
+      props,
+      monoModuleConstructor,
+    });
+
+    this.registerDefaultIOs();
+  }
+}