elektron-lfo 1.0.0

package/src/engine/triggers.ts

@@ -0,0 +1,179 @@
+/**
+ * Trigger mode handling for Elektron Digitakt II LFO
+ *
+ * Trigger Modes:
+ * - FRE (Free): LFO runs continuously, triggers ignored
+ * - TRG (Trigger): Restarts LFO phase and fade on trigger
+ * - HLD (Hold): Captures and holds output on trigger, LFO continues in background
+ * - ONE (One-shot): Runs one complete cycle then stops, can be retriggered
+ * - HLF (Half): Runs half cycle then stops, can be retriggered
+ */
+
+import type { LFOConfig, LFOState, TriggerMode } from './types';
+
+/**
+ * Handle a trigger event based on the current mode
+ * Returns updated state after trigger processing
+ */
+export function handleTrigger(
+  config: LFOConfig,
+  state: LFOState,
+  currentRawOutput: number
+): LFOState {
+  const newState = { ...state };
+  newState.triggerCount++;
+
+  switch (config.mode) {
+    case 'FRE':
+      // Free running - triggers are ignored
+      // LFO continues without interruption
+      break;
+
+    case 'TRG':
+      // Trigger mode - reset phase and fade
+      newState.phase = newState.startPhaseNormalized;
+      newState.previousPhase = newState.startPhaseNormalized;
+      newState.fadeProgress = 0;
+      newState.fadeMultiplier = config.fade < 0 ? 0 : 1;
+      newState.cycleCount = 0;
+      // Generate new random value on trigger for RND waveform
+      if (config.waveform === 'RND') {
+        newState.randomValue = Math.random() * 2 - 1;
+        newState.randomStep = Math.floor(newState.phase * 16);
+      }
+      break;
+
+    case 'HLD':
+      // Hold mode - capture current output, LFO continues in background
+      newState.heldOutput = currentRawOutput;
+      // Note: Phase continues running, only output is held
+      // Fade resets on trigger
+      newState.fadeProgress = 0;
+      newState.fadeMultiplier = config.fade < 0 ? 0 : 1;
+      break;
+
+    case 'ONE':
+      // One-shot mode - reset and run one complete cycle
+      newState.phase = newState.startPhaseNormalized;
+      newState.previousPhase = newState.startPhaseNormalized;
+      newState.isRunning = true;
+      newState.hasTriggered = true;
+      newState.fadeProgress = 0;
+      newState.fadeMultiplier = config.fade < 0 ? 0 : 1;
+      newState.cycleCount = 0;
+      if (config.waveform === 'RND') {
+        newState.randomValue = Math.random() * 2 - 1;
+        newState.randomStep = Math.floor(newState.phase * 16);
+      }
+      break;
+
+    case 'HLF':
+      // Half mode - reset and run half cycle
+      newState.phase = newState.startPhaseNormalized;
+      newState.previousPhase = newState.startPhaseNormalized;
+      newState.isRunning = true;
+      newState.hasTriggered = true;
+      newState.fadeProgress = 0;
+      newState.fadeMultiplier = config.fade < 0 ? 0 : 1;
+      newState.cycleCount = 0;
+      if (config.waveform === 'RND') {
+        newState.randomValue = Math.random() * 2 - 1;
+        newState.randomStep = Math.floor(newState.phase * 16);
+      }
+      break;
+  }
+
+  return newState;
+}
+
+/**
+ * Check if the LFO should stop based on mode and phase
+ *
+ * For ONE mode: Stop when phase wraps and returns to start phase (one complete cycle)
+ * For HLF mode: Stop when phase reaches 0.5 past start phase (half cycle)
+ */
+export function checkModeStop(
+  config: LFOConfig,
+  state: LFOState,
+  previousPhase: number,
+  currentPhase: number
+): { shouldStop: boolean; cycleCompleted: boolean } {
+  // Only ONE and HLF modes can stop
+  if (config.mode !== 'ONE' && config.mode !== 'HLF') {
+    return { shouldStop: false, cycleCompleted: false };
+  }
+
+  // Need to have been triggered to run
+  if (!state.hasTriggered) {
+    return { shouldStop: true, cycleCompleted: false };
+  }
+
+  const startPhase = state.startPhaseNormalized;
+  const isForward = config.speed >= 0;
+
+  if (config.mode === 'ONE') {
+    // ONE mode: Stop after completing one full cycle
+    // We detect this by checking if cycleCount has incremented (phase wrapped)
+    // and we've returned to or passed the start phase
+    if (state.cycleCount >= 1) {
+      return { shouldStop: true, cycleCompleted: true };
+    }
+  } else if (config.mode === 'HLF') {
+    // HLF mode: Stop after half cycle (0.5 phase distance from start)
+    const halfPhase = (startPhase + 0.5) % 1;
+
+    if (isForward) {
+      // Check if we crossed the half-point
+      if (startPhase < 0.5) {
+        // Half point is greater than start (no wrap needed)
+        if (previousPhase < halfPhase && currentPhase >= halfPhase) {
+          return { shouldStop: true, cycleCompleted: true };
+        }
+      } else {
+        // Half point wraps around through 0 (halfPhase < startPhase)
+        // We need to cross 1->0 boundary first, then reach halfPhase
+        if (state.cycleCount >= 1 || (previousPhase < halfPhase && currentPhase >= halfPhase)) {
+          return { shouldStop: true, cycleCompleted: true };
+        }
+      }
+    } else {
+      // Backward direction: halfPhase is 0.5 BEHIND start
+      const halfPhaseBackward = (startPhase - 0.5 + 1) % 1;
+      if (startPhase >= 0.5) {
+        // Half point is less than start (no wrap needed)
+        if (previousPhase > halfPhaseBackward && currentPhase <= halfPhaseBackward) {
+          return { shouldStop: true, cycleCompleted: true };
+        }
+      } else {
+        // Half point wraps around through 1
+        if (state.cycleCount >= 1 || (previousPhase > halfPhaseBackward && currentPhase <= halfPhaseBackward)) {
+          return { shouldStop: true, cycleCompleted: true };
+        }
+      }
+    }
+  }
+
+  return { shouldStop: false, cycleCompleted: false };
+}
+
+/**
+ * Check if a trigger mode requires a trigger to start
+ */
+export function requiresTriggerToStart(mode: TriggerMode): boolean {
+  return mode === 'ONE' || mode === 'HLF';
+}
+
+/**
+ * Check if a trigger mode resets phase on trigger
+ */
+export function resetsPhaseOnTrigger(mode: TriggerMode): boolean {
+  return mode === 'TRG' || mode === 'ONE' || mode === 'HLF';
+}
+
+/**
+ * Check if a trigger mode resets fade on trigger
+ */
+export function resetsFadeOnTrigger(mode: TriggerMode): boolean {
+  // FRE mode doesn't reset fade (fade doesn't work in FRE mode per spec)
+  return mode !== 'FRE';
+}

