elektron-lfo 1.0.0

package/tests/presets.test.ts

@@ -0,0 +1,344 @@
+import { describe, test, expect } from 'bun:test';
+import { LFO } from '../src/engine/lfo';
+
+/**
+ * Integration tests for the 5 presets from DIGITAKT_II_LFO_PRESETS.md
+ */
+
+describe('Preset 1: Fade-In One-Shot', () => {
+  // RMP, SPD=8, MULT=16, ONE mode, FADE=-32
+  // 1 bar cycle (2000ms at 120 BPM), stops after one cycle
+
+  test('has correct timing (2000ms at 120 BPM)', () => {
+    const lfo = new LFO({
+      waveform: 'RMP',
+      speed: 8,
+      multiplier: 16, // 8 * 16 = 128 = 1 bar
+      mode: 'ONE',
+      fade: -32,
+      depth: 63,
+    }, 120);
+
+    const timing = lfo.getTimingInfo();
+    expect(timing.cycleTimeMs).toBeCloseTo(2000, 0);
+    expect(timing.noteValue).toBe('1 bar');
+    expect(timing.product).toBe(128);
+  });
+
+  test('stops after one cycle', () => {
+    const lfo = new LFO({
+      waveform: 'RMP',
+      speed: 8,
+      multiplier: 16,
+      mode: 'ONE',
+      fade: -32,
+      depth: 63,
+    }, 120);
+
+    lfo.trigger();
+    lfo.update(0);
+
+    // Run for 2500ms (more than one 2000ms cycle)
+    let lastTime = 0;
+    for (let t = 0; t < 2500; t += 50) {
+      lfo.update(t);
+      lastTime = t;
+    }
+
+    expect(lfo.isRunning()).toBe(false);
+  });
+
+  test('fade multiplier increases over time (fade in)', () => {
+    const lfo = new LFO({
+      waveform: 'RMP',
+      speed: 8,
+      multiplier: 16,
+      mode: 'ONE',
+      fade: -32, // Negative = fade IN
+      depth: 63,
+    }, 120);
+
+    lfo.trigger();
+    lfo.update(0);
+
+    const state1 = lfo.update(100);
+    expect(state1.fadeMultiplier).toBeLessThan(0.5);
+
+    // 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) {
+      const state = lfo.update(t);
+      midFadeMultiplier = state.fadeMultiplier;
+    }
+    expect(midFadeMultiplier).toBeGreaterThan(0.3);
+    expect(midFadeMultiplier).toBeLessThan(0.8);
+  });
+});
+
+describe('Preset 2: Ambient Drift', () => {
+  // SIN, SPD=1, MULT=1, FRE mode
+  // 128 bars cycle (256000ms at 120 BPM)
+
+  test('has correct timing (256000ms at 120 BPM)', () => {
+    const lfo = new LFO({
+      waveform: 'SIN',
+      speed: 1,
+      multiplier: 1, // 1 * 1 = 1 = 128 bars
+      mode: 'FRE',
+      depth: 24,
+      fade: 0,
+    }, 120);
+
+    const timing = lfo.getTimingInfo();
+    expect(timing.cycleTimeMs).toBeCloseTo(256000, 0);
+    expect(timing.noteValue).toBe('128 bars');
+    expect(timing.product).toBe(1);
+  });
+
+  test('continues running despite triggers', () => {
+    const lfo = new LFO({
+      waveform: 'SIN',
+      speed: 1,
+      multiplier: 1,
+      mode: 'FRE',
+      depth: 24,
+    }, 120);
+
+    lfo.update(0);
+    const state1 = lfo.update(1000);
+    const phase1 = state1.phase;
+
+    // Trigger should not affect phase in FRE mode
+    lfo.trigger();
+    const state2 = lfo.update(1100);
+
+    // Phase should have continued from where it was
+    expect(state2.phase).toBeGreaterThan(phase1);
+    expect(lfo.isRunning()).toBe(true);
+  });
+
+  test('output is within moderate depth range', () => {
+    const lfo = new LFO({
+      waveform: 'SIN',
+      speed: 1,
+      multiplier: 1,
+      mode: 'FRE',
+      depth: 24, // Moderate depth
+    }, 120);
+
+    lfo.update(0);
+    let maxOutput = 0;
+
+    // Sample some outputs
+    for (let t = 0; t < 10000; t += 500) {
+      const state = lfo.update(t);
+      maxOutput = Math.max(maxOutput, Math.abs(state.output));
+    }
+
+    // Depth 24/63 ≈ 0.38
+    expect(maxOutput).toBeLessThanOrEqual(24 / 63 + 0.05);
+  });
+});
+
+describe('Preset 3: Hi-Hat Humanizer', () => {
+  // RND, SPD=32, MULT=64, FRE mode
+  // 1/16 note cycle (125ms at 120 BPM)
+
+  test('has correct timing (125ms at 120 BPM)', () => {
+    const lfo = new LFO({
+      waveform: 'RND',
+      speed: 32,
+      multiplier: 64, // 32 * 64 = 2048 = 1/16
+      mode: 'FRE',
+      depth: 12,
+    }, 120);
+
+    const timing = lfo.getTimingInfo();
+    expect(timing.cycleTimeMs).toBeCloseTo(125, 0);
+    expect(timing.noteValue).toBe('1/16');
+    expect(timing.product).toBe(2048);
+  });
+
+  test('random values change over time', () => {
+    const lfo = new LFO({
+      waveform: 'RND',
+      speed: 32,
+      multiplier: 64,
+      mode: 'FRE',
+      depth: 12,
+    }, 120);
+
+    lfo.update(0);
+    const values = new Set<number>();
+
+    // Collect random values over 500ms (4 cycles)
+    for (let t = 0; t < 500; t += 5) {
+      const state = lfo.update(t);
+      values.add(Math.round(state.rawOutput * 1000) / 1000);
+    }
+
+    // Should have multiple different values
+    expect(values.size).toBeGreaterThan(5);
+  });
+
+  test('output within depth range', () => {
+    const lfo = new LFO({
+      waveform: 'RND',
+      speed: 32,
+      multiplier: 64,
+      mode: 'FRE',
+      depth: 12, // Subtle depth
+    }, 120);
+
+    lfo.update(0);
+    let maxOutput = 0;
+
+    for (let t = 0; t < 500; t += 5) {
+      const state = lfo.update(t);
+      maxOutput = Math.max(maxOutput, Math.abs(state.output));
+    }
+
+    // Depth 12/63 ≈ 0.19
+    expect(maxOutput).toBeLessThanOrEqual(12 / 63 + 0.02);
+  });
+});
+
+describe('Preset 4: Pumping Sidechain', () => {
+  // EXP, SPD=32, MULT=4, TRG mode, DEP=-63
+  // 1 bar cycle (2000ms at 120 BPM)
+
+  test('has correct timing (2000ms at 120 BPM)', () => {
+    const lfo = new LFO({
+      waveform: 'EXP',
+      speed: 32,
+      multiplier: 4, // 32 * 4 = 128 = 1 bar
+      mode: 'TRG',
+      depth: -63, // Inverted
+    }, 120);
+
+    const timing = lfo.getTimingInfo();
+    expect(timing.cycleTimeMs).toBeCloseTo(2000, 0);
+    expect(timing.product).toBe(128);
+  });
+
+  test('restarts on trigger', () => {
+    const lfo = new LFO({
+      waveform: 'EXP',
+      speed: 32,
+      multiplier: 4,
+      mode: 'TRG',
+      depth: -63,
+    }, 120);
+
+    lfo.trigger();
+    lfo.update(0);
+
+    // Let it run partway through
+    for (let t = 0; t < 1000; t += 50) {
+      lfo.update(t);
+    }
+
+    const stateBefore = lfo.update(1000);
+    const phaseBefore = stateBefore.phase;
+
+    // Trigger again
+    lfo.trigger();
+    const stateAfter = lfo.update(1050);
+
+    // Phase should have reset to near 0
+    expect(stateAfter.phase).toBeLessThan(phaseBefore);
+    expect(stateAfter.phase).toBeLessThan(0.1);
+  });
+
+  test('produces inverted (negative) output', () => {
+    const lfo = new LFO({
+      waveform: 'EXP',
+      speed: 32,
+      multiplier: 4,
+      mode: 'TRG',
+      depth: -63, // Negative depth inverts
+      startPhase: 0,
+    }, 120);
+
+    lfo.trigger();
+    lfo.update(0);
+
+    // EXP goes 0 to 1, with -63 depth it should go 0 to -1
+    let minOutput = Infinity;
+    for (let t = 0; t < 2000; t += 50) {
+      const state = lfo.update(t);
+      minOutput = Math.min(minOutput, state.output);
+    }
+
+    expect(minOutput).toBeLessThan(-0.8);
+  });
+});
+
+describe('Preset 5: Wobble Bass', () => {
+  // SIN, SPD=16, MULT=8, TRG mode, SPH=32, DEP=+48
+  // 1 bar cycle (2000ms at 120 BPM), starts at peak
+
+  test('has correct timing (2000ms at 120 BPM)', () => {
+    const lfo = new LFO({
+      waveform: 'SIN',
+      speed: 16,
+      multiplier: 8, // 16 * 8 = 128 = 1 bar
+      mode: 'TRG',
+      startPhase: 32, // 90 degrees = peak
+      depth: 48,
+    }, 120);
+
+    const timing = lfo.getTimingInfo();
+    expect(timing.cycleTimeMs).toBeCloseTo(2000, 0);
+    expect(timing.noteValue).toBe('1 bar');
+  });
+
+  test('starts at peak (phase 90 degrees)', () => {
+    const lfo = new LFO({
+      waveform: 'SIN',
+      speed: 16,
+      multiplier: 8,
+      mode: 'TRG',
+      startPhase: 32, // 32/128 = 0.25 = 90 degrees
+      depth: 48,
+    }, 120);
+
+    lfo.trigger();
+    lfo.update(0);
+
+    const state = lfo.update(1);
+    // At phase 0.25, SIN should be at +1
+    expect(state.phase).toBeCloseTo(0.25, 2);
+    // Raw output should be near peak
+    expect(state.rawOutput).toBeGreaterThan(0.95);
+  });
+
+  test('strong depth produces dramatic sweep', () => {
+    const lfo = new LFO({
+      waveform: 'SIN',
+      speed: 16,
+      multiplier: 8,
+      mode: 'TRG',
+      startPhase: 32,
+      depth: 48, // Strong depth
+    }, 120);
+
+    lfo.trigger();
+    lfo.update(0);
+
+    let maxOutput = 0;
+    let minOutput = Infinity;
+
+    for (let t = 0; t < 2500; t += 50) {
+      const state = lfo.update(t);
+      maxOutput = Math.max(maxOutput, state.output);
+      minOutput = Math.min(minOutput, state.output);
+    }
+
+    // Depth 48/63 ≈ 0.76
+    const expectedRange = 48 / 63;
+    expect(maxOutput).toBeGreaterThan(expectedRange * 0.9);
+    expect(minOutput).toBeLessThan(-expectedRange * 0.9);
+  });
+});

