dspx 0.1.1-alpha.0

package/src/ts/examples/redis-example.ts

@@ -0,0 +1,202 @@
+/**
+ * Example showing how to use Redis for DSP state persistence
+ *
+ * This demonstrates:
+ * 1. Creating a pipeline with Redis configuration
+ * 2. Processing audio data
+ * 3. Saving/loading state (when Redis integration is fully implemented)
+ *
+ * Note: This example shows the intended API. Full C++ Redis integration
+ * requires implementing saveState/loadState methods in DspPipeline.cc
+ */
+
+import { createClient } from "redis";
+import { createDspPipeline } from "../bindings";
+
+async function redisExample(startFresh = false) {
+  console.log("=== DSP Pipeline with Redis State Persistence ===\n");
+
+  // 1. Create Redis client
+  const redis = await createClient({ url: "redis://localhost:6379" }).connect();
+
+  // 2. Create DSP pipeline with Redis configuration
+  const stateKey = "dsp:pipeline:channel1";
+
+  // Optional: Clear previous state to start fresh
+  if (startFresh) {
+    console.log("Clearing previous state to start fresh...");
+    await redis.del(stateKey);
+    console.log("State cleared\n");
+  }
+
+  const pipeline = createDspPipeline({
+    redisHost: "localhost",
+    redisPort: 6379,
+    stateKey: stateKey,
+  });
+
+  // 3. Build the pipeline
+  pipeline.MovingAverage({ mode: "moving", windowSize: 3 });
+
+  console.log("Pipeline created with moving average filter (window=3)");
+
+  // 4. Try to restore previous state (if exists)
+  const previousState = await redis.get(stateKey);
+  if (previousState) {
+    console.log("Found previous state in Redis, restoring...");
+    await pipeline.loadState(previousState);
+    console.log("State restored successfully!");
+  } else {
+    console.log("No previous state found in Redis");
+  }
+
+  // 5. First batch of audio
+  console.log("\n--- Processing first batch ---");
+  const batch1 = new Float32Array([1, 2, 3, 4, 5]);
+  console.log("Input batch 1:", Array.from(batch1));
+
+  const output1 = await pipeline.processCopy(batch1, {
+    sampleRate: 1000,
+    channels: 1,
+  });
+  console.log("Output batch 1:", Array.from(output1));
+
+  // 6. Save state to Redis
+  console.log("\n--- Saving state to Redis ---");
+  const state = await pipeline.saveState();
+  await redis.set(stateKey, state);
+  console.log("State saved:", state);
+
+  // 7. Simulate stopping and restarting the process
+  console.log("\n--- Simulating restart ---");
+
+  // 8. Create new pipeline and restore state
+  const pipeline2 = createDspPipeline({
+    redisHost: "localhost",
+    redisPort: 6379,
+    stateKey: stateKey,
+  });
+
+  pipeline2.MovingAverage({ mode: "moving", windowSize: 3 });
+
+  const restoredState = await redis.get(stateKey);
+  if (restoredState) {
+    console.log("Restored state from Redis");
+    await pipeline2.loadState(restoredState);
+    console.log(
+      "State restoration complete - continuing from where we left off!"
+    );
+  }
+
+  // 9. Continue processing with restored state
+  console.log("\n--- Processing second batch (after 'restart') ---");
+  const batch2 = new Float32Array([6, 7, 8]);
+  console.log("Input batch 2:", Array.from(batch2));
+
+  const output2 = await pipeline2.processCopy(batch2, {
+    sampleRate: 1000,
+    channels: 1,
+  });
+  console.log("Output batch 2:", Array.from(output2));
+
+  console.log(
+    "\nNote: With state restoration, batch2 continues the moving average from where batch1 left off!"
+  );
+  console.log(
+    "Expected output without state: [6, 6.5, 7] - but we got continuous averaging!"
+  );
+
+  // 10. Optional: Clear state (commented out to persist between runs)
+  // console.log("\n--- Clearing state ---");
+  // await redis.del(stateKey);
+  // pipeline2.clearState();
+  // console.log("State cleared from Redis");
+
+  // Disconnect from Redis
+  await redis.disconnect();
+} // Real-world use case example
+async function streamingExample(startFresh = false) {
+  console.log("\n\n=== Streaming Audio Processing Example ===\n");
+
+  const redis = await createClient({ url: "redis://localhost:6379" }).connect();
+  const channelId = "audio-stream-ch1";
+  const stateKey = `dsp:stream:${channelId}`;
+
+  // Optional: Clear previous state to start fresh
+  if (startFresh) {
+    console.log("Clearing previous streaming state to start fresh...");
+    await redis.del(stateKey);
+    console.log("Streaming state cleared\n");
+  }
+
+  // Create pipeline
+  const pipeline = createDspPipeline({
+    redisHost: "localhost",
+    redisPort: 6379,
+    stateKey: stateKey,
+  });
+
+  pipeline.MovingAverage({ mode: "moving", windowSize: 5 });
+
+  // Restore state if processing was interrupted
+  const savedState = await redis.get(stateKey);
+  if (savedState) {
+    console.log("Resuming from saved state...");
+    await pipeline.loadState(savedState);
+  }
+
+  // Simulate streaming audio chunks
+  const chunks = [
+    new Float32Array([1, 2, 3, 4, 5]),
+    new Float32Array([6, 7, 8, 9, 10]),
+    new Float32Array([11, 12, 13, 14, 15]),
+  ];
+
+  console.log("Processing audio stream in chunks...\n");
+
+  for (let i = 0; i < chunks.length; i++) {
+    const chunk = chunks[i];
+    console.log(`Chunk ${i + 1} input:`, Array.from(chunk));
+
+    const processed = await pipeline.processCopy(chunk, {
+      sampleRate: 44100,
+      channels: 1,
+    });
+
+    console.log(`Chunk ${i + 1} output:`, Array.from(processed));
+
+    // Save state after each chunk (for crash recovery)
+    const state = await pipeline.saveState();
+    await redis.set(stateKey, state);
+    console.log(`State saved after chunk ${i + 1}\n`);
+  }
+
+  console.log("Stream processing complete. State saved for next session.");
+
+  // Disconnect from Redis
+  await redis.disconnect();
+}
+
+// Run examples
+console.log("Running DSP + Redis examples...\n");
+
+// Set to true to clear previous state and start fresh
+// Set to false to demonstrate state persistence across runs
+const START_FRESH = false;
+
+redisExample(START_FRESH)
+  .then(() => streamingExample(START_FRESH))
+  .then(() => {
+    console.log("\nAll examples completed successfully!");
+    console.log(
+      "\nTip: Set START_FRESH = true to clear Redis state and start fresh"
+    );
+    console.log(
+      "Tip: Set START_FRESH = false to see state persistence across runs"
+    );
+    process.exit(0);
+  })
+  .catch((error) => {
+    console.error("\nError:", error);
+    process.exit(1);
+  });

