dspx 0.1.1-alpha.0

package/src/ts/__tests__/MovingAverage.test.ts

@@ -0,0 +1,322 @@
+import { describe, test, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import { createDspPipeline, DspProcessor } from "../bindings.js";
+
+const DEFAULT_OPTIONS = { channels: 1, sampleRate: 44100 };
+
+function assertCloseTo(actual: number, expected: number, precision = 5) {
+  const tolerance = Math.pow(10, -precision);
+  assert.ok(
+    Math.abs(actual - expected) < tolerance,
+    `Expected ${actual} to be close to ${expected} (tolerance: ${tolerance})`
+  );
+}
+
+describe("MovingAverage Filter", () => {
+  let processor: DspProcessor;
+
+  beforeEach(() => {
+    processor = createDspPipeline();
+  });
+
+  describe("Batch Mode (Stateless)", () => {
+    test("should compute batch average correctly", async () => {
+      processor.MovingAverage({ mode: "batch" });
+
+      const input = new Float32Array([1, 2, 3, 4, 5]);
+      const output = await processor.process(input, DEFAULT_OPTIONS);
+
+      // Mean of [1,2,3,4,5] = 3
+      // All samples should be replaced with the average
+      assert.equal(output.length, 5);
+      output.forEach((val) => assertCloseTo(val, 3));
+    });
+
+    test("should compute average of zero signal", async () => {
+      processor.MovingAverage({ mode: "batch" });
+
+      const input = new Float32Array([0, 0, 0, 0]);
+      const output = await processor.process(input, DEFAULT_OPTIONS);
+
+      output.forEach((val) => assertCloseTo(val, 0));
+    });
+
+    test("should compute average of constant signal", async () => {
+      processor.MovingAverage({ mode: "batch" });
+
+      const input = new Float32Array([5, 5, 5, 5, 5]);
+      const output = await processor.process(input, DEFAULT_OPTIONS);
+
+      output.forEach((val) => assertCloseTo(val, 5));
+    });
+
+    test("should handle negative values correctly", async () => {
+      processor.MovingAverage({ mode: "batch" });
+
+      const input = new Float32Array([-2, -1, 0, 1, 2]);
+      const output = await processor.process(input, DEFAULT_OPTIONS);
+
+      // Mean = 0
+      output.forEach((val) => assertCloseTo(val, 0));
+    });
+
+    test("should be stateless between calls", async () => {
+      processor.MovingAverage({ mode: "batch" });
+
+      const input1 = new Float32Array([1, 2, 3, 4, 5]);
+      const output1 = await processor.process(input1, DEFAULT_OPTIONS);
+
+      const input2 = new Float32Array([10, 20, 30]);
+      const output2 = await processor.process(input2, DEFAULT_OPTIONS);
+
+      // First batch: mean = 3
+      output1.forEach((val) => assertCloseTo(val, 3));
+
+      // Second batch: mean = 20 (independent of first)
+      output2.forEach((val) => assertCloseTo(val, 20));
+    });
+
+    test("should handle multi-channel data independently", async () => {
+      processor.MovingAverage({ mode: "batch" });
+
+      // 2 channels, 5 samples per channel
+      // Channel 0: [1, 3, 5, 7, 9] → mean = 5
+      // Channel 1: [10, 20, 30, 40, 50] → mean = 30
+      const input = new Float32Array([1, 10, 3, 20, 5, 30, 7, 40, 9, 50]);
+      const output = await processor.process(input, {
+        sampleRate: 1000,
+        channels: 2,
+      });
+
+      // Extract channels
+      const ch0 = [];
+      const ch1 = [];
+      for (let i = 0; i < output.length; i++) {
+        if (i % 2 === 0) ch0.push(output[i]);
+        else ch1.push(output[i]);
+      }
+
+      ch0.forEach((val) => assertCloseTo(val, 5));
+      ch1.forEach((val) => assertCloseTo(val, 30));
+    });
+  });
+
+  describe("Moving Mode (Stateful)", () => {
+    test("should compute moving average with window size 3", async () => {
+      processor.MovingAverage({ mode: "moving", windowSize: 3 });
+
+      const input = new Float32Array([1, 2, 3, 4, 5]);
+      const output = await processor.process(input, DEFAULT_OPTIONS);
+
+      // First value: [1] → avg = 1
+      // Second value: [1, 2] → avg = 1.5
+      // Third value: [1, 2, 3] → avg = 2
+      // Fourth value: [2, 3, 4] → avg = 3
+      // Fifth value: [3, 4, 5] → avg = 4
+      assert.equal(output.length, 5);
+      assertCloseTo(output[0], 1);
+      assertCloseTo(output[1], 1.5);
+      assertCloseTo(output[2], 2);
+      assertCloseTo(output[3], 3);
+      assertCloseTo(output[4], 4);
+    });
+
+    test("should handle single sample window", async () => {
+      processor.MovingAverage({ mode: "moving", windowSize: 1 });
+
+      const input = new Float32Array([10, 20, 30]);
+      const output = await processor.process(input, DEFAULT_OPTIONS);
+
+      assert.deepEqual(Array.from(output), [10, 20, 30]); // No smoothing with window size 1
+    });
+
+    test("should handle negative values", async () => {
+      processor.MovingAverage({ mode: "moving", windowSize: 2 });
+
+      const input = new Float32Array([-5, 5, -10, 10]);
+      const output = await processor.process(input, DEFAULT_OPTIONS);
+
+      assertCloseTo(output[0], -5);
+      assertCloseTo(output[1], 0); // (-5 + 5) / 2
+      assertCloseTo(output[2], -2.5); // (5 + -10) / 2
+      assertCloseTo(output[3], 0); // (-10 + 10) / 2
+    });
+
+    test("should maintain state across multiple process calls", async () => {
+      processor.MovingAverage({ mode: "moving", windowSize: 3 });
+
+      // Process first chunk
+      const output1 = await processor.process(
+        new Float32Array([1, 2]),
+        DEFAULT_OPTIONS
+      );
+      assertCloseTo(output1[0], 1);
+      assertCloseTo(output1[1], 1.5);
+
+      // Process second chunk - should continue from previous state
+      const output2 = await processor.process(
+        new Float32Array([3, 4]),
+        DEFAULT_OPTIONS
+      );
+      assertCloseTo(output2[0], 2); // (1 + 2 + 3) / 3
+      assertCloseTo(output2[1], 3); // (2 + 3 + 4) / 3
+    });
+
+    test("should throw error for moving mode without window size", () => {
+      assert.throws(() => {
+        processor.MovingAverage({ mode: "moving" } as any);
+      }, /either windowSize or windowDuration must be specified/);
+    });
+
+    test("should throw error for invalid window size", () => {
+      assert.throws(() => {
+        processor.MovingAverage({ mode: "moving", windowSize: 0 });
+      }, /windowSize must be a positive integer/);
+
+      assert.throws(() => {
+        processor.MovingAverage({ mode: "moving", windowSize: -5 });
+      }, /windowSize must be a positive integer/);
+
+      assert.throws(() => {
+        processor.MovingAverage({ mode: "moving", windowSize: 3.14 });
+      }, /windowSize must be a positive integer/);
+    });
+  });
+
+  describe("State Management", () => {
+    test("should serialize and deserialize state correctly", async () => {
+      processor.MovingAverage({ mode: "moving", windowSize: 3 });
+
+      // Process some data to build state
+      await processor.process(
+        new Float32Array([1, 2, 3, 4, 5]),
+        DEFAULT_OPTIONS
+      );
+
+      // Save state
+      const stateJson = await processor.saveState();
+      const state = JSON.parse(stateJson);
+
+      assert.ok(state);
+      assert.ok(state.timestamp);
+      assert.equal(state.stages.length, 1);
+      assert.equal(state.stages[0].type, "movingAverage");
+
+      // Create new processor with same pipeline structure and load state
+      const processor2 = createDspPipeline();
+      processor2.MovingAverage({ mode: "moving", windowSize: 3 }); // Must match original pipeline
+      await processor2.loadState(stateJson);
+
+      // Process should continue from saved state
+      const output1 = await processor.process(
+        new Float32Array([6]),
+        DEFAULT_OPTIONS
+      );
+      const output2 = await processor2.process(
+        new Float32Array([6]),
+        DEFAULT_OPTIONS
+      );
+
+      assertCloseTo(output2[0], output1[0]);
+    });
+
+    test("should reset state correctly", async () => {
+      processor.MovingAverage({ mode: "moving", windowSize: 3 });
+
+      // Build up state
+      await processor.process(new Float32Array([1, 2, 3]), DEFAULT_OPTIONS);
+
+      // Reset
+      processor.clearState();
+
+      // Should start fresh
+      const output = await processor.process(
+        new Float32Array([10]),
+        DEFAULT_OPTIONS
+      );
+      assertCloseTo(output[0], 10); // Only 10 in buffer
+    });
+
+    test("should validate runningSum on state load", async () => {
+      processor.MovingAverage({ mode: "moving", windowSize: 3 });
+      await processor.process(new Float32Array([1, 2, 3]), DEFAULT_OPTIONS);
+
+      const stateJson = await processor.saveState();
+      const state = JSON.parse(stateJson);
+
+      // Corrupt the runningSum (note: it's in state.stages[0].state.channels)
+      if (state.stages[0].state.channels && state.stages[0].state.channels[0]) {
+        state.stages[0].state.channels[0].runningSum = 9999;
+      }
+
+      // Should throw when loading corrupted state
+      const processor2 = createDspPipeline();
+      processor2.MovingAverage({ mode: "moving", windowSize: 3 }); // Must match original pipeline
+      await assert.rejects(
+        async () => await processor2.loadState(JSON.stringify(state)),
+        /Running sum validation failed/
+      );
+    });
+
+    test("should validate window size on state load", async () => {
+      processor.MovingAverage({ mode: "moving", windowSize: 3 });
+      await processor.process(new Float32Array([1, 2, 3]), DEFAULT_OPTIONS);
+
+      const stateJson = await processor.saveState();
+      const state = JSON.parse(stateJson);
+
+      // Corrupt the window size parameter itself
+      if (state.stages[0].state) {
+        state.stages[0].state.windowSize = 5; // Change from 3 to 5
+      }
+
+      // Should throw when loading corrupted state
+      const processor2 = createDspPipeline();
+      processor2.MovingAverage({ mode: "moving", windowSize: 3 }); // Original window size
+      await assert.rejects(
+        async () => await processor2.loadState(JSON.stringify(state)),
+        /Window size mismatch/
+      );
+    });
+
+    test("should handle empty input", async () => {
+      processor.MovingAverage({ mode: "moving", windowSize: 3 });
+      const output = await processor.process(
+        new Float32Array([]),
+        DEFAULT_OPTIONS
+      );
+      assert.equal(output.length, 0);
+    });
+  });
+
+  describe("Multi-channel Processing", () => {
+    test("should process data with stateful continuity", async () => {
+      processor.MovingAverage({ mode: "moving", windowSize: 2 });
+
+      // Process first batch
+      const output1 = await processor.process(
+        new Float32Array([1, 2, 3]),
+        DEFAULT_OPTIONS
+      );
+      assertCloseTo(output1[0], 1); // [1]
+      assertCloseTo(output1[1], 1.5); // [1, 2]
+      assertCloseTo(output1[2], 2.5); // [2, 3]
+
+      // Process second batch - state continues from previous
+      const output2 = await processor.process(
+        new Float32Array([10, 20, 30]),
+        DEFAULT_OPTIONS
+      );
+      assertCloseTo(output2[0], 6.5); // [3, 10]
+      assertCloseTo(output2[1], 15); // [10, 20]
+      assertCloseTo(output2[2], 25); // [20, 30]
+
+      // Process third batch - state continues
+      const output3 = await processor.process(
+        new Float32Array([4]),
+        DEFAULT_OPTIONS
+      );
+      assertCloseTo(output3[0], 17); // [30, 4]
+    });
+  });
+});

package/src/ts/__tests__/RMS.test.ts

@@ -0,0 +1,315 @@
+import { describe, test, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import { createDspPipeline, DspProcessor } from "../bindings.js";
+
+const DEFAULT_OPTIONS = { channels: 1, sampleRate: 44100 };
+
+function assertCloseTo(actual: number, expected: number, precision = 5) {
+  const tolerance = Math.pow(10, -precision);
+  assert.ok(
+    Math.abs(actual - expected) < tolerance,
+    `Expected ${actual} to be close to ${expected} (tolerance: ${tolerance})`
+  );
+}
+
+describe("RMS Filter", () => {
+  let processor: DspProcessor;
+
+  beforeEach(() => {
+    processor = createDspPipeline();
+  });
+
+  describe("Basic Functionality", () => {
+    test("should compute RMS with window size 3", async () => {
+      processor.Rms({ mode: "moving", windowSize: 3 });
+
+      const input = new Float32Array([3, 4, 0, 6, 8]);
+      const output = await processor.process(input, DEFAULT_OPTIONS);
+
+      // First value: sqrt(3²) = 3
+      // Second value: sqrt((3² + 4²) / 2) = sqrt(25 / 2) = 3.5355...
+      // Third value: sqrt((3² + 4² + 0²) / 3) = sqrt(25 / 3) = 2.8867...
+      // Fourth value: sqrt((4² + 0² + 6²) / 3) = sqrt(52 / 3) = 4.1633...
+      // Fifth value: sqrt((0² + 6² + 8²) / 3) = sqrt(100 / 3) = 5.7735...
+      assert.equal(output.length, 5);
+      assertCloseTo(output[0], 3);
+      assertCloseTo(output[1], 3.5355, 4);
+      assertCloseTo(output[2], 2.8867, 4);
+      assertCloseTo(output[3], 4.1633, 4);
+      assertCloseTo(output[4], 5.7735, 4);
+    });
+
+    test("should handle single sample window", async () => {
+      processor.Rms({ mode: "moving", windowSize: 1 });
+
+      const input = new Float32Array([3, 4, 5]);
+      const output = await processor.process(input, DEFAULT_OPTIONS);
+
+      // RMS of single sample is just the absolute value
+      assertCloseTo(output[0], 3);
+      assertCloseTo(output[1], 4);
+      assertCloseTo(output[2], 5);
+    });
+
+    test("should compute RMS correctly for negative values", async () => {
+      processor.Rms({ mode: "moving", windowSize: 2 });
+
+      const input = new Float32Array([-3, 4, -5, 12]);
+      const output = await processor.process(input, DEFAULT_OPTIONS);
+
+      // First: sqrt((-3)²) = 3
+      // Second: sqrt((9 + 16) / 2) = sqrt(12.5) = 3.5355...
+      // Third: sqrt((16 + 25) / 2) = sqrt(20.5) = 4.5277...
+      // Fourth: sqrt((25 + 144) / 2) = sqrt(84.5) = 9.1924...
+      assertCloseTo(output[0], 3);
+      assertCloseTo(output[1], 3.5355, 4);
+      assertCloseTo(output[2], 4.5277, 4);
+      assertCloseTo(output[3], 9.1924, 4);
+    });
+
+    test("should maintain state across multiple process calls", async () => {
+      processor.Rms({ mode: "moving", windowSize: 3 });
+
+      // First batch: [3, 4]
+      const output1 = await processor.process(
+        new Float32Array([3, 4]),
+        DEFAULT_OPTIONS
+      );
+      assertCloseTo(output1[0], 3);
+      assertCloseTo(output1[1], 3.5355, 4);
+
+      // Second batch: [5] - should use [3, 4, 5] for RMS
+      const output2 = await processor.process(
+        new Float32Array([5]),
+        DEFAULT_OPTIONS
+      );
+      // sqrt((3² + 4² + 5²) / 3) = sqrt(50 / 3) = 4.0824...
+      assertCloseTo(output2[0], 4.0824, 4);
+    });
+  });
+
+  describe("State Management", () => {
+    test("should serialize and deserialize state correctly", async () => {
+      processor.Rms({ mode: "moving", windowSize: 3 });
+
+      // Build state
+      await processor.process(new Float32Array([3, 4, 5]), DEFAULT_OPTIONS);
+
+      const stateJson = await processor.saveState();
+      const state = JSON.parse(stateJson);
+
+      assert.ok(state);
+      assert.ok(state.timestamp);
+      assert.equal(state.stages.length, 1);
+      assert.equal(state.stages[0].type, "rms");
+      assert.equal(state.stages[0].state.windowSize, 3);
+      assert.ok(state.stages[0].state.channels);
+
+      // Create new processor and load state
+      const processor2 = createDspPipeline();
+      processor2.Rms({ mode: "moving", windowSize: 3 });
+      await processor2.loadState(stateJson);
+
+      // Both should produce same output for next sample
+      const output1 = await processor.process(
+        new Float32Array([6]),
+        DEFAULT_OPTIONS
+      );
+      const output2 = await processor2.process(
+        new Float32Array([6]),
+        DEFAULT_OPTIONS
+      );
+
+      assertCloseTo(output2[0], output1[0]);
+    });
+
+    test("should reset state correctly", async () => {
+      processor.Rms({ mode: "moving", windowSize: 3 });
+
+      // Build state
+      await processor.process(new Float32Array([3, 4, 5]), DEFAULT_OPTIONS);
+
+      // Reset
+      processor.clearState();
+
+      // Should start fresh
+      const output = await processor.process(
+        new Float32Array([10]),
+        DEFAULT_OPTIONS
+      );
+      assertCloseTo(output[0], 10); // RMS of single value
+    });
+
+    test("should validate runningSumOfSquares on state load", async () => {
+      processor.Rms({ mode: "moving", windowSize: 3 });
+      await processor.process(new Float32Array([3, 4, 5]), DEFAULT_OPTIONS);
+
+      const stateJson = await processor.saveState();
+      const state = JSON.parse(stateJson);
+
+      // Corrupt runningSumOfSquares
+      if (state.stages[0].state.channels && state.stages[0].state.channels[0]) {
+        state.stages[0].state.channels[0].runningSumOfSquares = 9999;
+      }
+
+      // Should throw when loading corrupted state
+      const processor2 = createDspPipeline();
+      processor2.Rms({ mode: "moving", windowSize: 3 });
+      await assert.rejects(
+        async () => await processor2.loadState(JSON.stringify(state)),
+        /Running sum of squares validation failed/
+      );
+    });
+
+    test("should validate window size on state load", async () => {
+      processor.Rms({ mode: "moving", windowSize: 3 });
+      await processor.process(new Float32Array([3, 4, 5]), DEFAULT_OPTIONS);
+
+      const stateJson = await processor.saveState();
+      const state = JSON.parse(stateJson);
+
+      // Corrupt window size
+      if (state.stages[0].state) {
+        state.stages[0].state.windowSize = 5;
+      }
+
+      // Should throw when loading corrupted state
+      const processor2 = createDspPipeline();
+      processor2.Rms({ mode: "moving", windowSize: 3 });
+      await assert.rejects(
+        async () => await processor2.loadState(JSON.stringify(state)),
+        /Window size mismatch/
+      );
+    });
+  });
+
+  describe("Mathematical Properties", () => {
+    test("should compute RMS of constant signal correctly", async () => {
+      processor.Rms({ mode: "moving", windowSize: 4 });
+
+      const input = new Float32Array([5, 5, 5, 5]);
+      const output = await processor.process(input, DEFAULT_OPTIONS);
+
+      // RMS of constant signal equals the constant
+      output.forEach((val) => assertCloseTo(val, 5));
+    });
+
+    test("should compute RMS of zero signal", async () => {
+      processor.Rms({ mode: "moving", windowSize: 3 });
+
+      const input = new Float32Array([0, 0, 0, 0]);
+      const output = await processor.process(input, DEFAULT_OPTIONS);
+
+      output.forEach((val) => assertCloseTo(val, 0));
+    });
+
+    test("should handle alternating positive/negative", async () => {
+      processor.Rms({ mode: "moving", windowSize: 2 });
+
+      const input = new Float32Array([3, -3, 4, -4]);
+      const output = await processor.process(input, DEFAULT_OPTIONS);
+
+      // First: sqrt(9) = 3
+      // Second: sqrt((9 + 9) / 2) = 3
+      // Third: sqrt((9 + 16) / 2) = sqrt(12.5) = 3.5355...
+      // Fourth: sqrt((16 + 16) / 2) = 4
+      assertCloseTo(output[0], 3);
+      assertCloseTo(output[1], 3);
+      assertCloseTo(output[2], 3.5355, 4);
+      assertCloseTo(output[3], 4);
+    });
+
+    test("should produce value equal to or less than max absolute value", async () => {
+      processor.Rms({ mode: "moving", windowSize: 3 });
+
+      const input = new Float32Array([1, 5, 2]);
+      const output = await processor.process(input, DEFAULT_OPTIONS);
+
+      // RMS should be <= max absolute value for each window
+      assert.ok(output[0] <= 1);
+      assert.ok(output[1] <= 5);
+      assert.ok(output[2] <= 5);
+    });
+  });
+
+  describe("Edge Cases", () => {
+    test("should handle empty input array", async () => {
+      processor.Rms({ mode: "moving", windowSize: 3 });
+
+      const output = await processor.process(
+        new Float32Array([]),
+        DEFAULT_OPTIONS
+      );
+      assert.equal(output.length, 0);
+    });
+
+    test("should handle very small values", async () => {
+      processor.Rms({ mode: "moving", windowSize: 2 });
+
+      const input = new Float32Array([0.0001, 0.0002, 0.0001]);
+      const output = await processor.process(input, DEFAULT_OPTIONS);
+
+      assert.ok(output.every((v) => v > 0 && v < 0.001));
+    });
+
+    test("should handle very large values", async () => {
+      processor.Rms({ mode: "moving", windowSize: 2 });
+
+      const input = new Float32Array([1e6, 1e6]);
+      const output = await processor.process(input, DEFAULT_OPTIONS);
+
+      assertCloseTo(output[0], 1e6);
+      assertCloseTo(output[1], 1e6);
+    });
+
+    test("should handle mixed magnitude ranges", async () => {
+      processor.Rms({ mode: "moving", windowSize: 3 });
+
+      const input = new Float32Array([0.001, 1000, 0.001]);
+      const output = await processor.process(input, DEFAULT_OPTIONS);
+
+      assert.ok(output.every((v) => v >= 0));
+      assert.ok(output.some((v) => v > 100)); // Large value influences RMS
+    });
+  });
+
+  describe("Multi-channel Processing", () => {
+    test("should process data with stateful continuity", async () => {
+      processor.Rms({ mode: "moving", windowSize: 2 });
+
+      // First batch
+      const output1 = await processor.process(
+        new Float32Array([3, 4]),
+        DEFAULT_OPTIONS
+      );
+      assertCloseTo(output1[0], 3);
+      assertCloseTo(output1[1], 3.5355, 4);
+
+      // Second batch - continues from previous
+      const output2 = await processor.process(
+        new Float32Array([5, 0]),
+        DEFAULT_OPTIONS
+      );
+      // sqrt((16 + 25) / 2) = sqrt(20.5) = 4.5277...
+      assertCloseTo(output2[0], 4.5277, 4);
+      // sqrt((25 + 0) / 2) = sqrt(12.5) = 3.5355...
+      assertCloseTo(output2[1], 3.5355, 4);
+    });
+
+    test("should maintain separate state across multiple batches", async () => {
+      processor.Rms({ mode: "moving", windowSize: 2 });
+
+      const batches = [
+        new Float32Array([1, 2]),
+        new Float32Array([3, 4]),
+        new Float32Array([5, 6]),
+      ];
+
+      for (const batch of batches) {
+        const output = await processor.process(batch, DEFAULT_OPTIONS);
+        assert.equal(output.length, batch.length);
+        assert.ok(output.every((v) => v > 0));
+      }
+    });
+  });
+});