elektron-lfo 1.0.3 → 1.0.6

package/dist/cli/args.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Command-line argument parsing for Elektron LFO CLI
+ */
+import type { LFOConfig } from '../engine/types';
+export interface CLIArgs extends LFOConfig {
+    bpm: number;
+    help: boolean;
+}
+export declare function printHelp(): void;
+export declare function parseArgs(args: string[]): CLIArgs;

package/dist/cli/display.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Terminal display for Elektron LFO CLI
+ *
+ * Renders the LFO state with ASCII waveform visualization
+ */
+import type { LFOConfig, LFOState, TimingInfo } from '../engine/types';
+/**
+ * Render the full display
+ */
+export declare function render(config: LFOConfig, state: LFOState, timing: TimingInfo, bpm: number): string;

package/dist/cli/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env bun
+/**
+ * Elektron LFO CLI - Main Entry Point
+ *
+ * Real-time terminal visualization of the Digitakt II LFO engine
+ */
+export {};

package/dist/cli/keyboard.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Keyboard input handling for Elektron LFO CLI
+ */
+import type { Waveform, TriggerMode, Multiplier } from '../engine/types';
+export type KeyAction = {
+    type: 'trigger';
+} | {
+    type: 'quit';
+} | {
+    type: 'bpm';
+    delta: number;
+} | {
+    type: 'speed';
+    delta: number;
+} | {
+    type: 'waveform';
+    waveform: Waveform;
+} | {
+    type: 'mode';
+    mode: TriggerMode;
+} | {
+    type: 'multiplier';
+    multiplier: Multiplier;
+} | {
+    type: 'depth';
+    delta: number;
+} | {
+    type: 'fade';
+    delta: number;
+} | {
+    type: 'unknown';
+};
+/**
+ * Parse a key input into an action
+ */
+export declare function parseKey(key: Buffer, currentWaveform: Waveform, currentMode: TriggerMode, currentMultiplier: Multiplier): KeyAction;
+/**
+ * Set up raw mode input handling
+ */
+export declare function setupKeyboardInput(onKey: (key: Buffer) => void, onExit: () => void): void;
+/**
+ * Clean up keyboard input handling
+ */
+export declare function cleanupKeyboardInput(): void;

package/dist/engine/lfo.d.ts

@@ -73,4 +73,11 @@ export declare class LFO {
      * Stop the LFO
      */
     stop(): void;
+    /**
+     * Reset timing so the next update() call has deltaMs = 0
+     *
+     * Call this after trigger() when restarting from a paused state
+     * to prevent the LFO from jumping ahead by the paused duration.
+     */
+    resetTiming(): void;
 }

package/dist/engine/waveforms.d.ts

