elektron-lfo 1.0.0

package/tests/depth-fade.test.ts

@@ -0,0 +1,306 @@
+import { describe, test, expect } from 'bun:test';
+import {
+  calculateFadeMultiplier,
+  calculateFadeCycles,
+  updateFade,
+  resetFade,
+  shouldResetFadeOnTrigger,
+  applyFade,
+} from '../src/engine/fade';
+import { LFO } from '../src/engine/lfo';
+import type { LFOConfig, LFOState } from '../src/engine/types';
+import { DEFAULT_CONFIG } from '../src/engine/types';
+
+function createConfig(overrides: Partial<LFOConfig>): LFOConfig {
+  return { ...DEFAULT_CONFIG, ...overrides };
+}
+
+function createState(overrides: Partial<LFOState> = {}): LFOState {
+  return {
+    phase: 0.5,
+    output: 0.5,
+    rawOutput: 0.5,
+    isRunning: true,
+    fadeMultiplier: 1,
+    fadeProgress: 0,
+    randomValue: 0.5,
+    previousPhase: 0.4,
+    heldOutput: 0,
+    startPhaseNormalized: 0,
+    cycleCount: 0,
+    triggerCount: 0,
+    hasTriggered: false,
+    randomStep: 8,
+    ...overrides,
+  };
+}
+
+describe('Depth', () => {
+  test('depth 0 produces 0 output', () => {
+    const lfo = new LFO({ waveform: 'SIN', depth: 0 }, 120);
+
+    lfo.update(0);
+    // Run for a bit to get various waveform positions
+    for (let t = 0; t < 500; t += 50) {
+      const state = lfo.update(t);
+      expect(state.output).toBe(0);
+    }
+  });
+
+  test('depth 63 produces full output', () => {
+    const lfo = new LFO({ waveform: 'SIN', depth: 63, mode: 'FRE' }, 120);
+
+    lfo.update(0);
+    let maxOutput = 0;
+
+    // Run through a full cycle
+    for (let t = 0; t < 2500; t += 10) {
+      const state = lfo.update(t);
+      maxOutput = Math.max(maxOutput, Math.abs(state.output));
+    }
+
+    // Should reach near 1.0 at peak
+    expect(maxOutput).toBeGreaterThan(0.9);
+  });
+
+  test('depth 32 produces ~half output', () => {
+    const lfo = new LFO({ waveform: 'SIN', depth: 32, mode: 'FRE' }, 120);
+
+    lfo.update(0);
+    let maxOutput = 0;
+
+    for (let t = 0; t < 2500; t += 10) {
+      const state = lfo.update(t);
+      maxOutput = Math.max(maxOutput, Math.abs(state.output));
+    }
+
+    // Should be approximately 32/63 ≈ 0.5
+    expect(maxOutput).toBeCloseTo(32 / 63, 1);
+  });
+
+  test('negative depth inverts output', () => {
+    const lfoPos = new LFO({ waveform: 'SIN', depth: 63, startPhase: 32 }, 120);
+    const lfoNeg = new LFO({ waveform: 'SIN', depth: -63, startPhase: 32 }, 120);
+
+    lfoPos.update(0);
+    lfoNeg.update(0);
+
+    const statePos = lfoPos.update(10);
+    const stateNeg = lfoNeg.update(10);
+
+    // Should have opposite signs
+    expect(statePos.output * stateNeg.output).toBeLessThan(0);
+  });
+
+  test('negative depth with unipolar waveform (EXP)', () => {
+    const lfo = new LFO({ waveform: 'EXP', depth: -63, mode: 'FRE' }, 120);
+
+    lfo.update(0);
+    let minOutput = Infinity;
+
+    for (let t = 0; t < 2500; t += 10) {
+      const state = lfo.update(t);
+      minOutput = Math.min(minOutput, state.output);
+    }
+
+    // EXP goes 0 to 1, with negative depth should go 0 to -1
+    expect(minOutput).toBeLessThan(-0.8);
+  });
+});
+
+describe('calculateFadeMultiplier', () => {
+  test('returns 1 for fade = 0', () => {
+    expect(calculateFadeMultiplier(0, 0)).toBe(1);
+    expect(calculateFadeMultiplier(0, 0.5)).toBe(1);
+    expect(calculateFadeMultiplier(0, 1)).toBe(1);
+  });
+
+  test('fade in (negative fade) increases from 0 to 1', () => {
+    expect(calculateFadeMultiplier(-32, 0)).toBe(0);
+    expect(calculateFadeMultiplier(-32, 0.5)).toBe(0.5);
+    expect(calculateFadeMultiplier(-32, 1)).toBe(1);
+  });
+
+  test('fade out (positive fade) decreases from 1 to 0', () => {
+    expect(calculateFadeMultiplier(32, 0)).toBe(1);
+    expect(calculateFadeMultiplier(32, 0.5)).toBe(0.5);
+    expect(calculateFadeMultiplier(32, 1)).toBe(0);
+  });
+});
+
+describe('calculateFadeCycles', () => {
+  test('returns 0 for fade = 0', () => {
+    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);
+  });
+});
+
+describe('updateFade', () => {
+  test('returns full fade for fade = 0', () => {
+    const config = createConfig({ fade: 0 });
+    const state = createState();
+
+    const result = updateFade(config, state, 2000, 100);
+    expect(result.fadeMultiplier).toBe(1);
+    expect(result.fadeProgress).toBe(1);
+  });
+
+  test('does not update fade in FRE mode', () => {
+    const config = createConfig({ fade: -32, mode: 'FRE' });
+    const state = createState({ fadeProgress: 0.5 });
+
+    const result = updateFade(config, state, 2000, 100);
+    expect(result.fadeMultiplier).toBe(1);
+    expect(result.fadeProgress).toBe(1);
+  });
+
+  test('progresses fade over time', () => {
+    const config = createConfig({ fade: -64, mode: 'TRG' }); // 1 cycle fade
+    const state = createState({ fadeProgress: 0 });
+
+    // 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);
+  });
+});
+
+describe('resetFade', () => {
+  test('resets fade in to 0', () => {
+    const config = createConfig({ fade: -32 });
+    const result = resetFade(config);
+    expect(result.fadeProgress).toBe(0);
+    expect(result.fadeMultiplier).toBe(0);
+  });
+
+  test('resets fade out to 1', () => {
+    const config = createConfig({ fade: 32 });
+    const result = resetFade(config);
+    expect(result.fadeProgress).toBe(0);
+    expect(result.fadeMultiplier).toBe(1);
+  });
+
+  test('returns 1 for no fade', () => {
+    const config = createConfig({ fade: 0 });
+    const result = resetFade(config);
+    expect(result.fadeProgress).toBe(1);
+    expect(result.fadeMultiplier).toBe(1);
+  });
+});
+
+describe('shouldResetFadeOnTrigger', () => {
+  test('returns true for all modes except FRE', () => {
+    expect(shouldResetFadeOnTrigger('TRG')).toBe(true);
+    expect(shouldResetFadeOnTrigger('ONE')).toBe(true);
+    expect(shouldResetFadeOnTrigger('HLF')).toBe(true);
+    expect(shouldResetFadeOnTrigger('HLD')).toBe(true);
+  });
+
+  test('returns false for FRE', () => {
+    expect(shouldResetFadeOnTrigger('FRE')).toBe(false);
+  });
+});
+
+describe('applyFade', () => {
+  test('scales output by fade multiplier', () => {
+    expect(applyFade(1, 1)).toBe(1);
+    expect(applyFade(1, 0.5)).toBe(0.5);
+    expect(applyFade(1, 0)).toBe(0);
+    expect(applyFade(-1, 0.5)).toBe(-0.5);
+  });
+});
+
+describe('Fade with LFO integration', () => {
+  test('fade in starts at 0 output and increases', () => {
+    const lfo = new LFO({
+      waveform: 'SIN',
+      depth: 63,
+      fade: -64, // Fade in over 1 cycle
+      mode: 'TRG',
+    }, 120);
+
+    lfo.trigger();
+    lfo.update(0);
+
+    const state1 = lfo.update(100);
+    expect(Math.abs(state1.output)).toBeLessThan(0.1); // Start near 0
+
+    // After more time, output should increase
+    let maxOutput = 0;
+    for (let t = 100; t < 2500; t += 100) {
+      const state = lfo.update(t);
+      maxOutput = Math.max(maxOutput, Math.abs(state.output));
+    }
+    expect(maxOutput).toBeGreaterThan(0.5);
+  });
+
+  test('fade out starts at full output and decreases', () => {
+    const lfo = new LFO({
+      waveform: 'SIN',
+      depth: 63,
+      fade: 64, // Fade out over 1 cycle
+      mode: 'TRG',
+      startPhase: 32, // Start at peak
+    }, 120);
+
+    lfo.trigger();
+    lfo.update(0);
+
+    const state1 = lfo.update(10);
+    // Should start near full output (at SIN peak)
+    expect(Math.abs(state1.output)).toBeGreaterThan(0.8);
+
+    // After fade completes, output should be near 0
+    let lastOutput = 0;
+    for (let t = 10; t < 3000; t += 100) {
+      const state = lfo.update(t);
+      lastOutput = Math.abs(state.output);
+    }
+    expect(lastOutput).toBeLessThan(0.2);
+  });
+
+  test('fade resets on trigger for TRG mode', () => {
+    const lfo = new LFO({
+      waveform: 'SIN',
+      fade: -64,
+      mode: 'TRG',
+    }, 120);
+
+    lfo.trigger();
+    lfo.update(0);
+
+    // Let fade progress
+    for (let t = 0; t < 1500; t += 100) {
+      lfo.update(t);
+    }
+
+    // Trigger again
+    lfo.trigger();
+    const stateAfterTrigger = lfo.update(1600);
+
+    // Fade should have reset (multiplier back to 0 for fade in)
+    expect(stateAfterTrigger.fadeMultiplier).toBeLessThan(0.2);
+  });
+
+  test('fade does not work in FRE mode', () => {
+    const lfo = new LFO({
+      waveform: 'SIN',
+      depth: 63,
+      fade: -64, // Would be fade in
+      mode: 'FRE',
+      startPhase: 32,
+    }, 120);
+
+    lfo.update(0);
+    const state = lfo.update(10);
+
+    // In FRE mode, fade is always 1 (full output immediately)
+    expect(state.fadeMultiplier).toBe(1);
+  });
+});

