@amaster.ai/asr-client 1.0.0-beta.7 → 1.0.0-beta.72

package/dist/index.d.ts

@@ -1,40 +1,300 @@
+import { HttpClient } from '@amaster.ai/http-client';
+
 /**
- * ASR Realtime WebSocket Client
- */
-/**
- * Simple ASR: start listening and get transcript
- * @returns stop function
+ * ASR Realtime WebSocket Client for Qwen-ASR Realtime API
+ *
+ * WebSocket-based real-time speech recognition for streaming transcription.
+ * Follows the Qwen-ASR Realtime API protocol with proper event handling.
+ *
  * @example
- * const stop = await listen((text, isFinal) => console.log(text))
- * // later: stop()
+ * ```typescript
+ * const client = createASRClient({
+ *   language: "zh",
+ *   enableVAD: true,
+ *   onReady() {
+ *     console.log("ASR connected");
+ *   },
+ *   onTranscript(text, isFinal) {
+ *     console.log(isFinal ? "[Final]" : "[Interim]", text);
+ *   },
+ *   onError(err) {
+ *     console.error("ASR error:", err);
+ *   },
+ * });
+ *
+ * await client.connect();
+ * await client.startRecording();
+ * // ... stop ...
+ * await client.stopRecording();
+ * await client.close();
+ * ```
  */