@@ -23,7 +23,7 @@ export declare function generateSine(phase: number): number;
 export declare function generateSquare(phase: number): number;
 /**
  * Sawtooth waveform - Bipolar
- * Linear rise from -1 to +1
+ * Linear fall from +1 to -1 (with positive depth)
  */
 export declare function generateSawtooth(phase: number): number;
 /**
@@ -33,7 +33,7 @@ export declare function generateSawtooth(phase: number): number;
 export declare function generateExponential(phase: number): number;
 /**
  * Ramp waveform - Unipolar (0 to +1)
- * Linear fall from +1 to 0
+ * Linear rise from 0 to +1
  */
 export declare function generateRamp(phase: number): number;
 /**

package/dist/index.js

@@ -66,14 +66,15 @@ function generateSquare(phase) {
   return phase < 0.5 ? 1 : -1;
 }
 function generateSawtooth(phase) {
-  return phase * 2 - 1;
+  return 1 - phase * 2;
 }
 function generateExponential(phase) {
-  const k = 4;
-  return (Math.exp(phase * k) - 1) / (Math.exp(k) - 1);
+  const k = 3;
+  const expK = Math.exp(-k);
+  return (Math.exp(-phase * k) - expK) / (1 - expK);
 }
 function generateRamp(phase) {
-  return 1 - phase;
+  return phase;
 }
 function generateRandom(phase, state) {
   const stepsPerCycle = 16;

package/package.json

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

package/src/engine/waveforms.ts

@@ -40,27 +40,32 @@ export function generateSquare(phase: number): number {
 
 /**
  * Sawtooth waveform - Bipolar
- * Linear rise from -1 to +1
+ * Linear fall from +1 to -1 (with positive depth)
  */
 export function generateSawtooth(phase: number): number {
-  return phase * 2 - 1;
+  return 1 - phase * 2;
 }
 
 /**
  * Exponential waveform - Unipolar (0 to +1)
- * Accelerating curve from 0 to 1
+ * Decaying curve from 1 to 0 (matches Digitakt II behavior)
+ * Fast initial decay, slowing toward the end (true exponential decay shape)
  */
 export function generateExponential(phase: number): number {
-  const k = 4; // Steepness factor
-  return (Math.exp(phase * k) - 1) / (Math.exp(k) - 1);
+  const k = 3; // Decay rate - controls steepness of decay
+  // True exponential decay: starts at 1, decays rapidly then slows
+  // Formula: (exp(-phase * k) - exp(-k)) / (1 - exp(-k))
+  // This normalizes to exactly [1, 0] range
+  const expK = Math.exp(-k);
+  return (Math.exp(-phase * k) - expK) / (1 - expK);
 }
 
 /**
  * Ramp waveform - Unipolar (0 to +1)
- * Linear fall from +1 to 0
+ * Linear rise from 0 to +1
  */
 export function generateRamp(phase: number): number {
-  return 1 - phase;
+  return phase;
 }
 
 /**

package/tests/unipolar-digitakt.test.ts

@@ -0,0 +1,387 @@
+/**
+ * Expectation-based tests for EXP and RMP waveforms.
+ *
+ * Based on Digitakt II hardware verification, these waveforms should behave as:
+ *
+ * EXP (Exponential):
+ * - DECAY curve: starts at 1 (peak), decays toward 0 (center)
+ * - Unipolar output range: 0 to 1
+ * - With positive depth: CC goes from (64+depth) down to 64
+ * - Shape: Fast initial decay, slowing toward the end
+ *
+ * RMP (Ramp):
+ * - RISE curve: starts at 0 (center), rises toward 1 (peak)
+ * - Unipolar output range: 0 to 1
+ * - With positive depth: CC goes from 64 up to (64+depth)
+ * - Shape: Linear rise
+ */
+
+import { describe, test, expect } from 'bun:test';
+import { generateExponential, generateRamp } from '../src/engine/waveforms';
+import { LFO } from '../src/engine/lfo';
+
+// Helper to convert LFO output to CC value
+const outputToCC = (output: number): number => {
+  return Math.max(0, Math.min(127, Math.round(64 + output * 63)));
+};
+
+describe('EXP Waveform - Expected Behavior', () => {
+  describe('raw waveform generator', () => {
+    test('should return 1.0 at phase 0 (starts at peak)', () => {
+      expect(generateExponential(0)).toBeCloseTo(1.0, 2);
+    });
+
+    test('should return value < 0.5 at phase 0.5 (decaying)', () => {
+      const value = generateExponential(0.5);
+      expect(value).toBeLessThan(0.5);
+      expect(value).toBeGreaterThan(0);
+    });
+
+    test('should return value near 0 at phase 1 (decayed to center)', () => {
+      expect(generateExponential(1)).toBeLessThan(0.1);
+    });
+
+    test('should monotonically decrease from phase 0 to 1', () => {
+      const phases = [0, 0.2, 0.4, 0.6, 0.8, 1.0];
+      const values = phases.map(p => generateExponential(p));
+
+      for (let i = 1; i < values.length; i++) {
+        expect(values[i]).toBeLessThan(values[i - 1]);
+      }
+    });
+
+    test('should be unipolar (output range 0 to 1)', () => {
+      for (let i = 0; i <= 100; i++) {
+        const value = generateExponential(i / 100);
+        expect(value).toBeGreaterThanOrEqual(0);
+        expect(value).toBeLessThanOrEqual(1);
+      }
+    });
+  });
+
+  describe('full LFO with depth=40', () => {
+    const BPM = 120;
+    const DEPTH = 40;
+
+    test('should produce CC near 104 at phase 0 (start at peak)', () => {
+      const lfo = new LFO({
+        waveform: 'EXP',
+        speed: 16,
+        multiplier: 4,
+        depth: DEPTH,
+        startPhase: 0,
+        mode: 'TRG',
+      }, BPM);
+
+      lfo.trigger();
+      const state = lfo.update(1);
+      const cc = outputToCC(state.output);
+
+      // At phase 0, EXP should be at peak: CC = 64 + 40 = 104
+      expect(cc).toBeGreaterThan(100);
+      expect(cc).toBeLessThanOrEqual(104);
+    });
+
+    test('should produce CC near 64 at phase 1 (end at center)', () => {
+      const lfo = new LFO({
+        waveform: 'EXP',
+        speed: 16,
+        multiplier: 4,
+        depth: DEPTH,
+        startPhase: 0,
+        mode: 'TRG',
+      }, BPM);
+
+      lfo.trigger();
+      // First update to set initial time (deltaMs=0 on first call)
+      lfo.update(1);
+      // Update to near end of cycle
+      const cycleMs = 4000;
+      const state = lfo.update(1 + cycleMs * 0.99);
+      const cc = outputToCC(state.output);
+
+      // At phase ~1, EXP should be near center: CC ≈ 64
+      expect(cc).toBeGreaterThanOrEqual(64);
+      expect(cc).toBeLessThan(75);
+    });
+
+    test('CC should decrease over time (decay behavior)', () => {
+      const lfo = new LFO({
+        waveform: 'EXP',
+        speed: 16,
+        multiplier: 4,
+        depth: DEPTH,
+        startPhase: 0,
+        mode: 'TRG',
+      }, BPM);
+
+      lfo.trigger();
+      const cycleMs = 4000;
+
+      const ccStart = outputToCC(lfo.update(1).output);
+      const ccMid = outputToCC(lfo.update(1 + cycleMs * 0.5).output);
+      const ccEnd = outputToCC(lfo.update(1 + cycleMs * 0.99).output);
+
+      expect(ccStart).toBeGreaterThan(ccMid);
+      expect(ccMid).toBeGreaterThan(ccEnd);
+    });
+  });
+});
+
+describe('RMP Waveform - Expected Behavior', () => {
+  describe('raw waveform generator', () => {
+    test('should return 0 at phase 0 (starts at center)', () => {
+      expect(generateRamp(0)).toBe(0);
+    });
+
+    test('should return 0.5 at phase 0.5 (linear rise)', () => {
+      expect(generateRamp(0.5)).toBe(0.5);
+    });
+
+    test('should return 1.0 at phase 1 (ends at peak)', () => {
+      expect(generateRamp(1)).toBe(1);
+    });
+
+    test('should rise linearly from phase 0 to 1', () => {
+      for (let i = 0; i <= 100; i++) {
+        const phase = i / 100;
+        expect(generateRamp(phase)).toBeCloseTo(phase, 5);
+      }
+    });
+
+    test('should be unipolar (output range 0 to 1)', () => {
+      for (let i = 0; i <= 100; i++) {
+        const value = generateRamp(i / 100);
+        expect(value).toBeGreaterThanOrEqual(0);
+        expect(value).toBeLessThanOrEqual(1);
+      }
+    });
+  });
+
+  describe('full LFO with depth=40', () => {
+    const BPM = 120;
+    const DEPTH = 40;
+
+    test('should produce CC near 64 at phase 0 (start at center)', () => {
+      const lfo = new LFO({
+        waveform: 'RMP',
+        speed: 16,
+        multiplier: 4,
+        depth: DEPTH,
+        startPhase: 0,
+        mode: 'TRG',
+      }, BPM);
+
+      lfo.trigger();
+      const state = lfo.update(1);
+      const cc = outputToCC(state.output);
+
+      // At phase 0, RMP should be at center: CC = 64
+      expect(cc).toBe(64);
+    });
+
+    test('should produce CC near 104 at phase 1 (end at peak)', () => {
+      const lfo = new LFO({
+        waveform: 'RMP',
+        speed: 16,
+        multiplier: 4,
+        depth: DEPTH,
+        startPhase: 0,
+        mode: 'TRG',
+      }, BPM);
+
+      lfo.trigger();
+      // First update to set initial time (deltaMs=0 on first call)
+      lfo.update(1);
+      const cycleMs = 4000;
+      const state = lfo.update(1 + cycleMs * 0.99);
+      const cc = outputToCC(state.output);
+
+      // At phase ~1, RMP should be at peak: CC = 64 + 40 = 104
+      expect(cc).toBeGreaterThan(100);
+      expect(cc).toBeLessThanOrEqual(104);
+    });
+
+    test('CC should increase over time (rise behavior)', () => {
+      const lfo = new LFO({
+        waveform: 'RMP',
+        speed: 16,
+        multiplier: 4,
+        depth: DEPTH,
+        startPhase: 0,
+        mode: 'TRG',
+      }, BPM);
+
+      lfo.trigger();
+      const cycleMs = 4000;
+
+      const ccStart = outputToCC(lfo.update(1).output);
+      const ccMid = outputToCC(lfo.update(1 + cycleMs * 0.5).output);
+      const ccEnd = outputToCC(lfo.update(1 + cycleMs * 0.99).output);
+
+      expect(ccStart).toBeLessThan(ccMid);
+      expect(ccMid).toBeLessThan(ccEnd);
+    });
+
+    test('should produce CC range [64-104] over full cycle', () => {
+      const lfo = new LFO({
+        waveform: 'RMP',
+        speed: 16,
+        multiplier: 4,
+        depth: DEPTH,
+        startPhase: 0,
+        mode: 'TRG',
+      }, BPM);
+
+      lfo.trigger();
+      const cycleMs = 4000;
+      let minCC = 127, maxCC = 0;
+
+      for (let i = 0; i <= 100; i++) {
+        const state = lfo.update(1 + (i / 100) * cycleMs);
+        const cc = outputToCC(state.output);
+        minCC = Math.min(minCC, cc);
+        maxCC = Math.max(maxCC, cc);
+      }
+
+      expect(minCC).toBe(64);
+      expect(maxCC).toBeGreaterThanOrEqual(103);
+      expect(maxCC).toBeLessThanOrEqual(104);
+    });
+  });
+});
+
+describe('Depth Scaling Comparison', () => {
+  const BPM = 120;
+  const DEPTH = 40;
+
+  test('TRI (bipolar) should swing ±40 from center [24-104]', () => {
+    const lfo = new LFO({
+      waveform: 'TRI',
+      speed: 16,
+      multiplier: 4,
+      depth: DEPTH,
+      startPhase: 0,
+      mode: 'TRG',
+    }, BPM);
+
+    lfo.trigger();
+    const cycleMs = 4000;
+    let minCC = 127, maxCC = 0;
+
+    for (let i = 0; i <= 100; i++) {
+      const state = lfo.update(1 + (i / 100) * cycleMs);
+      const cc = outputToCC(state.output);
+      minCC = Math.min(minCC, cc);
+      maxCC = Math.max(maxCC, cc);
+    }
+
+    // Bipolar: 64 - 40 = 24, 64 + 40 = 104
+    expect(minCC).toBe(24);
+    expect(maxCC).toBe(104);
+  });
+
+  test('RMP (unipolar) should swing +40 from center [64-104]', () => {
+    const lfo = new LFO({
+      waveform: 'RMP',
+      speed: 16,
+      multiplier: 4,
+      depth: DEPTH,
+      startPhase: 0,
+      mode: 'TRG',
+    }, BPM);
+
+    lfo.trigger();
+    const cycleMs = 4000;
+    let minCC = 127, maxCC = 0;
+
+    for (let i = 0; i <= 100; i++) {
+      const state = lfo.update(1 + (i / 100) * cycleMs);
+      const cc = outputToCC(state.output);
+      minCC = Math.min(minCC, cc);
+      maxCC = Math.max(maxCC, cc);
+    }
+
+    // Unipolar rising: 64 to 64 + 40 = 104
+    expect(minCC).toBe(64);
+    expect(maxCC).toBeGreaterThanOrEqual(103);
+  });
+
+  test('EXP (unipolar) should swing +40 from center [64-104]', () => {
+    const lfo = new LFO({
+      waveform: 'EXP',
+      speed: 16,
+      multiplier: 4,
+      depth: DEPTH,
+      startPhase: 0,
+      mode: 'TRG',
+    }, BPM);
+
+    lfo.trigger();
+    const cycleMs = 4000;
+    let minCC = 127, maxCC = 0;
+
+    for (let i = 0; i <= 100; i++) {
+      const state = lfo.update(1 + (i / 100) * cycleMs);
+      const cc = outputToCC(state.output);
+      minCC = Math.min(minCC, cc);
+      maxCC = Math.max(maxCC, cc);
+    }
+
+    // Unipolar decay: starts at 64 + 40 = 104, decays to 64
+    expect(minCC).toBeGreaterThanOrEqual(64);
+    expect(minCC).toBeLessThan(70);
+    expect(maxCC).toBeGreaterThanOrEqual(103);
+  });
+});
+
+describe('Negative Depth', () => {
+  const BPM = 120;
+  const DEPTH = -40;
+
+  test('EXP with negative depth should produce CC below center', () => {
+    const lfo = new LFO({
+      waveform: 'EXP',
+      speed: 16,
+      multiplier: 4,
+      depth: DEPTH,
+      startPhase: 0,
+      mode: 'TRG',
+    }, BPM);
+
+    lfo.trigger();
+    const state = lfo.update(1);
+    const cc = outputToCC(state.output);
+
+    // With negative depth, peak should be BELOW center: 64 - 40 = 24
+    expect(cc).toBeLessThan(30);
+    expect(cc).toBeGreaterThanOrEqual(24);
+  });
+
+  test('RMP with negative depth should rise toward center', () => {
+    const lfo = new LFO({
+      waveform: 'RMP',
+      speed: 16,
+      multiplier: 4,
+      depth: DEPTH,
+      startPhase: 0,
+      mode: 'TRG',
+    }, BPM);
+
+    lfo.trigger();
+    const state = lfo.update(1);
+    const cc = outputToCC(state.output);
+
+    // At phase 0, RMP should be at center
+    expect(cc).toBe(64);
+
+    // At end of cycle, should be at negative peak
+    const cycleMs = 4000;
+    const stateEnd = lfo.update(1 + cycleMs * 0.99);
+    const ccEnd = outputToCC(stateEnd.output);
+
+    // 64 - 40 = 24
+    expect(ccEnd).toBeLessThan(30);
+    expect(ccEnd).toBeGreaterThanOrEqual(24);
+  });
+});

