dspx 0.1.1-alpha.0

package/src/ts/examples/fft-examples.ts

@@ -0,0 +1,349 @@
+/**
+ * FFT Examples - Demonstrating Radix-2 Handling and Windowing
+ *
+ * This example demonstrates:
+ * 1. Power-of-2 requirement and auto-padding
+ * 2. FFT vs DFT performance comparison
+ * 3. Windowing for spectral leakage reduction
+ * 4. Practical audio analysis scenarios
+ */
+
+import {
+  FftProcessor,
+  MovingFftProcessor,
+  FftUtils,
+  type ComplexArray,
+} from "../fft.js";
+
+console.log("=== FFT Examples: Radix-2 and Windowing ===\n");
+
+// ============================================================
+// Example 1: Power-of-2 Requirement
+// ============================================================
+
+console.log("--- Example 1: Power-of-2 Requirement ---");
+
+// Generate a signal with non-power-of-2 length
+const signalLength = 1000; // Not a power of 2!
+const rawSignal = new Float32Array(signalLength);
+for (let i = 0; i < signalLength; i++) {
+  rawSignal[i] = Math.sin((2 * Math.PI * 10 * i) / 1000); // 10 Hz sine wave
+}
+
+console.log(`Original signal length: ${signalLength}`);
+console.log(`Is power of 2: ${FftUtils.isPowerOfTwo(signalLength)}`);
+
+// Try to use FFT directly (this will fail)
+try {
+  const badFft = new FftProcessor(signalLength);
+  badFft.rfft(rawSignal);
+  console.log("❌ This should have thrown an error!");
+} catch (error) {
+  console.log(`✅ Expected error: ${(error as Error).message}`);
+}
+
+// Solution 1: Auto-padding (recommended)
+console.log("\n✅ Solution 1: Auto-padding");
+const padded = FftUtils.padToPowerOfTwo(rawSignal);
+console.log(`Padded length: ${padded.length}`);
+console.log(`Is power of 2: ${FftUtils.isPowerOfTwo(padded.length)}`);
+
+const fftWithPadding = new FftProcessor(padded.length);
+const spectrum1 = fftWithPadding.rfft(padded);
+console.log(`Spectrum size: ${spectrum1.real.length} bins`);
+
+// Solution 2: Use DFT (slower but exact)
+console.log("\n✅ Solution 2: Use DFT");
+const dftProcessor = new FftProcessor(signalLength);
+const spectrum2 = dftProcessor.rdft(rawSignal);
+console.log(`Spectrum size: ${spectrum2.real.length} bins`);
+
+// ============================================================
+// Example 2: FFT vs DFT Performance Comparison
+// ============================================================
+
+console.log("\n--- Example 2: FFT vs DFT Performance ---");
+
+const sizes = [256, 1024, 4096];
+
+for (const size of sizes) {
+  const testSignal = new Float32Array(size);
+  for (let i = 0; i < size; i++) {
+    testSignal[i] = Math.random();
+  }
+
+  // FFT timing
+  const fft = new FftProcessor(size);
+  const fftStart = performance.now();
+  for (let i = 0; i < 100; i++) {
+    fft.rfft(testSignal);
+  }
+  const fftTime = (performance.now() - fftStart) / 100;
+
+  // DFT timing
+  const dft = new FftProcessor(size);
+  const dftStart = performance.now();
+  for (let i = 0; i < 10; i++) {
+    // Only 10 iterations for DFT (it's slow!)
+    dft.rdft(testSignal);
+  }
+  const dftTime = (performance.now() - dftStart) / 10;
+
+  const speedup = dftTime / fftTime;
+  console.log(
+    `Size ${size}: FFT=${fftTime.toFixed(3)}ms, DFT=${dftTime.toFixed(
+      3
+    )}ms, Speedup=${speedup.toFixed(1)}x`
+  );
+}
+
+// ============================================================
+// Example 3: Windowing for Spectral Leakage Reduction
+// ============================================================
+
+console.log("\n--- Example 3: Windowing Effects ---");
+
+const fftSize = 1024;
+const sampleRate = 8000; // 8 kHz
+
+// Generate a pure tone (100 Hz) with some noise
+const pureSignal = new Float32Array(fftSize);
+const targetFreq = 100; // Hz
+for (let i = 0; i < fftSize; i++) {
+  pureSignal[i] =
+    Math.sin((2 * Math.PI * targetFreq * i) / sampleRate) + 0.1 * Math.random(); // Add 10% noise
+}
+
+console.log(
+  `\nAnalyzing ${targetFreq} Hz tone at ${sampleRate} Hz sample rate`
+);
+
+// Test different window types
+const windowTypes = ["none", "hann", "hamming", "blackman"] as const;
+
+for (const windowType of windowTypes) {
+  const fft = new MovingFftProcessor({
+    fftSize,
+    windowType,
+    realInput: true,
+  });
+
+  // Add all samples at once
+  fft.addSamples(pureSignal, () => {});
+
+  // Force computation
+  fft.computeSpectrum();
+  const magnitudes = fft.getMagnitudeSpectrum();
+  const freqs = fft.getFrequencyBins(sampleRate);
+
+  // Find peak
+  let maxIdx = 0;
+  let maxMag = 0;
+  for (let i = 0; i < magnitudes.length; i++) {
+    if (magnitudes[i] > maxMag) {
+      maxMag = magnitudes[i];
+      maxIdx = i;
+    }
+  }
+
+  const peakFreq = freqs[maxIdx];
+
+  // Calculate total power in neighboring bins (leakage indicator)
+  let leakagePower = 0;
+  const peakBin = Math.round((targetFreq * fftSize) / sampleRate);
+  for (let i = peakBin - 5; i <= peakBin + 5; i++) {
+    if (i >= 0 && i < magnitudes.length && i !== peakBin) {
+      leakagePower += magnitudes[i] * magnitudes[i];
+    }
+  }
+
+  console.log(
+    `Window: ${windowType.padEnd(8)} | Peak: ${peakFreq.toFixed(
+      2
+    )} Hz | Leakage: ${leakagePower.toFixed(6)}`
+  );
+}
+
+// ============================================================
+// Example 4: Practical Audio Spectral Analysis
+// ============================================================
+
+console.log("\n--- Example 4: Audio Spectral Analysis ---");
+
+// Simulate audio with multiple frequencies
+const audioLength = 4096;
+const audioSampleRate = 44100; // 44.1 kHz
+const audioSignal = new Float32Array(audioLength);
+
+// Mix: 440 Hz (A4) + 880 Hz (A5) + 1320 Hz (E6)
+const frequencies = [440, 880, 1320];
+for (let i = 0; i < audioLength; i++) {
+  audioSignal[i] = 0;
+  for (const freq of frequencies) {
+    audioSignal[i] +=
+      Math.sin((2 * Math.PI * freq * i) / audioSampleRate) / frequencies.length;
+  }
+}
+
+// Analyze with Hann windowing (standard for audio)
+const audioFft = new MovingFftProcessor({
+  fftSize: audioLength,
+  windowType: "hann", // ✅ Recommended for audio
+  realInput: true,
+});
+
+audioFft.addSamples(audioSignal, () => {});
+audioFft.computeSpectrum();
+
+const audioMagnitudes = audioFft.getMagnitudeSpectrum();
+const audioFreqs = audioFft.getFrequencyBins(audioSampleRate);
+const audioDb = FftUtils.toDecibels(audioMagnitudes);
+
+// Find top 3 peaks
+interface Peak {
+  frequency: number;
+  magnitude: number;
+  db: number;
+}
+
+const peaks: Peak[] = [];
+for (let i = 1; i < audioMagnitudes.length - 1; i++) {
+  // Local maxima
+  if (
+    audioMagnitudes[i] > audioMagnitudes[i - 1] &&
+    audioMagnitudes[i] > audioMagnitudes[i + 1]
+  ) {
+    if (audioMagnitudes[i] > 0.01) {
+      // Threshold
+      peaks.push({
+        frequency: audioFreqs[i],
+        magnitude: audioMagnitudes[i],
+        db: audioDb[i],
+      });
+    }
+  }
+}
+
+peaks.sort((a, b) => b.magnitude - a.magnitude);
+
+console.log("\nDetected frequencies:");
+for (let i = 0; i < Math.min(3, peaks.length); i++) {
+  console.log(
+    `${i + 1}. ${peaks[i].frequency.toFixed(2)} Hz (${peaks[i].db.toFixed(
+      2
+    )} dB, mag=${peaks[i].magnitude.toFixed(4)})`
+  );
+}
+
+// ============================================================
+// Example 5: Streaming Spectrogram
+// ============================================================
+
+console.log("\n--- Example 5: Streaming Spectrogram ---");
+
+const spectrogramFft = new MovingFftProcessor({
+  fftSize: 512,
+  hopSize: 128, // 75% overlap
+  mode: "batched",
+  windowType: "hann",
+  realInput: true,
+});
+
+// Simulate streaming audio (2 seconds at 8 kHz)
+const streamDuration = 2.0; // seconds
+const streamSampleRate = 8000;
+const totalSamples = streamDuration * streamSampleRate;
+const chunkSize = 512;
+
+console.log(
+  `\nStreaming ${streamDuration}s of audio at ${streamSampleRate} Hz`
+);
+console.log(`Chunk size: ${chunkSize}, FFT size: 512, Hop: 128 (75% overlap)`);
+
+let frameCount = 0;
+for (let offset = 0; offset < totalSamples; offset += chunkSize) {
+  const chunk = new Float32Array(chunkSize);
+
+  // Generate chunk: sweep from 100 Hz to 2000 Hz over 2 seconds
+  for (let i = 0; i < chunkSize; i++) {
+    const t = (offset + i) / streamSampleRate;
+    const freq = 100 + (1900 * t) / streamDuration; // Linear sweep
+    chunk[i] = Math.sin(2 * Math.PI * freq * t);
+  }
+
+  // Process chunk
+  const numFrames = spectrogramFft.addSamples(
+    chunk,
+    (_spectrum: ComplexArray, _size: number) => {
+      frameCount++;
+    }
+  );
+
+  if (numFrames > 0) {
+    const mags = spectrogramFft.getMagnitudeSpectrum();
+    const freqs = spectrogramFft.getFrequencyBins(streamSampleRate);
+
+    // Find peak in current frame
+    let maxIdx = 0;
+    let maxMag = 0;
+    for (let i = 0; i < mags.length; i++) {
+      if (mags[i] > maxMag) {
+        maxMag = mags[i];
+        maxIdx = i;
+      }
+    }
+
+    const peakFreq = freqs[maxIdx];
+
+    // Only print every 10th frame
+    if (frameCount % 10 === 0) {
+      console.log(`Frame ${frameCount}: Peak at ${peakFreq.toFixed(2)} Hz`);
+    }
+  }
+}
+
+console.log(`Total spectrogram frames: ${frameCount}`);
+
+// ============================================================
+// Example 6: Zero-Padding Effects
+// ============================================================
+
+console.log("\n--- Example 6: Zero-Padding Effects ---");
+
+// Short signal
+const shortSignal = new Float32Array(100);
+for (let i = 0; i < 100; i++) {
+  shortSignal[i] = Math.sin((2 * Math.PI * 5 * i) / 100);
+}
+
+console.log("\nOriginal signal: 100 samples");
+const paddedSizes = [128, 256, 512, 1024];
+
+for (const padSize of paddedSizes) {
+  const padded = FftUtils.zeroPad(shortSignal, padSize);
+  const fft = new FftProcessor(padded.length);
+  const spectrum = fft.rfft(padded);
+
+  console.log(
+    `Padded to ${padSize}: ${spectrum.real.length} frequency bins (spectral interpolation)`
+  );
+}
+
+console.log(
+  "\n⚠️  Note: More bins ≠ better resolution! Resolution is determined by original signal length."
+);
+
+// ============================================================
+// Summary
+// ============================================================
+
+console.log("\n=== Summary ===");
+console.log("✅ Use FftUtils.padToPowerOfTwo() for non-power-of-2 signals");
+console.log("✅ FFT is 100-1000x faster than DFT for large signals");
+console.log(
+  "✅ Always use windowing (hann, hamming, blackman) to reduce spectral leakage"
+);
+console.log("✅ Hann window is recommended for general audio analysis");
+console.log("✅ Use 50-75% overlap for smooth spectrograms");
+console.log("✅ Zero-padding increases bins but NOT spectral resolution");
+console.log("\n📚 See docs/FFT_USER_GUIDE.md for detailed explanations");

