@volley/recognition-client-sdk 0.1.424 → 0.1.621

package/dist/browser.bundled.d.ts

@@ -15,7 +15,11 @@ declare enum RecognitionProvider {
     GOOGLE = "google",
     GEMINI_BATCH = "gemini-batch",
     OPENAI_BATCH = "openai-batch",
-    OPENAI_REALTIME = "openai-realtime"
+    OPENAI_REALTIME = "openai-realtime",
+    MISTRAL_VOXTRAL = "mistral-voxtral",
+    DASHSCOPE = "dashscope",
+    TEST_ASR_PROVIDER_QUOTA = "test-asr-provider-quota",
+    TEST_ASR_STREAMING = "test-asr-streaming"
 }
 /**
  * ASR API type - distinguishes between streaming and file-based transcription APIs
@@ -77,14 +81,31 @@ declare enum ElevenLabsModel {
  * OpenAI Realtime API transcription models
  * These are the verified `input_audio_transcription.model` values.
  * @see https://platform.openai.com/docs/guides/realtime
+ * @see https://platform.openai.com/docs/models/gpt-4o-transcribe
  */
 declare enum OpenAIRealtimeModel {
+    GPT_4O_TRANSCRIBE = "gpt-4o-transcribe",
     GPT_4O_MINI_TRANSCRIBE = "gpt-4o-mini-transcribe"
 }
+/**
+ * Mistral Voxtral Realtime transcription models
+ * @see https://docs.mistral.ai/models/voxtral-mini-transcribe-realtime-26-02
+ */
+declare enum MistralVoxtralModel {
+    VOXTRAL_MINI_REALTIME_2602 = "voxtral-mini-transcribe-realtime-2602"
+}
+/**
+ * DashScope Qwen-ASR Realtime transcription models
+ * @see https://www.alibabacloud.com/help/en/model-studio/qwen-real-time-speech-recognition
+ */
+declare enum DashScopeModel {
+    QWEN3_ASR_FLASH_REALTIME_2602 = "qwen3-asr-flash-realtime-2026-02-10",
+    QWEN3_ASR_FLASH_REALTIME = "qwen3-asr-flash-realtime"
+}
 /**
  * Type alias for any model from any provider
  */
