elektron-lfo 1.0.0

package/src/engine/fade.ts

@@ -0,0 +1,137 @@
+/**
+ * Fade envelope system for Elektron Digitakt II LFO
+ *
+ * Fade behavior:
+ * - FADE = 0: No fade, full modulation immediately
+ * - FADE < 0 (negative): Fade IN - starts at 0, increases to full over |FADE| cycles
+ * - FADE > 0 (positive): Fade OUT - starts at full, decreases to 0 over FADE cycles
+ *
+ * Important notes from research:
+ * - Fade does NOT work in FRE mode (requires trigger to initiate)
+ * - Fade resets on trigger for TRG, ONE, HLF, and HLD modes
+ * - Fade timing is relative to LFO cycles, not absolute time
+ */
+
+import type { LFOConfig, LFOState, TriggerMode } from './types';
+
+/**
+ * Calculate the fade multiplier based on fade progress
+ *
+ * @param fadeValue - The FADE parameter (-64 to +63)
+ * @param fadeProgress - Progress through the fade (0.0 to 1.0)
+ * @returns The fade multiplier (0.0 to 1.0)
+ */
+export function calculateFadeMultiplier(
+  fadeValue: number,
+  fadeProgress: number
+): number {
+  if (fadeValue === 0) {
+    // No fade - always full modulation
+    return 1;
+  }
+
+  // Clamp progress to 0-1 range
+  const progress = Math.max(0, Math.min(1, fadeProgress));
+
+  if (fadeValue < 0) {
+    // Fade IN: starts at 0, increases to 1
+    // Linear interpolation from 0 to 1
+    return progress;
+  } else {
+    // Fade OUT: starts at 1, decreases to 0
+    // Linear interpolation from 1 to 0
+    return 1 - progress;
+  }
+}
+
+/**
+ * Calculate fade cycles - how many LFO cycles for complete fade
+ *
+ * The FADE parameter (-64 to +63) maps to fade duration in cycles:
+ * - |FADE| / 64 gives the number of cycles (approximately)
+ * - At |FADE| = 64, fade takes 1 cycle
+ * - At |FADE| = 32, fade takes 0.5 cycles
+ * - At |FADE| = 1, fade takes ~1/64 of a cycle
+ */
+export function calculateFadeCycles(fadeValue: number): number {
+  if (fadeValue === 0) return 0;
+  // Map |FADE| to cycles: |FADE| / 64 cycles
+  // Maximum fade (64) = 1 cycle, minimum (1) = 1/64 cycle
+  return Math.abs(fadeValue) / 64;
+}
+
+/**
+ * Update fade progress based on elapsed time
+ *
+ * @param config - LFO configuration
+ * @param state - Current LFO state
+ * @param cycleTimeMs - Duration of one LFO cycle in milliseconds
+ * @param deltaMs - Time elapsed since last update
+ * @returns Updated fade progress and multiplier
+ */
+export function updateFade(
+  config: LFOConfig,
+  state: LFOState,
+  cycleTimeMs: number,
+  deltaMs: number
+): { fadeProgress: number; fadeMultiplier: number } {
+  // No fade or FRE mode - fade doesn't work in FRE mode
+  if (config.fade === 0 || config.mode === 'FRE') {
+    return {
+      fadeProgress: 1,
+      fadeMultiplier: 1,
+    };
+  }
+
+  // Calculate how many cycles the fade takes
+  const fadeCycles = calculateFadeCycles(config.fade);
+  const fadeDurationMs = fadeCycles * cycleTimeMs;
+
+  if (fadeDurationMs === 0 || fadeDurationMs === Infinity) {
+    return {
+      fadeProgress: 1,
+      fadeMultiplier: config.fade < 0 ? 0 : 1,
+    };
+  }
+
+  // Calculate progress increment
+  const progressIncrement = deltaMs / fadeDurationMs;
+  const newProgress = Math.min(1, state.fadeProgress + progressIncrement);
+
+  return {
+    fadeProgress: newProgress,
+    fadeMultiplier: calculateFadeMultiplier(config.fade, newProgress),
+  };
+}
+
+/**
+ * Reset fade state (called on trigger for modes that reset fade)
+ */
+export function resetFade(config: LFOConfig): { fadeProgress: number; fadeMultiplier: number } {
+  if (config.fade === 0) {
+    return { fadeProgress: 1, fadeMultiplier: 1 };
+  }
+
+  if (config.fade < 0) {
+    // Fade IN: start at 0
+    return { fadeProgress: 0, fadeMultiplier: 0 };
+  } else {
+    // Fade OUT: start at 1
+    return { fadeProgress: 0, fadeMultiplier: 1 };
+  }
+}
+
+/**
+ * Check if fade should reset on trigger for a given mode
+ */
+export function shouldResetFadeOnTrigger(mode: TriggerMode): boolean {
+  // FRE mode never resets fade (and fade doesn't work in FRE mode)
+  return mode !== 'FRE';
+}
+
+/**
+ * Apply fade multiplier to output value
+ */
+export function applyFade(rawOutput: number, fadeMultiplier: number): number {
+  return rawOutput * fadeMultiplier;
+}