package/src/ts/examples/simd-benchmark.ts

@@ -0,0 +1,126 @@
+/**
+ * SIMD Performance Benchmark
+ *
+ * This benchmark demonstrates the performance of SIMD-accelerated operations.
+ *
+ * Run with: npm test (to see it passes), then check operation timings
+ *
+ * Note: For accurate benchmarks, build in Release mode and run multiple times
+ * to account for V8 JIT compilation and CPU thermal throttling.
+ */
+
+import { createDspPipeline } from "../bindings.js";
+
+console.log("🚀 SIMD Performance Demonstration");
+console.log("===================================\n");
+
+async function demonstrateSIMD() {
+  const BUFFER_SIZE = 100000; // 100k samples
+  const ITERATIONS = 50;
+
+  // Create test signal with mixed positive/negative values
+  const signal = new Float32Array(BUFFER_SIZE);
+  for (let i = 0; i < BUFFER_SIZE; i++) {
+    signal[i] = Math.sin(i * 0.1) * 100 + Math.cos(i * 0.05) * 50;
+  }
+
+  console.log(`📊 Test Configuration:`);
+  console.log(`  • Buffer size: ${BUFFER_SIZE.toLocaleString()} samples`);
+  console.log(`  • Iterations: ${ITERATIONS}`);
+  console.log(
+    `  • Total samples: ${(BUFFER_SIZE * ITERATIONS).toLocaleString()}\n`
+  );
+
+  // Test 1: Rectify (SIMD-accelerated)
+  console.log("🔧 Test 1: Rectify (Full-Wave) - SIMD Accelerated");
+  const processor1 = createDspPipeline();
+  processor1.Rectify({ mode: "full" });
+
+  const start1 = performance.now();
+  for (let i = 0; i < ITERATIONS; i++) {
+    const buffer = signal.slice();
+    await processor1.process(buffer, { channels: 1 });
+  }
+  const end1 = performance.now();
+  const time1 = end1 - start1;
+  const throughput1 = ((BUFFER_SIZE * ITERATIONS) / time1) * 1000;
+
+  console.log(`  ✅ Time: ${time1.toFixed(2)} ms`);
+  console.log(
+    `  ✅ Throughput: ${(throughput1 / 1_000_000).toFixed(2)} M samples/sec\n`
+  );
+
+  // Test 2: Batch Average (SIMD-accelerated for single channel)
+  console.log("🔧 Test 2: Batch Average - SIMD Accelerated");
+  const processor2 = createDspPipeline();
+  processor2.MovingAverage({ mode: "batch" });
+
+  const start2 = performance.now();
+  for (let i = 0; i < ITERATIONS; i++) {
+    const buffer = signal.slice();
+    await processor2.process(buffer, { channels: 1 });
+  }
+  const end2 = performance.now();
+  const time2 = end2 - start2;
+  const throughput2 = ((BUFFER_SIZE * ITERATIONS) / time2) * 1000;
+
+  console.log(`  ✅ Time: ${time2.toFixed(2)} ms`);
+  console.log(
+    `  ✅ Throughput: ${(throughput2 / 1_000_000).toFixed(2)} M samples/sec\n`
+  );
+
+  // Test 3: Batch RMS (SIMD-accelerated for single channel)
+  console.log("🔧 Test 3: Batch RMS - SIMD Accelerated");
+  const processor3 = createDspPipeline();
+  processor3.Rms({ mode: "batch" });
+
+  const start3 = performance.now();
+  for (let i = 0; i < ITERATIONS; i++) {
+    const buffer = signal.slice();
+    await processor3.process(buffer, { channels: 1 });
+  }
+  const end3 = performance.now();
+  const time3 = end3 - start3;
+  const throughput3 = ((BUFFER_SIZE * ITERATIONS) / time3) * 1000;
+
+  console.log(`  ✅ Time: ${time3.toFixed(2)} ms`);
+  console.log(
+    `  ✅ Throughput: ${(throughput3 / 1_000_000).toFixed(2)} M samples/sec\n`
+  );
+
+  console.log("─".repeat(60));
+  console.log("\n📈 SIMD Optimization Summary:\n");
+  console.log("✨ What makes these operations fast:");
+  console.log("  1. Compiler optimizations (-O3, /O2, -ffast-math)");
+  console.log("  2. SIMD intrinsics (AVX2/SSE2/NEON)");
+  console.log("  3. Zero-copy processing (in-place modification)");
+  console.log("  4. C++ Native code (no JavaScript overhead)\n");
+
+  console.log("🎯 Platform-specific SIMD support:");
+  console.log("  • x86/x64 + AVX2:  8 floats/cycle  → 4-8x speedup");
+  console.log("  • x86/x64 + SSE2:  4 floats/cycle  → 2-4x speedup");
+  console.log("  • ARM + NEON:      4 floats/cycle  → 2-4x speedup");
+  console.log(
+    "  • Scalar fallback: 1 float/cycle   → compiler auto-vectorizes\n"
+  );
+
+  console.log("💡 Best performance tips:");
+  console.log("  • Use single-channel data when possible (contiguous memory)");
+  console.log("  • Prefer batch mode for one-time calculations");
+  console.log("  • Use moving mode only when state continuity is needed");
+  console.log("  • Process larger buffers to amortize overhead\n");
+
+  console.log("� For more details, see:");
+  console.log("  docs/SIMD_OPTIMIZATIONS.md\n");
+}
+
+// Run demonstration
+demonstrateSIMD()
+  .then(() => {
+    console.log("✅ Demonstration complete\n");
+    process.exit(0);
+  })
+  .catch((error) => {
+    console.error("❌ Demonstration failed:", error);
+    process.exit(1);
+  });

