@blibliki/engine 0.5.2 → 0.9.0

package/src/core/module/VoiceScheduler.ts

@@ -12,10 +12,18 @@ export const voiceSchedulerPropSchema: ModulePropSchema<IVoiceSchedulerProps> =
   {};
 const DEFAULT_PROPS = {};
 
+interface OccupationRange {
+  noteName: string;
+  startTime: ContextTime;
+  endTime: ContextTime; // Can be Infinity if noteOff hasn't been triggered yet
+}
+
 class Voice extends Module<ModuleType.VoiceScheduler> {
   declare audioNode: undefined;
   activeNote: string | null = null;
   triggeredAt: ContextTime = 0;
+  // Track all current and future occupation ranges
+  private occupationRanges: OccupationRange[] = [];
 
   constructor(
     engineId: string,
@@ -29,21 +37,88 @@ class Voice extends Module<ModuleType.VoiceScheduler> {
     });
   }
 
+  /**
+   * Check if this voice is occupied at a given time
+   */
+  isOccupiedAt(time: ContextTime): boolean {
+    return this.occupationRanges.some(
+      (range) => time >= range.startTime && time < range.endTime,
+    );
+  }
+
+  /**
+   * Get the earliest end time of all occupation ranges at or after the given time
+   * Returns Infinity if the voice has infinite occupation
+   */
+  getEarliestEndTimeAfter(time: ContextTime): ContextTime {
+    const relevantRanges = this.occupationRanges.filter(
+      (range) => range.endTime > time,
+    );
+
+    if (relevantRanges.length === 0) return -Infinity;
+
+    return Math.min(...relevantRanges.map((range) => range.endTime));
+  }
+
+  /**
+   * Clean up past occupation ranges that are no longer needed
+   */
+  private cleanupPastRanges(currentTime: ContextTime) {
+    this.occupationRanges = this.occupationRanges.filter(
+      (range) => range.endTime > currentTime || range.endTime === Infinity,
+    );
+  }
+
+  /**
+   * Clear all occupation ranges
+   * Useful when resetting or stopping playback
+   */
+  clearOccupationRanges() {
+    this.occupationRanges = [];
+  }
+
   midiTriggered = (midiEvent: MidiEvent) => {
     const { triggeredAt, note, type } = midiEvent;
 
     if (!note) return;
     const noteName = note.fullName;
 
+    this.cleanupPastRanges(triggeredAt);
+
+    // Determine if this is a future event (more than 10ms ahead)
+    const currentTime = this.context.audioContext.currentTime;
+    const isFutureEvent = triggeredAt - currentTime > 0.01;
+
     switch (type) {
-      case MidiEventType.noteOn:
+      case MidiEventType.noteOn: {
         this.activeNote = noteName;
         this.triggeredAt = triggeredAt;
 
+        // Only add occupation ranges for future events
+        // Real-time events use activeNote field only
+        if (isFutureEvent) {
+          this.occupationRanges.push({
+            noteName,
+            startTime: triggeredAt,
+            endTime: Infinity,
+          });
+        }
+
         break;
-      case MidiEventType.noteOff:
+      }
+      case MidiEventType.noteOff: {
         this.activeNote = null;
+
+        // Always try to close any open occupation range for this note
+        // This handles both scheduled future events and cleanup when stopping
+        const range = this.occupationRanges.find(
+          (r) => r.noteName === noteName && r.endTime === Infinity,
+        );
+        if (range) {
+          range.endTime = triggeredAt;
+        }
         break;
+      }
       default:
         throw Error("This type is not a note");
     }
@@ -79,7 +154,7 @@ export default class VoiceScheduler extends PolyModule<ModuleType.VoiceScheduler
 
     switch (midiEvent.type) {
       case MidiEventType.noteOn:
-        voice = this.findFreeVoice();
+        voice = this.findFreeVoice(midiEvent.triggeredAt);
 
         break;
       case MidiEventType.noteOff:
@@ -87,6 +162,9 @@ export default class VoiceScheduler extends PolyModule<ModuleType.VoiceScheduler
           (v) => v.activeNote === midiEvent.note!.fullName,
         );
         break;
+      case MidiEventType.cc:
+        this.midiOutput.onMidiEvent(midiEvent);
+        return;
       default:
         throw Error("This type is not a note");
     }
@@ -98,23 +176,85 @@ export default class VoiceScheduler extends PolyModule<ModuleType.VoiceScheduler
     this.midiOutput.onMidiEvent(midiEvent);
   };
 