-type RecognitionModel = DeepgramModel | GoogleModel | FireworksModel | ElevenLabsModel | OpenAIRealtimeModel | string;
+type RecognitionModel = DeepgramModel | GoogleModel | FireworksModel | ElevenLabsModel | OpenAIRealtimeModel | MistralVoxtralModel | DashScopeModel | string;
 
 /**
  * Audio encoding types
@@ -230,8 +251,10 @@ declare const TranscriptionResultSchemaV1: z.ZodObject<{
     type: z.ZodLiteral<RecognitionResultTypeV1.TRANSCRIPTION>;
     audioUtteranceId: z.ZodString;
     finalTranscript: z.ZodString;
+    finalTranscriptRaw: z.ZodString;
     finalTranscriptConfidence: z.ZodOptional<z.ZodNumber>;
     pendingTranscript: z.ZodOptional<z.ZodString>;
+    pendingTranscriptRaw: z.ZodOptional<z.ZodString>;
     pendingTranscriptConfidence: z.ZodOptional<z.ZodNumber>;
     is_finished: z.ZodBoolean;
     voiceStart: z.ZodOptional<z.ZodNumber>;
@@ -241,13 +264,16 @@ declare const TranscriptionResultSchemaV1: z.ZodObject<{
     endTimestamp: z.ZodOptional<z.ZodNumber>;
     receivedAtMs: z.ZodOptional<z.ZodNumber>;
     accumulatedAudioTimeMs: z.ZodOptional<z.ZodNumber>;
+    rawAudioTimeMs: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     type: RecognitionResultTypeV1.TRANSCRIPTION;
     audioUtteranceId: string;
     finalTranscript: string;
+    finalTranscriptRaw: string;
     is_finished: boolean;
     finalTranscriptConfidence?: number | undefined;
     pendingTranscript?: string | undefined;
+    pendingTranscriptRaw?: string | undefined;
     pendingTranscriptConfidence?: number | undefined;
     voiceStart?: number | undefined;
     voiceDuration?: number | undefined;
@@ -256,13 +282,16 @@ declare const TranscriptionResultSchemaV1: z.ZodObject<{
     endTimestamp?: number | undefined;
     receivedAtMs?: number | undefined;
     accumulatedAudioTimeMs?: number | undefined;
+    rawAudioTimeMs?: number | undefined;
 }, {
     type: RecognitionResultTypeV1.TRANSCRIPTION;
     audioUtteranceId: string;
     finalTranscript: string;
+    finalTranscriptRaw: string;
     is_finished: boolean;
     finalTranscriptConfidence?: number | undefined;
     pendingTranscript?: string | undefined;
+    pendingTranscriptRaw?: string | undefined;
     pendingTranscriptConfidence?: number | undefined;
     voiceStart?: number | undefined;
     voiceDuration?: number | undefined;
@@ -271,6 +300,7 @@ declare const TranscriptionResultSchemaV1: z.ZodObject<{
     endTimestamp?: number | undefined;
     receivedAtMs?: number | undefined;
     accumulatedAudioTimeMs?: number | undefined;
+    rawAudioTimeMs?: number | undefined;
 }>;
 type TranscriptionResultV1 = z.infer<typeof TranscriptionResultSchemaV1>;
 /**
@@ -300,11 +330,22 @@ type FunctionCallResultV1 = z.infer<typeof FunctionCallResultSchemaV1>;
  * - WITH_CONTENT → recog.client.websocket.transcript.final_with_content
  * - EMPTY → recog.client.websocket.transcript.final_empty
  * - NEVER_SENT → derived from sessions.streamed - final_with_content - final_empty
+ * - ERROR_* → 1:1 mapping to ErrorTypeV1 for error-caused outcomes
  */
 declare enum TranscriptOutcomeType {
     WITH_CONTENT = "with_content",
     EMPTY = "empty",
-    NEVER_SENT = "never_sent"
+    NEVER_SENT = "never_sent",
+    ERROR_AUTHENTICATION = "error_authentication",
+    ERROR_VALIDATION = "error_validation",
+    ERROR_PROVIDER = "error_provider",
+    ERROR_TIMEOUT = "error_timeout",
+    ERROR_QUOTA = "error_quota",
+    ERROR_INTERNAL_QUOTA = "error_internal_quota",
+    ERROR_CONNECTION = "error_connection",
+    ERROR_NO_AUDIO = "error_no_audio",
+    ERROR_CIRCUIT_BREAKER = "error_circuit_breaker",
+    ERROR_UNKNOWN = "error_unknown"
 }
 /**
  * Metadata result V1 - contains metadata, timing information, and ASR config
@@ -314,6 +355,7 @@ declare enum TranscriptOutcomeType {
 declare const MetadataResultSchemaV1: z.ZodObject<{
     type: z.ZodLiteral<RecognitionResultTypeV1.METADATA>;
     audioUtteranceId: z.ZodString;
+    connectionInitiatedAtMs: z.ZodOptional<z.ZodNumber>;
     recordingStartMs: z.ZodOptional<z.ZodNumber>;
     recordingEndMs: z.ZodOptional<z.ZodNumber>;
     transcriptEndMs: z.ZodOptional<z.ZodNumber>;
@@ -321,14 +363,53 @@ declare const MetadataResultSchemaV1: z.ZodObject<{
     duration: z.ZodOptional<z.ZodNumber>;
     volume: z.ZodOptional<z.ZodNumber>;
     accumulatedAudioTimeMs: z.ZodOptional<z.ZodNumber>;
+    rawAudioTimeMs: z.ZodOptional<z.ZodNumber>;
     costInUSD: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
     apiType: z.ZodOptional<z.ZodNativeEnum<typeof ASRApiType>>;
     asrConfig: z.ZodOptional<z.ZodString>;
     rawAsrMetadata: z.ZodOptional<z.ZodString>;
     transcriptOutcome: z.ZodOptional<z.ZodNativeEnum<typeof TranscriptOutcomeType>>;
+    audioMetrics: z.ZodOptional<z.ZodObject<{
+        valid: z.ZodBoolean;
+        audioBeginMs: z.ZodNumber;
+        audioEndMs: z.ZodNumber;
+        maxVolume: z.ZodNumber;
+        minVolume: z.ZodNumber;
+        avgVolume: z.ZodNumber;
+        silenceRatio: z.ZodNumber;
+        clippingRatio: z.ZodNumber;
+        snrEstimate: z.ZodNullable<z.ZodNumber>;
+        lastNonSilenceMs: z.ZodNumber;
+        timestamp: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        valid: boolean;
+        audioBeginMs: number;
+        audioEndMs: number;
+        maxVolume: number;
+        minVolume: number;
+        avgVolume: number;
+        silenceRatio: number;
+        clippingRatio: number;
+        snrEstimate: number | null;
+        lastNonSilenceMs: number;
+        timestamp: string;
+    }, {
+        valid: boolean;
+        audioBeginMs: number;
+        audioEndMs: number;
+        maxVolume: number;
+        minVolume: number;
+        avgVolume: number;
+        silenceRatio: number;
+        clippingRatio: number;
+        snrEstimate: number | null;
+        lastNonSilenceMs: number;
+        timestamp: string;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     type: RecognitionResultTypeV1.METADATA;
     audioUtteranceId: string;
+    connectionInitiatedAtMs?: number | undefined;
     recordingStartMs?: number | undefined;
     recordingEndMs?: number | undefined;
     transcriptEndMs?: number | undefined;
@@ -336,14 +417,29 @@ declare const MetadataResultSchemaV1: z.ZodObject<{
     duration?: number | undefined;
     volume?: number | undefined;
     accumulatedAudioTimeMs?: number | undefined;
+    rawAudioTimeMs?: number | undefined;
     costInUSD?: number | undefined;
     apiType?: ASRApiType | undefined;
     asrConfig?: string | undefined;
     rawAsrMetadata?: string | undefined;
     transcriptOutcome?: TranscriptOutcomeType | undefined;
+    audioMetrics?: {
+        valid: boolean;
+        audioBeginMs: number;
+        audioEndMs: number;
+        maxVolume: number;
+        minVolume: number;
+        avgVolume: number;
+        silenceRatio: number;
+        clippingRatio: number;
+        snrEstimate: number | null;
+        lastNonSilenceMs: number;
+        timestamp: string;
+    } | undefined;
 }, {
     type: RecognitionResultTypeV1.METADATA;
     audioUtteranceId: string;
+    connectionInitiatedAtMs?: number | undefined;
     recordingStartMs?: number | undefined;
     recordingEndMs?: number | undefined;
     transcriptEndMs?: number | undefined;
@@ -351,11 +447,25 @@ declare const MetadataResultSchemaV1: z.ZodObject<{
     duration?: number | undefined;
     volume?: number | undefined;
     accumulatedAudioTimeMs?: number | undefined;
+    rawAudioTimeMs?: number | undefined;
     costInUSD?: number | undefined;
     apiType?: ASRApiType | undefined;
     asrConfig?: string | undefined;
     rawAsrMetadata?: string | undefined;
     transcriptOutcome?: TranscriptOutcomeType | undefined;
+    audioMetrics?: {
+        valid: boolean;
+        audioBeginMs: number;
+        audioEndMs: number;
+        maxVolume: number;
+        minVolume: number;
+        avgVolume: number;
+        silenceRatio: number;
+        clippingRatio: number;
+        snrEstimate: number | null;
+        lastNonSilenceMs: number;
+        timestamp: string;
+    } | undefined;
 }>;
 type MetadataResultV1 = z.infer<typeof MetadataResultSchemaV1>;
 /**
@@ -367,7 +477,10 @@ declare enum ErrorTypeV1 {
     PROVIDER_ERROR = "provider_error",
     TIMEOUT_ERROR = "timeout_error",
     QUOTA_EXCEEDED = "quota_exceeded",
+    INTERNAL_QUOTA_EXHAUSTED = "internal_quota_exhausted",
     CONNECTION_ERROR = "connection_error",
+    NO_AUDIO_ERROR = "no_audio_error",
+    CIRCUIT_BREAKER_OPEN = "circuit_breaker_open",
     UNKNOWN_ERROR = "unknown_error"
 }
 /**
@@ -419,6 +532,15 @@ declare enum ControlSignalTypeV1 {
     START_RECORDING = "start_recording",
     STOP_RECORDING = "stop_recording"
 }
+/**
+ * Prefix audio mode for ASR Request V1
+ * Controls how prefix audio is handled during recognition
+ */
+declare enum PrefixMode {
+    NONE = "none",
+    CLIENT = "client",
+    STORED = "stored"
+}
 /**
  * Game context V1 - contains game state information
  */