package/src/ts/examples/tap-debugging.ts

@@ -0,0 +1,230 @@
+/**
+ * Example: Using .tap() for Pipeline Debugging
+ * Demonstrates how to inspect intermediate results at any point in the pipeline
+ */
+
+import { createDspPipeline } from "../index.js";
+
+console.log("🔍 Pipeline Debugging with .tap()\n");
+
+// Example 1: Basic inspection
+console.log("Example 1: Basic Inspection");
+const pipeline1 = createDspPipeline()
+  .MovingAverage({ mode: "moving", windowSize: 3 })
+  .tap((samples, stage) => {
+    console.log(`  After ${stage}:`);
+    console.log(
+      `    First 5 samples: [${Array.from(samples.slice(0, 5))
+        .map((v) => v.toFixed(2))
+        .join(", ")}]`
+    );
+    console.log(`    Length: ${samples.length}`);
+  })
+  .Rectify({ mode: "full" })
+  .tap((samples, stage) => {
+    console.log(`  After ${stage}:`);
+    console.log(
+      `    First 5 samples: [${Array.from(samples.slice(0, 5))
+        .map((v) => v.toFixed(2))
+        .join(", ")}]`
+    );
+  });
+
+const input1 = Float32Array.from(
+  { length: 10 },
+  (_, i) => Math.sin(i * 0.5) - 0.5
+);
+await pipeline1.process(input1, { sampleRate: 1000 });
+
+// Example 2: Conditional alerts based on thresholds
+console.log("\n\nExample 2: Threshold Monitoring");
+const THRESHOLD = 0.8;
+let alertCount = 0;
+
+const pipeline2 = createDspPipeline()
+  .MovingAverage({ mode: "moving", windowSize: 5 })
+  .Rectify({ mode: "full" })
+  .Rms({ mode: "moving", windowSize: 10 })
+  .tap((samples, stage) => {
+    const max = Math.max(...samples);
+    const avg = samples.reduce((a, b) => a + b, 0) / samples.length;
+
+    console.log(`  Stats after ${stage}:`);
+    console.log(`     Max: ${max.toFixed(4)}, Avg: ${avg.toFixed(4)}`);
+
+    if (max > THRESHOLD) {
+      alertCount++;
+      console.log(
+        `     🚨 ALERT: Max value ${max.toFixed(
+          4
+        )} exceeds threshold ${THRESHOLD}`
+      );
+    }
+  });
+
+const input2 = Float32Array.from(
+  { length: 50 },
+  (_, i) => Math.sin(i * 0.3) * (1 + Math.random() * 0.5)
+);
+await pipeline2.process(input2, { sampleRate: 1000 });
+console.log(`\n  Total alerts: ${alertCount}`);
+
+// Example 3: Multiple taps in complex pipeline
+console.log("\n\n🔗 Example 3: Multi-Stage Inspection");
+const stages: Array<{
+  name: string;
+  stats: { min: number; max: number; mean: number };
+}> = [];
+
+const pipeline3 = createDspPipeline()
+  .tap((samples) => {
+    const stats = {
+      min: Math.min(...samples),
+      max: Math.max(...samples),
+      mean: samples.reduce((a, b) => a + b, 0) / samples.length,
+    };
+    stages.push({ name: "raw input", stats });
+  })
+  .MovingAverage({ mode: "moving", windowSize: 5 })
+  .tap((samples, stage) => {
+    const stats = {
+      min: Math.min(...samples),
+      max: Math.max(...samples),
+      mean: samples.reduce((a, b) => a + b, 0) / samples.length,
+    };
+    stages.push({ name: stage, stats });
+  })
+  .Rectify({ mode: "full" })
+  .tap((samples, stage) => {
+    const stats = {
+      min: Math.min(...samples),
+      max: Math.max(...samples),
+      mean: samples.reduce((a, b) => a + b, 0) / samples.length,
+    };
+    stages.push({ name: stage, stats });
+  })
+  .Rms({ mode: "moving", windowSize: 3 })
+  .tap((samples, stage) => {
+    const stats = {
+      min: Math.min(...samples),
+      max: Math.max(...samples),
+      mean: samples.reduce((a, b) => a + b, 0) / samples.length,
+    };
+    stages.push({ name: stage, stats });
+  });
+
+const input3 = Float32Array.from(
+  { length: 100 },
+  (_, i) => Math.sin(i * 0.1) * 2 - 1
+);
+await pipeline3.process(input3, { sampleRate: 1000 });
+
+console.log("\n  Pipeline Statistics Table:");
+console.log(
+  "  ┌─────────────────────────────────┬──────────┬──────────┬──────────┐"
+);
+console.log(
+  "  │ Stage                           │ Min      │ Max      │ Mean     │"
+);
+console.log(
+  "  ├─────────────────────────────────┼──────────┼──────────┼──────────┤"
+);
+stages.forEach(({ name, stats }) => {
+  const paddedName = name.padEnd(31);
+  console.log(
+    `  │ ${paddedName} │ ${stats.min.toFixed(4).padStart(8)} │ ${stats.max
+      .toFixed(4)
+      .padStart(8)} │ ${stats.mean.toFixed(4).padStart(8)} │`
+  );
+});
+console.log(
+  "  └─────────────────────────────────┴──────────┴──────────┴──────────┘"
+);
+
+// Example 4: Debugging with logger integration
+console.log("\n\nExample 4: Logger Integration");
+const logger = {
+  debug: (msg: string, data?: any) =>
+    console.log(`  [DEBUG] ${msg}`, data || ""),
+  info: (msg: string, data?: any) =>
+    console.log(`  [INFO]  ${msg}`, data || ""),
+  warn: (msg: string, data?: any) =>
+    console.log(`  [WARN]  ${msg}`, data || ""),
+};
+
+const pipeline4 = createDspPipeline()
+  .MovingAverage({ mode: "moving", windowSize: 10 })
+  .tap((samples, stage) =>
+    logger.debug(`Processed ${stage}`, { sampleCount: samples.length })
+  )
+  .Rectify()
+  .tap((samples, stage) => {
+    const hasNegative = samples.some((v) => v < 0);
+    if (hasNegative) {
+      logger.warn(`Unexpected negative values after ${stage}`);
+    } else {
+      logger.info(`${stage} completed successfully`);
+    }
+  })
+  .Rms({ mode: "moving", windowSize: 5 })
+  .tap((samples, stage) => {
+    const max = Math.max(...samples);
+    logger.debug(`Max RMS value`, { value: max.toFixed(4) });
+  });
+
+const input4 = Float32Array.from({ length: 20 }, (_, i) => Math.cos(i * 0.2));
+await pipeline4.process(input4, { sampleRate: 1000 });
+
+// Example 5: Performance impact measurement
+console.log("\n\nExample 5: Performance Impact of .tap()");
+const iterations = 1000;
+const sampleSize = 1000;
+
+// Without tap
+const pipelineNoTap = createDspPipeline()
+  .MovingAverage({ mode: "moving", windowSize: 10 })
+  .Rectify()
+  .Rms({ mode: "moving", windowSize: 5 });
+
+const startNoTap = performance.now();
+for (let i = 0; i < iterations; i++) {
+  const input = Float32Array.from({ length: sampleSize }, () => Math.random());
+  await pipelineNoTap.process(input, { sampleRate: 1000 });
+}
+const durationNoTap = performance.now() - startNoTap;
+
+// With tap (minimal work)
+const pipelineWithTap = createDspPipeline()
+  .MovingAverage({ mode: "moving", windowSize: 10 })
+  .tap(() => {}) // Empty tap
+  .Rectify()
+  .tap(() => {}) // Empty tap
+  .Rms({ mode: "moving", windowSize: 5 })
+  .tap(() => {}); // Empty tap
+
+const startWithTap = performance.now();
+for (let i = 0; i < iterations; i++) {
+  const input = Float32Array.from({ length: sampleSize }, () => Math.random());
+  await pipelineWithTap.process(input, { sampleRate: 1000 });
+}
+const durationWithTap = performance.now() - startWithTap;
+
+console.log(
+  `  Without .tap(): ${durationNoTap.toFixed(2)}ms for ${iterations} iterations`
+);
+console.log(
+  `  With .tap():    ${durationWithTap.toFixed(
+    2
+  )}ms for ${iterations} iterations`
+);
+console.log(
+  `  Overhead:       ${(durationWithTap - durationNoTap).toFixed(2)}ms (${(
+    (durationWithTap / durationNoTap - 1) *
+    100
+  ).toFixed(2)}%)`
+);
+console.log(
+  `\n  Tip: Remove .tap() calls in production or use conditional logic`
+);
+
+console.log("\nAll examples completed!");