elektron-lfo 1.0.0

package/src/cli/args.ts

@@ -0,0 +1,182 @@
+/**
+ * Command-line argument parsing for Elektron LFO CLI
+ */
+
+import type { LFOConfig, Waveform, TriggerMode, Multiplier } from '../engine/types';
+import { DEFAULT_CONFIG, VALID_MULTIPLIERS, isValidMultiplier } from '../engine/types';
+
+export interface CLIArgs extends LFOConfig {
+  bpm: number;
+  help: boolean;
+}
+
+const WAVEFORMS: Waveform[] = ['TRI', 'SIN', 'SQR', 'SAW', 'EXP', 'RMP', 'RND'];
+const TRIGGER_MODES: TriggerMode[] = ['FRE', 'TRG', 'HLD', 'ONE', 'HLF'];
+
+export function printHelp(): void {
+  console.log(`
+Elektron LFO Visualizer - Digitakt II LFO Engine
+
+Usage: elektron-lfo [options]
+
+Options:
+  -w, --waveform <type>   Waveform type: TRI, SIN, SQR, SAW, EXP, RMP, RND
+                          (default: ${DEFAULT_CONFIG.waveform})
+  -s, --speed <value>     Speed: -64.00 to +63.00 (default: ${DEFAULT_CONFIG.speed})
+  -m, --multiplier <val>  Multiplier: 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048
+                          (default: ${DEFAULT_CONFIG.multiplier})
+  -f, --fixed             Use fixed 120 BPM instead of project BPM
+  -p, --phase <value>     Start phase: 0-127 (default: ${DEFAULT_CONFIG.startPhase})
+  -M, --mode <mode>       Trigger mode: FRE, TRG, HLD, ONE, HLF
+                          (default: ${DEFAULT_CONFIG.mode})
+  -d, --depth <value>     Depth: -64.00 to +63.00 (default: ${DEFAULT_CONFIG.depth})
+  -F, --fade <value>      Fade: -64 to +63 (default: ${DEFAULT_CONFIG.fade})
+  -b, --bpm <value>       Project BPM: 1-999 (default: 120)
+  -h, --help              Show this help
+
+Controls:
+  [SPACE]   Trigger the LFO
+  [Q]       Quit
+  [↑/↓]     Adjust BPM (+/- 1)
+  [←/→]     Adjust speed (+/- 1)
+  [W]       Cycle waveform
+  [M]       Cycle mode
+
+Examples:
+  elektron-lfo                           # Default triangle LFO
+  elektron-lfo -w SIN -s 16 -m 8         # Sine wave, 1 bar cycle at 120 BPM
+  elektron-lfo -w RND -s 32 -m 64 -M FRE # Random hi-hat humanizer
+  elektron-lfo -w EXP -M TRG -d -63      # Pumping sidechain effect
+`);
+}
+
+export function parseArgs(args: string[]): CLIArgs {
+  const result: CLIArgs = {
+    ...DEFAULT_CONFIG,
+    bpm: 120,
+    help: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    const nextArg = args[i + 1];
+
+    switch (arg) {
+      case '-h':
+      case '--help':
+        result.help = true;
+        break;
+
+      case '-w':
+      case '--waveform': {
+        const waveform = nextArg?.toUpperCase() as Waveform;
+        if (!WAVEFORMS.includes(waveform)) {
+          console.error(`Invalid waveform: ${nextArg}. Valid: ${WAVEFORMS.join(', ')}`);
+          process.exit(1);
+        }
+        result.waveform = waveform;
+        i++;
+        break;
+      }
+
+      case '-s':
+      case '--speed': {
+        const speed = parseFloat(nextArg);
+        if (isNaN(speed) || speed < -64 || speed > 63) {
+          console.error(`Invalid speed: ${nextArg}. Must be -64.00 to +63.00`);
+          process.exit(1);
+        }
+        result.speed = speed;
+        i++;
+        break;
+      }
+
+      case '-m':
+      case '--multiplier': {
+        const mult = parseInt(nextArg, 10);
+        if (!isValidMultiplier(mult)) {
+          console.error(`Invalid multiplier: ${nextArg}. Valid: ${VALID_MULTIPLIERS.join(', ')}`);
+          process.exit(1);
+        }
+        result.multiplier = mult;
+        i++;
+        break;
+      }
+
+      case '-f':
+      case '--fixed':
+        result.useFixedBPM = true;
+        break;
+
+      case '-p':
+      case '--phase': {
+        const phase = parseInt(nextArg, 10);
+        if (isNaN(phase) || phase < 0 || phase > 127) {
+          console.error(`Invalid phase: ${nextArg}. Must be 0-127`);
+          process.exit(1);
+        }
+        result.startPhase = phase;
+        i++;
+        break;
+      }
+
+      case '-M':
+      case '--mode': {
+        const mode = nextArg?.toUpperCase() as TriggerMode;
+        if (!TRIGGER_MODES.includes(mode)) {
+          console.error(`Invalid mode: ${nextArg}. Valid: ${TRIGGER_MODES.join(', ')}`);
+          process.exit(1);
+        }
+        result.mode = mode;
+        i++;
+        break;
+      }
+
+      case '-d':
+      case '--depth': {
+        const depth = parseFloat(nextArg);
+        if (isNaN(depth) || depth < -64 || depth > 63) {
+          console.error(`Invalid depth: ${nextArg}. Must be -64.00 to +63.00`);
+          process.exit(1);
+        }
+        result.depth = depth;
+        i++;
+        break;
+      }
+
+      case '-F':
+      case '--fade': {
+        const fade = parseInt(nextArg, 10);
+        if (isNaN(fade) || fade < -64 || fade > 63) {
+          console.error(`Invalid fade: ${nextArg}. Must be -64 to +63`);
+          process.exit(1);
+        }
+        result.fade = fade;
+        i++;
+        break;
+      }
+
+      case '-b':
+      case '--bpm': {
+        const bpm = parseInt(nextArg, 10);
+        if (isNaN(bpm) || bpm < 1 || bpm > 999) {
+          console.error(`Invalid BPM: ${nextArg}. Must be 1-999`);
+          process.exit(1);
+        }
+        result.bpm = bpm;
+        i++;
+        break;
+      }
+
+      default:
+        if (arg.startsWith('-')) {
+          console.error(`Unknown option: ${arg}`);
+          printHelp();
+          process.exit(1);
+        }
+        break;
+    }
+  }
+
+  return result;
+}

