elektron-lfo 1.0.13 → 1.0.16

package/dist/index.js

@@ -177,10 +177,10 @@ function calculateNoteValue(product) {
   if (product >= 128)
     return "1 bar";
   const bars = 128 / product;
-  if (bars === Math.floor(bars)) {
-    return `${bars} bars`;
-  }
-  return `${bars.toFixed(1)} bars`;
+  const rounded = Math.round(bars * 10) / 10;
+  const isWhole = rounded === Math.floor(rounded);
+  const barsStr = isWhole ? String(Math.floor(rounded)) : rounded.toFixed(1);
+  return `${barsStr} bars`;
 }
 function calculateTimingInfo(config, bpm) {
   const product = calculateProduct(config);
@@ -411,20 +411,29 @@ class LFO {
     if (shouldUpdatePhase) {
       const previousPhase = this.state.phase;
       let newPhase = this.state.phase + phaseIncrement * deltaMs;
+      let cycleCompleted = false;
       if (newPhase >= 1) {
         newPhase = newPhase % 1;
         this.state.cycleCount++;
+        cycleCompleted = true;
       } else if (newPhase < 0) {
         newPhase = 1 + newPhase % 1;
         if (newPhase === 1)
           newPhase = 0;
         this.state.cycleCount++;
+        cycleCompleted = true;
+      }
+      if (cycleCompleted && this.config.waveform === "RND") {
+        if (this.config.mode === "FRE" || this.config.mode === "TRG") {
+          this.state.randomValue = Math.random() * 2 - 1;
+          this.state.randomStep = Math.floor(newPhase * 16);
+        }
       }
       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;
+          newPhase = 1;
         } else if (this.config.mode === "HLF") {
           newPhase = (this.state.startPhaseNormalized + 0.5) % 1;
         }
@@ -450,7 +459,11 @@ class LFO {
       effectiveRawOutput = this.state.heldOutput;
     }
     if (this.config.speed < 0) {
-      effectiveRawOutput = -effectiveRawOutput;
+      if (isUnipolar(this.config.waveform)) {
+        effectiveRawOutput = 1 - effectiveRawOutput;
+      } else {
+        effectiveRawOutput = -effectiveRawOutput;
+      }
     }
     const depthScale = this.config.depth / 63;
     let scaledOutput = effectiveRawOutput * depthScale;

package/docs/PLAN.md

@@ -421,15 +421,15 @@ types.ts
 
 2. **Random waveform state** needs special handling - must track previous phase to detect step changes.
 
-3. **ONE mode stopping** requires careful detection of phase wrapping past the start phase. Must work for both positive AND negative speed.
+3. **ONE mode stopping** occurs immediately when phase wraps (cycleCount >= 1), NOT when returning to start phase. This was verified against Digitakt II hardware - non-zero startPhase results in partial amplitude coverage.
 
 4. **HLF mode** stops at the phase 0.5 beyond start phase (wrapping), not absolute 0.5.
 
-5. **HLD mode** captures the current output when triggered and holds it until the next trigger, but the LFO continues running in the background.
+5. **HLD mode** captures the current output when triggered and holds it until the next trigger. The LFO continues running in background. Note: Digitakt hardware only sends MIDI CC when the held value CHANGES between triggers - if multiple triggers capture the same value, only one CC is sent.
 
-6. **Fade timing** is relative to LFO cycles, not absolute time. This ensures consistency across BPM changes.
+6. **Fade timing** is relative to LFO cycles, not absolute time. Hardware-verified formula: Linear region (|FADE| ≤ 16): `cycles = 0.1 * |FADE| + 0.6`; Exponential region (|FADE| > 16): `cycles = 2.2 * 2^((|FADE| - 16) / 4.5)`. Higher |FADE| = slower fade.
 
-7. **Fade resets** on trigger for TRG, ONE, and HLF modes. FRE mode does not reset fade.
+7. **Fade resets** on trigger for TRG, ONE, and HLF modes. FRE mode does not reset fade, and importantly, fade does NOT work in FRE mode at all (requires a trigger to initiate).
 
 8. **60fps update rate** is sufficient for visualization but may need adjustment for audio-rate LFO applications.
 

package/docs/TEST_QUESTIONS.md

@@ -541,6 +541,79 @@ Use this checklist to track test completion:
 
 ---
 
+## Hardware-Verified Findings (January 2026)
+
+The following behaviors were verified against real Digitakt II hardware via MIDI CC monitoring.
+
+### ONE Mode Stop Behavior
+
+**Finding:** ONE mode stops immediately when phase wraps (cycleCount >= 1), NOT when phase returns to startPhase.
+
+**Implications:**
+- Non-zero startPhase results in partial amplitude coverage before wrap
+- Phase=0: full waveform traversed before wrap
+- Phase=32 (90°): full amplitude range (peak to trough)
+- Phase=64 (180°): half amplitude range (starts at middle)
+- Phase=96 (270°): half amplitude range (starts at trough)
+
+**Test Updates:** TEST 2 and TEST 17 expected results should be revised - the LFO stops on phase wrap, not when returning to start phase.
+
+### HLD Mode MIDI Behavior
+
+**Finding:** The Digitakt only sends MIDI CC messages when the held value CHANGES between triggers.
+
+**Behavior:**
+- LFO continues running in background between triggers
+- Each trigger captures and holds the current LFO value
+- If multiple triggers capture the same value, only one CC is sent
+- Verification: expect ≤N unique CC values for N triggers, all within valid range
+
+**Test Updates:** TEST 5 verification should account for this - you may receive fewer CCs than triggers if values repeat.
+
+### HLF Mode (Half Cycle)
+
+**Finding:** HLF runs for exactly 0.5 phase distance then stops.
+
+**Verification:**
+- For TRI with startPhase=0: goes from middle to peak only = 50% amplitude range
+- Correctly outputs half the expected full-cycle range
+
+### Fade Formula (Empirical)
+
+**Finding:** The fade envelope follows a piecewise formula:
+
+```
+Linear region (|FADE| ≤ 16):   cycles = 0.1 * |FADE| + 0.6
+Exponential region (|FADE| > 16): cycles = 2.2 * 2^((|FADE| - 16) / 4.5)
+```
+
+**Key observations:**
+- Higher |FADE| = SLOWER fade (more cycles to complete)
+- NO "disabled" threshold - even |FADE|=63 fades, just very slowly (~3000 cycles)
+- Fade does NOT work in FRE mode (requires trigger to initiate)
+- Fade-out: Cycle 1 has full amplitude; fade effect starts from cycle 2
+- Each trigger resets fade progress to 0
+
+**Formula validated at extremes (60-second tests):**
+- FADE=-48 (304 cycles to complete): observed 20% progress ✓
+- FADE=-56 (1043 cycles): observed 6% progress ✓
+- FADE=-63 (3066 cycles): observed 2% progress ✓
+
+**Measured values:**
+| FADE | Cycles |
+|------|--------|
+| 4    | ~1     |
+| 8    | ~1.4   |
+| 16   | ~2.2   |
+| 24   | ~7.5   |
+| 32   | ~26    |
+| 48   | ~300   |
+| 63   | ~3000  |
+
+**Test Updates:** TEST 8 and TEST 12 expected results should use this formula for accurate predictions.
+
+---
+
 ## Document Metadata
 
 - **Created:** Based on DIGITAKT_II_LFO_SPEC.md and DIGITAKT_II_LFO_PRESETS.md

package/package.json

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

package/src/engine/lfo.ts

@@ -67,13 +67,25 @@ export class LFO {
       let newPhase = this.state.phase + phaseIncrement * deltaMs;
 
       // Wrap phase to 0-1 range
+      let cycleCompleted = false;
       if (newPhase >= 1) {
         newPhase = newPhase % 1;
         this.state.cycleCount++;
+        cycleCompleted = true;
       } else if (newPhase < 0) {
         newPhase = 1 + (newPhase % 1);
         if (newPhase === 1) newPhase = 0;
         this.state.cycleCount++;
+        cycleCompleted = true;
+      }
+
+      // Regenerate RND waveform values at cycle end (for FRE/TRG modes only)
+      // ONE/HLF modes don't cycle - they stop, and only regenerate on retrigger
+      if (cycleCompleted && this.config.waveform === 'RND') {
+        if (this.config.mode === 'FRE' || this.config.mode === 'TRG') {
+          this.state.randomValue = Math.random() * 2 - 1;
+          this.state.randomStep = Math.floor(newPhase * 16);
+        }
       }
 
       // Check for mode-based stopping (ONE/HLF)
@@ -86,9 +98,15 @@ export class LFO {
 
       if (stopCheck.shouldStop) {
         this.state.isRunning = false;
-        // Snap to stop position
+        // Snap to stop position - stay at END of waveform curve, not start
+        // Hardware verified (Jan 2026): ONE mode stops at the visual end of the curve
+        // With SPH offset, you traverse a partial curve (SPH → end), not a full cycle
         if (this.config.mode === 'ONE') {
-          newPhase = this.state.startPhaseNormalized;
+          // Phase=1 is the end of the waveform curve
+          // Final output values for unipolar waveforms (EXP/RMP):
+          //   speed+ depth+ → 0,  speed+ depth- → 0
+          //   speed- depth+ → +1, speed- depth- → -1
+          newPhase = 1;
         } else if (this.config.mode === 'HLF') {
           newPhase = (this.state.startPhaseNormalized + 0.5) % 1;
         }
@@ -134,9 +152,20 @@ export class LFO {
       effectiveRawOutput = this.state.heldOutput;
     }
 
-    // Invert output for negative speed (phase still runs forward)
+    // Handle negative speed: flip waveform direction
+    // For unipolar waveforms (EXP, RMP), flip shape (1-x) so decay becomes attack
+    // For bipolar waveforms, invert sign (-x) to reverse direction
+    // This matches Digitakt II hardware behavior:
+    //   EXP speed+ depth+ = +1→0, speed- depth+ = 0→+1
+    //   EXP speed+ depth- = -1→0, speed- depth- = 0→-1
     if (this.config.speed < 0) {
-      effectiveRawOutput = -effectiveRawOutput;
+      if (isUnipolar(this.config.waveform)) {
+        // Flip unipolar waveform: decay (1→0) becomes attack (0→1)
+        effectiveRawOutput = 1 - effectiveRawOutput;
+      } else {
+        // Invert bipolar waveform
+        effectiveRawOutput = -effectiveRawOutput;
+      }
     }
 
     // Apply depth

package/src/engine/timing.ts

@@ -101,10 +101,11 @@ export function calculateNoteValue(product: number): string {
 
   // For products < 128: slower than 1 bar
   const bars = 128 / product;
-  if (bars === Math.floor(bars)) {
-    return `${bars} bars`;
-  }
-  return `${bars.toFixed(1)} bars`;
+  // Round to 1 decimal place, then drop trailing .0 for whole numbers
+  const rounded = Math.round(bars * 10) / 10;
+  const isWhole = rounded === Math.floor(rounded);
+  const barsStr = isWhole ? String(Math.floor(rounded)) : rounded.toFixed(1);
+  return `${barsStr} bars`;
 }
 
 /**

package/tests/negative-speed.test.ts

@@ -161,7 +161,10 @@ describe('Negative Speed - RMP waveform (unipolar)', () => {
     expect(stateMid.rawOutput).toBeCloseTo(0.5, 1);
   });
 
-  test('negative speed RMP has inverted output (0 to -1)', () => {
+  test('negative speed RMP has flipped output (1 to 0) - Digitakt II verified', () => {
+    // Hardware behavior: negative speed flips unipolar waveforms
+    // RMP normally: 0→1 (ramp up)
+    // RMP speed-: 1→0 (ramp down) via 1-x transformation
     const lfo = new LFO({
       waveform: 'RMP',
       speed: -16,
@@ -173,15 +176,15 @@ describe('Negative Speed - RMP waveform (unipolar)', () => {
     lfo.update(0);
     const stateStart = lfo.update(1);
 
-    // rawOutput is still 0 (RMP at phase 0), output is negated to 0
+    // rawOutput is still 0 (RMP at phase 0), but output is flipped: 1-0=1
     expect(stateStart.rawOutput).toBeCloseTo(0, 1);
-    expect(stateStart.output).toBeCloseTo(0, 1); // -0 = 0
+    expect(stateStart.output).toBeCloseTo(1, 1); // Flipped to 1
 
-    // After half cycle, rawOutput is 0.5, output is -0.5 * depth
+    // After half cycle, rawOutput is 0.5, flipped to 0.5
     const cycleMs = lfo.getTimingInfo().cycleTimeMs;
     const stateMid = lfo.update(cycleMs * 0.5);
     expect(stateMid.rawOutput).toBeCloseTo(0.5, 1);
-    expect(stateMid.output).toBeLessThan(0); // Negated
+    expect(stateMid.output).toBeCloseTo(0.5, 1); // 1-0.5=0.5, still positive
   });
 });
 
@@ -208,7 +211,10 @@ describe('Negative Speed - EXP waveform (unipolar)', () => {
     expect(stateEnd.rawOutput).toBeLessThan(0.2);
   });
 
-  test('negative speed EXP has inverted output (-1 to 0)', () => {
+  test('negative speed EXP has flipped output (0 to 1) - Digitakt II verified', () => {
+    // Hardware behavior: negative speed flips unipolar waveforms
+    // EXP normally: 1→0 (decay)
+    // EXP speed-: 0→1 (attack/swell) via 1-x transformation
     const lfo = new LFO({
       waveform: 'EXP',
       speed: -16,
@@ -220,9 +226,14 @@ describe('Negative Speed - EXP waveform (unipolar)', () => {
     lfo.update(0);
     const stateStart = lfo.update(1);
 
-    // rawOutput is still 1 (EXP at phase 0), output is negated to -1
+    // rawOutput is still 1 (EXP at phase 0), but output is flipped: 1-1=0
     expect(stateStart.rawOutput).toBeCloseTo(1, 1);
-    expect(stateStart.output).toBeLessThan(-0.9); // Inverted!
+    expect(stateStart.output).toBeCloseTo(0, 1); // Flipped to 0
+
+    // Near end of cycle, rawOutput approaches 0, flipped to 1
+    const cycleMs = lfo.getTimingInfo().cycleTimeMs;
+    const stateEnd = lfo.update(cycleMs * 0.95);
+    expect(stateEnd.output).toBeGreaterThan(0.8); // Flipped: near 1
   });
 });