package/src/engine/types.ts

@@ -0,0 +1,126 @@
+/**
+ * Elektron Digitakt II LFO Engine Types
+ */
+
+/** Available LFO waveform types */
+export type Waveform = 'TRI' | 'SIN' | 'SQR' | 'SAW' | 'EXP' | 'RMP' | 'RND';
+
+/** LFO trigger/behavior modes */
+export type TriggerMode = 'FRE' | 'TRG' | 'HLD' | 'ONE' | 'HLF';
+
+/** Available tempo multiplier values */
+export type Multiplier = 1 | 2 | 4 | 8 | 16 | 32 | 64 | 128 | 256 | 512 | 1024 | 2048;
+
+/** LFO configuration parameters */
+export interface LFOConfig {
+  /** Waveform type */
+  waveform: Waveform;
+  /** Speed parameter: -64.00 to +63.00 */
+  speed: number;
+  /** Tempo multiplier */
+  multiplier: Multiplier;
+  /** Use fixed 120 BPM instead of project BPM */
+  useFixedBPM: boolean;
+  /** Start phase: 0 to 127 (maps to 0-360 degrees) */
+  startPhase: number;
+  /** Trigger/behavior mode */
+  mode: TriggerMode;
+  /** Modulation depth: -64.00 to +63.00 */
+  depth: number;
+  /** Fade amount: -64 to +63 (negative = fade in, positive = fade out) */
+  fade: number;
+}
+
+/** LFO runtime state */
+export interface LFOState {
+  /** Current phase position: 0.0 to 1.0 */
+  phase: number;
+  /** Final output value after depth and fade processing */
+  output: number;
+  /** Raw waveform output before depth/fade processing */
+  rawOutput: number;
+  /** Whether the LFO is currently running */
+  isRunning: boolean;
+  /** Current fade envelope multiplier: 0.0 to 1.0 */
+  fadeMultiplier: number;
+  /** Fade envelope progress: 0.0 to 1.0 */
+  fadeProgress: number;
+  /** Current random value for RND waveform */
+  randomValue: number;
+  /** Previous phase value for detecting step changes */
+  previousPhase: number;
+  /** Held output value for HLD mode */
+  heldOutput: number;
+  /** Normalized start phase: 0.0 to 1.0 */
+  startPhaseNormalized: number;
+  /** Number of complete cycles */
+  cycleCount: number;
+  /** Number of triggers received */
+  triggerCount: number;
+  /** Whether the LFO has been triggered at least once (for ONE/HLF modes) */
+  hasTriggered: boolean;
+  /** Current random step (0-15 for 16 steps per cycle) */
+  randomStep: number;
+}
+
+/** Timing information for an LFO configuration */
+export interface TimingInfo {
+  /** Duration of one complete cycle in milliseconds */
+  cycleTimeMs: number;
+  /** Musical note value representation (e.g., "1/4", "1 bar", "4 bars") */
+  noteValue: string;
+  /** LFO frequency in Hz */
+  frequencyHz: number;
+  /** Number of LFO cycles per bar */
+  cyclesPerBar: number;
+  /** Product of |SPD| × MULT */
+  product: number;
+}
+
+/** Default LFO configuration */
+export const DEFAULT_CONFIG: LFOConfig = {
+  waveform: 'TRI',
+  speed: 16,
+  multiplier: 8,
+  useFixedBPM: false,
+  startPhase: 0,
+  mode: 'FRE',
+  depth: 63,
+  fade: 0,
+};
+
+/** Create initial LFO state */
+export function createInitialState(config: LFOConfig): LFOState {
+  const startPhaseNormalized = config.startPhase / 128;
+  return {
+    phase: startPhaseNormalized,
+    output: 0,
+    rawOutput: 0,
+    isRunning: true,
+    fadeMultiplier: config.fade < 0 ? 0 : 1, // Fade in starts at 0, fade out starts at 1
+    fadeProgress: 0,
+    randomValue: Math.random() * 2 - 1, // Initial random value: -1 to +1
+    previousPhase: startPhaseNormalized,
+    heldOutput: 0,
+    startPhaseNormalized,
+    cycleCount: 0,
+    triggerCount: 0,
+    hasTriggered: false,
+    randomStep: 0,
+  };
+}
+
+/** Clamp a value to a range */
+export function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}
+
+/** Valid multiplier values for validation */
+export const VALID_MULTIPLIERS: readonly Multiplier[] = [
+  1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048,
+] as const;
+
+/** Check if a number is a valid multiplier */
+export function isValidMultiplier(value: number): value is Multiplier {
+  return VALID_MULTIPLIERS.includes(value as Multiplier);
+}