package/src/cli/display.ts

@@ -0,0 +1,237 @@
+/**
+ * Terminal display for Elektron LFO CLI
+ *
+ * Renders the LFO state with ASCII waveform visualization
+ */
+
+import type { LFOConfig, LFOState, TimingInfo, Waveform } from '../engine/types';
+import { formatCycleTime, formatFrequency } from '../engine/timing';
+import { generateWaveform, isUnipolar } from '../engine/waveforms';
+
+// ANSI escape codes
+const CLEAR_SCREEN = '\x1b[2J';
+const CURSOR_HOME = '\x1b[H';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const CYAN = '\x1b[36m';
+const RED = '\x1b[31m';
+const MAGENTA = '\x1b[35m';
+
+const WAVEFORM_WIDTH = 60;
+const WAVEFORM_HEIGHT = 9;
+
+/**
+ * Generate ASCII waveform preview
+ */
+function generateWaveformPreview(
+  waveform: Waveform,
+  phase: number,
+  state: LFOState
+): string[] {
+  const lines: string[] = [];
+  const unipolar = isUnipolar(waveform);
+
+  // Sample the waveform at WAVEFORM_WIDTH points
+  const samples: number[] = [];
+  const tempState = { ...state };
+
+  for (let i = 0; i < WAVEFORM_WIDTH; i++) {
+    const samplePhase = i / WAVEFORM_WIDTH;
+    const result = generateWaveform(waveform, samplePhase, tempState);
+    samples.push(result.value);
+    if (result.newRandomValue !== undefined) {
+      tempState.randomValue = result.newRandomValue;
+    }
+    if (result.newRandomStep !== undefined) {
+      tempState.randomStep = result.newRandomStep;
+    }
+  }
+
+  // Find phase position
+  const phasePos = Math.floor(phase * WAVEFORM_WIDTH);
+
+  // Build character grid
+  for (let row = 0; row < WAVEFORM_HEIGHT; row++) {
+    let line = '';
+    const rowValue = unipolar
+      ? 1 - row / (WAVEFORM_HEIGHT - 1) // 0 to 1 mapping
+      : 1 - (row / (WAVEFORM_HEIGHT - 1)) * 2; // -1 to 1 mapping
+
+    for (let col = 0; col < WAVEFORM_WIDTH; col++) {
+      const sampleValue = samples[col];
+      const isPhaseIndicator = col === phasePos;
+
+      // Check if this cell should show the waveform
+      const cellThreshold = unipolar
+        ? rowValue - 0.5 / (WAVEFORM_HEIGHT - 1)
+        : rowValue - 1 / (WAVEFORM_HEIGHT - 1);
+
+      let char = ' ';
+
+      if (unipolar) {
+        // For unipolar, show the waveform as filled area from bottom
+        if (sampleValue >= cellThreshold && rowValue <= 1) {
+          char = isPhaseIndicator ? '█' : '░';
+        }
+      } else {
+        // For bipolar, show just the line
+        const nextRowValue = row < WAVEFORM_HEIGHT - 1
+          ? 1 - ((row + 1) / (WAVEFORM_HEIGHT - 1)) * 2
+          : -2;
+
+        if (
+          (sampleValue >= cellThreshold && sampleValue < rowValue) ||
+          (sampleValue <= rowValue && sampleValue > nextRowValue)
+        ) {
+          char = isPhaseIndicator ? '█' : '●';
+        } else if (row === Math.floor((WAVEFORM_HEIGHT - 1) / 2)) {
+          // Center line (zero crossing)
+          char = isPhaseIndicator ? '█' : '─';
+        }
+      }
+
+      if (isPhaseIndicator && char === ' ') {
+        char = '│';
+      }
+
+      line += char;
+    }
+    lines.push(line);
+  }
+
+  return lines;
+}
+
+/**
+ * Format output bar
+ */
+function formatOutputBar(output: number, width: number = 30): string {
+  const normalizedOutput = (output + 1) / 2; // Convert -1..1 to 0..1
+  const position = Math.round(normalizedOutput * (width - 1));
+  const centerPos = Math.floor(width / 2);
+
+  let bar = '';
+  for (let i = 0; i < width; i++) {
+    if (i === centerPos) {
+      bar += '│';
+    } else if (
+      (output >= 0 && i > centerPos && i <= position) ||
+      (output < 0 && i >= position && i < centerPos)
+    ) {
+      bar += '=';
+    } else {
+      bar += ' ';
+    }
+  }
+
+  return `[${bar}]`;
+}
+
+/**
+ * Get status color based on mode and running state
+ */
+function getStatusColor(isRunning: boolean, mode: string): string {
+  if (!isRunning) return RED;
+  if (mode === 'FRE') return GREEN;
+  return CYAN;
+}
+
+/**
+ * Get status text
+ */
+function getStatusText(isRunning: boolean, mode: string): string {
+  if (!isRunning) {
+    return mode === 'ONE' || mode === 'HLF' ? 'STOPPED - Press SPACE to trigger' : 'STOPPED';
+  }
+  return mode === 'FRE' ? 'FREE RUNNING' : 'RUNNING';
+}
+
+/**
+ * Render the full display
+ */
+export function render(
+  config: LFOConfig,
+  state: LFOState,
+  timing: TimingInfo,
+  bpm: number
+): string {
+  const lines: string[] = [];
+
+  // Header
+  lines.push(`${BOLD}═══ Elektron LFO Visualizer ═══${RESET}`);
+  lines.push('');
+
+  // Parameters row 1
+  const waveColor = isUnipolar(config.waveform) ? MAGENTA : CYAN;
+  lines.push(
+    `${BOLD}WAVE:${RESET} ${waveColor}${config.waveform}${RESET}  ` +
+    `${BOLD}SPD:${RESET} ${config.speed >= 0 ? '+' : ''}${config.speed.toFixed(2)}  ` +
+    `${BOLD}MULT:${RESET} ${config.multiplier}  ` +
+    `${BOLD}MODE:${RESET} ${YELLOW}${config.mode}${RESET}`
+  );
+
+  // Parameters row 2
+  const phaseDegrees = Math.round((config.startPhase / 128) * 360);
+  const fadeSign = config.fade > 0 ? '+' : config.fade < 0 ? '' : ' ';
+  const fadeLabel = config.fade < 0 ? 'IN' : config.fade > 0 ? 'OUT' : '';
+  lines.push(
+    `${BOLD}SPH:${RESET} ${config.startPhase} (${phaseDegrees}°)  ` +
+    `${BOLD}DEP:${RESET} ${config.depth >= 0 ? '+' : ''}${config.depth.toFixed(2)}  ` +
+    `${BOLD}FADE:${RESET} ${fadeSign}${config.fade} ${fadeLabel}`
+  );
+
+  // Timing info
+  const effectiveBpm = config.useFixedBPM ? 120 : bpm;
+  const bpmSuffix = config.useFixedBPM ? ' (fixed)' : '';
+  lines.push(
+    `${BOLD}BPM:${RESET} ${effectiveBpm}${bpmSuffix}  ` +
+    `${BOLD}Cycle:${RESET} ${formatCycleTime(timing.cycleTimeMs)} (${timing.noteValue})  ` +
+    `${BOLD}Hz:${RESET} ${formatFrequency(timing.frequencyHz)}`
+  );
+
+  lines.push('');
+
+  // Waveform visualization
+  const waveformLines = generateWaveformPreview(config.waveform, state.phase, state);
+  for (const line of waveformLines) {
+    lines.push(`  ${DIM}${line}${RESET}`);
+  }
+
+  lines.push('');
+
+  // Output display
+  const outputSign = state.output >= 0 ? '+' : '';
+  const outputBar = formatOutputBar(state.output);
+  lines.push(
+    `${BOLD}Output:${RESET} ${outputSign}${state.output.toFixed(4)} ${outputBar}`
+  );
+
+  // State info
+  const fadePercent = Math.round(state.fadeMultiplier * 100);
+  const phasePercent = (state.phase * 100).toFixed(1);
+  lines.push(
+    `${BOLD}Phase:${RESET} ${phasePercent}%  ` +
+    `${BOLD}Fade:${RESET} ${fadePercent}%  ` +
+    `${BOLD}Cycles:${RESET} ${state.cycleCount}  ` +
+    `${BOLD}Triggers:${RESET} ${state.triggerCount}`
+  );
+
+  lines.push('');
+
+  // Status
+  const statusColor = getStatusColor(state.isRunning, config.mode);
+  const statusText = getStatusText(state.isRunning, config.mode);
+  lines.push(`${statusColor}[${statusText}]${RESET}`);
+
+  lines.push('');
+
+  // Controls
+  lines.push(
+    `${DIM}Controls: [SPACE] Trigger  [Q] Quit  [↑/↓] BPM  [←/→] Speed  [W] Wave  [M] Mode${RESET}`
+  );
+
+  return CLEAR_SCREEN + CURSOR_HOME + lines.join('\n');
+}