package/src/ts/examples/filter-examples.ts

@@ -0,0 +1,320 @@
+/**
+ * Filter Design Examples
+ *
+ * Demonstrates the filter API:
+ * - FIR filters (low-pass, high-pass, band-pass, band-stop)
+ * - IIR filters (Butterworth, Chebyshev, Biquad EQ)
+ * - Direct class methods for creating filters
+ */
+
+import { FirFilter, IirFilter } from "../filters.js";
+
+console.log("=== Filter Design Examples ===\n");
+
+const sampleRate = 8000; // 8 kHz
+
+// ============================================================
+// Example 1: FIR Low-Pass Filter
+// ============================================================
+
+console.log("--- Example 1: FIR Low-Pass Filter ---");
+
+// Using class static method
+const firLowpass1 = FirFilter.createLowPass({
+  cutoffFrequency: 1000,
+  sampleRate,
+  order: 51,
+  windowType: "hamming",
+});
+
+console.log(`✅ FIR Low-pass (1000 Hz, order 51)`);
+console.log(`   Coefficients: ${firLowpass1.getCoefficients().length} taps`);
+
+// Method 2: Using class static method (direct)
+const firLowpass2 = FirFilter.createLowPass({
+  cutoffFrequency: 1000,
+  sampleRate,
+  order: 51,
+  windowType: "hamming",
+});
+
+console.log(`✅ Same filter using FirFilter.createLowPass()`);
+
+// Test with sample data
+const testSignal = new Float32Array(100);
+for (let i = 0; i < testSignal.length; i++) {
+  // Mix 500 Hz (pass) + 2000 Hz (reject)
+  testSignal[i] =
+    Math.sin((2 * Math.PI * 500 * i) / sampleRate) +
+    Math.sin((2 * Math.PI * 2000 * i) / sampleRate);
+}
+
+const filtered = await firLowpass1.process(testSignal);
+console.log(
+  `   Filtered ${testSignal.length} samples (2 kHz component attenuated)\n`
+);
+
+// ============================================================
+// Example 2: FIR High-Pass Filter
+// ============================================================
+
+console.log("--- Example 2: FIR High-Pass Filter ---");
+
+const firHighpass = FirFilter.createHighPass({
+  cutoffFrequency: 2000,
+  sampleRate,
+  order: 61,
+  windowType: "hann",
+});
+
+console.log(`✅ FIR High-pass (2000 Hz, order 61, Hann window)`);
+console.log(`   Coefficients: ${firHighpass.getCoefficients().length} taps\n`);
+
+// ============================================================
+// Example 3: FIR Band-Pass Filter (Voice Band)
+// ============================================================
+
+console.log("--- Example 3: FIR Band-Pass Filter (Voice Band) ---");
+
+const voiceBandpass = FirFilter.createBandPass({
+  lowCutoffFrequency: 300,
+  highCutoffFrequency: 3400,
+  sampleRate,
+  order: 101,
+  windowType: "blackman",
+});
+
+console.log(`✅ Voice band-pass (300-3400 Hz, order 101, Blackman window)`);
+console.log(`   Coefficients: ${voiceBandpass.getCoefficients().length} taps`);
+console.log(`   Use case: Telephone/voice communication\n`);
+
+// ============================================================
+// Example 4: FIR Band-Stop (Notch) Filter
+// ============================================================
+
+console.log("--- Example 4: FIR Band-Stop (Notch) Filter ---");
+
+// Remove 50 Hz powerline hum
+const notch50Hz = FirFilter.createBandStop({
+  lowCutoffFrequency: 48,
+  highCutoffFrequency: 52,
+  sampleRate,
+  order: 201,
+  windowType: "hamming",
+});
+
+console.log(`✅ 50 Hz notch filter (48-52 Hz, order 201)`);
+console.log(`   Coefficients: ${notch50Hz.getCoefficients().length} taps`);
+console.log(`   Use case: Remove powerline interference\n`);
+
+// ============================================================
+// Example 5: Butterworth Low-Pass Filter
+// ============================================================
+
+console.log("--- Example 5: Butterworth Low-Pass Filter ---");
+
+const butterworthLowpass = IirFilter.createButterworthLowPass({
+  cutoffFrequency: 1000,
+  sampleRate,
+  order: 4,
+});
+
+console.log(`✅ Butterworth low-pass (1000 Hz, 4th-order)`);
+console.log(
+  `   B coefficients: ${butterworthLowpass.getBCoefficients().length}`
+);
+console.log(
+  `   A coefficients: ${butterworthLowpass.getACoefficients().length}`
+);
+console.log(`   Stable: ${butterworthLowpass.isStable()}`);
+console.log(`   Characteristics: Maximally flat passband\n`);
+
+// ============================================================
+// Example 6: Butterworth High-Pass Filter
+// ============================================================
+
+console.log("--- Example 6: Butterworth High-Pass Filter ---");
+
+const butterworthHighpass = IirFilter.createButterworthHighPass({
+  cutoffFrequency: 500,
+  sampleRate,
+  order: 2,
+});
+
+console.log(`✅ Butterworth high-pass (500 Hz, 2nd-order)`);
+console.log(`   Use case: Remove DC offset and low-frequency drift\n`);
+
+// ============================================================
+// Example 7: Butterworth Band-Pass Filter
+// ============================================================
+
+console.log("--- Example 7: Butterworth Band-Pass Filter ---");
+
+const butterworthBandpass = IirFilter.createButterworthBandPass({
+  lowCutoffFrequency: 1000,
+  highCutoffFrequency: 2000,
+  sampleRate,
+  order: 3,
+});
+
+console.log(`✅ Butterworth band-pass (1000-2000 Hz, 3rd-order)`);
+console.log(
+  `   Total order: ${butterworthBandpass.getOrder()} (2x3 = 6th-order)`
+);
+console.log(`   Use case: Extract specific frequency band\n`);
+
+// ============================================================
+// Example 8: First-Order IIR Filters
+// ============================================================
+
+console.log("--- Example 8: First-Order IIR Filters ---");
+
+const simpleLP = IirFilter.createFirstOrderLowPass({
+  cutoffFrequency: 1000,
+  sampleRate,
+});
+
+const simpleHP = IirFilter.createFirstOrderHighPass({
+  cutoffFrequency: 100,
+  sampleRate,
+});
+
+console.log(`✅ First-order low-pass (1000 Hz)`);
+console.log(`   Simple RC filter, gentle rolloff (-20 dB/decade)`);
+console.log(`✅ First-order high-pass (100 Hz)`);
+console.log(`   Use case: Fast, low-latency filtering\n`);
+
+// ============================================================
+// Example 9: Comparing FIR vs IIR Performance
+// ============================================================
+
+console.log("--- Example 9: FIR vs IIR Performance Comparison ---");
+
+const fir = FirFilter.createLowPass({
+  cutoffFrequency: 1000,
+  sampleRate,
+  order: 51,
+});
+
+const iir = IirFilter.createButterworthLowPass({
+  cutoffFrequency: 1000,
+  sampleRate,
+  order: 4,
+});
+
+console.log("FIR (51 taps):");
+console.log(
+  `  - Coefficients: ${
+    fir.getCoefficients().length
+  } (multiply-accumulates per sample)`
+);
+console.log(`  - Always stable`);
+console.log(`  - Linear phase possible`);
+
+console.log("\nIIR (4th-order Butterworth):");
+console.log(
+  `  - B coefficients: ${iir.getBCoefficients().length}, A coefficients: ${
+    iir.getACoefficients().length
+  }`
+);
+console.log(`  - Much more efficient (fewer operations)`);
+console.log(`  - Non-linear phase`);
+console.log(`  - Stable: ${iir.isStable()}\n`);
+
+// ============================================================
+// Example 10: Real-Time Filtering
+// ============================================================
+
+console.log("--- Example 10: Real-Time Filtering ---");
+
+const realtimeFilter = IirFilter.createButterworthLowPass({
+  cutoffFrequency: 1000,
+  sampleRate,
+  order: 4,
+});
+
+console.log("Simulating real-time sample-by-sample processing:");
+
+// Simulate streaming samples
+for (let i = 0; i < 10; i++) {
+  const input = Math.sin((2 * Math.PI * 500 * i) / sampleRate);
+  const output = await realtimeFilter.processSample(input);
+
+  if (i < 5) {
+    console.log(
+      `  Sample ${i}: in=${input.toFixed(4)}, out=${output.toFixed(4)}`
+    );
+  }
+}
+console.log("  ...");
+console.log(`✅ Processed 10 samples sample-by-sample\n`);
+
+// ============================================================
+// Example 11: Filter State Management
+// ============================================================
+
+console.log("--- Example 11: Filter State Management ---");
+
+const statefulFilter = FirFilter.createLowPass({
+  cutoffFrequency: 1000,
+  sampleRate,
+  order: 31,
+});
+
+// Process first batch
+const batch1 = new Float32Array(50);
+for (let i = 0; i < batch1.length; i++) {
+  batch1[i] = Math.sin((2 * Math.PI * 500 * i) / sampleRate);
+}
+
+const out1 = await statefulFilter.process(batch1);
+console.log(`✅ Processed batch 1: ${batch1.length} samples`);
+
+// Process second batch (state is maintained)
+const batch2 = new Float32Array(50);
+for (let i = 0; i < batch2.length; i++) {
+  batch2[i] = Math.sin((2 * Math.PI * 500 * (i + 50)) / sampleRate);
+}
+
+const out2 = await statefulFilter.process(batch2);
+console.log(
+  `✅ Processed batch 2: ${batch2.length} samples (state maintained)`
+);
+
+// Reset state
+statefulFilter.reset();
+console.log(`✅ Reset filter state\n`);
+
+// ============================================================
+// Summary
+// ============================================================
+
+console.log("=== Summary ===");
+console.log("\n✅ FIR Filters:");
+console.log("   - Low-pass, High-pass, Band-pass, Band-stop/Notch");
+console.log("   - Window types: Hamming, Hann, Blackman, Bartlett");
+console.log("   - Always stable, linear phase possible");
+console.log("   - More taps = sharper transition, more computation");
+
+console.log("\n✅ IIR Filters:");
+console.log("   - Butterworth: Maximally flat passband");
+console.log("   - Chebyshev: Sharper rolloff with passband ripple");
+console.log("   - First-order: Simple, fast, gentle rolloff");
+console.log("   - More efficient than FIR (fewer coefficients)");
+console.log("   - Non-linear phase, can be unstable");
+
+console.log("\n✅ Filter API:");
+console.log("   - FirFilter.createLowPass/HighPass/BandPass/BandStop()");
+console.log("   - IirFilter.createButterworthX() - Maximally flat");
+console.log("   - IirFilter.createChebyshevX() - Sharp rolloff");
+console.log("   - IirFilter.createPeakingEQ/LowShelf/HighShelf() - Biquad EQ");
+
+console.log("\n✅ Use Cases:");
+console.log("   - Audio: FIR with Hann/Hamming window");
+console.log("   - Real-time: IIR Butterworth (low latency)");
+console.log("   - Voice band: 300-3400 Hz band-pass");
+console.log("   - Powerline removal: 50/60 Hz notch filter");
+console.log("   - DC removal: High-pass filter");
+
+console.log("\n📚 All filter design math is done in C++ for performance!");
+console.log("🚀 SIMD-optimized convolution for FIR filters!");