@@ -476,13 +598,13 @@ declare enum FinalTranscriptStability {
      */
     AGGRESSIVE = "aggressive",
     /**
-     * Balanced mode: 200ms timeout (default)
+     * Balanced mode: 500ms timeout (default)
      * Natural middle ground for most conversational scenarios
      * Use cases: General customer support, tech support, typical voice interactions
      */
     BALANCED = "balanced",
     /**
-     * Conservative mode: 400ms timeout
+     * Conservative mode: 1000ms timeout
      * Wait longer for providers, optimized for complex/reflective speech
      * Use cases: Healthcare, complex queries, careful thought processes
      */
@@ -574,13 +696,70 @@ interface ASRRequestConfig {
      * doesn't respond with is_final=true after stopRecording().
      *
      * - aggressive: 100ms - fast response, may cut off slow providers
-     * - balanced: 200ms - current default, good for most cases
-     * - conservative: 400ms - wait longer for complex utterances
+     * - balanced: 500ms - current default, good for most cases
+     * - conservative: 1000ms - wait longer for complex utterances
      *
      * @default 'balanced'
      * @see FinalTranscriptStability enum for detailed descriptions
      */
     finalTranscriptStability?: FinalTranscriptStability | string;
+    /**
+     * Traffic control priority for quota slot allocation
+     *
+     * Controls which quota slots this request can use when traffic control is enabled.
+     * The quota system reserves a portion of slots for high-priority requests.
+     *
+     * - 'high': Can use all quota slots (reserved for critical games like song-quiz)
+     * - 'low': Limited to non-reserved slots (default for most requests)
+     *
+     * @default 'low'
+     */
+    priority?: 'low' | 'high';
+    /**
+     * Prefix audio injection mode
+     *
+     * Controls how prefix audio is handled:
+     * - 'none': No prefix audio (default)
+     * - 'client': Client sends PREFIX_AUDIO before user audio
+     * - 'stored': Server injects stored prefix audio by prefixId
+     *
+     * @default 'none'
+     */
+    prefixMode?: PrefixMode | string;
+    /**
+     * Stored prefix audio identifier
+     *
+     * Only used when prefixMode='stored'. The server will look up this ID
+     * in the PrefixAudioCache and inject the corresponding audio before
+     * user audio is processed.
+     *
+     * @example 'song_quiz'
+     */
+    prefixId?: string;
+    /**
+     * Prefix text patterns to remove from transcripts
+     *
+     * Array of prefix text variants that should be stripped from the transcript.
+     * This is used when prefix audio is injected and the ASR transcribes both
+     * the prefix and user speech - we remove the prefix portion.
+     *
+     * Multiple variants are supported because ASR may transcribe contractions
+     * differently (e.g., "What's this song" vs "What is this song").
+     *
+     * Matching rules:
+     * - Case insensitive
+     * - Leading/trailing whitespace trimmed
+     * - Multiple spaces collapsed
+     * - Punctuation (?.!,) stripped for matching
+     * - Apostrophes preserved (part of contractions)
+     *
+     * Can be set via:
+     * - Server-side game config (production)
+     * - Client-side ASRRequest (testing/override) - takes precedence
+     *
+     * @example ["What's this song", "What is this song"]
+     */
+    prefixTextToRemove?: string[];
     /**
      * Additional provider-specific options
      *
@@ -1040,6 +1219,26 @@ interface IRecognitionClient {
      * @returns WebSocket URL string
      */
     getUrl(): string;
+    /**
+     * Send game context after connection is established (for preconnect flow).
+     *
+     * Preconnect flow: Create client with asrRequestConfig (useContext: true) but
+     * WITHOUT gameContext → call connect() → WS opens, ASRRequest sent, server
+     * waits in PENDING_CONTEXT → later call sendGameContext() with slotMap →
+     * server attaches provider and sends READY.
+     *
+     * This enables connecting early (before slotMap is known) and sending
+     * game context later when question data is available.
+     *
+     * @param context - Game context including slotMap for keyword boosting
+     */
+    sendGameContext(context: GameContextV1): void;
+    /**
+     * Check if server has sent READY signal (provider is connected and ready for audio).
+     * In preconnect flow, this becomes true after sendGameContext() triggers provider attachment.
+     * @returns true if server is ready to receive audio
+     */
+    isServerReady(): boolean;
 }
 /**
  * Client statistics interface
@@ -1114,8 +1313,11 @@ type TranscriptionResult = TranscriptionResultV1;
  */
 declare class RealTimeTwoWayWebSocketRecognitionClient extends WebSocketAudioClient<number, any, any> implements IRecognitionClient {
     private static readonly PROTOCOL_VERSION;
+    private static readonly MAX_PREFIX_BUFFER_BYTES;
     private config;
     private audioBuffer;
+    private prefixBuffer;
+    private prefixBufferBytes;
     private messageHandler;
     private state;
     private connectionPromise;
@@ -1160,6 +1362,8 @@ declare class RealTimeTwoWayWebSocketRecognitionClient extends WebSocketAudioCli
     isStopping(): boolean;
     isTranscriptionFinished(): boolean;
     isBufferOverflowing(): boolean;
+    isServerReady(): boolean;
+    sendGameContext(context: GameContextV1): void;
     getStats(): IRecognitionClientStats;
     protected onConnected(): void;
     protected onDisconnected(code: number, reason: string): void;
@@ -1183,6 +1387,28 @@ declare class RealTimeTwoWayWebSocketRecognitionClient extends WebSocketAudioCli
      * @param audioData - Audio data to send
      */
     private sendAudioNow;
+    /**
+     * Send prefix audio to the server.
+     * Prefix audio is sent before user audio and is used for context/priming.
+     * The server will process it but adjust timing so transcripts reflect user audio timing.
+     *
+     * Note: Prefix audio is buffered until READY state, then flushed before user audio.
+     * This ensures proper ordering even if called before server is ready.
+     *
+     * @param audioData - Prefix audio data (ArrayBuffer, ArrayBufferView, or Blob)
+     */
+    sendPrefixAudio(audioData: ArrayBuffer | ArrayBufferView | Blob): void;
+    /**
+     * Internal method to handle prefix audio with buffering
+     * Buffers if not READY, sends immediately if READY
+     */
+    private sendPrefixAudioInternal;
+    /**
+     * Send prefix audio immediately to the server (without buffering)
+     * Uses encoding offset to mark as prefix audio
+     * @param audioData - Prefix audio data to send
+     */
+    private sendPrefixAudioNow;
 }
 
 export { AudioEncoding, ControlSignalTypeV1 as ControlSignal, RealTimeTwoWayWebSocketRecognitionClient, RecognitionContextTypeV1 };