package/src/engine/index.ts

@@ -0,0 +1,72 @@
+/**
+ * Elektron LFO Engine
+ *
+ * A TypeScript implementation of the Elektron Digitakt II LFO engine
+ */
+
+// Main LFO class
+export { LFO } from './lfo';
+
+// Types
+export type {
+  Waveform,
+  TriggerMode,
+  Multiplier,
+  LFOConfig,
+  LFOState,
+  TimingInfo,
+} from './types';
+
+export {
+  DEFAULT_CONFIG,
+  createInitialState,
+  clamp,
+  VALID_MULTIPLIERS,
+  isValidMultiplier,
+} from './types';
+
+// Waveform functions
+export {
+  generateTriangle,
+  generateSine,
+  generateSquare,
+  generateSawtooth,
+  generateExponential,
+  generateRamp,
+  generateRandom,
+  generateWaveform,
+  isUnipolar,
+  getWaveformRange,
+} from './waveforms';
+
+// Timing functions
+export {
+  calculateProduct,
+  calculateCycleTimeMs,
+  calculateFrequencyHz,
+  calculatePhaseIncrement,
+  calculateCyclesPerBar,
+  calculateNoteValue,
+  calculateTimingInfo,
+  formatCycleTime,
+  formatFrequency,
+} from './timing';
+
+// Trigger functions
+export {
+  handleTrigger,
+  checkModeStop,
+  requiresTriggerToStart,
+  resetsPhaseOnTrigger,
+  resetsFadeOnTrigger,
+} from './triggers';
+
+// Fade functions
+export {
+  calculateFadeMultiplier,
+  calculateFadeCycles,
+  updateFade,
+  resetFade,
+  shouldResetFadeOnTrigger,
+  applyFade,
+} from './fade';

package/src/engine/lfo.ts

