elektron-lfo 1.0.0 → 1.0.2

package/dist/engine/fade.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 declare function calculateFadeMultiplier(fadeValue: number, fadeProgress: number): number;
+/**
+ * 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 declare function calculateFadeCycles(fadeValue: number): number;
+/**
+ * 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 declare function updateFade(config: LFOConfig, state: LFOState, cycleTimeMs: number, deltaMs: number): {
+    fadeProgress: number;
+    fadeMultiplier: number;
+};
+/**
+ * Reset fade state (called on trigger for modes that reset fade)
+ */
+export declare function resetFade(config: LFOConfig): {
+    fadeProgress: number;
+    fadeMultiplier: number;
+};
+/**
+ * Check if fade should reset on trigger for a given mode
+ */
+export declare function shouldResetFadeOnTrigger(mode: TriggerMode): boolean;
+/**
+ * Apply fade multiplier to output value
+ */
+export declare function applyFade(rawOutput: number, fadeMultiplier: number): number;

package/dist/engine/index.d.ts

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

package/dist/engine/lfo.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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';
+export declare class LFO {
+    private config;
+    private state;
+    private bpm;
+    private lastUpdateTime;
+    constructor(config?: Partial<LFOConfig>, bpm?: number);
+    /**
+     * 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;
+    /**
+     * Trigger the LFO
+     */
+    trigger(): void;
+    /**
+     * Get current state
+     */
+    getState(): LFOState;
+    /**
+     * Get current configuration
+     */
+    getConfig(): LFOConfig;
+    /**
+     * Update configuration
+     */
+    setConfig(config: Partial<LFOConfig>): void;
+    /**
+     * Set BPM
+     */
+    setBpm(bpm: number): void;
+    /**
+     * Get current BPM
+     */
+    getBpm(): number;
+    /**
+     * Get timing information
+     */
+    getTimingInfo(): TimingInfo;
+    /**
+     * Reset the LFO to initial state
+     */
+    reset(): void;
+    /**
+     * Check if the LFO is running
+     */
+    isRunning(): boolean;
+    /**
+     * Get the current output value
+     */
+    getOutput(): number;
+    /**
+     * Get the current phase (0-1)
+     */
+    getPhase(): number;
+    /**
+     * Start the LFO (for ONE/HLF modes that are stopped)
+     */
+    start(): void;
+    /**
+     * Stop the LFO
+     */
+    stop(): void;
+}

package/dist/engine/timing.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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 declare function calculateProduct(config: LFOConfig): number;
+/**
+ * Calculate cycle time in milliseconds
+ *
+ * Formula: cycle_time_ms = (60000 / BPM) × 4 × (128 / product)
+ */
+export declare function calculateCycleTimeMs(config: LFOConfig, bpm: number): number;
+/**
+ * Calculate LFO frequency in Hz
+ *
+ * Frequency is simply 1 / cycleTime in seconds
+ * frequency_hz = 1000 / cycleTimeMs
+ */
+export declare function calculateFrequencyHz(config: LFOConfig, bpm: number): number;
+/**
+ * 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 declare function calculatePhaseIncrement(config: LFOConfig, bpm: number): number;
+/**
+ * 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 declare function calculateCyclesPerBar(config: LFOConfig): number;
+/**
+ * Convert product to musical note value string
+ */
+export declare function calculateNoteValue(product: number): string;
+/**
+ * Calculate complete timing information
+ */
+export declare function calculateTimingInfo(config: LFOConfig, bpm: number): TimingInfo;
+/**
+ * Format cycle time for display
+ */
+export declare function formatCycleTime(cycleTimeMs: number): string;
+/**
+ * Format frequency for display
+ */
+export declare function formatFrequency(frequencyHz: number): string;

package/dist/engine/triggers.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 declare function handleTrigger(config: LFOConfig, state: LFOState, currentRawOutput: number): LFOState;
+/**
+ * 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 declare function checkModeStop(config: LFOConfig, state: LFOState, previousPhase: number, currentPhase: number): {
+    shouldStop: boolean;
+    cycleCompleted: boolean;
+};
+/**
+ * Check if a trigger mode requires a trigger to start
+ */
+export declare function requiresTriggerToStart(mode: TriggerMode): boolean;
+/**
+ * Check if a trigger mode resets phase on trigger
+ */
+export declare function resetsPhaseOnTrigger(mode: TriggerMode): boolean;
+/**
+ * Check if a trigger mode resets fade on trigger
+ */
+export declare function resetsFadeOnTrigger(mode: TriggerMode): boolean;