-declare function listen(onTranscript: (text: string, isFinal: boolean) => void): Promise<() => void>;
+type ASRLanguage = "zh" | "yue" | "en" | "ja" | "de" | "ko" | "ru" | "fr" | "pt" | "ar" | "it" | "es" | "hi" | "id" | "th" | "tr" | "uk" | "vi" | "cs" | "da" | "fil" | "fi" | "is" | "ms" | "no" | "pl" | "sv";
+type ClientEventType = "session.update" | "input_audio_buffer.append" | "input_audio_buffer.commit" | "session.finish";
+type ServerEventType = "session.created" | "session.updated" | "input_audio_buffer.speech_started" | "input_audio_buffer.speech_stopped" | "input_audio_buffer.committed" | "conversation.item.input_audio_transcription.text" | "conversation.item.input_audio_transcription.completed" | "session.finished" | "error";
+interface BaseEvent {
+    event_id: string;
+    type: ClientEventType | ServerEventType;
+}
+interface SessionUpdateEvent extends BaseEvent {
+    type: "session.update";
+    session: SessionConfig;
+}
+interface InputAudioBufferAppendEvent extends BaseEvent {
+    type: "input_audio_buffer.append";
+    audio: string;
+}
+interface InputAudioBufferCommitEvent extends BaseEvent {
+    type: "input_audio_buffer.commit";
+}
+interface SessionFinishEvent extends BaseEvent {
+    type: "session.finish";
+}
+type ClientEvent = SessionUpdateEvent | InputAudioBufferAppendEvent | InputAudioBufferCommitEvent | SessionFinishEvent;
+interface SessionCreatedEvent extends BaseEvent {
+    type: "session.created";
+    session: {
+        id: string;
+    };
+}
+interface SessionUpdatedEvent extends BaseEvent {
+    type: "session.updated";
+    session: SessionConfig;
+}
+interface SpeechStartedEvent extends BaseEvent {
+    type: "input_audio_buffer.speech_started";
+}
+interface SpeechStoppedEvent extends BaseEvent {
+    type: "input_audio_buffer.speech_stopped";
+}
+interface InputAudioBufferCommittedEvent extends BaseEvent {
+    type: "input_audio_buffer.committed";
+}
+interface TranscriptionTextEvent extends BaseEvent {
+    type: "conversation.item.input_audio_transcription.text";
+    text?: string;
+    stash?: string;
+    transcript?: string;
+}
+interface TranscriptionCompletedEvent extends BaseEvent {
+    type: "conversation.item.input_audio_transcription.completed";
+    text?: string;
+    transcript?: string;
+}
+interface SessionFinishedEvent extends BaseEvent {
+    type: "session.finished";
+}
+interface ErrorEvent extends BaseEvent {
+    type: "error";
+    error: {
+        message: string;
+        code?: string;
+    };
+}
+type ServerEvent = SessionCreatedEvent | SessionUpdatedEvent | SpeechStartedEvent | SpeechStoppedEvent | InputAudioBufferCommittedEvent | TranscriptionTextEvent | TranscriptionCompletedEvent | SessionFinishedEvent | ErrorEvent;
+interface TurnDetectionConfig {
+    type: "server_vad";
+    /** VAD检测阈值，推荐设为 0.0，默认值 0.2，范围 [-1, 1] */
+    threshold?: number;
+    /** VAD断句检测阈值(ms)，推荐设为 400，默认值 800，范围 [200, 6000] */
+    silence_duration_ms?: number;
+}
+interface InputAudioTranscriptionConfig {
+    language?: ASRLanguage;
+}
+interface SessionConfig {
+    input_audio_format?: "pcm" | "opus";
+    sample_rate?: 16000 | 8000;
+    input_audio_transcription?: InputAudioTranscriptionConfig;
+    turn_detection?: TurnDetectionConfig | null;
+}
 interface ASRClientConfig {
-    /** Audio format, default 'pcm16' */
-    audioFormat?: 'pcm16' | 'g711a' | 'g711u';
-    /** Sample rate, default 16000 */
-    sampleRate?: number;
-    /** Called when connection is ready */
+    /**
+     * Audio format
+     * @default "pcm"
+     */
+    audioFormat?: "pcm" | "opus";
+    /**
+     * Sample rate in Hz
+     * @default 16000
+     * @description 支持 16000 和 8000。设置为 8000 时，服务端会先升采样到16000Hz再进行识别，可能引入微小延迟。
+     */
+    sampleRate?: 16000 | 8000;
+    /**
+     * Audio source language
+     * @default "zh"
+     * @description 支持多种语言，包括 zh（中文）、yue（粤语）、en（英文）、ja（日语）等
+     */
+    language?: ASRLanguage;
+    /**
+     * Enable VAD (Voice Activity Detection) mode
+     * @default true
+     * @description true = VAD模式（服务端自动检测语音开始/结束），false = Manual模式（客户端手动控制）
+     */
+    enableVAD?: boolean;
+    /**
+     * VAD detection threshold
+     * @default 0.2
+     * @description 推荐设为 0.0。取值范围 [-1, 1]。较低的阈值会提高 VAD 的灵敏度。
+     */
+    vadThreshold?: number;
+    /**
+     * VAD silence duration threshold in milliseconds
+     * @default 800
+     * @description 推荐设为 400。取值范围 [200, 6000]。静音持续时长超过该阈值将被认为是语句结束。
+     */
+    vadSilenceDurationMs?: number;
+    /**
+     * Get access token for WebSocket authentication
+     */
+    getAccessToken?: () => string | null;
+    /**
+     * Called when connection is ready (session.created received and session.update sent)
+     */
     onReady?: () => void;
-    /** Called when speech is detected */
+    /**
+     * Called when speech is detected (VAD mode only)
+     */
     onSpeechStart?: () => void;
-    /** Called when speech stops */
+    /**
+     * Called when speech stops (VAD mode only)
+     */
     onSpeechEnd?: () => void;
-    /** Called on transcript result */
+    /**
+     * Called on transcript result
+     * @param text - Transcribed text
+     * @param isFinal - Whether this is the final result
+     */
     onTranscript?: (text: string, isFinal: boolean) => void;
-    /** Called on error */
+    /**
+     * Called when audio buffer is committed (non-VAD mode only)
+     */
+    onAudioBufferCommitted?: () => void;
+    /**
+     * Called when session is finished
+     */
+    onSessionFinished?: () => void;
+    /**
+     * Called on error
+     */
     onError?: (error: Error) => void;
+    /**
+     * Called on close
+     */
+    onClose?: () => void;
 }
 interface ASRClient {
-    /** Connect to ASR service */
+    /** Connect to ASR service and establish session */
     connect(): Promise<void>;
     /** Start recording from microphone */
     startRecording(): Promise<void>;
-    /** Stop recording */
-    stopRecording(): void;
-    /** Close connection */
-    close(): void;
+    /**
+     * Stop recording
+     * @description In non-VAD mode, this triggers recognition by sending input_audio_buffer.commit
+     */
+    stopRecording(): Promise<void>;
+    /**
+     * Close connection gracefully
+     * @description Sends session.finish and waits for session.finished before closing
+     */
+    close(): Promise<void>;
+    /**
+     * Check if currently recording
+     */
+    isRecording(): boolean;
+    /**
+     * Check if connected to server
+     */
+    isConnected(): boolean;
+}
+declare const _default$1: (authConfig: Pick<ASRClientConfig, "getAccessToken">) => (config: ASRClientConfig) => ASRClient;
+
+/**
+ * HTTP ASR Client - Press-to-talk style speech recognition
+ *
+ * HTTP-based speech recognition suitable for press-to-talk scenarios where you hold to speak
+ * and release to recognize. Good for voice messages, voice search, etc.
+ *
+ * @example
+ * ```typescript
+ * const client = createASRHttpClient({
+ *   onRecordingStart() {
+ *     console.log("Recording started");
+ *   },
+ *   onRecordingStop() {
+ *     console.log("Recording stopped");
+ *   },
+ *   onResult(text) {
+ *     console.log("Recognized:", text);
+ *   },
+ *   onError(err) {
+ *     console.error("ASR error:", err);
+ *   },
+ * });
+ *
+ * // Hold to speak, release to recognize
+ * await client.startRecording();
+ * // ... stop ...
+ * const result = await client.stopRecording();
+ * ```
+ */
+
+type Status = "idle" | "recording" | "recognizing";
+interface Recorder {
+    /** Start recording */
+    start(): Promise<void>;
+    /**
+     * Stop recording and get base64-encoded WAV audio data. You can use this data to call the ASR API.
+     *
+     * @returns Base64-encoded WAV audio data
+     */
+    stop(): Promise<void>;
+}
+interface RecorderOptions {
+    /** Called when recording starts */
+    onStart?: () => void;
+    /**
+     * Called when recording stops, with base64-encoded WAV audio data. You can use this data to call the ASR API.
+     *
+     * @param base64 - Base64-encoded WAV audio data
+     * @returns void
+     */
+    onStop?: (base64: string) => void;
+    onError?: (error: Error) => void;
+}
+interface ASRHttpClientConfig {
+    http?: HttpClient;
+    /** Get access token */
+    getAccessToken?(): string | null;
+    /** Language, default 'zh' */
+    language?: string;
+    /** Sample rate, default 16000 */
+    sampleRate?: number;
+    /** Create custom recorder */
+    createRecorder?(options?: RecorderOptions): Promise<Recorder>;
+    /** Called when recording starts */
+    onRecordingStart?: () => void;
+    /** Called when recording stops */
+    onRecordingStop?: () => void;
+    /** Called with recognition result */
+    onResult?: (text: string) => void;
+    /** Called on error */
+    onError?: (error: Error) => void;
+    /** Called when status changes */
+    onStatusChange?: (status: Status) => void;
+}
+interface ASRHttpClient {
+    /** Start recording (press-to-talk) */
+    startRecording(): Promise<void>;
+    /** Stop recording and get result */
+    stopRecording(): Promise<void>;
+    /** Record for specific duration then recognize */
+    recordAndRecognize(durationMs: number): Promise<void>;
+    /** Recognize audio file (File or Blob) */
+    recognizeFile(base64: string): Promise<string>;
+    /** Recognize audio from URL */
+    recognizeUrl(audioUrl: string): Promise<string>;
 }
-declare function createASRClient(config: ASRClientConfig): ASRClient;
+declare const _default: (authConfig: Pick<ASRHttpClientConfig, "getAccessToken" | "http">) => (config: ASRHttpClientConfig) => ASRHttpClient;
 
-export { type ASRClient, type ASRClientConfig, createASRClient, createASRClient as createAsrClient, listen };
+export { type ASRClient, type ASRClientConfig, type ASRHttpClient, type ASRHttpClientConfig, type ASRLanguage, type ClientEvent, type ErrorEvent, type InputAudioBufferAppendEvent, type InputAudioBufferCommitEvent, type InputAudioTranscriptionConfig, type ServerEvent, type SessionConfig, type SessionCreatedEvent, type SessionFinishEvent, type SessionFinishedEvent, type SessionUpdateEvent, type SessionUpdatedEvent, type TranscriptionCompletedEvent, type TranscriptionTextEvent, type TurnDetectionConfig, _default$1 as createASRClient, _default as createASRHttpClient };