@volley/recognition-client-sdk 0.1.424 → 0.1.622

package/src/simplified-vgf-recognition-client.ts

@@ -27,7 +27,7 @@ import {
     updateStateOnStop,
     resetRecognitionVGFState
 } from './vgf-recognition-mapper.js';
-import { RecognitionContextTypeV1 } from '@recog/shared-types';
+import { RecognitionContextTypeV1, type GameContextV1 } from '@recog/shared-types';
 
 /**
  * Configuration for SimplifiedVGFRecognitionClient
@@ -124,6 +124,23 @@ export interface ISimplifiedVGFRecognitionClient {
      */
     isBufferOverflowing(): boolean;
 
+    // ============= Preconnect Methods =============
+    /**
+     * Send game context after connection is established (for preconnect flow).
+     *
+     * Preconnect flow: Create client with asrRequestConfig (useContext: true) but
+     * WITHOUT gameContext → call connect() → later call sendGameContext() with slotMap.
+     *
+     * @param context - Game context including slotMap for keyword boosting
+     */
+    sendGameContext(context: GameContextV1): void;
+
+    /**
+     * Check if server has sent READY signal (provider connected, ready for audio).
+     * In preconnect flow, this becomes true after sendGameContext() triggers provider attachment.
+     */
+    isServerReady(): boolean;
+
     // ============= Utility Methods =============
     /**
      * Get the audio utterance ID for this session
@@ -202,6 +219,8 @@ export class SimplifiedVGFRecognitionClient implements ISimplifiedVGFRecognition
         } else {
             // Initialize VGF state from config
             this.state = createVGFStateFromConfig(clientConfig);
+            // Ensure clientConfig uses the same UUID as VGF state
+            clientConfig.audioUtteranceId = this.state.audioUtteranceId;
         }
 
         // Client is immediately ready to accept audio (will buffer if not connected)
@@ -430,6 +449,14 @@ export class SimplifiedVGFRecognitionClient implements ISimplifiedVGFRecognition
         return this.client.isBufferOverflowing();
     }
 
+    sendGameContext(context: GameContextV1): void {
+        this.client.sendGameContext(context);
+    }
+
+    isServerReady(): boolean {
+        return this.client.isServerReady();
+    }
+
 
     // VGF State access (read-only for consumers)
     getVGFState(): RecognitionState {

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/vgf-recognition-mapper.ts

@@ -86,6 +86,14 @@ export function mapTranscriptionResultToState(
                 newState.finalConfidence = result.finalTranscriptConfidence;
             }
         }
+
+        // Update voice timing on every transcript message
+        if (result.voiceEnd !== undefined) {
+            newState.voiceEnd = result.voiceEnd;
+        }
+        if (result.lastNonSilence !== undefined) {
+            newState.lastNonSilence = result.lastNonSilence;
+        }
     } else {
         // Transcription is finished
         newState.transcriptionStatus = TranscriptionStatus.FINALIZED;
@@ -95,6 +103,14 @@ export function mapTranscriptionResultToState(
         }
         newState.finalTranscriptionTimestamp = new Date().toISOString();
 
+        // Update voice timing on final transcript
+        if (result.voiceEnd !== undefined) {
+            newState.voiceEnd = result.voiceEnd;
+        }
+        if (result.lastNonSilence !== undefined) {
+            newState.lastNonSilence = result.lastNonSilence;
+        }
+
         // Clear pending when we have final
         newState.pendingTranscript = "";
         newState.pendingConfidence = undefined;
@@ -167,7 +183,9 @@ export function resetRecognitionVGFState(currentState: RecognitionState): Recogn
         transcriptionStatus: TranscriptionStatus.NOT_STARTED,
         startRecordingStatus: RecordingStatus.READY,
         recognitionActionProcessingState: RecognitionActionProcessingState.NOT_STARTED,
-        finalTranscript: undefined
+        finalTranscript: undefined,
+        voiceEnd: undefined,
+        lastNonSilence: undefined
     };
 }
 

package/src/vgf-recognition-state.ts

@@ -22,6 +22,10 @@ export const RecognitionVGFStateSchema = z.object({
     finalTranscript: z.string().optional(), // Full finalized transcript for the utterance. Will not change.
     finalConfidence: z.number().optional(),
 
+    // Voice timing (ms from stream start, prefix-adjusted)
+    voiceEnd: z.number().optional(), // voice end time identified by ASR
+    lastNonSilence: z.number().optional(), // last non-silence sample time from PCM analysis
+
     // Tracking-only metadata
     asrConfig: z.string().optional(), // Json format of the ASR config
     startRecordingTimestamp: z.string().optional(), // Start of recording. Immutable after set.