elektron-lfo 1.0.11 → 1.0.13

package/dist/index.js

@@ -283,15 +283,7 @@ function checkModeStop(config, state, previousPhase, currentPhase) {
   const isForward = config.speed >= 0;
   if (config.mode === "ONE") {
     if (state.cycleCount >= 1) {
-      if (isForward) {
-        if (startPhase === 0 || currentPhase >= startPhase) {
-          return { shouldStop: true, cycleCompleted: true };
-        }
-      } else {
-        if (startPhase === 0 || currentPhase <= startPhase) {
-          return { shouldStop: true, cycleCompleted: true };
-        }
-      }
+      return { shouldStop: true, cycleCompleted: true };
     }
   } else if (config.mode === "HLF") {
     const halfPhase = (startPhase + 0.5) % 1;
@@ -346,14 +338,11 @@ function calculateFadeCycles(fadeValue) {
   if (fadeValue === 0)
     return 0;
   const absFade = Math.abs(fadeValue);
-  if (absFade >= 48) {
-    return Infinity;
-  }
   if (absFade <= 16) {
-    return Math.max(0.5, absFade / 6);
+    return Math.max(0.5, 0.1 * absFade + 0.6);
   }
-  const baseAt16 = 16 / 6;
-  return baseAt16 * Math.pow(2, (absFade - 16) / 5);
+  const baseAt16 = 2.2;
+  return baseAt16 * Math.pow(2, (absFade - 16) / 4.5);
 }
 function updateFade(config, state, cycleTimeMs, deltaMs) {
   if (config.fade === 0 || config.mode === "FRE") {
@@ -363,12 +352,6 @@ function updateFade(config, state, cycleTimeMs, deltaMs) {
     };
   }
   const fadeCycles = calculateFadeCycles(config.fade);
-  if (!isFinite(fadeCycles)) {
-    return {
-      fadeProgress: 0,
-      fadeMultiplier: 0
-    };
-  }
   const fadeDurationMs = fadeCycles * cycleTimeMs;
   if (fadeDurationMs === 0) {
     return {
@@ -387,10 +370,6 @@ function resetFade(config) {
   if (config.fade === 0) {
     return { fadeProgress: 1, fadeMultiplier: 1 };
   }
-  const fadeCycles = calculateFadeCycles(config.fade);
-  if (!isFinite(fadeCycles)) {
-    return { fadeProgress: 0, fadeMultiplier: 0 };
-  }
   if (config.fade < 0) {
     return { fadeProgress: 0, fadeMultiplier: 0 };
   } else {

package/package.json

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

package/src/engine/fade.ts

@@ -47,14 +47,23 @@ export function calculateFadeMultiplier(
 /**
  * Calculate fade cycles - how many LFO cycles for complete fade
  *
- * Based on empirical testing against Digitakt II hardware:
- * - |FADE| <= 16: Fast fade, roughly linear (~|FADE|/6 cycles)
- *   - |FADE| = 4: ~1 cycle (nearly instant)
- *   - |FADE| = 8: ~1.5 cycles
- *   - |FADE| = 16: ~2.5 cycles
- * - |FADE| > 16: Exponential slowdown
- *   - |FADE| = 32: ~25 cycles
- * - |FADE| >= 48: Effectively disabled (infinitely slow)
+ * Based on empirical testing against Digitakt II hardware (January 2025):
+ *
+ * Key observations:
+ * - |FADE| <= 16: Linear region, ~1 cycle at FADE=4, ~2.2 cycles at FADE=16
+ * - |FADE| > 16: Exponential slowdown, doubling every ~4.7 units
+ * - NO "disabled" threshold - even |FADE|=63 continues fading, just very slowly
+ *
+ * Measured values:
+ *   |FADE| = 4:  ~1 cycle
+ *   |FADE| = 8:  ~1.6 cycles
+ *   |FADE| = 16: ~2.2 cycles
+ *   |FADE| = 24: ~7 cycles
+ *   |FADE| = 32: ~26 cycles
+ *   |FADE| = 40: ~90 cycles
+ *   |FADE| = 48: ~320 cycles
+ *   |FADE| = 56: ~1100 cycles
+ *   |FADE| = 63: ~3300 cycles
  *
  * IMPORTANT: Higher |FADE| = SLOWER fade (opposite of what you might expect)
  */
@@ -63,22 +72,16 @@ export function calculateFadeCycles(fadeValue: number): number {
 
   const absFade = Math.abs(fadeValue);
 
-  // |FADE| >= 48 is effectively disabled (infinitely slow fade)
-  if (absFade >= 48) {
-    return Infinity;
-  }
-
-  // Fast fade region: roughly linear
+  // Linear region (|FADE| <= 16): ~1 cycle at FADE=4, ~2.2 cycles at FADE=16
+  // Formula: 0.1 * |FADE| + 0.6, with minimum of 0.5
   if (absFade <= 16) {
-    // |FADE|=4 → ~0.7 cycles, |FADE|=16 → ~2.7 cycles
-    return Math.max(0.5, absFade / 6);
+    return Math.max(0.5, 0.1 * absFade + 0.6);
   }
 
-  // Slow fade region: exponential growth
-  // Base of ~2.7 cycles at |FADE|=16, doubling every 5 units
-  const baseAt16 = 16 / 6; // ~2.67 cycles
-  return baseAt16 * Math.pow(2, (absFade - 16) / 5);
-  // |FADE|=32: 2.67 * 2^3.2 ≈ 24.5 cycles (matches hardware)
+  // Exponential region (|FADE| > 16): starts at 2.2 cycles at FADE=16
+  // Doubles every ~4.5 units of |FADE|
+  const baseAt16 = 2.2;
+  return baseAt16 * Math.pow(2, (absFade - 16) / 4.5);
 }
 
 /**
@@ -107,14 +110,8 @@ export function updateFade(
   // Calculate how many cycles the fade takes
   const fadeCycles = calculateFadeCycles(config.fade);
 
-  // Handle disabled fade (|FADE| >= 48)
-  // Both fade-in and fade-out with high values result in no modulation
-  if (!isFinite(fadeCycles)) {
-    return {
-      fadeProgress: 0,
-      fadeMultiplier: 0, // No modulation when fade is disabled
-    };
-  }
+  // Note: There is no "disabled" threshold - even extreme fade values
+  // just result in very slow fades (thousands of cycles for |FADE|=63)
 
   const fadeDurationMs = fadeCycles * cycleTimeMs;
 
@@ -137,19 +134,15 @@ export function updateFade(
 
 /**
  * Reset fade state (called on trigger for modes that reset fade)
+ *
+ * Note: There is no "disabled" threshold - even extreme fade values
+ * will eventually complete, just over thousands of cycles.
  */
 export function resetFade(config: LFOConfig): { fadeProgress: number; fadeMultiplier: number } {
   if (config.fade === 0) {
     return { fadeProgress: 1, fadeMultiplier: 1 };
   }
 
-  // Check if fade is disabled (|FADE| >= 48)
-  const fadeCycles = calculateFadeCycles(config.fade);
-  if (!isFinite(fadeCycles)) {
-    // Disabled fade = no modulation
-    return { fadeProgress: 0, fadeMultiplier: 0 };
-  }
-
   if (config.fade < 0) {
     // Fade IN: start at 0
     return { fadeProgress: 0, fadeMultiplier: 0 };

package/src/engine/triggers.ts

@@ -112,23 +112,17 @@ export function checkModeStop(
   const isForward = config.speed >= 0;
 
   if (config.mode === 'ONE') {
-    // 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
+    // ONE mode: Stop immediately when phase completes one wrap (cycleCount >= 1)
+    // Based on Digitakt II hardware testing (January 2025):
+    // - Phase runs from startPhase until it wraps (crosses 1.0→0.0 or 0.0→1.0)
+    // - Stops immediately on wrap, does NOT continue back to startPhase
+    // - This means non-zero startPhase values result in partial amplitude coverage:
+    //   - Phase=0: full amplitude range (0→1→0, complete waveform)
+    //   - Phase=32: full amplitude range (0.25→1→0, starts at peak)
+    //   - Phase=64: half amplitude range (0.5→1→0, starts at middle)
+    //   - Phase=96: half amplitude range (0.75→1→0, starts at trough)
     if (state.cycleCount >= 1) {
-      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 };
-        }
-      }
+      return { shouldStop: true, cycleCompleted: true };
     }
   } else if (config.mode === 'HLF') {
     // HLF mode: Stop after half cycle (0.5 phase distance from start)

package/tests/depth-fade.test.ts

@@ -133,28 +133,53 @@ describe('calculateFadeCycles', () => {
     expect(calculateFadeCycles(0)).toBe(0);
   });
 
-  test('calculates cycles based on fade value (empirical formula)', () => {
-    // Based on Digitakt II hardware testing:
+  test('calculates cycles based on fade value (empirical formula from Digitakt II)', () => {
+    // Based on Digitakt II hardware testing (January 2025):
     // - Higher |FADE| = SLOWER fade (more cycles)
-    // - |FADE| >= 48 is disabled (Infinity)
-
-    // Fast fade region (|FADE| <= 16): ~|FADE|/6 cycles
-    expect(calculateFadeCycles(4)).toBeCloseTo(0.67, 1);   // ~0.67 cycles
-    expect(calculateFadeCycles(-4)).toBeCloseTo(0.67, 1);
-    expect(calculateFadeCycles(8)).toBeCloseTo(1.33, 1);   // ~1.33 cycles
-    expect(calculateFadeCycles(-8)).toBeCloseTo(1.33, 1);
-    expect(calculateFadeCycles(16)).toBeCloseTo(2.67, 1);  // ~2.67 cycles
-    expect(calculateFadeCycles(-16)).toBeCloseTo(2.67, 1);
-
-    // Slow fade region (16 < |FADE| < 48): exponential
-    expect(calculateFadeCycles(32)).toBeCloseTo(24.5, 0);  // ~24.5 cycles
-    expect(calculateFadeCycles(-32)).toBeCloseTo(24.5, 0);
-
-    // Disabled region (|FADE| >= 48)
-    expect(calculateFadeCycles(48)).toBe(Infinity);
-    expect(calculateFadeCycles(-48)).toBe(Infinity);
-    expect(calculateFadeCycles(64)).toBe(Infinity);
-    expect(calculateFadeCycles(-64)).toBe(Infinity);
+    // - NO disabled threshold - even extreme values fade, just slowly
+
+    // Linear region (|FADE| <= 16): 0.1 * |FADE| + 0.6
+    expect(calculateFadeCycles(4)).toBeCloseTo(1.0, 1);    // ~1 cycle
+    expect(calculateFadeCycles(-4)).toBeCloseTo(1.0, 1);
+    expect(calculateFadeCycles(8)).toBeCloseTo(1.4, 1);    // ~1.4 cycles
+    expect(calculateFadeCycles(-8)).toBeCloseTo(1.4, 1);
+    expect(calculateFadeCycles(16)).toBeCloseTo(2.2, 1);   // ~2.2 cycles
+    expect(calculateFadeCycles(-16)).toBeCloseTo(2.2, 1);
+
+    // Exponential region (|FADE| > 16): 2.2 * 2^((|FADE| - 16) / 4.5)
+    expect(calculateFadeCycles(24)).toBeCloseTo(7.5, 0);   // ~7-8 cycles
+    expect(calculateFadeCycles(-24)).toBeCloseTo(7.5, 0);
+    expect(calculateFadeCycles(32)).toBeCloseTo(26, 0);    // ~26 cycles
+    expect(calculateFadeCycles(-32)).toBeCloseTo(26, 0);
+
+    // Extreme values - NOT disabled, just very slow
+    // Using loose precision since exact values are less critical at extremes
+    const fade40 = calculateFadeCycles(40);
+    const fade48 = calculateFadeCycles(48);
+    const fade56 = calculateFadeCycles(56);
+    const fade63 = calculateFadeCycles(63);
+
+    expect(fade40).toBeGreaterThan(70);
+    expect(fade40).toBeLessThan(120);      // ~90 cycles
+    expect(fade48).toBeGreaterThan(250);
+    expect(fade48).toBeLessThan(400);      // ~300 cycles
+    expect(fade56).toBeGreaterThan(800);
+    expect(fade56).toBeLessThan(1400);     // ~1000 cycles
+    expect(fade63).toBeGreaterThan(2500);
+    expect(fade63).toBeLessThan(4000);     // ~3000 cycles
+  });
+
+  test('is symmetric for positive and negative fade values', () => {
+    expect(calculateFadeCycles(-16)).toBe(calculateFadeCycles(16));
+    expect(calculateFadeCycles(-32)).toBe(calculateFadeCycles(32));
+    expect(calculateFadeCycles(-48)).toBe(calculateFadeCycles(48));
+  });
+
+  test('extreme fade values return finite (large) cycle counts', () => {
+    // Verify no Infinity values - Digitakt continues fading even at extremes
+    expect(isFinite(calculateFadeCycles(48))).toBe(true);
+    expect(isFinite(calculateFadeCycles(63))).toBe(true);
+    expect(isFinite(calculateFadeCycles(-64))).toBe(true);
   });
 });
 
@@ -178,27 +203,29 @@ describe('updateFade', () => {
   });
 
   test('progresses fade over time', () => {
-    // fade=-16 takes ~2.67 cycles (based on new formula)
+    // fade=-16 takes ~2.2 cycles (based on new empirical formula)
     const config = createConfig({ fade: -16, mode: 'TRG' });
     const state = createState({ fadeProgress: 0 });
     const cycleTimeMs = 1000;
 
-    // Fade duration = ~2.67 cycles * 1000ms = ~2670ms
-    // After 1000ms (~37.5% of fade), progress should be ~0.375
+    // Fade duration = ~2.2 cycles * 1000ms = ~2200ms
+    // After 1000ms (~45% of fade), progress should be ~0.45
     const result = updateFade(config, state, cycleTimeMs, 1000);
-    expect(result.fadeProgress).toBeCloseTo(0.375, 1);
-    expect(result.fadeMultiplier).toBeCloseTo(0.375, 1);
+    expect(result.fadeProgress).toBeCloseTo(0.45, 1);
+    expect(result.fadeMultiplier).toBeCloseTo(0.45, 1);
   });
 
-  test('returns 0 multiplier for disabled fade', () => {
-    // fade=-64 is disabled (|FADE| >= 48)
+  test('extreme fade values still progress, just very slowly', () => {
+    // fade=-64 takes ~3500+ cycles - NOT disabled, just very slow
     const config = createConfig({ fade: -64, mode: 'TRG' });
     const state = createState({ fadeProgress: 0 });
-    const cycleTimeMs = 2000;
+    const cycleTimeMs = 1000;
 
+    // After 1000ms (1 cycle), progress should be 1/3500 = ~0.0003
     const result = updateFade(config, state, cycleTimeMs, 1000);
-    expect(result.fadeProgress).toBe(0);
-    expect(result.fadeMultiplier).toBe(0); // No modulation when disabled
+    expect(result.fadeProgress).toBeGreaterThan(0);
+    expect(result.fadeProgress).toBeLessThan(0.01);
+    expect(result.fadeMultiplier).toBeGreaterThan(0);
   });
 });
 
@@ -252,7 +279,7 @@ describe('Fade with LFO integration', () => {
     const lfo = new LFO({
       waveform: 'SIN',
       depth: 63,
-      fade: -16, // Fade in over ~2.67 cycles
+      fade: -16, // Fade in over ~2.2 cycles
       mode: 'TRG',
     }, 120);
 
@@ -262,7 +289,7 @@ describe('Fade with LFO integration', () => {
     const state1 = lfo.update(100);
     expect(Math.abs(state1.output)).toBeLessThan(0.2); // Start near 0
 
-    // Fade takes ~2.67 cycles = ~5340ms at 2000ms/cycle
+    // Fade takes ~2.2 cycles = ~4400ms at 2000ms/cycle
     // After more time, output should increase significantly
     let maxOutput = 0;
     for (let t = 100; t < 6000; t += 100) {
@@ -272,31 +299,34 @@ describe('Fade with LFO integration', () => {
     expect(maxOutput).toBeGreaterThan(0.5);
   });
 
-  test('disabled fade returns no modulation', () => {
+  test('extreme fade values progress very slowly but are not disabled', () => {
     const lfo = new LFO({
       waveform: 'SIN',
       depth: 63,
-      fade: -64, // Disabled (|FADE| >= 48)
+      fade: -64, // Very slow fade (~3500 cycles), NOT disabled
       mode: 'TRG',
     }, 120);
 
     lfo.trigger();
     lfo.update(0);
 
-    // With disabled fade, output should stay at 0 (no modulation)
+    // With extreme fade, output starts near 0 and increases VERY slowly
+    // After 10 seconds (~5 cycles), fade is only 5/3500 = 0.14% complete
     let maxOutput = 0;
     for (let t = 100; t < 10000; t += 100) {
       const state = lfo.update(t);
       maxOutput = Math.max(maxOutput, Math.abs(state.output));
     }
-    expect(maxOutput).toBe(0);
+    // Should have some tiny output (not zero) since fade is progressing
+    expect(maxOutput).toBeGreaterThan(0);
+    expect(maxOutput).toBeLessThan(0.05); // But still very small
   });
 
   test('fade out starts at full output and decreases', () => {
     const lfo = new LFO({
       waveform: 'SIN',
       depth: 63,
-      fade: 16, // Fade out over ~2.67 cycles
+      fade: 16, // Fade out over ~2.2 cycles
       mode: 'TRG',
       startPhase: 32, // Start at peak
     }, 120);
@@ -308,7 +338,7 @@ describe('Fade with LFO integration', () => {
     // Should start near full output (at SIN peak)
     expect(Math.abs(state1.output)).toBeGreaterThan(0.8);
 
-    // Fade takes ~2.67 cycles = ~5340ms at 2000ms/cycle
+    // Fade takes ~2.2 cycles = ~4400ms at 2000ms/cycle
     // After fade completes, output should be near 0
     let lastOutput = 0;
     for (let t = 10; t < 6000; t += 100) {

package/tests/triggers.test.ts

@@ -241,62 +241,40 @@ describe('checkModeStop - ONE mode', () => {
     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
+  test('with non-zero startPhase, stops immediately on wrap (Digitakt II verified)', () => {
+    // Hardware verified (January 2025): ONE mode stops immediately when phase wraps,
+    // regardless of startPhase. It does NOT continue back to startPhase.
+    // This means non-zero startPhase results in partial amplitude coverage:
+    //   - Phase=64 (0.5): only covers half the waveform amplitude
+    //   - Phase=96 (0.75): only covers quarter of phase distance
     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
+    // After wrap, cycleCount = 1, should stop IMMEDIATELY
     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);
+    const resultAfterWrap = checkModeStop(config, stateAfterWrap, 0.05, 0.1);
+    expect(resultAfterWrap.shouldStop).toBe(true);
+    expect(resultAfterWrap.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
+  test('with non-zero startPhase (backward), stops immediately on wrap (Digitakt II verified)', () => {
+    // Hardware verified: backward direction also stops immediately on wrap
     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
+    // After wrap going backward, cycleCount = 1, should stop IMMEDIATELY
     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);
+    expect(resultAfterWrap.shouldStop).toBe(true);
+    expect(resultAfterWrap.cycleCompleted).toBe(true);
   });
 });