package/tests/timing.test.ts

@@ -0,0 +1,232 @@
+import { describe, test, expect } from 'bun:test';
+import {
+  calculateProduct,
+  calculateCycleTimeMs,
+  calculateFrequencyHz,
+  calculatePhaseIncrement,
+  calculateCyclesPerBar,
+  calculateNoteValue,
+  calculateTimingInfo,
+  formatCycleTime,
+  formatFrequency,
+} from '../src/engine/timing';
+import type { LFOConfig } from '../src/engine/types';
+import { DEFAULT_CONFIG } from '../src/engine/types';
+
+// Helper to create config with defaults
+function createConfig(overrides: Partial<LFOConfig>): LFOConfig {
+  return { ...DEFAULT_CONFIG, ...overrides };
+}
+
+describe('calculateProduct', () => {
+  test('calculates |SPD| × MULT', () => {
+    expect(calculateProduct(createConfig({ speed: 16, multiplier: 8 }))).toBe(128);
+    expect(calculateProduct(createConfig({ speed: 32, multiplier: 64 }))).toBe(2048);
+    expect(calculateProduct(createConfig({ speed: 1, multiplier: 1 }))).toBe(1);
+  });
+
+  test('uses absolute value of speed', () => {
+    expect(calculateProduct(createConfig({ speed: -16, multiplier: 8 }))).toBe(128);
+    expect(calculateProduct(createConfig({ speed: -32, multiplier: 64 }))).toBe(2048);
+  });
+
+  test('handles speed of 0', () => {
+    expect(calculateProduct(createConfig({ speed: 0, multiplier: 8 }))).toBe(0);
+  });
+});
+
+describe('calculateCycleTimeMs', () => {
+  test('calculates correct cycle time for 1 bar at 120 BPM', () => {
+    // Product 128 = 1 bar = 2000ms at 120 BPM
+    const config = createConfig({ speed: 16, multiplier: 8 }); // 128
+    expect(calculateCycleTimeMs(config, 120)).toBeCloseTo(2000, 1);
+  });
+
+  test('calculates correct cycle time for 1/16 note at 120 BPM', () => {
+    // Product 2048 = 1/16 note = 125ms at 120 BPM
+    const config = createConfig({ speed: 32, multiplier: 64 }); // 2048
+    expect(calculateCycleTimeMs(config, 120)).toBeCloseTo(125, 1);
+  });
+
+  test('calculates correct cycle time for 128 bars at 120 BPM', () => {
+    // Product 1 = 128 bars = 256000ms at 120 BPM
+    const config = createConfig({ speed: 1, multiplier: 1 }); // 1
+    expect(calculateCycleTimeMs(config, 120)).toBeCloseTo(256000, 1);
+  });
+
+  test('uses fixed 120 BPM when useFixedBPM is true', () => {
+    const config = createConfig({ speed: 16, multiplier: 8, useFixedBPM: true });
+    // Should be 2000ms regardless of passed BPM
+    expect(calculateCycleTimeMs(config, 90)).toBeCloseTo(2000, 1);
+    expect(calculateCycleTimeMs(config, 180)).toBeCloseTo(2000, 1);
+  });
+
+  test('returns Infinity for speed 0', () => {
+    const config = createConfig({ speed: 0, multiplier: 8 });
+    expect(calculateCycleTimeMs(config, 120)).toBe(Infinity);
+  });
+
+  test('scales with BPM', () => {
+    const config = createConfig({ speed: 16, multiplier: 8 }); // 128 = 1 bar
+    // At 60 BPM, 1 bar = 4000ms
+    expect(calculateCycleTimeMs(config, 60)).toBeCloseTo(4000, 1);
+    // At 240 BPM, 1 bar = 1000ms
+    expect(calculateCycleTimeMs(config, 240)).toBeCloseTo(1000, 1);
+  });
+});
+
+describe('calculateFrequencyHz', () => {
+  test('calculates correct frequency for 1 bar at 120 BPM', () => {
+    // 1 bar at 120 BPM = 2000ms cycle = 0.5 Hz
+    const config = createConfig({ speed: 16, multiplier: 8 }); // 128
+    expect(calculateFrequencyHz(config, 120)).toBeCloseTo(0.5, 5);
+  });
+
+  test('calculates correct frequency for 1/16 note at 120 BPM', () => {
+    // 1/16 at 120 BPM = 125ms cycle = 8 Hz
+    const config = createConfig({ speed: 32, multiplier: 64 }); // 2048
+    expect(calculateFrequencyHz(config, 120)).toBeCloseTo(8, 5);
+  });
+
+  test('returns 0 for speed 0', () => {
+    const config = createConfig({ speed: 0, multiplier: 8 });
+    expect(calculateFrequencyHz(config, 120)).toBe(0);
+  });
+});
+
+describe('calculatePhaseIncrement', () => {
+  test('calculates positive increment for positive speed', () => {
+    const config = createConfig({ speed: 16, multiplier: 8 }); // 2000ms cycle
+    const increment = calculatePhaseIncrement(config, 120);
+    expect(increment).toBeGreaterThan(0);
+    // 1ms should give 1/2000 phase increment
+    expect(increment).toBeCloseTo(1 / 2000, 8);
+  });
+
+  test('calculates negative increment for negative speed', () => {
+    const config = createConfig({ speed: -16, multiplier: 8 }); // 2000ms cycle, backward
+    const increment = calculatePhaseIncrement(config, 120);
+    expect(increment).toBeLessThan(0);
+    expect(increment).toBeCloseTo(-1 / 2000, 8);
+  });
+
+  test('returns 0 for speed 0', () => {
+    const config = createConfig({ speed: 0, multiplier: 8 });
+    expect(calculatePhaseIncrement(config, 120)).toBe(0);
+  });
+});
+
+describe('calculateCyclesPerBar', () => {
+  test('returns 1 for product 128', () => {
+    const config = createConfig({ speed: 16, multiplier: 8 }); // 128
+    expect(calculateCyclesPerBar(config)).toBe(1);
+  });
+
+  test('returns 16 for product 2048', () => {
+    const config = createConfig({ speed: 32, multiplier: 64 }); // 2048
+    expect(calculateCyclesPerBar(config)).toBe(16);
+  });
+
+  test('returns 1/128 for product 1', () => {
+    const config = createConfig({ speed: 1, multiplier: 1 }); // 1
+    expect(calculateCyclesPerBar(config)).toBeCloseTo(1 / 128, 8);
+  });
+});
+
+describe('calculateNoteValue', () => {
+  test('returns correct note values', () => {
+    expect(calculateNoteValue(2048)).toBe('1/16');
+    expect(calculateNoteValue(1024)).toBe('1/8');
+    expect(calculateNoteValue(512)).toBe('1/4');
+    expect(calculateNoteValue(256)).toBe('1/2');
+    expect(calculateNoteValue(128)).toBe('1 bar');
+  });
+
+  test('returns bar counts for slow cycles', () => {
+    expect(calculateNoteValue(64)).toBe('2 bars');
+    expect(calculateNoteValue(32)).toBe('4 bars');
+    expect(calculateNoteValue(16)).toBe('8 bars');
+    expect(calculateNoteValue(1)).toBe('128 bars');
+  });
+
+  test('returns ∞ for product 0', () => {
+    expect(calculateNoteValue(0)).toBe('∞');
+  });
+});
+
+describe('calculateTimingInfo', () => {
+  test('returns complete timing info', () => {
+    const config = createConfig({ speed: 16, multiplier: 8 });
+    const info = calculateTimingInfo(config, 120);
+
+    expect(info.product).toBe(128);
+    expect(info.cycleTimeMs).toBeCloseTo(2000, 1);
+    expect(info.frequencyHz).toBeCloseTo(0.5, 5);
+    expect(info.cyclesPerBar).toBe(1);
+    expect(info.noteValue).toBe('1 bar');
+  });
+});
+
+describe('formatCycleTime', () => {
+  test('formats milliseconds', () => {
+    expect(formatCycleTime(125)).toBe('125.0ms');
+    expect(formatCycleTime(500)).toBe('500.0ms');
+  });
+
+  test('formats seconds', () => {
+    expect(formatCycleTime(2000)).toBe('2.00s');
+    expect(formatCycleTime(4500)).toBe('4.50s');
+  });
+
+  test('formats minutes', () => {
+    expect(formatCycleTime(120000)).toBe('2.0min');
+    expect(formatCycleTime(256000)).toBe('4.3min');
+  });
+
+  test('formats infinity', () => {
+    expect(formatCycleTime(Infinity)).toBe('∞');
+  });
+});
+
+describe('formatFrequency', () => {
+  test('formats Hz', () => {
+    expect(formatFrequency(8)).toBe('8.00 Hz');
+    expect(formatFrequency(0.5)).toBe('0.500 Hz');
+  });
+
+  test('formats mHz for very low frequencies', () => {
+    expect(formatFrequency(0.005)).toBe('5.000 mHz');
+  });
+
+  test('formats 0 Hz', () => {
+    expect(formatFrequency(0)).toBe('0 Hz');
+  });
+});
+
+describe('Spec timing examples', () => {
+  // Verify against the timing examples from the spec
+
+  test('SPD=32, MULT=64: 1/16 note, 125ms at 120 BPM', () => {
+    const config = createConfig({ speed: 32, multiplier: 64 });
+    expect(calculateCycleTimeMs(config, 120)).toBeCloseTo(125, 1);
+    expect(calculateNoteValue(32 * 64)).toBe('1/16');
+  });
+
+  test('SPD=16, MULT=8: 1 bar, 2000ms at 120 BPM', () => {
+    const config = createConfig({ speed: 16, multiplier: 8 });
+    expect(calculateCycleTimeMs(config, 120)).toBeCloseTo(2000, 1);
+    expect(calculateNoteValue(16 * 8)).toBe('1 bar');
+  });
+
+  test('SPD=1, MULT=1: 128 bars, 256000ms at 120 BPM', () => {
+    const config = createConfig({ speed: 1, multiplier: 1 });
+    expect(calculateCycleTimeMs(config, 120)).toBeCloseTo(256000, 1);
+    expect(calculateNoteValue(1 * 1)).toBe('128 bars');
+  });
+
+  test('SPD=8, MULT=16: 1 bar, 2000ms at 120 BPM', () => {
+    const config = createConfig({ speed: 8, multiplier: 16 });
+    expect(calculateCycleTimeMs(config, 120)).toBeCloseTo(2000, 1);
+    expect(calculateNoteValue(8 * 16)).toBe('1 bar');
+  });
+});