@@ -0,0 +1,269 @@
+/**
+ * Main LFO class for Elektron Digitakt II LFO engine
+ *
+ * This class ties together all the components:
+ * - Waveform generation
+ * - Timing calculations
+ * - Trigger mode handling
+ * - Fade envelope
+ */
+
+import type { LFOConfig, LFOState, TimingInfo } from './types';
+import { DEFAULT_CONFIG, createInitialState, clamp } from './types';
+import { generateWaveform, isUnipolar } from './waveforms';
+import {
+  calculatePhaseIncrement,
+  calculateTimingInfo,
+  calculateCycleTimeMs,
+} from './timing';
+import { handleTrigger, checkModeStop } from './triggers';
+import { updateFade, resetFade } from './fade';
+
+export class LFO {
+  private config: LFOConfig;
+  private state: LFOState;
+  private bpm: number;
+  private lastUpdateTime: number;
+
+  constructor(config: Partial<LFOConfig> = {}, bpm: number = 120) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.bpm = bpm;
+    this.state = createInitialState(this.config);
+    this.lastUpdateTime = 0;
+
+    // For FRE mode, fade is always 1 (fade doesn't work in FRE mode)
+    if (this.config.mode === 'FRE') {
+      this.state.fadeMultiplier = 1;
+      this.state.fadeProgress = 1;
+    }
+
+    // For ONE/HLF modes, don't run until triggered
+    if (this.config.mode === 'ONE' || this.config.mode === 'HLF') {
+      this.state.isRunning = false;
+    }
+  }
+
+  /**
+   * Update the LFO state based on elapsed time
+   *
+   * @param currentTimeMs - Current time in milliseconds (e.g., performance.now())
+   * @returns The current LFO state
+   */
+  update(currentTimeMs: number): LFOState {
+    // Calculate delta time
+    const deltaMs = this.lastUpdateTime === 0 ? 0 : currentTimeMs - this.lastUpdateTime;
+    this.lastUpdateTime = currentTimeMs;
+
+    // Skip phase update if not running (but still generate output)
+    const shouldUpdatePhase = this.state.isRunning && deltaMs > 0;
+
+    // Calculate timing
+    const cycleTimeMs = calculateCycleTimeMs(this.config, this.bpm);
+    const phaseIncrement = calculatePhaseIncrement(this.config, this.bpm);
+
+    // Update phase if running
+    if (shouldUpdatePhase) {
+      const previousPhase = this.state.phase;
+      let newPhase = this.state.phase + phaseIncrement * deltaMs;
+
+      // Wrap phase to 0-1 range
+      if (newPhase >= 1) {
+        newPhase = newPhase % 1;
+        this.state.cycleCount++;
+      } else if (newPhase < 0) {
+        newPhase = 1 + (newPhase % 1);
+        if (newPhase === 1) newPhase = 0;
+        this.state.cycleCount++;
+      }
+
+      // Check for mode-based stopping (ONE/HLF)
+      const stopCheck = checkModeStop(
+        this.config,
+        this.state,
+        previousPhase,
+        newPhase
+      );
+
+      if (stopCheck.shouldStop) {
+        this.state.isRunning = false;
+        // Snap to stop position
+        if (this.config.mode === 'ONE') {
+          newPhase = this.state.startPhaseNormalized;
+        } else if (this.config.mode === 'HLF') {
+          newPhase = (this.state.startPhaseNormalized + 0.5) % 1;
+        }
+      }
+
+      this.state.previousPhase = previousPhase;
+      this.state.phase = newPhase;
+    }
+
+    // Generate waveform output
+    const waveformResult = generateWaveform(
+      this.config.waveform,
+      this.state.phase,
+      this.state
+    );
+
+    // Update random state if needed
+    if (waveformResult.newRandomValue !== undefined) {
+      this.state.randomValue = waveformResult.newRandomValue;
+    }
+    if (waveformResult.newRandomStep !== undefined) {
+      this.state.randomStep = waveformResult.newRandomStep;
+    }
+
+    this.state.rawOutput = waveformResult.value;
+
+    // Update fade (only if running and time has passed)
+    if (shouldUpdatePhase) {
+      const fadeResult = updateFade(
+        this.config,
+        this.state,
+        cycleTimeMs,
+        deltaMs
+      );
+      this.state.fadeProgress = fadeResult.fadeProgress;
+      this.state.fadeMultiplier = fadeResult.fadeMultiplier;
+    }
+
+    // Calculate final output
+    // For HLD mode, use held output
+    let effectiveRawOutput = this.state.rawOutput;
+    if (this.config.mode === 'HLD' && this.state.triggerCount > 0) {
+      effectiveRawOutput = this.state.heldOutput;
+    }
+
+    // Apply depth
+    // Depth scales the output: depth of 63 = 100%, depth of 0 = 0%
+    // Negative depth inverts the waveform
+    const depthScale = this.config.depth / 63;
+    let scaledOutput = effectiveRawOutput * depthScale;
+
+    // Apply fade
+    scaledOutput *= this.state.fadeMultiplier;
+
+    // For unipolar waveforms with negative depth, clamp to valid range
+    if (isUnipolar(this.config.waveform)) {
+      // Unipolar waveforms output 0 to 1
+      // With negative depth, they output 0 to -1
+      // The output range becomes -1 to +1 depending on depth sign
+    }
+
+    this.state.output = scaledOutput;
+
+    return { ...this.state };
+  }
+
+  /**
+   * Trigger the LFO
+   */
+  trigger(): void {
+    this.state = handleTrigger(this.config, this.state, this.state.rawOutput);
+  }
+
+  /**
+   * Get current state
+   */
+  getState(): LFOState {
+    return { ...this.state };
+  }
+
+  /**
+   * Get current configuration
+   */
+  getConfig(): LFOConfig {
+    return { ...this.config };
+  }
+
+  /**
+   * Update configuration
+   */
+  setConfig(config: Partial<LFOConfig>): void {
+    const previousMode = this.config.mode;
+    this.config = { ...this.config, ...config };
+
+    // Update start phase normalization if startPhase changed
+    if (config.startPhase !== undefined) {
+      this.state.startPhaseNormalized = config.startPhase / 128;
+    }
+
+    // If switching to ONE/HLF mode, stop until triggered
+    if (
+      (config.mode === 'ONE' || config.mode === 'HLF') &&
+      previousMode !== config.mode
+    ) {
+      this.state.isRunning = false;
+      this.state.hasTriggered = false;
+    }
+  }
+
+  /**
+   * Set BPM
+   */
+  setBpm(bpm: number): void {
+    this.bpm = clamp(bpm, 1, 999);
+  }
+
+  /**
+   * Get current BPM
+   */
+  getBpm(): number {
+    return this.bpm;
+  }
+
+  /**
+   * Get timing information
+   */
+  getTimingInfo(): TimingInfo {
+    return calculateTimingInfo(this.config, this.bpm);
+  }
+
+  /**
+   * Reset the LFO to initial state
+   */
+  reset(): void {
+    this.state = createInitialState(this.config);
+
+    // For ONE/HLF modes, don't run until triggered
+    if (this.config.mode === 'ONE' || this.config.mode === 'HLF') {
+      this.state.isRunning = false;
+    }
+  }
+
+  /**
+   * Check if the LFO is running
+   */
+  isRunning(): boolean {
+    return this.state.isRunning;
+  }
+
+  /**
+   * Get the current output value
+   */
+  getOutput(): number {
+    return this.state.output;
+  }
+
+  /**
+   * Get the current phase (0-1)
+   */
+  getPhase(): number {
+    return this.state.phase;
+  }
+
+  /**
+   * Start the LFO (for ONE/HLF modes that are stopped)
+   */
+  start(): void {
+    this.state.isRunning = true;
+    this.state.hasTriggered = true;
+  }
+
+  /**
+   * Stop the LFO
+   */
+  stop(): void {
+    this.state.isRunning = false;
+  }
+}