package/src/cli/index.ts

@@ -0,0 +1,129 @@
+#!/usr/bin/env bun
+/**
+ * Elektron LFO CLI - Main Entry Point
+ *
+ * Real-time terminal visualization of the Digitakt II LFO engine
+ */
+
+import { LFO } from '../engine/lfo';
+import { clamp } from '../engine/types';
+import { parseArgs, printHelp } from './args';
+import { render } from './display';
+import { setupKeyboardInput, cleanupKeyboardInput, parseKey } from './keyboard';
+
+const TARGET_FPS = 60;
+const FRAME_TIME_MS = 1000 / TARGET_FPS;
+
+async function main() {
+  // Parse command line arguments
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  // Create LFO instance
+  const lfo = new LFO(
+    {
+      waveform: args.waveform,
+      speed: args.speed,
+      multiplier: args.multiplier,
+      useFixedBPM: args.useFixedBPM,
+      startPhase: args.startPhase,
+      mode: args.mode,
+      depth: args.depth,
+      fade: args.fade,
+    },
+    args.bpm
+  );
+
+  let bpm = args.bpm;
+  let running = true;
+
+  // Hide cursor
+  process.stdout.write('\x1b[?25l');
+
+  // Set up keyboard input
+  setupKeyboardInput(
+    (key: Buffer) => {
+      const config = lfo.getConfig();
+      const action = parseKey(key, config.waveform, config.mode, config.multiplier);
+
+      switch (action.type) {
+        case 'quit':
+          running = false;
+          break;
+
+        case 'trigger':
+          lfo.trigger();
+          break;
+
+        case 'bpm':
+          bpm = clamp(bpm + action.delta, 1, 999);
+          lfo.setBpm(bpm);
+          break;
+
+        case 'speed': {
+          const newSpeed = clamp(config.speed + action.delta, -64, 63);
+          lfo.setConfig({ speed: newSpeed });
+          break;
+        }
+
+        case 'waveform':
+          lfo.setConfig({ waveform: action.waveform });
+          break;
+
+        case 'mode':
+          lfo.setConfig({ mode: action.mode });
+          break;
+
+        case 'multiplier':
+          lfo.setConfig({ multiplier: action.multiplier });
+          break;
+
+        case 'depth': {
+          const newDepth = clamp(config.depth + action.delta, -64, 63);
+          lfo.setConfig({ depth: newDepth });
+          break;
+        }
+
+        case 'fade': {
+          const newFade = clamp(config.fade + action.delta, -64, 63);
+          lfo.setConfig({ fade: newFade });
+          break;
+        }
+      }
+    },
+    () => {
+      running = false;
+    }
+  );
+
+  // Main render loop
+  const startTime = performance.now();
+
+  while (running) {
+    const currentTime = performance.now();
+    const state = lfo.update(currentTime - startTime);
+    const config = lfo.getConfig();
+    const timing = lfo.getTimingInfo();
+
+    // Render display
+    const display = render(config, state, timing, bpm);
+    process.stdout.write(display);
+
+    // Wait for next frame
+    await Bun.sleep(FRAME_TIME_MS);
+  }
+
+  // Cleanup
+  cleanupKeyboardInput();
+  console.log('Goodbye!');
+}
+
+main().catch((error) => {
+  cleanupKeyboardInput();
+  console.error('Error:', error);
+  process.exit(1);
+});

