@volley/recognition-client-sdk-node22 0.1.424

package/src/utils/audio-ring-buffer.spec.ts

@@ -0,0 +1,335 @@
+/**
+ * Audio Ring Buffer Tests
+ */
+
+import { AudioRingBuffer } from './audio-ring-buffer.js';
+
+describe('AudioRingBuffer', () => {
+  describe('constructor', () => {
+    it('should initialize with correct buffer size', () => {
+      const buffer = new AudioRingBuffer({
+        maxBufferDurationSec: 10,
+        chunksPerSecond: 100
+      });
+
+      expect(buffer.isEmpty()).toBe(true);
+      expect(buffer.getBufferedCount()).toBe(0);
+      expect(buffer.isOverflowing()).toBe(false);
+    });
+
+    it('should accept logger function', () => {
+      const logger = jest.fn();
+      const buffer = new AudioRingBuffer({
+        maxBufferDurationSec: 1,
+        chunksPerSecond: 10,
+        logger
+      });
+
+      expect(buffer).toBeDefined();
+    });
+  });
+
+  describe('write', () => {
+    it('should write ArrayBuffer data', () => {
+      const buffer = new AudioRingBuffer({
+        maxBufferDurationSec: 1,
+        chunksPerSecond: 10
+      });
+
+      const data = new ArrayBuffer(100);
+      buffer.write(data);
+
+      expect(buffer.isEmpty()).toBe(false);
+      expect(buffer.getBufferedCount()).toBe(1);
+    });
+
+    it('should write ArrayBufferView data', () => {
+      const buffer = new AudioRingBuffer({
+        maxBufferDurationSec: 1,
+        chunksPerSecond: 10
+      });
+
+      const data = new Uint8Array(100);
+      buffer.write(data);
+
+      expect(buffer.isEmpty()).toBe(false);
+      expect(buffer.getBufferedCount()).toBe(1);
+    });
+
+    it('should track total buffered bytes', () => {
+      const buffer = new AudioRingBuffer({
+        maxBufferDurationSec: 1,
+        chunksPerSecond: 10
+      });
+
+      buffer.write(new ArrayBuffer(100));
+      buffer.write(new ArrayBuffer(200));
+
+      const stats = buffer.getStats();
+      expect(stats.totalBufferedBytes).toBe(300);
+      expect(stats.chunksBuffered).toBe(2);
+    });
+
+    it('should handle multiple writes', () => {
+      const buffer = new AudioRingBuffer({
+        maxBufferDurationSec: 1,
+        chunksPerSecond: 100
+      });
+
+      for (let i = 0; i < 50; i++) {
+        buffer.write(new ArrayBuffer(10));
+      }
+
+      expect(buffer.getBufferedCount()).toBe(50);
+      expect(buffer.isOverflowing()).toBe(false);
+    });
+  });
+
+  describe('overflow detection', () => {
+    it('should detect overflow when buffer is full', () => {
+      const buffer = new AudioRingBuffer({
+        maxBufferDurationSec: 1,
+        chunksPerSecond: 5 // Small buffer of 5 chunks
+      });
+
+      // Write more than buffer can hold
+      for (let i = 0; i < 10; i++) {
+        buffer.write(new ArrayBuffer(10));
+      }
+
+      expect(buffer.isOverflowing()).toBe(true);
+      const stats = buffer.getStats();
+      expect(stats.hasWrapped).toBe(true);
+      expect(stats.overflowCount).toBeGreaterThan(0);
+    });
+
+    it('should call logger on overflow', () => {
+      const logger = jest.fn();
+      const buffer = new AudioRingBuffer({
+        maxBufferDurationSec: 1,
+        chunksPerSecond: 3, // Small buffer
+        logger
+      });
+
+      // Fill buffer to overflow
+      for (let i = 0; i < 10; i++) {
+        buffer.write(new ArrayBuffer(10));
+      }
+
+      // Logger should have been called with overflow message
+      expect(logger).toHaveBeenCalledWith(
+        'debug',
+        expect.stringContaining('overflow'),
+        expect.any(Object)
+      );
+    });
+  });
+
+  describe('read', () => {
+    it('should return null when buffer is empty', () => {
+      const buffer = new AudioRingBuffer({
+        maxBufferDurationSec: 1,
+        chunksPerSecond: 10
+      });
+
+      expect(buffer.read()).toBeNull();
+    });
+
+    it('should return data in FIFO order', () => {
+      const buffer = new AudioRingBuffer({
+        maxBufferDurationSec: 1,
+        chunksPerSecond: 10
+      });
+
+      const data1 = new Uint8Array([1, 2, 3]);
+      const data2 = new Uint8Array([4, 5, 6]);
+
+      buffer.write(data1);
+      buffer.write(data2);
+
+      const chunk1 = buffer.read();
+      expect(chunk1).not.toBeNull();
+      expect(chunk1!.data).toBe(data1);
+
+      const chunk2 = buffer.read();
+      expect(chunk2).not.toBeNull();
+      expect(chunk2!.data).toBe(data2);
+    });
+
+    it('should decrement buffered count after read', () => {
+      const buffer = new AudioRingBuffer({
+        maxBufferDurationSec: 1,
+        chunksPerSecond: 10
+      });
+
+      buffer.write(new ArrayBuffer(10));
+      buffer.write(new ArrayBuffer(10));
+
+      expect(buffer.getBufferedCount()).toBe(2);
+
+      buffer.read();
+      expect(buffer.getBufferedCount()).toBe(1);
+
+      buffer.read();
+      expect(buffer.getBufferedCount()).toBe(0);
+      expect(buffer.isEmpty()).toBe(true);
+    });
+  });
+
+  describe('readAll', () => {
+    it('should return empty array when buffer is empty', () => {
+      const buffer = new AudioRingBuffer({
+        maxBufferDurationSec: 1,
+        chunksPerSecond: 10
+      });
+
+      expect(buffer.readAll()).toEqual([]);
+    });
+
+    it('should return all chunks without removing them', () => {
+      const buffer = new AudioRingBuffer({
+        maxBufferDurationSec: 1,
+        chunksPerSecond: 10
+      });
+
+      buffer.write(new ArrayBuffer(10));
+      buffer.write(new ArrayBuffer(20));
+      buffer.write(new ArrayBuffer(30));
+
+      const chunks = buffer.readAll();
+      expect(chunks).toHaveLength(3);
+
+      // Should still have all chunks
+      expect(buffer.getBufferedCount()).toBe(3);
+    });
+  });
+
+  describe('flush', () => {
+    it('should return all chunks and clear buffer', () => {
+      const buffer = new AudioRingBuffer({
+        maxBufferDurationSec: 1,
+        chunksPerSecond: 10
+      });
+
+      buffer.write(new ArrayBuffer(10));
+      buffer.write(new ArrayBuffer(20));
+
+      const chunks = buffer.flush();
+      expect(chunks).toHaveLength(2);
+      expect(buffer.isEmpty()).toBe(true);
+      expect(buffer.getBufferedCount()).toBe(0);
+    });
+  });
+
+  describe('clear', () => {
+    it('should reset all state', () => {
+      const buffer = new AudioRingBuffer({
+        maxBufferDurationSec: 1,
+        chunksPerSecond: 5
+      });
+
+      // Fill and overflow
+      for (let i = 0; i < 10; i++) {
+        buffer.write(new ArrayBuffer(100));
+      }
+
+      expect(buffer.isOverflowing()).toBe(true);
+
+      buffer.clear();
+
+      expect(buffer.isEmpty()).toBe(true);
+      expect(buffer.getBufferedCount()).toBe(0);
+      expect(buffer.isOverflowing()).toBe(false);
+
+      const stats = buffer.getStats();
+      expect(stats.chunksBuffered).toBe(0);
+      expect(stats.totalBufferedBytes).toBe(0);
+      expect(stats.overflowCount).toBe(0);
+      expect(stats.hasWrapped).toBe(false);
+    });
+
+    it('should call logger when clearing', () => {
+      const logger = jest.fn();
+      const buffer = new AudioRingBuffer({
+        maxBufferDurationSec: 1,
+        chunksPerSecond: 10,
+        logger
+      });
+
+      buffer.write(new ArrayBuffer(10));
+      buffer.clear();
+
+      expect(logger).toHaveBeenCalledWith(
+        'debug',
+        expect.stringContaining('cleared')
+      );
+    });
+  });
+
+  describe('getStats', () => {
+    it('should return correct statistics', () => {
+      const buffer = new AudioRingBuffer({
+        maxBufferDurationSec: 1,
+        chunksPerSecond: 10
+      });
+
+      buffer.write(new ArrayBuffer(100));
+      buffer.write(new ArrayBuffer(200));
+
+      const stats = buffer.getStats();
+
+      expect(stats.chunksBuffered).toBe(2);
+      expect(stats.currentBufferedChunks).toBe(2);
+      expect(stats.totalBufferedBytes).toBe(300);
+      expect(stats.hasWrapped).toBe(false);
+      expect(stats.overflowCount).toBe(0);
+    });
+  });
+
+  describe('getBufferedCount with wraparound', () => {
+    it('should correctly count after partial read and more writes', () => {
+      const buffer = new AudioRingBuffer({
+        maxBufferDurationSec: 1,
+        chunksPerSecond: 10 // Buffer size of 10
+      });
+
+      // Write 5 chunks
+      for (let i = 0; i < 5; i++) {
+        buffer.write(new ArrayBuffer(10));
+      }
+      expect(buffer.getBufferedCount()).toBe(5);
+
+      // Read 3 chunks
+      buffer.read();
+      buffer.read();
+      buffer.read();
+      expect(buffer.getBufferedCount()).toBe(2);
+
+      // Write 4 more (wraps around in buffer)
+      for (let i = 0; i < 4; i++) {
+        buffer.write(new ArrayBuffer(10));
+      }
+
+      // Should have 2 + 4 = 6 chunks
+      expect(buffer.getBufferedCount()).toBe(6);
+      expect(buffer.isOverflowing()).toBe(false);
+    });
+
+    it('should handle buffer overflow correctly', () => {
+      const buffer = new AudioRingBuffer({
+        maxBufferDurationSec: 1,
+        chunksPerSecond: 3 // Buffer size of 3
+      });
+
+      // Write 5 chunks (more than buffer can hold)
+      for (let i = 0; i < 5; i++) {
+        buffer.write(new ArrayBuffer(10));
+      }
+
+      // Buffer should be full but not exceed capacity
+      // Ring buffer drops oldest when full
+      expect(buffer.getBufferedCount()).toBeLessThanOrEqual(3);
+      expect(buffer.isOverflowing()).toBe(true);
+    });
+  });
+});

