elektron-lfo 1.0.6 → 1.0.8

package/dist/index.js

@@ -155,8 +155,7 @@ function calculatePhaseIncrement(config, bpm) {
   if (cycleTimeMs === Infinity || cycleTimeMs === 0) {
     return 0;
   }
-  const direction = config.speed >= 0 ? 1 : -1;
-  return direction / cycleTimeMs;
+  return 1 / cycleTimeMs;
 }
 function calculateCyclesPerBar(config) {
   const product = calculateProduct(config);
@@ -346,7 +345,7 @@ function calculateFadeMultiplier(fadeValue, fadeProgress) {
 function calculateFadeCycles(fadeValue) {
   if (fadeValue === 0)
     return 0;
-  return Math.abs(fadeValue) / 64;
+  return 128 / Math.abs(fadeValue);
 }
 function updateFade(config, state, cycleTimeMs, deltaMs) {
   if (config.fade === 0 || config.mode === "FRE") {
@@ -453,6 +452,9 @@ class LFO {
     if (this.config.mode === "HLD" && this.state.triggerCount > 0) {
       effectiveRawOutput = this.state.heldOutput;
     }
+    if (this.config.speed < 0) {
+      effectiveRawOutput = -effectiveRawOutput;
+    }
     const depthScale = this.config.depth / 63;
     let scaledOutput = effectiveRawOutput * depthScale;
     scaledOutput *= this.state.fadeMultiplier;
@@ -461,7 +463,18 @@ class LFO {
     return { ...this.state };
   }
   trigger() {
-    this.state = handleTrigger(this.config, this.state, this.state.rawOutput);
+    let rawOutputForTrigger = this.state.rawOutput;
+    if (this.config.mode === "HLD") {
+      const waveformResult = generateWaveform(this.config.waveform, this.state.phase, this.state);
+      rawOutputForTrigger = waveformResult.value;
+      if (waveformResult.newRandomValue !== undefined) {
+        this.state.randomValue = waveformResult.newRandomValue;
+      }
+      if (waveformResult.newRandomStep !== undefined) {
+        this.state.randomStep = waveformResult.newRandomStep;
+      }
+    }
+    this.state = handleTrigger(this.config, this.state, rawOutputForTrigger);
   }
   getState() {
     return { ...this.state };
@@ -511,6 +524,9 @@ class LFO {
   stop() {
     this.state.isRunning = false;
   }
+  resetTiming() {
+    this.lastUpdateTime = 0;
+  }
 }
 export {
   updateFade,

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "elektron-lfo",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "Elektron LFO engine simulator implementation with CLI visualization",
   "main": "dist/index.js",
   "module": "src/index.ts",
   "types": "dist/index.d.ts",
   "bin": {
-    "elektron-lfo": "./src/cli/index.ts"
+    "elektron-lfo": "src/cli/index.ts"
   },
   "scripts": {
     "dev": "bun run src/cli/index.ts",

package/src/engine/fade.ts

@@ -48,16 +48,21 @@ export function calculateFadeMultiplier(
  * 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
+ * - 128 / |FADE| gives the number of cycles
+ * - At |FADE| = 64, fade takes 2 cycles
+ * - At |FADE| = 32, fade takes 4 cycles
+ * - At |FADE| = 16, fade takes 8 cycles
+ * - At |FADE| = 1, fade takes 128 cycles
+ *
+ * This follows the same "128" convention used in LFO timing calculations,
+ * where 128 is the crossover point for bar-length cycles.
+ * Higher |FADE| values = faster fade, lower |FADE| values = slower fade.
  */
 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;
+  // Map |FADE| to cycles: 128 / |FADE| cycles
+  // Maximum fade (64) = 2 cycles, minimum (1) = 128 cycles
+  return 128 / Math.abs(fadeValue);
 }
 
 /**

package/src/engine/lfo.ts

@@ -134,6 +134,11 @@ export class LFO {
       effectiveRawOutput = this.state.heldOutput;
     }
 
+    // Invert output for negative speed (phase still runs forward)
+    if (this.config.speed < 0) {
+      effectiveRawOutput = -effectiveRawOutput;
+    }
+
     // Apply depth
     // Depth scales the output: depth of 63 = 100%, depth of 0 = 0%
     // Negative depth inverts the waveform
@@ -157,9 +162,32 @@ export class LFO {
 
   /**
    * Trigger the LFO
+   *
+   * For HLD mode, this computes the current waveform value at the current phase
+   * to ensure the held value is accurate, even if trigger() is called before
+   * any update() calls.
    */
   trigger(): void {
-    this.state = handleTrigger(this.config, this.state, this.state.rawOutput);
+    // For HLD mode, compute fresh waveform output at current phase.
+    // This is necessary because rawOutput may be stale if trigger() is called
+    // before update() has been called (e.g., when initializing an HLD mode LFO).
+    let rawOutputForTrigger = this.state.rawOutput;
+    if (this.config.mode === 'HLD') {
+      const waveformResult = generateWaveform(
+        this.config.waveform,
+        this.state.phase,
+        this.state
+      );
+      rawOutputForTrigger = waveformResult.value;
+      // Update random state if needed (for RND waveform)
+      if (waveformResult.newRandomValue !== undefined) {
+        this.state.randomValue = waveformResult.newRandomValue;
+      }
+      if (waveformResult.newRandomStep !== undefined) {
+        this.state.randomStep = waveformResult.newRandomStep;
+      }
+    }
+    this.state = handleTrigger(this.config, this.state, rawOutputForTrigger);
   }
 
   /**
@@ -266,4 +294,12 @@ export class LFO {
   stop(): void {
     this.state.isRunning = false;
   }
+
+  /**
+   * Reset timing so the next update() call treats it as the first call (deltaMs = 0).
+   * Use this when resuming from pause or starting transport to avoid large phase jumps.
+   */
+  resetTiming(): void {
+    this.lastUpdateTime = 0;
+  }
 }

package/src/engine/timing.ts

@@ -62,9 +62,8 @@ export function calculatePhaseIncrement(config: LFOConfig, bpm: number): number
     return 0;
   }
 
-  // Negative speed runs phase backwards
-  const direction = config.speed >= 0 ? 1 : -1;
-  return direction / cycleTimeMs;
+  // Phase always moves forward; negative speed is handled by inverting waveform output
+  return 1 / cycleTimeMs;
 }
 
 /**

package/tests/depth-fade.test.ts

@@ -133,11 +133,16 @@ describe('calculateFadeCycles', () => {
     expect(calculateFadeCycles(0)).toBe(0);
   });
 
-  test('calculates cycles based on fade value', () => {
-    expect(calculateFadeCycles(64)).toBe(1); // Full fade = 1 cycle
-    expect(calculateFadeCycles(-64)).toBe(1);
-    expect(calculateFadeCycles(32)).toBe(0.5); // Half fade = 0.5 cycle
-    expect(calculateFadeCycles(-32)).toBe(0.5);
+  test('calculates cycles based on fade value (128/|FADE|)', () => {
+    // Higher |FADE| = faster fade (fewer cycles)
+    expect(calculateFadeCycles(64)).toBe(2);   // 128/64 = 2 cycles
+    expect(calculateFadeCycles(-64)).toBe(2);
+    expect(calculateFadeCycles(32)).toBe(4);   // 128/32 = 4 cycles
+    expect(calculateFadeCycles(-32)).toBe(4);
+    expect(calculateFadeCycles(16)).toBe(8);   // 128/16 = 8 cycles
+    expect(calculateFadeCycles(-16)).toBe(8);
+    expect(calculateFadeCycles(1)).toBe(128);  // 128/1 = 128 cycles (slowest)
+    expect(calculateFadeCycles(-1)).toBe(128);
   });
 });
 
@@ -161,13 +166,16 @@ describe('updateFade', () => {
   });
 
   test('progresses fade over time', () => {
-    const config = createConfig({ fade: -64, mode: 'TRG' }); // 1 cycle fade
+    // fade=-64 takes 128/64 = 2 cycles
+    const config = createConfig({ fade: -64, mode: 'TRG' });
     const state = createState({ fadeProgress: 0 });
+    const cycleTimeMs = 2000;
 
-    // After half the cycle time, progress should be ~0.5
-    const result = updateFade(config, state, 2000, 1000);
-    expect(result.fadeProgress).toBeCloseTo(0.5, 1);
-    expect(result.fadeMultiplier).toBeCloseTo(0.5, 1);
+    // Fade duration = 2 cycles * 2000ms = 4000ms
+    // After 1000ms (1/4 of fade), progress should be ~0.25
+    const result = updateFade(config, state, cycleTimeMs, 1000);
+    expect(result.fadeProgress).toBeCloseTo(0.25, 1);
+    expect(result.fadeMultiplier).toBeCloseTo(0.25, 1);
   });
 });
 
@@ -221,7 +229,7 @@ describe('Fade with LFO integration', () => {
     const lfo = new LFO({
       waveform: 'SIN',
       depth: 63,
-      fade: -64, // Fade in over 1 cycle
+      fade: -64, // Fade in over 2 cycles (128/64)
       mode: 'TRG',
     }, 120);
 
@@ -231,9 +239,10 @@ describe('Fade with LFO integration', () => {
     const state1 = lfo.update(100);
     expect(Math.abs(state1.output)).toBeLessThan(0.1); // Start near 0
 
-    // After more time, output should increase
+    // Fade takes 2 cycles = 4000ms at 2000ms/cycle
+    // After more time, output should increase significantly
     let maxOutput = 0;
-    for (let t = 100; t < 2500; t += 100) {
+    for (let t = 100; t < 5000; t += 100) {
       const state = lfo.update(t);
       maxOutput = Math.max(maxOutput, Math.abs(state.output));
     }
@@ -244,7 +253,7 @@ describe('Fade with LFO integration', () => {
     const lfo = new LFO({
       waveform: 'SIN',
       depth: 63,
-      fade: 64, // Fade out over 1 cycle
+      fade: 64, // Fade out over 2 cycles (128/64)
       mode: 'TRG',
       startPhase: 32, // Start at peak
     }, 120);
@@ -256,9 +265,10 @@ describe('Fade with LFO integration', () => {
     // Should start near full output (at SIN peak)
     expect(Math.abs(state1.output)).toBeGreaterThan(0.8);
 
+    // Fade takes 2 cycles = 4000ms at 2000ms/cycle
     // After fade completes, output should be near 0
     let lastOutput = 0;
-    for (let t = 10; t < 3000; t += 100) {
+    for (let t = 10; t < 5000; t += 100) {
       const state = lfo.update(t);
       lastOutput = Math.abs(state.output);
     }

package/tests/phase.test.ts

@@ -23,11 +23,11 @@ describe('Phase wrapping', () => {
     expect(wrappedFromOne).toBe(true);
   });
 
-  test('phase wraps from 0 to 1 (backward/negative speed)', () => {
-    const lfo = new LFO({ speed: -32, multiplier: 64 }, 120); // Fast backward cycle
+  test('phase wraps from 1 to 0 (negative speed - phase still runs forward)', () => {
+    const lfo = new LFO({ speed: -32, multiplier: 64 }, 120); // Fast cycle, negative speed
 
     let lastTime = 0;
-    let wrappedToOne = false;
+    let wrappedFromOne = false;
     let previousPhase = 0;
 
     // First update to initialize
@@ -36,15 +36,16 @@ describe('Phase wrapping', () => {
 
     for (let i = 0; i < 200; i++) {
       const state = lfo.update(lastTime);
-      if (previousPhase < 0.1 && state.phase > 0.9) {
-        wrappedToOne = true;
+      // Phase still runs forward even with negative speed
+      if (previousPhase > 0.9 && state.phase < 0.1) {
+        wrappedFromOne = true;
         break;
       }
       previousPhase = state.phase;
       lastTime += 10;
     }
 
-    expect(wrappedToOne).toBe(true);
+    expect(wrappedFromOne).toBe(true);
   });
 
   test('phase stays within 0-1 range', () => {
@@ -61,16 +62,23 @@ describe('Phase wrapping', () => {
 });
 
 describe('Negative speed', () => {
-  test('negative speed runs phase backwards', () => {
-    const lfo = new LFO({ speed: -16, multiplier: 8, startPhase: 64 }, 120);
-
-    // Initialize
-    lfo.update(0);
-    const state1 = lfo.update(100);
-    const state2 = lfo.update(200);
-
-    // Phase should decrease
-    expect(state2.phase).toBeLessThan(state1.phase);
+  test('negative speed inverts output (phase still runs forward)', () => {
+    // Positive speed LFO
+    const lfoPos = new LFO({ speed: 16, multiplier: 8, waveform: 'TRI' }, 120);
+    // Negative speed LFO (same magnitude)
+    const lfoNeg = new LFO({ speed: -16, multiplier: 8, waveform: 'TRI' }, 120);
+
+    // Initialize both
+    lfoPos.update(0);
+    lfoNeg.update(0);
+
+    const statePos = lfoPos.update(500);
+    const stateNeg = lfoNeg.update(500);
+
+    // Phase should be the same (both run forward)
+    expect(stateNeg.phase).toBeCloseTo(statePos.phase, 4);
+    // Output should be inverted
+    expect(stateNeg.output).toBeCloseTo(-statePos.output, 4);
   });
 
   test('positive speed runs phase forwards', () => {

package/tests/presets.test.ts

@@ -62,17 +62,17 @@ describe('Preset 1: Fade-In One-Shot', () => {
     lfo.update(0);
 
     const state1 = lfo.update(100);
-    expect(state1.fadeMultiplier).toBeLessThan(0.5);
+    expect(state1.fadeMultiplier).toBeLessThan(0.2);
 
-    // Fade -32 = 0.5 cycles = 1000ms at 2000ms cycle
-    // After ~500ms, should be about halfway
-    let midFadeMultiplier = 0;
-    for (let t = 100; t < 600; t += 50) {
+    // Fade -32 = 128/32 = 4 cycles = 8000ms at 2000ms cycle
+    // After ~2000ms (1 cycle), should be at 25% (2000/8000)
+    let laterFadeMultiplier = 0;
+    for (let t = 100; t < 2100; t += 50) {
       const state = lfo.update(t);
-      midFadeMultiplier = state.fadeMultiplier;
+      laterFadeMultiplier = state.fadeMultiplier;
     }
-    expect(midFadeMultiplier).toBeGreaterThan(0.3);
-    expect(midFadeMultiplier).toBeLessThan(0.8);
+    expect(laterFadeMultiplier).toBeGreaterThan(0.15);
+    expect(laterFadeMultiplier).toBeLessThan(0.4);
   });
 });
 

package/tests/timing.test.ts

@@ -103,11 +103,12 @@ describe('calculatePhaseIncrement', () => {
     expect(increment).toBeCloseTo(1 / 2000, 8);
   });
 
-  test('calculates negative increment for negative speed', () => {
-    const config = createConfig({ speed: -16, multiplier: 8 }); // 2000ms cycle, backward
+  test('calculates positive increment for negative speed (phase always forward)', () => {
+    const config = createConfig({ speed: -16, multiplier: 8 }); // 2000ms cycle
     const increment = calculatePhaseIncrement(config, 120);
-    expect(increment).toBeLessThan(0);
-    expect(increment).toBeCloseTo(-1 / 2000, 8);
+    // Phase always moves forward; output inversion is handled in LFO class
+    expect(increment).toBeGreaterThan(0);
+    expect(increment).toBeCloseTo(1 / 2000, 8);
   });
 
   test('returns 0 for speed 0', () => {