@volley/recognition-client-sdk/dist/simplified-vgf-recognition-client.d.ts

Recognition Service TypeScript/Node.js Client SDK

/**
 * Simplified VGF Recognition Client
 *
 * A thin wrapper around RealTimeTwoWayWebSocketRecognitionClient that maintains
 * a VGF RecognitionState as a pure sink/output of recognition events.
 *
 * The VGF state is updated based on events but never influences client behavior.
 * All functionality is delegated to the underlying client.
 */
import { RecognitionState } from './vgf-recognition-state.js';
import { IRecognitionClientConfig, ClientState } from './recognition-client.types.js';
/**
 * Configuration for SimplifiedVGFRecognitionClient
 */
export interface SimplifiedVGFClientConfig extends IRecognitionClientConfig {
    /**
     * Callback invoked whenever the VGF state changes
     * Use this to update your UI or React state
     */
    onStateChange?: (state: RecognitionState) => void;
    /**
     * Optional initial state to restore from a previous session
     * If provided, audioUtteranceId will be extracted and used
     */
    initialState?: RecognitionState;
}
/**
 * Interface for SimplifiedVGFRecognitionClient
 *
 * A simplified client that maintains VGF state for game developers.
 * All methods from the underlying client are available, plus VGF state management.
 */
export interface ISimplifiedVGFRecognitionClient {
    /**
     * Connect to the recognition service WebSocket
     * @returns Promise that resolves when connected and ready
     */
    connect(): Promise<void>;
    /**
     * Send audio data for transcription
     * @param audioData - PCM audio data as ArrayBuffer, typed array, or Blob
     */
    sendAudio(audioData: ArrayBuffer | ArrayBufferView | Blob): void;
    /**
     * Stop recording and wait for final transcription
     * @returns Promise that resolves when transcription is complete
     */
    stopRecording(): Promise<void>;
    /**
     * Force stop and immediately close connection without waiting for server
     *
     * WARNING: This is an abnormal shutdown that bypasses the graceful stop flow:
     * - Does NOT wait for server to process remaining audio
     * - Does NOT receive final transcript from server (VGF state set to empty)
     * - Immediately closes WebSocket connection
     * - Cleans up resources (buffers, listeners)
     *
     * Use Cases:
     * - User explicitly cancels/abandons the session
     * - Timeout scenarios where waiting is not acceptable
     * - Need immediate cleanup and can't wait for server
     *
     * RECOMMENDED: Use stopRecording() for normal shutdown.
     * Only use this when immediate disconnection is required.
     */
    stopAbnormally(): void;
    /**
     * Get the current VGF recognition state
     * @returns Current RecognitionState with all transcription data
     */
    getVGFState(): RecognitionState;
    /**
     * Check if connected to the WebSocket
     */
    isConnected(): boolean;
    /**
     * Check if currently connecting
     */
    isConnecting(): boolean;
    /**
     * Check if currently stopping
     */
    isStopping(): boolean;
    /**
     * Check if transcription has finished
     */
    isTranscriptionFinished(): boolean;
    /**
     * Check if the audio buffer has overflowed
     */
    isBufferOverflowing(): boolean;
    /**
     * Get the audio utterance ID for this session
     */
    getAudioUtteranceId(): string;
    /**
     * Get the WebSocket URL being used
     */
    getUrl(): string;
    /**
     * Get the underlying client state (for advanced usage)
     */
    getState(): ClientState;
}
/**
 * This wrapper ONLY maintains VGF state as a sink.
 * All actual functionality is delegated to the underlying client.
 */
export declare class SimplifiedVGFRecognitionClient implements ISimplifiedVGFRecognitionClient {
    private client;
    private state;
    private isRecordingAudio;
    private stateChangeCallback;
    private expectedUuid;
    private logger;
    constructor(config: SimplifiedVGFClientConfig);
    connect(): Promise<void>;
    sendAudio(audioData: ArrayBuffer | ArrayBufferView | Blob): void;
    stopRecording(): Promise<void>;
    stopAbnormally(): void;
    getAudioUtteranceId(): string;
    getUrl(): string;
    getState(): ClientState;
    isConnected(): boolean;
    isConnecting(): boolean;
    isStopping(): boolean;
    isTranscriptionFinished(): boolean;
    isBufferOverflowing(): boolean;
    getVGFState(): RecognitionState;
    private notifyStateChange;
}
/**
 * Factory function for creating simplified client
 * Usage examples:
 *
 * // Basic usage
 * const client = createSimplifiedVGFClient({
 *   asrRequestConfig: { provider: 'deepgram', language: 'en' },
 *   onStateChange: (state) => {
 *     console.log('VGF State updated:', state);
 *     // Update React state, game UI, etc.
 *   }
 * });
 *
 * // With initial state (e.g., restoring from previous session)
 * const client = createSimplifiedVGFClient({
 *   asrRequestConfig: { provider: 'deepgram', language: 'en' },
 *   initialState: previousState, // Will use audioUtteranceId from state
 *   onStateChange: (state) => setVGFState(state)
 * });
 *
 * // With initial state containing promptSlotMap for enhanced recognition
 * const stateWithSlots: RecognitionState = {
 *   audioUtteranceId: 'session-123',
 *   promptSlotMap: {
 *     'song_title': ['one time', 'baby'],
 *     'artists': ['justin bieber']
 *   }
 * };
 * const client = createSimplifiedVGFClient({
 *   asrRequestConfig: { provider: 'deepgram', language: 'en' },
 *   gameContext: {
 *     type: RecognitionContextTypeV1.GAME_CONTEXT,
 *     gameId: 'music-quiz',  // Your game's ID
 *     gamePhase: 'song-guessing'  // Current game phase
 *   },
 *   initialState: stateWithSlots, // promptSlotMap will be added to gameContext
 *   onStateChange: (state) => setVGFState(state)
 * });
 *
 * await client.connect();
 * client.sendAudio(audioData);
 * // VGF state automatically updates based on transcription results
 */
export declare function createSimplifiedVGFClient(config: SimplifiedVGFClientConfig): ISimplifiedVGFRecognitionClient;
//# sourceMappingURL=simplified-vgf-recognition-client.d.ts.map