package/src/utils/audio-ring-buffer.ts

@@ -0,0 +1,170 @@
+/**
+ * Audio Ring Buffer
+ * Manages circular buffer for audio data with overflow detection
+ */
+
+export interface BufferedAudio {
+  data: ArrayBuffer | ArrayBufferView;
+  timestamp: number;
+}
+
+export interface AudioRingBufferConfig {
+  maxBufferDurationSec: number;
+  chunksPerSecond: number;
+  logger?: (level: 'debug' | 'info' | 'warn' | 'error', message: string, data?: any) => void;
+}
+
+export class AudioRingBuffer {
+  private buffer: BufferedAudio[] = [];
+  private bufferSize: number;
+  private writeIndex = 0;
+  private readIndex = 0;
+  private hasWrapped = false;
+  private totalBufferedBytes = 0;
+  private overflowCount = 0;
+  private chunksBuffered = 0;
+  private logger?: (level: 'debug' | 'info' | 'warn' | 'error', message: string, data?: any) => void;
+
+  constructor(config: AudioRingBufferConfig) {
+    this.bufferSize = config.maxBufferDurationSec * config.chunksPerSecond;
+    this.buffer = new Array(this.bufferSize);
+    if (config.logger) {
+      this.logger = config.logger;
+    }
+  }
+
+  /**
+   * Write audio chunk to ring buffer with overflow detection
+   */
+  write(audioData: ArrayBuffer | ArrayBufferView): void {
+    const bytes = ArrayBuffer.isView(audioData) ? audioData.byteLength : audioData.byteLength;
+
+    // Write to current position
+    this.buffer[this.writeIndex] = {
+      data: audioData,
+      timestamp: Date.now()
+    };
+
+    // Advance write pointer
+    const nextWriteIndex = (this.writeIndex + 1) % this.bufferSize;
+
+    // Detect overflow: write caught up to read
+    if (nextWriteIndex === this.readIndex && this.writeIndex !== this.readIndex) {
+      this.hasWrapped = true;
+      this.overflowCount++;
+
+      // Log buffer overflow event
+      if (this.logger) {
+        this.logger('debug', '[RecogSDK] Buffer overflow detected', {
+          bufferSize: this.bufferSize,
+          totalOverflows: this.overflowCount,
+          droppedChunk: this.buffer[this.readIndex]?.timestamp
+        });
+      }
+
+      // Move read pointer forward to make room (drop oldest)
+      this.readIndex = (this.readIndex + 1) % this.bufferSize;
+    }
+
+    this.writeIndex = nextWriteIndex;
+    this.chunksBuffered++;
+    this.totalBufferedBytes += bytes;
+  }
+
+  /**
+   * Read next chunk from buffer
+   */
+  read(): BufferedAudio | null {
+    if (this.isEmpty()) {
+      return null;
+    }
+
+    const chunk = this.buffer[this.readIndex];
+    this.readIndex = (this.readIndex + 1) % this.bufferSize;
+    return chunk || null;
+  }
+
+  /**
+   * Read all buffered chunks without removing them
+   */
+  readAll(): BufferedAudio[] {
+    const chunks: BufferedAudio[] = [];
+    let index = this.readIndex;
+
+    while (index !== this.writeIndex) {
+      const chunk = this.buffer[index];
+      if (chunk) {
+        chunks.push(chunk);
+      }
+      index = (index + 1) % this.bufferSize;
+    }
+
+    return chunks;
+  }
+
+  /**
+   * Flush all buffered data and advance read pointer
+   */
+  flush(): BufferedAudio[] {
+    const chunks = this.readAll();
+    this.readIndex = this.writeIndex;
+    return chunks;
+  }
+
+  /**
+   * Get count of buffered chunks
+   */
+  getBufferedCount(): number {
+    if (this.writeIndex >= this.readIndex) {
+      return this.writeIndex - this.readIndex;
+    } else {
+      // Wrapped around
+      return this.bufferSize - this.readIndex + this.writeIndex;
+    }
+  }
+
+  /**
+   * Check if buffer is empty
+   */
+  isEmpty(): boolean {
+    return this.readIndex === this.writeIndex;
+  }
+
+  /**
+   * Check if buffer has overflowed
+   */
+  isOverflowing(): boolean {
+    return this.hasWrapped;
+  }
+
+  /**
+   * Clear the buffer and reset all counters
+   * Frees memory by releasing all stored audio chunks
+   */
+  clear(): void {
+    this.buffer = [];
+    this.writeIndex = 0;
+    this.readIndex = 0;
+    this.hasWrapped = false;
+    this.overflowCount = 0;
+    this.chunksBuffered = 0;
+    this.totalBufferedBytes = 0;
+
+    if (this.logger) {
+      this.logger('debug', '[RecogSDK] Audio buffer cleared');
+    }
+  }
+
+  /**
+   * Get buffer statistics
+   */
+  getStats() {
+    return {
+      chunksBuffered: this.chunksBuffered,
+      currentBufferedChunks: this.getBufferedCount(),
+      overflowCount: this.overflowCount,
+      hasWrapped: this.hasWrapped,
+      totalBufferedBytes: this.totalBufferedBytes
+    };
+  }
+}