package/src/cli/keyboard.ts

@@ -0,0 +1,143 @@
+/**
+ * Keyboard input handling for Elektron LFO CLI
+ */
+
+import type { Waveform, TriggerMode, Multiplier } from '../engine/types';
+import { VALID_MULTIPLIERS } from '../engine/types';
+
+const WAVEFORMS: Waveform[] = ['TRI', 'SIN', 'SQR', 'SAW', 'EXP', 'RMP', 'RND'];
+const TRIGGER_MODES: TriggerMode[] = ['FRE', 'TRG', 'HLD', 'ONE', 'HLF'];
+
+export type KeyAction =
+  | { type: 'trigger' }
+  | { type: 'quit' }
+  | { type: 'bpm'; delta: number }
+  | { type: 'speed'; delta: number }
+  | { type: 'waveform'; waveform: Waveform }
+  | { type: 'mode'; mode: TriggerMode }
+  | { type: 'multiplier'; multiplier: Multiplier }
+  | { type: 'depth'; delta: number }
+  | { type: 'fade'; delta: number }
+  | { type: 'unknown' };
+
+/**
+ * Parse a key input into an action
+ */
+export function parseKey(
+  key: Buffer,
+  currentWaveform: Waveform,
+  currentMode: TriggerMode,
+  currentMultiplier: Multiplier
+): KeyAction {
+  const keyStr = key.toString();
+
+  // Check for Ctrl+C
+  if (key[0] === 3) {
+    return { type: 'quit' };
+  }
+
+  // Check for escape sequences (arrow keys)
+  if (key[0] === 27 && key[1] === 91) {
+    switch (key[2]) {
+      case 65: // Up arrow
+        return { type: 'bpm', delta: 1 };
+      case 66: // Down arrow
+        return { type: 'bpm', delta: -1 };
+      case 67: // Right arrow
+        return { type: 'speed', delta: 1 };
+      case 68: // Left arrow
+        return { type: 'speed', delta: -1 };
+    }
+  }
+
+  // Single character commands
+  switch (keyStr.toLowerCase()) {
+    case ' ':
+      return { type: 'trigger' };
+
+    case 'q':
+      return { type: 'quit' };
+
+    case 'w': {
+      // Cycle to next waveform
+      const currentIndex = WAVEFORMS.indexOf(currentWaveform);
+      const nextIndex = (currentIndex + 1) % WAVEFORMS.length;
+      return { type: 'waveform', waveform: WAVEFORMS[nextIndex] };
+    }
+
+    case 'm': {
+      // Cycle to next mode
+      const currentIndex = TRIGGER_MODES.indexOf(currentMode);
+      const nextIndex = (currentIndex + 1) % TRIGGER_MODES.length;
+      return { type: 'mode', mode: TRIGGER_MODES[nextIndex] };
+    }
+
+    case '[': {
+      // Previous multiplier
+      const currentIndex = VALID_MULTIPLIERS.indexOf(currentMultiplier);
+      const prevIndex = Math.max(0, currentIndex - 1);
+      return { type: 'multiplier', multiplier: VALID_MULTIPLIERS[prevIndex] };
+    }
+
+    case ']': {
+      // Next multiplier
+      const currentIndex = VALID_MULTIPLIERS.indexOf(currentMultiplier);
+      const nextIndex = Math.min(VALID_MULTIPLIERS.length - 1, currentIndex + 1);
+      return { type: 'multiplier', multiplier: VALID_MULTIPLIERS[nextIndex] };
+    }
+
+    case '-':
+    case '_':
+      return { type: 'depth', delta: -1 };
+
+    case '=':
+    case '+':
+      return { type: 'depth', delta: 1 };
+
+    case ',':
+    case '<':
+      return { type: 'fade', delta: -1 };
+
+    case '.':
+    case '>':
+      return { type: 'fade', delta: 1 };
+
+    default:
+      return { type: 'unknown' };
+  }
+}
+
+/**
+ * Set up raw mode input handling
+ */
+export function setupKeyboardInput(
+  onKey: (key: Buffer) => void,
+  onExit: () => void
+): void {
+  // Enable raw mode for single keypress detection
+  if (process.stdin.isTTY) {
+    process.stdin.setRawMode(true);
+  }
+  process.stdin.resume();
+
+  process.stdin.on('data', (key: Buffer) => {
+    onKey(key);
+  });
+
+  // Handle process termination
+  process.on('SIGINT', onExit);
+  process.on('SIGTERM', onExit);
+}
+
+/**
+ * Clean up keyboard input handling
+ */
+export function cleanupKeyboardInput(): void {
+  if (process.stdin.isTTY) {
+    process.stdin.setRawMode(false);
+  }
+  process.stdin.pause();
+
+  // Clear screen and show cursor
+  process.stdout.write('\x1b[2J\x1b[H\x1b[?25h');
+}