package/tests/phase.test.ts

@@ -0,0 +1,219 @@
+import { describe, test, expect } from 'bun:test';
+import { LFO } from '../src/engine/lfo';
+
+describe('Phase wrapping', () => {
+  test('phase wraps from 1 back to 0 (forward)', () => {
+    const lfo = new LFO({ speed: 32, multiplier: 64 }, 120); // Fast cycle
+
+    // Simulate time passing
+    let lastTime = 0;
+    let wrappedFromOne = false;
+    let previousPhase = 0;
+
+    for (let i = 0; i < 200; i++) {
+      const state = lfo.update(lastTime);
+      if (previousPhase > 0.9 && state.phase < 0.1) {
+        wrappedFromOne = true;
+        break;
+      }
+      previousPhase = state.phase;
+      lastTime += 10; // 10ms per step
+    }
+
+    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
+
+    let lastTime = 0;
+    let wrappedToOne = false;
+    let previousPhase = 0;
+
+    // First update to initialize
+    lfo.update(lastTime);
+    lastTime += 10;
+
+    for (let i = 0; i < 200; i++) {
+      const state = lfo.update(lastTime);
+      if (previousPhase < 0.1 && state.phase > 0.9) {
+        wrappedToOne = true;
+        break;
+      }
+      previousPhase = state.phase;
+      lastTime += 10;
+    }
+
+    expect(wrappedToOne).toBe(true);
+  });
+
+  test('phase stays within 0-1 range', () => {
+    const lfo = new LFO({ speed: 32, multiplier: 64 }, 120);
+
+    let lastTime = 0;
+    for (let i = 0; i < 500; i++) {
+      const state = lfo.update(lastTime);
+      expect(state.phase).toBeGreaterThanOrEqual(0);
+      expect(state.phase).toBeLessThan(1);
+      lastTime += 5;
+    }
+  });
+});
+
+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('positive speed runs phase forwards', () => {
+    const lfo = new LFO({ speed: 16, multiplier: 8 }, 120);
+
+    lfo.update(0);
+    const state1 = lfo.update(100);
+    const state2 = lfo.update(200);
+
+    // Phase should increase
+    expect(state2.phase).toBeGreaterThan(state1.phase);
+  });
+
+  test('negative speed has same cycle time as positive speed', () => {
+    const lfoPos = new LFO({ speed: 16, multiplier: 8 }, 120);
+    const lfoNeg = new LFO({ speed: -16, multiplier: 8 }, 120);
+
+    expect(lfoPos.getTimingInfo().cycleTimeMs).toBe(lfoNeg.getTimingInfo().cycleTimeMs);
+  });
+});
+
+describe('Start phase', () => {
+  test('startPhase 0 starts at phase 0', () => {
+    const lfo = new LFO({ startPhase: 0 }, 120);
+    expect(lfo.getState().phase).toBe(0);
+  });
+
+  test('startPhase 64 starts at phase 0.5', () => {
+    const lfo = new LFO({ startPhase: 64 }, 120);
+    expect(lfo.getState().phase).toBeCloseTo(0.5, 5);
+  });
+
+  test('startPhase 127 starts at phase ~0.992', () => {
+    const lfo = new LFO({ startPhase: 127 }, 120);
+    expect(lfo.getState().phase).toBeCloseTo(127 / 128, 3);
+  });
+
+  test('startPhase 32 (90 degrees) affects waveform starting position', () => {
+    // SIN at phase 0.25 (90 degrees) should be at peak (+1)
+    const lfo = new LFO({ waveform: 'SIN', startPhase: 32 }, 120);
+    lfo.update(0);
+    const state = lfo.update(1); // Minimal time for initial output
+
+    // Phase should be at ~0.25, SIN should be near peak
+    expect(state.phase).toBeCloseTo(0.25, 2);
+  });
+});
+
+describe('ONE mode with non-zero startPhase', () => {
+  test('ONE mode stops after returning to start phase', () => {
+    const lfo = new LFO({
+      mode: 'ONE',
+      speed: 32,
+      multiplier: 64, // Fast 125ms cycle
+      startPhase: 32, // Start at 0.25
+    }, 120);
+
+    lfo.trigger();
+
+    let lastTime = 0;
+    let stopped = false;
+
+    // Run for long enough to complete at least one cycle
+    for (let i = 0; i < 100; i++) {
+      lfo.update(lastTime);
+      lastTime += 10;
+    }
+
+    stopped = !lfo.isRunning();
+    expect(stopped).toBe(true);
+  });
+});
+
+describe('HLF mode with non-zero startPhase', () => {
+  test('HLF mode stops at phase 0.5 beyond start', () => {
+    const lfo = new LFO({
+      mode: 'HLF',
+      speed: 32,
+      multiplier: 64, // Fast cycle
+      startPhase: 32, // Start at 0.25
+    }, 120);
+
+    lfo.trigger();
+
+    let lastTime = 0;
+    let stoppedAtPhase: number | null = null;
+
+    for (let i = 0; i < 100; i++) {
+      const state = lfo.update(lastTime);
+      if (!state.isRunning && stoppedAtPhase === null) {
+        stoppedAtPhase = state.phase;
+        break;
+      }
+      lastTime += 5;
+    }
+
+    // Should stop at 0.25 + 0.5 = 0.75
+    expect(stoppedAtPhase).toBeCloseTo(0.75, 1);
+  });
+
+  test('HLF mode with startPhase 96 stops correctly (wraps through 0)', () => {
+    const lfo = new LFO({
+      mode: 'HLF',
+      speed: 32,
+      multiplier: 64,
+      startPhase: 96, // Start at 0.75
+    }, 120);
+
+    lfo.trigger();
+
+    let lastTime = 0;
+    let stoppedAtPhase: number | null = null;
+
+    for (let i = 0; i < 100; i++) {
+      const state = lfo.update(lastTime);
+      if (!state.isRunning && stoppedAtPhase === null) {
+        stoppedAtPhase = state.phase;
+        break;
+      }
+      lastTime += 5;
+    }
+
+    // Should stop at 0.75 + 0.5 = 1.25 -> wraps to 0.25
+    expect(stoppedAtPhase).toBeCloseTo(0.25, 1);
+  });
+});
+
+describe('Cycle counting', () => {
+  test('cycle count increments on wrap', () => {
+    const lfo = new LFO({ speed: 32, multiplier: 64 }, 120); // 125ms cycle
+
+    lfo.update(0);
+
+    let lastTime = 0;
+    let maxCycles = 0;
+
+    // Run for 500ms (should complete ~4 cycles)
+    for (let i = 0; i < 100; i++) {
+      const state = lfo.update(lastTime);
+      maxCycles = Math.max(maxCycles, state.cycleCount);
+      lastTime += 5;
+    }
+
+    expect(maxCycles).toBeGreaterThanOrEqual(3);
+  });
+});