@volley/recognition-client-sdk
Version:
Recognition Service TypeScript/Node.js Client SDK
124 lines • 4.82 kB
TypeScript
/**
* RealTimeTwoWayWebSocketRecognitionClient - Clean, compact SDK for real-time speech recognition
*
* Features:
* - Ring buffer-based audio storage with fixed memory footprint
* - Automatic buffering when disconnected, immediate send when connected
* - Buffer persists after flush (for future retry/reconnection scenarios)
* - Built on WebSocketAudioClient for robust protocol handling
* - Simple API: connect() → sendAudio() → stopRecording()
* - Type-safe message handling with callbacks
* - Automatic backpressure management
* - Overflow detection with buffer state tracking
*
* Example:
* ```typescript
* const client = new RealTimeTwoWayWebSocketRecognitionClient({
* url: 'ws://localhost:3101/ws/v1/recognize',
* onTranscript: (result) => console.log(result.finalTranscript),
* onError: (error) => console.error(error),
* maxBufferDurationSec: 60 // Ring buffer for 60 seconds
* });
*
* await client.connect();
*
* // Send audio chunks - always stored in ring buffer, sent if connected
* micStream.on('data', (chunk) => client.sendAudio(chunk));
*
* // Signal end of audio and wait for final results
* await client.stopRecording();
*
* // Server will close connection after sending finals
* // No manual cleanup needed - browser handles it
* ```
*/
import { WebSocketAudioClient } from '@recog/websocket';
import { type TranscriptionResultV1 } from '@recog/shared-types';
import { ClientState } from './recognition-client.types.js';
import type { IRecognitionClient, IRecognitionClientStats, RealTimeTwoWayWebSocketRecognitionClientConfig } from './recognition-client.types.js';
/**
* Check if a WebSocket close code indicates normal closure
* @param code - WebSocket close code
* @returns true if the disconnection was normal/expected, false if it was an error
*/
export declare function isNormalDisconnection(code: number): boolean;
/**
* Re-export TranscriptionResultV1 as TranscriptionResult for backward compatibility
*/
export type TranscriptionResult = TranscriptionResultV1;
export type { RealTimeTwoWayWebSocketRecognitionClientConfig } from './recognition-client.types.js';
/**
* RealTimeTwoWayWebSocketRecognitionClient - SDK-level client for real-time speech recognition
*
* Implements IRecognitionClient interface for dependency injection and testing.
* Extends WebSocketAudioClient with local audio buffering and simple callback-based API.
*/
export declare class RealTimeTwoWayWebSocketRecognitionClient extends WebSocketAudioClient<number, any, any> implements IRecognitionClient {
private static readonly PROTOCOL_VERSION;
private config;
private audioBuffer;
private messageHandler;
private state;
private connectionPromise;
private isDebugLogEnabled;
private audioBytesSent;
private audioChunksSent;
private audioStatsLogInterval;
private lastAudioStatsLog;
constructor(config: RealTimeTwoWayWebSocketRecognitionClientConfig);
/**
* Internal logging helper - only logs if a logger was provided in config
* Debug logs are additionally gated by isDebugLogEnabled flag
* @param level - Log level: debug, info, warn, or error
* @param message - Message to log
* @param data - Optional additional data to log
*/
private log;
/**
* Clean up internal resources to free memory
* Called when connection closes (normally or abnormally)
*/
private cleanup;
connect(): Promise<void>;
/**
* Attempt to connect with retry logic
* Only retries on initial connection establishment, not mid-stream interruptions
*/
private connectWithRetry;
sendAudio(audioData: ArrayBuffer | ArrayBufferView | Blob): void;
private sendAudioInternal;
stopRecording(): Promise<void>;
stopAbnormally(): void;
getAudioUtteranceId(): string;
getUrl(): string;
getState(): ClientState;
isConnected(): boolean;
isConnecting(): boolean;
isStopping(): boolean;
isTranscriptionFinished(): boolean;
isBufferOverflowing(): boolean;
getStats(): IRecognitionClientStats;
protected onConnected(): void;
protected onDisconnected(code: number, reason: string): void;
/**
* Get human-readable description for WebSocket close code
*/
private getCloseCodeDescription;
protected onError(error: Event): void;
protected onMessage(msg: {
v: number;
type: string;
data: any;
}): void;
/**
* Handle control messages from server
* @param msg - Control message containing server actions
*/
private handleControlMessage;
/**
* Send audio immediately to the server (without buffering)
* @param audioData - Audio data to send
*/
private sendAudioNow;
}
//# sourceMappingURL=recognition-client.d.ts.map