package/dist/engine/types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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 declare const DEFAULT_CONFIG: LFOConfig;
+/** Create initial LFO state */
+export declare function createInitialState(config: LFOConfig): LFOState;
+/** Clamp a value to a range */
+export declare function clamp(value: number, min: number, max: number): number;
+/** Valid multiplier values for validation */
+export declare const VALID_MULTIPLIERS: readonly Multiplier[];
+/** Check if a number is a valid multiplier */
+export declare function isValidMultiplier(value: number): value is Multiplier;

package/dist/engine/waveforms.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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 declare function generateTriangle(phase: number): number;
+/**
+ * Sine waveform - Bipolar
+ * Standard sine wave starting at 0
+ */
+export declare function generateSine(phase: number): number;
+/**
+ * Square waveform - Bipolar
+ * +1 for first half, -1 for second half
+ */
+export declare function generateSquare(phase: number): number;
+/**
+ * Sawtooth waveform - Bipolar
+ * Linear rise from -1 to +1
+ */
+export declare function generateSawtooth(phase: number): number;
+/**
+ * Exponential waveform - Unipolar (0 to +1)
+ * Accelerating curve from 0 to 1
+ */
+export declare function generateExponential(phase: number): number;
+/**
+ * Ramp waveform - Unipolar (0 to +1)
+ * Linear fall from +1 to 0
+ */
+export declare function generateRamp(phase: number): number;
+/**
+ * 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 declare function generateRandom(phase: number, state: LFOState): {
+    value: number;
+    newRandomValue: number;
+    newRandomStep: number;
+};
+/**
+ * Generate waveform output for a given phase and waveform type
+ */
+export declare function generateWaveform(waveform: Waveform, phase: number, state: LFOState): {
+    value: number;
+    newRandomValue?: number;
+    newRandomStep?: number;
+};
+/**
+ * Check if a waveform is unipolar (0 to +1) vs bipolar (-1 to +1)
+ */
+export declare function isUnipolar(waveform: Waveform): boolean;
+/**
+ * Get the range of a waveform
+ */
+export declare function getWaveformRange(waveform: Waveform): {
+    min: number;
+    max: number;
+};

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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();
+ * ```
+ */
+export * from './engine';

package/dist/index.js

@@ -0,0 +1,543 @@
+// src/engine/types.ts
+var DEFAULT_CONFIG = {
+  waveform: "TRI",
+  speed: 16,
+  multiplier: 8,
+  useFixedBPM: false,
+  startPhase: 0,
+  mode: "FRE",
+  depth: 63,
+  fade: 0
+};
+function createInitialState(config) {
+  const startPhaseNormalized = config.startPhase / 128;
+  return {
+    phase: startPhaseNormalized,
+    output: 0,
+    rawOutput: 0,
+    isRunning: true,
+    fadeMultiplier: config.fade < 0 ? 0 : 1,
+    fadeProgress: 0,
+    randomValue: Math.random() * 2 - 1,
+    previousPhase: startPhaseNormalized,
+    heldOutput: 0,
+    startPhaseNormalized,
+    cycleCount: 0,
+    triggerCount: 0,
+    hasTriggered: false,
+    randomStep: 0
+  };
+}
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(max, value));
+}
+var VALID_MULTIPLIERS = [
+  1,
+  2,
+  4,
+  8,
+  16,
+  32,
+  64,
+  128,
+  256,
+  512,
+  1024,
+  2048
+];
+function isValidMultiplier(value) {
+  return VALID_MULTIPLIERS.includes(value);
+}
+
+// src/engine/waveforms.ts
+function generateTriangle(phase) {
+  if (phase < 0.25) {
+    return phase * 4;
+  }
+  if (phase < 0.75) {
+    return 1 - (phase - 0.25) * 4;
+  }
+  return -1 + (phase - 0.75) * 4;
+}
+function generateSine(phase) {
+  return Math.sin(phase * 2 * Math.PI);
+}
+function generateSquare(phase) {
+  return phase < 0.5 ? 1 : -1;
+}
+function generateSawtooth(phase) {
+  return phase * 2 - 1;
+}
+function generateExponential(phase) {
+  const k = 4;
+  return (Math.exp(phase * k) - 1) / (Math.exp(k) - 1);
+}
+function generateRamp(phase) {
+  return 1 - phase;
+}
+function generateRandom(phase, state) {
+  const stepsPerCycle = 16;
+  const currentStep = Math.floor(phase * stepsPerCycle);
+  if (currentStep !== state.randomStep) {
+    const newRandomValue = Math.random() * 2 - 1;
+    return {
+      value: newRandomValue,
+      newRandomValue,
+      newRandomStep: currentStep
+    };
+  }
+  return {
+    value: state.randomValue,
+    newRandomValue: state.randomValue,
+    newRandomStep: state.randomStep
+  };
+}
+function generateWaveform(waveform, phase, state) {
+  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: {
+      const _exhaustive = waveform;
+      throw new Error(`Unknown waveform: ${_exhaustive}`);
+    }
+  }
+}
+function isUnipolar(waveform) {
+  return waveform === "EXP" || waveform === "RMP";
+}
+function getWaveformRange(waveform) {
+  if (isUnipolar(waveform)) {
+    return { min: 0, max: 1 };
+  }
+  return { min: -1, max: 1 };
+}
+
+// src/engine/timing.ts
+function calculateProduct(config) {
+  return Math.abs(config.speed) * config.multiplier;
+}
+function calculateCycleTimeMs(config, bpm) {
+  const effectiveBpm = config.useFixedBPM ? 120 : bpm;
+  const product = calculateProduct(config);
+  if (product === 0) {
+    return Infinity;
+  }
+  return 60000 / effectiveBpm * 4 * (128 / product);
+}
+function calculateFrequencyHz(config, bpm) {
+  const cycleTimeMs = calculateCycleTimeMs(config, bpm);
+  if (cycleTimeMs === Infinity || cycleTimeMs === 0) {
+    return 0;
+  }
+  return 1000 / cycleTimeMs;
+}
+function calculatePhaseIncrement(config, bpm) {
+  const cycleTimeMs = calculateCycleTimeMs(config, bpm);
+  if (cycleTimeMs === Infinity || cycleTimeMs === 0) {
+    return 0;
+  }
+  const direction = config.speed >= 0 ? 1 : -1;
+  return direction / cycleTimeMs;
+}
+function calculateCyclesPerBar(config) {
+  const product = calculateProduct(config);
+  if (product === 0)
+    return 0;
+  return product / 128;
+}
+function calculateNoteValue(product) {
+  if (product === 0)
+    return "∞";
+  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";
+  const bars = 128 / product;
+  if (bars === Math.floor(bars)) {
+    return `${bars} bars`;
+  }
+  return `${bars.toFixed(1)} bars`;
+}
+function calculateTimingInfo(config, bpm) {
+  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
+  };
+}
+function formatCycleTime(cycleTimeMs) {
+  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`;
+}
+function formatFrequency(frequencyHz) {
+  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`;
+}
+
+// src/engine/triggers.ts
+function handleTrigger(config, state, currentRawOutput) {
+  const newState = { ...state };
+  newState.triggerCount++;
+  switch (config.mode) {
+    case "FRE":
+      break;
+    case "TRG":
+      newState.phase = newState.startPhaseNormalized;
+      newState.previousPhase = newState.startPhaseNormalized;
+      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 "HLD":
+      newState.heldOutput = currentRawOutput;
+      newState.fadeProgress = 0;
+      newState.fadeMultiplier = config.fade < 0 ? 0 : 1;
+      break;
+    case "ONE":
+      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":
+      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;
+}
+function checkModeStop(config, state, previousPhase, currentPhase) {
+  if (config.mode !== "ONE" && config.mode !== "HLF") {
+    return { shouldStop: false, cycleCompleted: false };
+  }
+  if (!state.hasTriggered) {
+    return { shouldStop: true, cycleCompleted: false };
+  }
+  const startPhase = state.startPhaseNormalized;
+  const isForward = config.speed >= 0;
+  if (config.mode === "ONE") {
+    if (state.cycleCount >= 1) {
+      return { shouldStop: true, cycleCompleted: true };
+    }
+  } else if (config.mode === "HLF") {
+    const halfPhase = (startPhase + 0.5) % 1;
+    if (isForward) {
+      if (startPhase < 0.5) {
+        if (previousPhase < halfPhase && currentPhase >= halfPhase) {
+          return { shouldStop: true, cycleCompleted: true };
+        }
+      } else {
+        if (state.cycleCount >= 1 || previousPhase < halfPhase && currentPhase >= halfPhase) {
+          return { shouldStop: true, cycleCompleted: true };
+        }
+      }
+    } else {
+      const halfPhaseBackward = (startPhase - 0.5 + 1) % 1;
+      if (startPhase >= 0.5) {
+        if (previousPhase > halfPhaseBackward && currentPhase <= halfPhaseBackward) {
+          return { shouldStop: true, cycleCompleted: true };
+        }
+      } else {
+        if (state.cycleCount >= 1 || previousPhase > halfPhaseBackward && currentPhase <= halfPhaseBackward) {
+          return { shouldStop: true, cycleCompleted: true };
+        }
+      }
+    }
+  }
+  return { shouldStop: false, cycleCompleted: false };
+}
+function requiresTriggerToStart(mode) {
+  return mode === "ONE" || mode === "HLF";
+}
+function resetsPhaseOnTrigger(mode) {
+  return mode === "TRG" || mode === "ONE" || mode === "HLF";
+}
+function resetsFadeOnTrigger(mode) {
+  return mode !== "FRE";
+}
+
+// src/engine/fade.ts
+function calculateFadeMultiplier(fadeValue, fadeProgress) {
+  if (fadeValue === 0) {
+    return 1;
+  }
+  const progress = Math.max(0, Math.min(1, fadeProgress));
+  if (fadeValue < 0) {
+    return progress;
+  } else {
+    return 1 - progress;
+  }
+}
+function calculateFadeCycles(fadeValue) {
+  if (fadeValue === 0)
+    return 0;
+  return Math.abs(fadeValue) / 64;
+}
+function updateFade(config, state, cycleTimeMs, deltaMs) {
+  if (config.fade === 0 || config.mode === "FRE") {
+    return {
+      fadeProgress: 1,
+      fadeMultiplier: 1
+    };
+  }
+  const fadeCycles = calculateFadeCycles(config.fade);
+  const fadeDurationMs = fadeCycles * cycleTimeMs;
+  if (fadeDurationMs === 0 || fadeDurationMs === Infinity) {
+    return {
+      fadeProgress: 1,
+      fadeMultiplier: config.fade < 0 ? 0 : 1
+    };
+  }
+  const progressIncrement = deltaMs / fadeDurationMs;
+  const newProgress = Math.min(1, state.fadeProgress + progressIncrement);
+  return {
+    fadeProgress: newProgress,
+    fadeMultiplier: calculateFadeMultiplier(config.fade, newProgress)
+  };
+}
+function resetFade(config) {
+  if (config.fade === 0) {
+    return { fadeProgress: 1, fadeMultiplier: 1 };
+  }
+  if (config.fade < 0) {
+    return { fadeProgress: 0, fadeMultiplier: 0 };
+  } else {
+    return { fadeProgress: 0, fadeMultiplier: 1 };
+  }
+}
+function shouldResetFadeOnTrigger(mode) {
+  return mode !== "FRE";
+}
+function applyFade(rawOutput, fadeMultiplier) {
+  return rawOutput * fadeMultiplier;
+}
+
+// src/engine/lfo.ts
+class LFO {
+  config;
+  state;
+  bpm;
+  lastUpdateTime;
+  constructor(config = {}, bpm = 120) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.bpm = bpm;
+    this.state = createInitialState(this.config);
+    this.lastUpdateTime = 0;
+    if (this.config.mode === "FRE") {
+      this.state.fadeMultiplier = 1;
+      this.state.fadeProgress = 1;
+    }
+    if (this.config.mode === "ONE" || this.config.mode === "HLF") {
+      this.state.isRunning = false;
+    }
+  }
+  update(currentTimeMs) {
+    const deltaMs = this.lastUpdateTime === 0 ? 0 : currentTimeMs - this.lastUpdateTime;
+    this.lastUpdateTime = currentTimeMs;
+    const shouldUpdatePhase = this.state.isRunning && deltaMs > 0;
+    const cycleTimeMs = calculateCycleTimeMs(this.config, this.bpm);
+    const phaseIncrement = calculatePhaseIncrement(this.config, this.bpm);
+    if (shouldUpdatePhase) {
+      const previousPhase = this.state.phase;
+      let newPhase = this.state.phase + phaseIncrement * deltaMs;
+      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++;
+      }
+      const stopCheck = checkModeStop(this.config, this.state, previousPhase, newPhase);
+      if (stopCheck.shouldStop) {
+        this.state.isRunning = false;
+        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;
+    }
+    const waveformResult = generateWaveform(this.config.waveform, this.state.phase, this.state);
+    if (waveformResult.newRandomValue !== undefined) {
+      this.state.randomValue = waveformResult.newRandomValue;
+    }
+    if (waveformResult.newRandomStep !== undefined) {
+      this.state.randomStep = waveformResult.newRandomStep;
+    }
+    this.state.rawOutput = waveformResult.value;
+    if (shouldUpdatePhase) {
+      const fadeResult = updateFade(this.config, this.state, cycleTimeMs, deltaMs);
+      this.state.fadeProgress = fadeResult.fadeProgress;
+      this.state.fadeMultiplier = fadeResult.fadeMultiplier;
+    }
+    let effectiveRawOutput = this.state.rawOutput;
+    if (this.config.mode === "HLD" && this.state.triggerCount > 0) {
+      effectiveRawOutput = this.state.heldOutput;
+    }
+    const depthScale = this.config.depth / 63;
+    let scaledOutput = effectiveRawOutput * depthScale;
+    scaledOutput *= this.state.fadeMultiplier;
+    if (isUnipolar(this.config.waveform)) {}
+    this.state.output = scaledOutput;
+    return { ...this.state };
+  }
+  trigger() {
+    this.state = handleTrigger(this.config, this.state, this.state.rawOutput);
+  }
+  getState() {
+    return { ...this.state };
+  }
+  getConfig() {
+    return { ...this.config };
+  }
+  setConfig(config) {
+    const previousMode = this.config.mode;
+    this.config = { ...this.config, ...config };
+    if (config.startPhase !== undefined) {
+      this.state.startPhaseNormalized = config.startPhase / 128;
+    }
+    if ((config.mode === "ONE" || config.mode === "HLF") && previousMode !== config.mode) {
+      this.state.isRunning = false;
+      this.state.hasTriggered = false;
+    }
+  }
+  setBpm(bpm) {
+    this.bpm = clamp(bpm, 1, 999);
+  }
+  getBpm() {
+    return this.bpm;
+  }
+  getTimingInfo() {
+    return calculateTimingInfo(this.config, this.bpm);
+  }
+  reset() {
+    this.state = createInitialState(this.config);
+    if (this.config.mode === "ONE" || this.config.mode === "HLF") {
+      this.state.isRunning = false;
+    }
+  }
+  isRunning() {
+    return this.state.isRunning;
+  }
+  getOutput() {
+    return this.state.output;
+  }
+  getPhase() {
+    return this.state.phase;
+  }
+  start() {
+    this.state.isRunning = true;
+    this.state.hasTriggered = true;
+  }
+  stop() {
+    this.state.isRunning = false;
+  }
+}
+export {
+  updateFade,
+  shouldResetFadeOnTrigger,
+  resetsPhaseOnTrigger,
+  resetsFadeOnTrigger,
+  resetFade,
+  requiresTriggerToStart,
+  isValidMultiplier,
+  isUnipolar,
+  handleTrigger,
+  getWaveformRange,
+  generateWaveform,
+  generateTriangle,
+  generateSquare,
+  generateSine,
+  generateSawtooth,
+  generateRandom,
+  generateRamp,
+  generateExponential,
+  formatFrequency,
+  formatCycleTime,
+  createInitialState,
+  clamp,
+  checkModeStop,
+  calculateTimingInfo,
+  calculateProduct,
+  calculatePhaseIncrement,
+  calculateNoteValue,
+  calculateFrequencyHz,
+  calculateFadeMultiplier,
+  calculateFadeCycles,
+  calculateCyclesPerBar,
+  calculateCycleTimeMs,
+  applyFade,
+  VALID_MULTIPLIERS,
+  LFO,
+  DEFAULT_CONFIG
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "elektron-lfo",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Elektron LFO engine simulator implementation with CLI visualization",
   "main": "dist/index.js",
   "module": "src/index.ts",

package/src/engine/triggers.ts

@@ -112,11 +112,23 @@ export function checkModeStop(
   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
+    // ONE mode: Stop after completing one full cycle back to startPhase
+    // For non-zero startPhase, we need to:
+    // 1. Wait for phase to wrap (cycleCount >= 1)
+    // 2. Then continue until we reach/pass the startPhase again
     if (state.cycleCount >= 1) {
-      return { shouldStop: true, cycleCompleted: true };
+      if (isForward) {
+        // Forward: stop when current phase reaches or passes startPhase after wrapping
+        // Handle the case where startPhase is 0 (stop immediately on wrap)
+        if (startPhase === 0 || currentPhase >= startPhase) {
+          return { shouldStop: true, cycleCompleted: true };
+        }
+      } else {
+        // Backward: stop when current phase reaches or goes below startPhase after wrapping
+        if (startPhase === 0 || currentPhase <= startPhase) {
+          return { shouldStop: true, cycleCompleted: true };
+        }
+      }
     }
   } else if (config.mode === 'HLF') {
     // HLF mode: Stop after half cycle (0.5 phase distance from start)

package/tests/triggers.test.ts

@@ -240,6 +240,64 @@ describe('checkModeStop - ONE mode', () => {
     const result = checkModeStop(config, state, 0.05, 0.95);
     expect(result.shouldStop).toBe(true);
   });
+
+  test('with non-zero startPhase, does NOT stop immediately after wrap - must reach startPhase', () => {
+    // Bug fix: With startPhase 53 (~0.414), the LFO should:
+    // 1. Start at 0.414
+    // 2. Run to 1.0, wrap to 0.0 (cycleCount = 1)
+    // 3. Continue from 0.0 to 0.414 (startPhase)
+    // 4. THEN stop
+    const config = createConfig({ mode: 'ONE', speed: 16, startPhase: 53 });
+    const startPhaseNormalized = 53 / 128; // ~0.414
+
+    // After wrap, phase is 0.1, which is BEFORE startPhase (0.414)
+    // Should NOT stop yet
+    const stateAfterWrap = createState({
+      hasTriggered: true,
+      startPhaseNormalized,
+      cycleCount: 1,
+    });
+    const resultBeforeStart = checkModeStop(config, stateAfterWrap, 0.05, 0.1);
+    expect(resultBeforeStart.shouldStop).toBe(false);
+
+    // Phase reaches 0.3, still before startPhase - should NOT stop
+    const resultStillBefore = checkModeStop(config, stateAfterWrap, 0.2, 0.3);
+    expect(resultStillBefore.shouldStop).toBe(false);
+
+    // Phase crosses startPhase (0.414) - NOW should stop
+    const resultAtStart = checkModeStop(config, stateAfterWrap, 0.4, 0.45);
+    expect(resultAtStart.shouldStop).toBe(true);
+    expect(resultAtStart.cycleCompleted).toBe(true);
+  });
+
+  test('with non-zero startPhase (backward), continues after wrap until reaching startPhase', () => {
+    // Backward direction with startPhase 53 (~0.414):
+    // 1. Start at 0.414
+    // 2. Run backward to 0.0, wrap to 1.0 (cycleCount = 1)
+    // 3. Continue from 1.0 down to 0.414
+    // 4. THEN stop
+    const config = createConfig({ mode: 'ONE', speed: -16, startPhase: 53 });
+    const startPhaseNormalized = 53 / 128; // ~0.414
+
+    // After wrap going backward, phase is 0.9, which is ABOVE startPhase (0.414)
+    // Should NOT stop yet
+    const stateAfterWrap = createState({
+      hasTriggered: true,
+      startPhaseNormalized,
+      cycleCount: 1,
+    });
+    const resultAfterWrap = checkModeStop(config, stateAfterWrap, 0.95, 0.9);
+    expect(resultAfterWrap.shouldStop).toBe(false);
+
+    // Phase reaches 0.5, still above startPhase - should NOT stop
+    const resultStillAbove = checkModeStop(config, stateAfterWrap, 0.6, 0.5);
+    expect(resultStillAbove.shouldStop).toBe(false);
+
+    // Phase crosses startPhase (0.414) going down - NOW should stop
+    const resultAtStart = checkModeStop(config, stateAfterWrap, 0.45, 0.4);
+    expect(resultAtStart.shouldStop).toBe(true);
+    expect(resultAtStart.cycleCompleted).toBe(true);
+  });
 });
 
 describe('checkModeStop - HLF mode', () => {