package/src/engine/timing.ts

@@ -0,0 +1,157 @@
+/**
+ * Timing calculations for Elektron Digitakt II LFO
+ *
+ * Core formulas from the spec:
+ * - phase_steps_per_bar = |SPD| × MULT
+ * - cycle_time_ms = (60000 / BPM) × 4 × (128 / (|SPD| × MULT))
+ * - frequency_hz = (BPM / 60) × (|SPD| × MULT / 128)
+ */
+
+import type { LFOConfig, TimingInfo } from './types';
+
+/**
+ * Calculate the product of |SPD| × MULT
+ */
+export function calculateProduct(config: LFOConfig): number {
+  return Math.abs(config.speed) * config.multiplier;
+}
+
+/**
+ * Calculate cycle time in milliseconds
+ *
+ * Formula: cycle_time_ms = (60000 / BPM) × 4 × (128 / product)
+ */
+export function calculateCycleTimeMs(config: LFOConfig, bpm: number): number {
+  const effectiveBpm = config.useFixedBPM ? 120 : bpm;
+  const product = calculateProduct(config);
+
+  if (product === 0) {
+    return Infinity; // Speed of 0 means infinite cycle time
+  }
+
+  return (60000 / effectiveBpm) * 4 * (128 / product);
+}
+
+/**
+ * Calculate LFO frequency in Hz
+ *
+ * Frequency is simply 1 / cycleTime in seconds
+ * frequency_hz = 1000 / cycleTimeMs
+ */
+export function calculateFrequencyHz(config: LFOConfig, bpm: number): number {
+  const cycleTimeMs = calculateCycleTimeMs(config, bpm);
+
+  if (cycleTimeMs === Infinity || cycleTimeMs === 0) {
+    return 0;
+  }
+
+  return 1000 / cycleTimeMs;
+}
+
+/**
+ * Calculate phase increment per millisecond
+ *
+ * Phase goes from 0 to 1 over one cycle
+ * Increment = 1 / cycle_time_ms (for positive speed)
+ * Increment = -1 / cycle_time_ms (for negative speed)
+ */
+export function calculatePhaseIncrement(config: LFOConfig, bpm: number): number {
+  const cycleTimeMs = calculateCycleTimeMs(config, bpm);
+
+  if (cycleTimeMs === Infinity || cycleTimeMs === 0) {
+    return 0;
+  }
+
+  // Negative speed runs phase backwards
+  const direction = config.speed >= 0 ? 1 : -1;
+  return direction / cycleTimeMs;
+}
+
+/**
+ * Calculate cycles per bar
+ *
+ * At product = 128, we get exactly 1 cycle per bar
+ * At product > 128, we get product/128 cycles per bar
+ * At product < 128, we get product/128 cycles per bar (fraction)
+ */
+export function calculateCyclesPerBar(config: LFOConfig): number {
+  const product = calculateProduct(config);
+  if (product === 0) return 0;
+  return product / 128;
+}
+
+/**
+ * Convert product to musical note value string
+ */
+export function calculateNoteValue(product: number): string {
+  if (product === 0) return '∞';
+
+  // Product to note value mapping
+  // 128 = 1 bar (whole note in 4/4)
+  // 256 = 1/2 bar (half note)
+  // 512 = 1/4 note
+  // 1024 = 1/8 note
+  // 2048 = 1/16 note
+
+  // For products > 128: faster than 1 bar
+  if (product >= 2048) return '1/16';
+  if (product >= 1024) return '1/8';
+  if (product >= 512) return '1/4';
+  if (product >= 256) return '1/2';
+  if (product >= 128) return '1 bar';
+
+  // For products < 128: slower than 1 bar
+  const bars = 128 / product;
+  if (bars === Math.floor(bars)) {
+    return `${bars} bars`;
+  }
+  return `${bars.toFixed(1)} bars`;
+}
+
+/**
+ * Calculate complete timing information
+ */
+export function calculateTimingInfo(config: LFOConfig, bpm: number): TimingInfo {
+  const product = calculateProduct(config);
+  const cycleTimeMs = calculateCycleTimeMs(config, bpm);
+  const frequencyHz = calculateFrequencyHz(config, bpm);
+  const cyclesPerBar = calculateCyclesPerBar(config);
+  const noteValue = calculateNoteValue(product);
+
+  return {
+    cycleTimeMs,
+    noteValue,
+    frequencyHz,
+    cyclesPerBar,
+    product,
+  };
+}
+
+/**
+ * Format cycle time for display
+ */
+export function formatCycleTime(cycleTimeMs: number): string {
+  if (cycleTimeMs === Infinity) return '∞';
+  if (cycleTimeMs >= 60000) {
+    const minutes = cycleTimeMs / 60000;
+    return `${minutes.toFixed(1)}min`;
+  }
+  if (cycleTimeMs >= 1000) {
+    return `${(cycleTimeMs / 1000).toFixed(2)}s`;
+  }
+  return `${cycleTimeMs.toFixed(1)}ms`;
+}
+
+/**
+ * Format frequency for display
+ */
+export function formatFrequency(frequencyHz: number): string {
+  if (frequencyHz === 0) return '0 Hz';
+  if (frequencyHz < 0.01) {
+    return `${(frequencyHz * 1000).toFixed(3)} mHz`;
+  }
+  if (frequencyHz < 1) {
+    return `${frequencyHz.toFixed(3)} Hz`;
+  }
+  return `${frequencyHz.toFixed(2)} Hz`;
+}