package/tests/waveforms.test.ts

@@ -123,32 +123,33 @@ describe('Square Waveform', () => {
 });
 
 describe('Sawtooth Waveform', () => {
-  test('starts at -1 at phase 0', () => {
-    expect(generateSawtooth(0)).toBe(-1);
+  test('starts at +1 at phase 0', () => {
+    expect(generateSawtooth(0)).toBe(1);
   });
 
   test('is 0 at phase 0.5', () => {
     expect(generateSawtooth(0.5)).toBe(0);
   });
 
-  test('approaches +1 at phase ~1', () => {
-    expect(generateSawtooth(1)).toBe(1);
-    expect(generateSawtooth(0.999)).toBeCloseTo(1, 2);
+  test('approaches -1 at phase ~1', () => {
+    expect(generateSawtooth(1)).toBe(-1);
+    expect(generateSawtooth(0.999)).toBeCloseTo(-1, 2);
   });
 
-  test('is bipolar and linear', () => {
-    expect(generateSawtooth(0.25)).toBeCloseTo(-0.5, 5);
-    expect(generateSawtooth(0.75)).toBeCloseTo(0.5, 5);
+  test('is bipolar and linear (falling)', () => {
+    expect(generateSawtooth(0.25)).toBeCloseTo(0.5, 5);
+    expect(generateSawtooth(0.75)).toBeCloseTo(-0.5, 5);
   });
 });
 
 describe('Exponential Waveform', () => {
-  test('starts at 0 at phase 0', () => {
-    expect(generateExponential(0)).toBeCloseTo(0, 5);
+  test('starts at 1 at phase 0 (peak, matching Digitakt II)', () => {
+    expect(generateExponential(0)).toBeCloseTo(1, 5);
   });
 
-  test('ends at 1 at phase 1', () => {
-    expect(generateExponential(1)).toBeCloseTo(1, 5);
+  test('decays toward 0 at phase 1', () => {
+    // Normalized exponential decay reaches exactly 0 at phase 1
+    expect(generateExponential(1)).toBeCloseTo(0, 5);
   });
 
   test('is unipolar (0 to +1)', () => {
@@ -157,20 +158,21 @@ describe('Exponential Waveform', () => {
     expect(Math.max(...samples)).toBeLessThanOrEqual(1);
   });
 
-  test('has accelerating (exponential) curve shape', () => {
-    // At phase 0.5, should be less than 0.5 (curve bends up)
+  test('has decaying (exponential decay) curve shape', () => {
+    // At phase 0.5, should be greater than 0.5 (decay curve starts high)
     const midValue = generateExponential(0.5);
+    expect(midValue).toBeGreaterThan(0.1);
     expect(midValue).toBeLessThan(0.5);
   });
 });
 
 describe('Ramp Waveform', () => {
-  test('starts at 1 at phase 0', () => {
-    expect(generateRamp(0)).toBe(1);
+  test('starts at 0 at phase 0', () => {
+    expect(generateRamp(0)).toBe(0);
   });
 
-  test('ends at 0 at phase 1', () => {
-    expect(generateRamp(1)).toBe(0);
+  test('ends at 1 at phase 1', () => {
+    expect(generateRamp(1)).toBe(1);
   });
 
   test('is 0.5 at phase 0.5', () => {
@@ -183,9 +185,9 @@ describe('Ramp Waveform', () => {
     expect(Math.max(...samples)).toBeLessThanOrEqual(1);
   });
 
-  test('is linear', () => {
-    expect(generateRamp(0.25)).toBe(0.75);
-    expect(generateRamp(0.75)).toBe(0.25);
+  test('is linear (rising)', () => {
+    expect(generateRamp(0.25)).toBe(0.25);
+    expect(generateRamp(0.75)).toBe(0.75);
   });
 });
 
@@ -237,8 +239,8 @@ describe('generateWaveform', () => {
     expect(generateWaveform('SIN', 0.25, state).value).toBeCloseTo(1, 5);
     expect(generateWaveform('SQR', 0.25, state).value).toBe(1);
     expect(generateWaveform('SAW', 0.5, state).value).toBe(0);
-    expect(generateWaveform('EXP', 1, state).value).toBeCloseTo(1, 5);
-    expect(generateWaveform('RMP', 0, state).value).toBe(1);
+    expect(generateWaveform('EXP', 0, state).value).toBeCloseTo(1, 5); // EXP starts at peak
+    expect(generateWaveform('RMP', 0, state).value).toBe(0);
   });
 });