@amaster.ai/asr-client 1.1.0-beta.50 → 1.1.0-beta.51

package/README.md

@@ -2,15 +2,19 @@
 
 基于 Web Audio + WebSocket 的 **实时语音识别（ASR）客户端 SDK**，用于将浏览器麦克风音频实时发送到 ASR 服务（如 Qwen ASR Realtime），并接收实时/最终转写结果。
 
+遵循 [Qwen-ASR Realtime API](https://help.aliyun.com/zh/model-studio/qwen-realtime-speech-recognition) 协议实现，完整支持会话管理、VAD 模式、手动模式等全部功能。
+
 ---
 
 ## 特性
 
 - 🎙 浏览器麦克风实时采集（16kHz / 单声道）
 - 🔁 实时音频流式发送（Base64 PCM16）
-- 🧠 支持语音开始 / 结束事件
+- 🧠 支持 VAD 模式（自动检测语音开始/结束）和 Manual 模式（手动控制）
+- 🌍 支持 25 种语言识别
 - ✍️ 支持中间结果与最终转写结果
-- 🔌 简单的 WebSocket 生命周期管理
+- 📡 完整的会话生命周期管理（session.update、session.finish）
+- 🔌 事件 ID 自动生成，符合协议规范
 - 🌐 同时支持 WebSocket 实时识别和 HTTP 按压识别
 
 ---
@@ -46,70 +50,95 @@ yarn add @amaster.ai/asr-client
 
 适合需要实时看到识别结果的场景，如语音输入、实时字幕等。
 
-#### 1️⃣ 创建 ASR Client
+#### VAD 模式（推荐）
+
+自动检测语音开始和结束：
 
 ```ts
 import { createASRClient } from "@amaster.ai/asr-client";
 
 const client = createASRClient({
+  // 语言配置
+  language: "zh", // 支持 zh、yue、en、ja 等 25 种语言
+
+  // VAD 配置（自动检测语音）
+  enableVAD: true,
+  vadThreshold: 0.0, // 推荐设为 0.0，默认 0.2
+  vadSilenceDurationMs: 400, // 推荐设为 400ms，默认 800ms
+
+  // 回调函数
   onReady() {
-    console.log("ASR 连接成功");
+    console.log("ASR 连接成功，会话已配置");
   },
 
   onSpeechStart() {
-    console.log("检测到说话开始");
+    console.log("🎤 检测到说话开始");
   },
 
   onSpeechEnd() {
-    console.log("检测到说话结束");
+    console.log("🛑 检测到说话结束");
   },
 
   onTranscript(text, isFinal) {
-    console.log(isFinal ? "最终结果：" : "实时结果：", text);
+    console.log(isFinal ? "✅ 最终结果：" : "📝 实时结果：", text);
+  },
+
+  onSessionFinished() {
+    console.log("👋 会话已结束");
   },
 
   onError(err) {
-    console.error("ASR 错误", err);
+    console.error("❌ ASR 错误", err);
   },
 
   onClose() {
-    console.log("连接已关闭");
+    console.log("🔌 连接已关闭");
   },
 });
-```
 
-#### 2️⃣ 建立 WebSocket 连接
-
-```ts
+// 1. 建立连接（自动发送 session.update）
 await client.connect();
-```
 
-连接成功后会触发 `onReady` 回调。
+// 2. 开始录音
+await client.startRecording();
 
-#### 3️⃣ 开始录音并实时识别
+// 3. 停止录音（VAD 模式下可选，会自动检测结束）
+await client.stopRecording();
 
-```ts
-await client.startRecording();
+// 4. 关闭连接（自动发送 session.finish）
+await client.close();
 ```
 
-- 自动请求麦克风权限
-- 自动开始推送音频流
-- 服务端会持续返回实时转写结果
+#### Manual 模式（非 VAD）
 
-#### 4️⃣ 停止录音
+手动控制识别时机，适合按住说话、松开识别的场景：
 
 ```ts
-client.stopRecording();
-```
+const client = createASRClient({
+  language: "zh",
+  enableVAD: false, // 关闭 VAD，使用手动模式
+
+  onReady() {
+    console.log("准备就绪");
+  },
 
-- 停止麦克风采集
-- 向服务端发送 `input_audio_buffer.commit`
-- 触发最终转写结果
+  onTranscript(text, isFinal) {
+    if (isFinal) {
+      console.log("识别结果：", text);
+    }
+  },
 
-#### 5️⃣ 关闭连接
+  onAudioBufferCommitted() {
+    console.log("音频已提交，等待识别结果...");
+  },
+});
 
-```ts
-client.close();
+await client.connect();
+await client.startRecording();
+
+// 用户说话中...
+
+await client.stopRecording(); // 触发 input_audio_buffer.commit
 ```
 
 ---
@@ -183,26 +212,73 @@ WebSocket 实时 ASR 客户端。
 
 #### `ASRClientConfig`
 
-| 参数             | 类型                                       | 说明                                   |
-| ---------------- | ------------------------------------------ | -------------------------------------- |
-| `audioFormat`    | `"pcm16" \| "g711a" \| "g711u"`            | 音频格式，默认 `'pcm16'`               |
-| `sampleRate`     | `number`                                   | 采样率，默认 `16000`                   |
-| `getAccessToken` | `() => string \| null`                     | 获取访问令牌（用于 WebSocket 认证）    |
-| `onReady`        | `() => void`                               | 会话创建完成                           |
-| `onSpeechStart`  | `() => void`                               | 检测到语音开始                         |
-| `onSpeechEnd`    | `() => void`                               | 检测到语音结束                         |
-| `onTranscript`   | `(text: string, isFinal: boolean) => void` | 转写回调，`isFinal` 表示是否为最终结果 |
-| `onError`        | `(error: Error) => void`                   | 错误回调                               |
-| `onClose`        | `() => void`                               | 连接关闭回调                           |
+| 参数                     | 类型                                       | 默认值  | 说明                                                     |
+| ------------------------ | ------------------------------------------ | ------- | -------------------------------------------------------- |
+| `audioFormat`            | `"pcm" \| "opus"`                          | `"pcm"` | 音频格式                                                 |
+| `sampleRate`             | `16000 \| 8000`                            | `16000` | 采样率。8000 会先升采样到 16000，可能引入微小延迟        |
+| `language`               | `ASRLanguage`                              | `"zh"`  | 音频源语言，支持 25 种语言（见下方语言列表）             |
+| `enableVAD`              | `boolean`                                  | `true`  | 是否启用 VAD 模式。`true`=自动检测，`false`=手动控制     |
+| `vadThreshold`           | `number`                                   | `0.2`   | VAD 检测阈值，推荐设为 `0.0`，范围 `[-1, 1]`             |
+| `vadSilenceDurationMs`   | `number`                                   | `800`   | VAD 断句检测阈值(ms)，推荐设为 `400`，范围 `[200, 6000]` |
+| `getAccessToken`         | `() => string \| null`                     | -       | 获取访问令牌（用于 WebSocket 认证）                      |
+| `onReady`                | `() => void`                               | -       | 会话创建并配置完成（收到 session.updated）               |
+| `onSpeechStart`          | `() => void`                               | -       | 检测到语音开始（VAD 模式）                               |
+| `onSpeechEnd`            | `() => void`                               | -       | 检测到语音结束（VAD 模式）                               |
+| `onTranscript`           | `(text: string, isFinal: boolean) => void` | -       | 转写回调，`isFinal` 表示是否为最终结果                   |
+| `onAudioBufferCommitted` | `() => void`                               | -       | 音频缓冲区已提交（非 VAD 模式）                          |
+| `onSessionFinished`      | `() => void`                               | -       | 会话已结束（收到 session.finished）                      |
+| `onError`                | `(error: Error) => void`                   | -       | 错误回调                                                 |
+| `onClose`                | `() => void`                               | -       | 连接关闭回调                                             |
+
+#### 支持的语言 (ASRLanguage)
+
+| 代码  | 语言                                 | 代码 | 语言     |
+| ----- | ------------------------------------ | ---- | -------- |
+| `zh`  | 中文（普通话、四川话、闽南语、吴语） | `it` | 意大利语 |
+| `yue` | 粤语                                 | `es` | 西班牙语 |
+| `en`  | 英文                                 | `hi` | 印地语   |
+| `ja`  | 日语                                 | `id` | 印尼语   |
+| `de`  | 德语                                 | `th` | 泰语     |
+| `ko`  | 韩语                                 | `tr` | 土耳其语 |
+| `ru`  | 俄语                                 | `uk` | 乌克兰语 |
+| `fr`  | 法语                                 | `vi` | 越南语   |
+| `pt`  | 葡萄牙语                             | `cs` | 捷克语   |
+| `ar`  | 阿拉伯语                             | `da` | 丹麦语   |
+| `fil` | 菲律宾语                             | `fi` | 芬兰语   |
+| `is`  | 冰岛语                               | `ms` | 马来语   |
+| `no`  | 挪威语                               | `pl` | 波兰语   |
+| `sv`  | 瑞典语                               |      |          |
 
 #### `ASRClient`
 
 ```ts
 interface ASRClient {
-  connect(): Promise<void>; // 建立 WebSocket 连接
-  startRecording(): Promise<void>; // 开始录音
-  stopRecording(): void; // 停止录音
-  close(): void; // 关闭连接
+  /** 建立 WebSocket 连接并发送 session.update */
+  connect(): Promise<void>;
+
+  /** 开始录音并流式发送音频 */
+  startRecording(): Promise<void>;
+
+  /**
+   * 停止录音
+   * - VAD 模式：停止发送音频
+   * - 非 VAD 模式：停止发送音频并触发识别（发送 input_audio_buffer.commit）
+   */
+  stopRecording(): Promise<void>;
+
+  /**
+   * 关闭连接
+   * - 发送 session.finish
+   * - 等待 session.finished
+   * - 关闭 WebSocket
+   */
+  close(): Promise<void>;
+
+  /** 是否正在录音 */
+  isRecording(): boolean;
+
+  /** 是否已连接到服务器 */
+  isConnected(): boolean;
 }
 ```
 
@@ -273,11 +349,42 @@ const result = await asrHttpClient.stopRecording();
 
 ---
 
+## VAD 模式 vs Manual 模式
+
+| 特性     | VAD 模式（enableVAD: true）            | Manual 模式（enableVAD: false） |
+| -------- | -------------------------------------- | ------------------------------- |
+| 语音检测 | 服务端自动检测                         | 客户端手动控制                  |
+| 适用场景 | 连续对话、实时字幕                     | 按住说话、语音消息              |
+| 开始录音 | `startRecording()`                     | `startRecording()`              |
+| 停止录音 | 自动检测 / `stopRecording()`           | `stopRecording()` 触发识别      |
+| 事件触发 | `onSpeechStart` / `onSpeechEnd`        | `onAudioBufferCommitted`        |
+| 配置参数 | `vadThreshold`, `vadSilenceDurationMs` | 无需 VAD 配置                   |
+
+### VAD 配置建议
+
+```ts
+// 快速响应场景（如实时字幕）
+const client = createASRClient({
+  enableVAD: true,
+  vadThreshold: 0.0, // 最灵敏
+  vadSilenceDurationMs: 400, // 较短停顿即断句
+});
+
+// 长句输入场景（如文章朗读）
+const client = createASRClient({
+  enableVAD: true,
+  vadThreshold: 0.2, // 默认灵敏度
+  vadSilenceDurationMs: 1200, // 较长停顿才断句
+});
+```
+
+---
+
 ## 音频参数说明
 
 ### WebSocket ASR
 
-- **采样率**：16000 Hz
+- **采样率**：16000 Hz（推荐）或 8000 Hz
 - **声道**：单声道
 - **格式**：PCM16 → Base64
 - **缓冲大小**：4096 frames
@@ -312,14 +419,27 @@ ASR 服务通常要求 16kHz PCM 输入，否则会影响识别效果或直接
 - iOS Safari 需用户手势触发录音
 - 后台会自动暂停音频采集
 
+### Q: VAD 模式下为什么要等一段时间才返回最终结果？
+
+VAD 需要检测到静音（silence）才会认为一句话结束，然后返回最终结果。`vadSilenceDurationMs` 配置了这个静音时长阈值。
+
+### Q: 如何切换语言？
+
+```ts
+const client = createASRClient({
+  language: "en", // 英文识别
+});
+```
+
 ---
 
 ## 注意事项
 
 - WebSocket 必须在 HTTPS 页面下使用麦克风
-- 页面关闭前建议调用 `client.close()`
+- 页面关闭前建议调用 `await client.close()` 优雅关闭
 - 不建议在多个 ASR Client 实例中共享麦克风
 - HTTP ASR 会自动将录音转为 WAV 格式上传
+- 每个事件都会自动生成唯一的 `event_id`，符合协议规范
 
 ---
 

package/dist/index.cjs

@@ -28,10 +28,10 @@ module.exports = __toCommonJS(index_exports);
 // src/asr-client.ts
 var ASR_PATH = "/api/proxy/builtin/platform/qwen-asr-realtime/api-ws/v1/realtime";
 async function createRealtimeRecorder() {
-  let stream;
-  let ctx;
-  let source;
-  let processor;
+  let stream = null;
+  let ctx = null;
+  let source = null;
+  let processor = null;
   return {
     async start(onAudio) {
       stream = await navigator.mediaDevices.getUserMedia({
@@ -63,18 +63,144 @@ async function createRealtimeRecorder() {
       stream?.getTracks().forEach((t) => t.stop());
       source?.disconnect();
       processor?.disconnect();
-      await ctx?.close();
+      if (ctx) {
+        await ctx.close();
+      }
+      stream = null;
+      ctx = null;
+      source = null;
+      processor = null;
     }
   };
 }
 var log = (message, type = "") => {
   console.log(`[${type}]`, message);
 };
+var eventIdCounter = 0;
+function generateEventId() {
+  return `event_${Date.now()}_${++eventIdCounter}`;
+}
 function createASRClient(config) {
-  const { onReady, onSpeechStart, onSpeechEnd, onTranscript, onError, onClose, getAccessToken } = config;
+  const {
+    onReady,
+    onSpeechStart,
+    onSpeechEnd,
+    onTranscript,
+    onAudioBufferCommitted,
+    onSessionFinished,
+    onError,
+    onClose,
+    getAccessToken,
+    audioFormat = "pcm",
+    sampleRate = 16e3,
+    language = "zh",
+    enableVAD = true,
+    vadThreshold = 0.2,
+    vadSilenceDurationMs = 400
+  } = config;
   let ws = null;
   let recorder = null;
+  let isRecordingFlag = false;
+  let isClosing = false;
   const path = ASR_PATH;
+  function sendEvent(event) {
+    if (!ws || ws.readyState !== WebSocket.OPEN) {
+      throw new Error("WebSocket not connected");
+    }
+    ws.send(JSON.stringify(event));
+  }
+  function buildSessionConfig() {
+    const sessionConfig = {
+      input_audio_format: audioFormat,
+      sample_rate: sampleRate,
+      input_audio_transcription: {
+        language
+      }
+    };
+    if (enableVAD) {
+      sessionConfig.turn_detection = {
+        type: "server_vad",
+        threshold: vadThreshold,
+        silence_duration_ms: vadSilenceDurationMs
+      };
+    } else {
+      sessionConfig.turn_detection = null;
+    }
+    return sessionConfig;
+  }
+  function sendSessionUpdate() {
+    const event = {
+      event_id: generateEventId(),
+      type: "session.update",
+      session: buildSessionConfig()
+    };
+    sendEvent(event);
+  }
+  function sendAudioBufferAppend(audio) {
+    const event = {
+      event_id: generateEventId(),
+      type: "input_audio_buffer.append",
+      audio
+    };
+    sendEvent(event);
+  }
+  function sendAudioBufferCommit() {
+    const event = {
+      event_id: generateEventId(),
+      type: "input_audio_buffer.commit"
+    };
+    sendEvent(event);
+  }
+  function sendSessionFinish() {
+    const event = {
+      event_id: generateEventId(),
+      type: "session.finish"
+    };
+    sendEvent(event);
+  }
+  function handleServerEvent(data) {
+    switch (data.type) {
+      case "session.created":
+        try {
+          sendSessionUpdate();
+        } catch (err2) {
+          onError?.(
+            new Error(
+              "Failed to send session.update: " + (err2 instanceof Error ? err2.message : String(err2))
+            )
+          );
+        }
+        break;
+      case "session.updated":
+        onReady?.();
+        break;
+      case "input_audio_buffer.speech_started":
+        onSpeechStart?.();
+        break;
+      case "input_audio_buffer.speech_stopped":
+        onSpeechEnd?.();
+        break;
+      case "input_audio_buffer.committed":
+        onAudioBufferCommitted?.();
+        break;
+      case "conversation.item.input_audio_transcription.text":
+        onTranscript?.(data.text || data.stash || data.transcript || "", false);
+        break;
+      case "conversation.item.input_audio_transcription.completed":
+        onTranscript?.(data.text || data.transcript || "", true);
+        break;
+      case "session.finished":
+        onSessionFinished?.();
+        ws?.close();
+        break;
+      case "error":
+        const err = new Error(data.error?.message || "ASR error");
+        onError?.(err);
+        break;
+      default:
+        console.warn("[ASR] Unknown server event:", data.type);
+    }
+  }
   async function connect() {
     let wsUrl = path;
     if (getAccessToken) {
@@ -84,30 +210,34 @@ function createASRClient(config) {
         wsUrl = `${path}${separator}token=${encodeURIComponent(token)}`;
       }
     }
+    if (typeof window !== "undefined" && window.location) {
+      const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
+      if (!wsUrl.startsWith("ws://") && !wsUrl.startsWith("wss://")) {
+        wsUrl = `${protocol}//${window.location.host}${wsUrl}`;
+      }
+    }
     ws = new WebSocket(wsUrl);
     return new Promise((resolve, reject) => {
+      if (!ws) {
+        reject(new Error("Failed to create WebSocket"));
+        return;
+      }
+      ws.onopen = () => {
+        log("WebSocket connected", "success");
+      };
       ws.onmessage = (event) => {
-        const data = JSON.parse(event.data);
-        if (data.type === "session.created") {
-          onReady?.();
-          resolve();
-        }
-        if (data.type === "input_audio_buffer.speech_started") {
-          onSpeechStart?.();
-        }
-        if (data.type === "input_audio_buffer.speech_stopped") {
-          onSpeechEnd?.();
-        }
-        if (data.type === "conversation.item.input_audio_transcription.text") {
-          onTranscript?.(data.text || data.stash || data.transcript || "", false);
-        }
-        if (data.type === "conversation.item.input_audio_transcription.completed") {
-          onTranscript?.(data.text || data.transcript || "", true);
-        }
-        if (data.type === "error") {
-          const err = new Error(data.error?.message || "ASR error");
-          onError?.(err);
-          reject(err);
+        try {
+          const data = JSON.parse(event.data);
+          handleServerEvent(data);
+          if (data.type === "session.updated") {
+            resolve();
+          }
+        } catch (err) {
+          const error = new Error(
+            "Failed to parse server message: " + (err instanceof Error ? err.message : String(err))
+          );
+          onError?.(error);
+          reject(error);
         }
       };
       ws.onerror = () => {
@@ -116,8 +246,7 @@ function createASRClient(config) {
         reject(err);
       };
       ws.onclose = () => {
-        recorder?.stop();
-        recorder = null;
+        isRecordingFlag = false;
         ws = null;
         onClose?.();
       };
@@ -127,37 +256,70 @@ function createASRClient(config) {
     if (!ws || ws.readyState !== WebSocket.OPEN) {
       throw new Error("WebSocket not connected");
     }
+    if (isRecordingFlag) {
+      throw new Error("Already recording");
+    }
     recorder = await createRealtimeRecorder();
+    isRecordingFlag = true;
     await recorder.start((audio) => {
       if (!ws || ws.readyState !== WebSocket.OPEN) return;
-      ws.send(
-        JSON.stringify({
-          type: "input_audio_buffer.append",
-          audio
-        })
-      );
+      try {
+        sendAudioBufferAppend(audio);
+      } catch (err) {
+        console.error("[ASR] Failed to send audio:", err);
+      }
     });
   }
   async function stopRecording() {
+    if (!isRecordingFlag) {
+      return;
+    }
     try {
       await recorder?.stop();
     } catch (err) {
+      console.error("[ASR] Error stopping recorder:", err);
     }
     recorder = null;
-    if (ws && ws.readyState === WebSocket.OPEN) {
-      ws.send(JSON.stringify({ type: "input_audio_buffer.commit" }));
+    isRecordingFlag = false;
+    if (!enableVAD && ws?.readyState === WebSocket.OPEN) {
+      try {
+        sendAudioBufferCommit();
+      } catch (err) {
+        console.error("[ASR] Failed to send commit:", err);
+      }
     }
   }
-  function close() {
-    stopRecording();
+  async function close() {
+    if (isClosing) {
+      return;
+    }
+    isClosing = true;
+    await stopRecording();
+    if (ws?.readyState === WebSocket.OPEN) {
+      try {
+        sendSessionFinish();
+        await new Promise((resolve) => setTimeout(resolve, 1e3));
+      } catch (err) {
+        console.error("[ASR] Failed to send session.finish:", err);
+      }
+    }
     ws?.close();
     ws = null;
+    isClosing = false;
+  }
+  function isRecording() {
+    return isRecordingFlag;
+  }
+  function isConnected() {
+    return ws !== null && ws.readyState === WebSocket.OPEN;
   }
   return {
     connect,
     startRecording,
     stopRecording,
-    close
+    close,
+    isRecording,
+    isConnected
   };
 }
 var asr_client_default = (authConfig) => (config) => createASRClient({ ...authConfig, ...config });