package/src/engine/waveforms.ts

@@ -0,0 +1,152 @@
+/**
+ * Waveform generators for Elektron Digitakt II LFO
+ *
+ * Waveform types:
+ * - Bipolar (-1 to +1): TRI, SIN, SQR, SAW, RND
+ * - Unipolar (0 to +1): EXP, RMP
+ */
+
+import type { Waveform, LFOState } from './types';
+
+/**
+ * Triangle waveform - Bipolar
+ * Starts at 0, peaks at +1 at phase 0.25, troughs at -1 at phase 0.75
+ */
+export function generateTriangle(phase: number): number {
+  if (phase < 0.25) {
+    return phase * 4; // 0 to +1
+  }
+  if (phase < 0.75) {
+    return 1 - (phase - 0.25) * 4; // +1 to -1
+  }
+  return -1 + (phase - 0.75) * 4; // -1 to 0
+}
+
+/**
+ * Sine waveform - Bipolar
+ * Standard sine wave starting at 0
+ */
+export function generateSine(phase: number): number {
+  return Math.sin(phase * 2 * Math.PI);
+}
+
+/**
+ * Square waveform - Bipolar
+ * +1 for first half, -1 for second half
+ */
+export function generateSquare(phase: number): number {
+  return phase < 0.5 ? 1 : -1;
+}
+
+/**
+ * Sawtooth waveform - Bipolar
+ * Linear rise from -1 to +1
+ */
+export function generateSawtooth(phase: number): number {
+  return phase * 2 - 1;
+}
+
+/**
+ * Exponential waveform - Unipolar (0 to +1)
+ * Accelerating curve from 0 to 1
+ */
+export function generateExponential(phase: number): number {
+  const k = 4; // Steepness factor
+  return (Math.exp(phase * k) - 1) / (Math.exp(k) - 1);
+}
+
+/**
+ * Ramp waveform - Unipolar (0 to +1)
+ * Linear fall from +1 to 0
+ */
+export function generateRamp(phase: number): number {
+  return 1 - phase;
+}
+
+/**
+ * Random waveform - Bipolar (-1 to +1)
+ * Sample-and-hold with 16 steps per cycle (16x frequency)
+ *
+ * Returns the current random value and potentially a new random value
+ * if a step boundary was crossed.
+ */
+export function generateRandom(
+  phase: number,
+  state: LFOState
+): { value: number; newRandomValue: number; newRandomStep: number } {
+  // 16 steps per cycle
+  const stepsPerCycle = 16;
+  const currentStep = Math.floor(phase * stepsPerCycle);
+
+  // Check if we crossed a step boundary
+  if (currentStep !== state.randomStep) {
+    // Generate new random value between -1 and +1
+    const newRandomValue = Math.random() * 2 - 1;
+    return {
+      value: newRandomValue,
+      newRandomValue,
+      newRandomStep: currentStep,
+    };
+  }
+
+  // No step change, return current value
+  return {
+    value: state.randomValue,
+    newRandomValue: state.randomValue,
+    newRandomStep: state.randomStep,
+  };
+}
+
+/**
+ * Generate waveform output for a given phase and waveform type
+ */
+export function generateWaveform(
+  waveform: Waveform,
+  phase: number,
+  state: LFOState
+): { value: number; newRandomValue?: number; newRandomStep?: number } {
+  switch (waveform) {
+    case 'TRI':
+      return { value: generateTriangle(phase) };
+    case 'SIN':
+      return { value: generateSine(phase) };
+    case 'SQR':
+      return { value: generateSquare(phase) };
+    case 'SAW':
+      return { value: generateSawtooth(phase) };
+    case 'EXP':
+      return { value: generateExponential(phase) };
+    case 'RMP':
+      return { value: generateRamp(phase) };
+    case 'RND': {
+      const result = generateRandom(phase, state);
+      return {
+        value: result.value,
+        newRandomValue: result.newRandomValue,
+        newRandomStep: result.newRandomStep,
+      };
+    }
+    default: {
+      // Exhaustive check
+      const _exhaustive: never = waveform;
+      throw new Error(`Unknown waveform: ${_exhaustive}`);
+    }
+  }
+}
+
+/**
+ * Check if a waveform is unipolar (0 to +1) vs bipolar (-1 to +1)
+ */
+export function isUnipolar(waveform: Waveform): boolean {
+  return waveform === 'EXP' || waveform === 'RMP';
+}
+
+/**
+ * Get the range of a waveform
+ */
+export function getWaveformRange(waveform: Waveform): { min: number; max: number } {
+  if (isUnipolar(waveform)) {
+    return { min: 0, max: 1 };
+  }
+  return { min: -1, max: 1 };
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Elektron LFO
+ *
+ * A TypeScript implementation of the Elektron Digitakt II LFO engine
+ * with real-time terminal visualization.
+ *
+ * @example
+ * ```typescript
+ * import { LFO } from 'elektron-lfo';
+ *
+ * const lfo = new LFO({
+ *   waveform: 'SIN',
+ *   speed: 16,
+ *   multiplier: 8,
+ *   mode: 'TRG',
+ *   depth: 63,
+ * }, 120);
+ *
+ * // Update at 60fps
+ * setInterval(() => {
+ *   const state = lfo.update(performance.now());
+ *   console.log('Output:', state.output);
+ * }, 1000 / 60);
+ *
+ * // Trigger the LFO
+ * lfo.trigger();
+ * ```
+ */
+
+// Re-export everything from engine
+export * from './engine';