-  private findFreeVoice(): Voice {
-    let voice = this.audioModules.find((v) => !v.activeNote);
+  private findFreeVoice(targetTime: ContextTime): Voice {
+    const currentTime = this.context.audioContext.currentTime;
+    // Consider it real-time if within 10ms of current time
+    const isRealTime = Math.abs(targetTime - currentTime) < 0.01;
+
+    let voice: Voice | undefined;
 
-    // If no available voice, get the one with the lowest triggeredAt
+    if (isRealTime) {
+      // For real-time events, use simple activeNote check (original behavior)
+      // This avoids issues with residual occupation ranges
+      voice = this.audioModules.find((v) => !v.activeNote);
+    } else {
+      // For future events, use occupation range system
+      voice = this.audioModules.find((v) => !v.isOccupiedAt(targetTime));
+    }
+
+    // If no available voice, steal one based on the strategy:
+    // Primary: voice with earliest end time at or after target time
+    // Secondary: among voices with similar end times, choose oldest (earliest triggeredAt)
     if (!voice) {
-      const sorted = this.audioModules.sort((a, b) => {
-        return a.triggeredAt - b.triggeredAt;
-      });
-      voice = sorted[0];
+      if (isRealTime) {
+        // For real-time, use original voice stealing strategy
+        const sorted = this.audioModules.sort((a, b) => {
+          return a.triggeredAt - b.triggeredAt;
+        });
+        voice = sorted[0];
+      } else {
+        // For future events, use occupation-aware strategy
+        const sorted = this.audioModules.sort((a, b) => {
+          const aEndTime = a.getEarliestEndTimeAfter(targetTime);
+          const bEndTime = b.getEarliestEndTimeAfter(targetTime);
+
+          // Primary sort by end time
+          if (aEndTime !== bEndTime) {
+            return aEndTime - bEndTime;
+          }
+
+          // Secondary sort by triggered time (oldest first)
+          return a.triggeredAt - b.triggeredAt;
+        });
+        voice = sorted[0];
+      }
+
       if (!voice) {
         throw new Error("No voices available in voice scheduler");
       }
+
+      // Important: Send a noteOff event for the stolen voice's current note
+      // This ensures the envelope releases properly before the new note starts
+      if (voice.activeNote) {
+        const stolenNoteName = voice.activeNote;
+        // Always release the stolen note at the current time for immediate audio release
+        const releaseTime = this.context.audioContext.currentTime;
+        const noteOffEvent = MidiEvent.fromNote(
+          stolenNoteName,
+          false, // noteOn = false means noteOff
+          releaseTime,
+        );
+        noteOffEvent.voiceNo = voice.voiceNo;
+
+        // Trigger the note off on this voice before reusing it
+        voice.midiTriggered(noteOffEvent);
+        this.midiOutput.onMidiEvent(noteOffEvent);
+      }
     }
 
     return voice;
   }
 
+  /**
+   * Clear all occupation ranges for all voices
+   * Call this when stopping playback or resetting the scheduler
+   */
+  clearAllOccupationRanges() {
+    this.audioModules.forEach((voice) => {
+      voice.clearOccupationRanges();
+    });
+  }
+
   private registerInputs() {
     this.registerMidiInput({
       name: "midi in",

package/src/core/module/index.ts

@@ -3,9 +3,14 @@ import { IModuleSerialize } from "./Module";
 import { IPolyModuleSerialize } from "./PolyModule";
 
 export { Module } from "./Module";
-export type { IModule, IModuleSerialize, SetterHooks } from "./Module";
+export type {
+  IModule,
+  IModuleSerialize,
+  SetterHooks,
+  StateSetterHooks,
+} from "./Module";
 export type { IPolyModule, IPolyModuleSerialize } from "./PolyModule";
 
-export type IAnyModuleSerialize =
-  | IModuleSerialize<ModuleType>
-  | IPolyModuleSerialize<ModuleType>;
+export type IAnyModuleSerialize<MT extends ModuleType = ModuleType> =
+  | IModuleSerialize<MT>
+  | IPolyModuleSerialize<MT>;

package/src/index.ts

@@ -17,11 +17,19 @@ export type {
   BooleanProp,
   ArrayProp,
   INote,
+  SetterHooks,
+  StateSetterHooks,
+} from "./core";
+export {
+  MidiDevice,
+  MidiInputDevice,
+  MidiOutputDevice,
+  MidiPortState,
+  Note,
 } from "./core";
-export { MidiDevice, MidiPortState, Note } from "./core";
 
 export { TransportState } from "@blibliki/transport";
-export type { TimeSignature, Position } from "@blibliki/transport";
+export type { BPM, TimeSignature, Position } from "@blibliki/transport";
 
 export { Context } from "@blibliki/utils";
 
@@ -30,18 +38,34 @@ export {
   moduleSchemas,
   OscillatorWave,
   MidiMappingMode,
+  LFOWaveform,
+  Resolution,
+  PlaybackMode,
+  stepPropSchema,
+  NoiseType,
+  DelayTimeMode,
 } from "./modules";
+export { default as StepSequencer } from "./modules/StepSequencer";
 export type {
   IOscillator,
   IGain,
   IMaster,
-  ISequence,
   IStepSequencerProps,
+  IStepSequencerState,
   IStepSequencer,
+  IStep,
+  IPage,
+  IPattern,
+  IStepNote,
+  IStepCC,
   ModuleTypeToPropsMapping,
+  ModuleTypeToStateMapping,
   ICreateModule,
   ModuleParams,
   IMidiMapper,
   IMidiMapperProps,
   MidiMapping,
+  ILFO,
+  ILFOProps,
+  INoise,
 } from "./modules";

package/src/modules/Chorus.ts

@@ -0,0 +1,222 @@
+import { Context } from "@blibliki/utils";
+import { GainNode } from "@blibliki/utils/web-audio-api";
+import { ModulePropSchema } from "@/core";
+import { IModule, Module, SetterHooks } from "@/core/module/Module";
+import { WetDryMixer } from "@/utils";
+import { ICreateModule, ModuleType } from ".";
+
+export type IChorusProps = {
+  rate: number; // 0.1-10 Hz (LFO frequency)
+  depth: number; // 0-1 (modulation depth)
+  mix: number; // 0-1 (dry/wet blend)
+  feedback: number; // 0-0.95 (feedback amount)
+};
+
+export type IChorus = IModule<ModuleType.Chorus>;
+
+export const chorusPropSchema: ModulePropSchema<IChorusProps> = {
+  rate: {
+    kind: "number",
+    min: 0.1,
+    max: 10,
+    step: 0.1,
+    exp: 2, // Exponential scaling for better low-frequency control
+    label: "Rate",
+  },
+  depth: {
+    kind: "number",
+    min: 0,
+    max: 1,
+    step: 0.01,
+    label: "Depth",
+  },
+  mix: {
+    kind: "number",
+    min: 0,
+    max: 1,
+    step: 0.01,
+    label: "Mix",
+  },
+  feedback: {
+    kind: "number",
+    min: 0,
+    max: 0.95,
+    step: 0.01,
+    label: "Feedback",
+  },
+};
+
+const DEFAULT_PROPS: IChorusProps = {
+  rate: 0.5, // 0.5 Hz (slow modulation)
+  depth: 0.5, // Medium depth
+  mix: 0.5, // 50/50 blend
+  feedback: 0.2, // Subtle feedback
+};
+
+export default class Chorus
+  extends Module<ModuleType.Chorus>
+  implements
+    Pick<
+      SetterHooks<IChorusProps>,
+      | "onAfterSetRate"
+      | "onAfterSetDepth"
+      | "onAfterSetMix"
+      | "onAfterSetFeedback"
+    >
+{
+  declare audioNode: GainNode; // Input node (inherited from Module)
+  private outputNode: GainNode; // Final output from mixer
+  private feedbackGain: GainNode; // Feedback amount
+  private delayLeft: DelayNode; // First chorus voice
+  private delayRight: DelayNode; // Second chorus voice
+  private lfoLeft: OscillatorNode; // LFO for left voice
+  private lfoRight: OscillatorNode; // LFO for right voice
+  private depthLeft: GainNode; // Modulation depth for left
+  private depthRight: GainNode; // Modulation depth for right
+  private merger: ChannelMergerNode; // Combine to stereo
+  private wetDryMixer: WetDryMixer; // Wet/dry blending
+  private rateModGain: GainNode; // External rate modulation input
+
+  constructor(engineId: string, params: ICreateModule<ModuleType.Chorus>) {
+    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.feedbackGain = audioContext.createGain();
+    this.delayLeft = audioContext.createDelay(0.1); // Max 0.1s delay
+    this.delayRight = audioContext.createDelay(0.1);
+    this.lfoLeft = audioContext.createOscillator();
+    this.lfoRight = audioContext.createOscillator();
+    this.depthLeft = audioContext.createGain();
+    this.depthRight = audioContext.createGain();
+    this.merger = audioContext.createChannelMerger(2);
+    this.wetDryMixer = new WetDryMixer(this.context);
+    this.rateModGain = audioContext.createGain();
+
+    // Configure LFOs
+    this.lfoLeft.type = "sine";
+    this.lfoRight.type = "sine";
+
+    // Connect audio graph
+    // Dry path
+    this.wetDryMixer.connectInput(this.audioNode);
+
+    // Rate modulation input connects to both LFO frequencies
+    this.rateModGain.connect(this.lfoLeft.frequency);
+    this.rateModGain.connect(this.lfoRight.frequency);
+
+    // LFO modulation to delay times
+    this.lfoLeft.connect(this.depthLeft);
+    this.depthLeft.connect(this.delayLeft.delayTime);
+    this.lfoRight.connect(this.depthRight);
+    this.depthRight.connect(this.delayRight.delayTime);
+
+    // Wet path with feedback
+    this.audioNode.connect(this.feedbackGain);
+    this.feedbackGain.connect(this.delayLeft);
+    this.feedbackGain.connect(this.delayRight);
+
+    // Delays to merger (stereo)
+    this.delayLeft.connect(this.merger, 0, 0); // Left channel
+    this.delayRight.connect(this.merger, 0, 1); // Right channel
+
+    // Feedback loop
+    this.merger.connect(this.feedbackGain);
+
+    // Merger to wet path
+    this.merger.connect(this.wetDryMixer.getWetInput());
+
+    // Output
+    this.outputNode = this.wetDryMixer.getOutput();
+
+    // Apply initial parameters
+    // Base delay time: 20ms typical for chorus
+    this.delayLeft.delayTime.value = 0.02;
+    this.delayRight.delayTime.value = 0.02;
+
+    // Set LFO frequency (rate)
+    this.lfoLeft.frequency.value = props.rate;
+    this.lfoRight.frequency.value = props.rate;
+
+    // Depth: convert (0-1) to seconds (0-0.01s = 0-10ms modulation)
+    const depthInSeconds = props.depth * 0.01;
+    this.depthLeft.gain.value = depthInSeconds;
+    this.depthRight.gain.value = depthInSeconds;
+
+    // Feedback
+    this.feedbackGain.gain.value = props.feedback;
+
+    // Mix
+    this.wetDryMixer.setMix(props.mix);
+
+    // Start oscillators with phase offset for stereo width
+    const now = this.context.audioContext.currentTime;
+    this.lfoLeft.start(now);
+    // Start right LFO with 180° phase offset (half period)
+    const phaseOffset = 1 / (2 * props.rate);
+    this.lfoRight.start(now + phaseOffset);
+
+    // Register IOs
+    this.registerDefaultIOs("in");
+    this.registerAdditionalInputs();
+    this.registerCustomOutput();
+  }
+
+  private registerAdditionalInputs() {
+    // External rate modulation input
+    this.registerAudioInput({
+      name: "rate",
+      getAudioNode: () => this.rateModGain,
+    });
+  }
+
+  private registerCustomOutput() {
+    this.registerAudioOutput({
+      name: "out",
+      getAudioNode: () => this.outputNode,
+    });
+  }
+
+  onAfterSetRate: SetterHooks<IChorusProps>["onAfterSetRate"] = (value) => {
+    this.lfoLeft.frequency.value = value;
+    this.lfoRight.frequency.value = value;
+    // Note: Phase offset maintained by start time, not adjustable at runtime
+  };
+
+  onAfterSetDepth: SetterHooks<IChorusProps>["onAfterSetDepth"] = (value) => {
+    const depthInSeconds = value * 0.01; // Convert to 0-10ms range
+    this.depthLeft.gain.value = depthInSeconds;
+    this.depthRight.gain.value = depthInSeconds;
+  };
+
+  onAfterSetMix: SetterHooks<IChorusProps>["onAfterSetMix"] = (value) => {
+    this.wetDryMixer.setMix(value);
+  };
+
+  onAfterSetFeedback: SetterHooks<IChorusProps>["onAfterSetFeedback"] = (
+    value,
+  ) => {
+    const cappedValue = Math.min(value, 0.95); // Prevent runaway feedback
+    this.feedbackGain.gain.value = cappedValue;
+  };
+
+  dispose() {
+    try {
+      this.lfoLeft.stop();
+      this.lfoRight.stop();
+    } catch {
+      // Ignore errors if already stopped
+    }
+    super.dispose();
+  }
+}

package/src/modules/Constant.ts

@@ -72,7 +72,7 @@ export default class Constant
     this.start(triggeredAt);
   };
 
-  triggerRelease = () => {
-    // Do nothing
+  triggerRelease = (_: Note, triggeredAt: ContextTime) => {
+    this.stop(triggeredAt);
   };
 }