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

package/README.md

@@ -2,20 +2,38 @@
 
 基于 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 按压识别
 
 ---
 
 ## 安装与环境要求
 
+### 安装
+
+```bash
+# npm
+npm install @amaster.ai/asr-client
+
+# pnpm
+pnpm add @amaster.ai/asr-client
+
+# yarn
+yarn add @amaster.ai/asr-client
+```
+
 ### 浏览器要求
 
 - 支持 `getUserMedia`
@@ -28,143 +46,400 @@
 
 ## 快速开始
 
-### 1️⃣ 创建 ASR Client
+### 方式一：WebSocket 实时 ASR（流式识别）
+
+适合需要实时看到识别结果的场景，如语音输入、实时字幕等。
+
+#### VAD 模式（推荐）
+
+自动检测语音开始和结束：
 
 ```ts
-import { createASRClient } from "./asr-client";
+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("🔌 连接已关闭");
   },
 });
+
+// 1. 建立连接（自动发送 session.update）
+await client.connect();
+
+// 2. 开始录音
+await client.startRecording();
+
+// 3. 停止录音（VAD 模式下可选，会自动检测结束）
+await client.stopRecording();
+
+// 4. 关闭连接（自动发送 session.finish）
+await client.close();
 ```
 
----
+#### Manual 模式（非 VAD）
 
-### 2️⃣ 建立 WebSocket 连接
+手动控制识别时机，适合按住说话、松开识别的场景：
 
 ```ts
-await client.connect();
-```
+const client = createASRClient({
+  language: "zh",
+  enableVAD: false, // 关闭 VAD，使用手动模式
 
-连接成功后会触发 `onReady` 回调。
+  onReady() {
+    console.log("准备就绪");
+  },
 
----
+  onTranscript(text, isFinal) {
+    if (isFinal) {
+      console.log("识别结果：", text);
+    }
+  },
 
-### 3️⃣ 开始录音并实时识别
+  onAudioBufferCommitted() {
+    console.log("音频已提交，等待识别结果...");
+  },
+});
 
-```ts
+await client.connect();
 await client.startRecording();
+
+// 用户说话中...
+
+await client.stopRecording(); // 触发 input_audio_buffer.commit
 ```
 
-* 自动请求麦克风权限
-* 自动开始推送音频流
-* 服务端会持续返回实时转写结果
+---
+
+### 方式二：HTTP 按压式 ASR（一句话识别）
+
+适合按住说话、松开识别的场景，如语音消息、语音搜索等。
+
+```tsx
+import { useRef, useState } from "react";
+import { createASRHttpClient } from "@amaster.ai/asr-client";
+
+function VoiceButton() {
+  const [recording, setRecording] = useState(false);
+  const [text, setText] = useState("");
+  const [error, setError] = useState<string | null>(null);
+
+  // 创建 HTTP ASR 客户端
+  const asrHttpClient = useRef(
+    createASRHttpClient({
+      onRecordingStart() {
+        setRecording(true);
+        setText("");
+        setError(null);
+      },
+      onRecordingStop() {
+        setRecording(false);
+      },
+      onResult(result) {
+        setText(result);
+      },
+      onError(err) {
+        setError(err.message);
+      },
+    })
+  ).current;
+
+  return (
+    <div>
+      <button
+        onMouseDown={() => asrHttpClient.startRecording()}
+        onMouseUp={() => asrHttpClient.stopRecording()}
+        onTouchStart={() => asrHttpClient.startRecording()}
+        onTouchEnd={() => asrHttpClient.stopRecording()}
+        style={{
+          padding: "12px 24px",
+          background: recording ? "#f87171" : "#4ade80",
+        }}
+      >
+        {recording ? "松开识别" : "按住说话"}
+      </button>
+
+      <div>
+        <strong>识别结果：</strong>
+        <div>{text || "（暂无）"}</div>
+      </div>
+
+      {error && <div style={{ color: "red" }}>错误：{error}</div>}
+    </div>
+  );
+}
+```
 
 ---
 
-### 4️⃣ 停止录音
+## API 说明
+
+### `createASRClient(config): ASRClient`
+
+WebSocket 实时 ASR 客户端。
+
+#### `ASRClientConfig`
+
+| 参数                     | 类型                                       | 默认值  | 说明                                                     |
+| ------------------------ | ------------------------------------------ | ------- | -------------------------------------------------------- |
+| `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
-client.stopRecording();
-```
+interface ASRClient {
+  /** 建立 WebSocket 连接并发送 session.update */
+  connect(): Promise<void>;
 
-* 停止麦克风采集
-* 向服务端发送 `input_audio_buffer.commit`
-* 触发最终转写结果
+  /** 开始录音并流式发送音频 */
+  startRecording(): Promise<void>;
+
+  /**
+   * 停止录音
+   * - VAD 模式：停止发送音频
+   * - 非 VAD 模式：停止发送音频并触发识别（发送 input_audio_buffer.commit）
+   */
+  stopRecording(): Promise<void>;
+
+  /**
+   * 关闭连接
+   * - 发送 session.finish
+   * - 等待 session.finished
+   * - 关闭 WebSocket
+   */
+  close(): Promise<void>;
+
+  /** 是否正在录音 */
+  isRecording(): boolean;
+
+  /** 是否已连接到服务器 */
+  isConnected(): boolean;
+}
+```
 
 ---
 
-### 5️⃣ 关闭连接
+### `createASRHttpClient(config): ASRHttpClient`
+
+HTTP 按压式 ASR 客户端。
+
+#### `ASRHttpClientConfig`
+
+| 参数               | 类型                     | 说明                 |
+| ------------------ | ------------------------ | -------------------- |
+| `getAccessToken`   | `() => string \| null`   | 获取访问令牌         |
+| `language`         | `string`                 | 语言，默认 `'zh'`    |
+| `sampleRate`       | `number`                 | 采样率，默认 `16000` |
+| `onRecordingStart` | `() => void`             | 录音开始回调         |
+| `onRecordingStop`  | `() => void`             | 录音停止回调         |
+| `onResult`         | `(text: string) => void` | 识别结果回调         |
+| `onError`          | `(error: Error) => void` | 错误回调             |
+
+#### `ASRHttpClient`
 
 ```ts
-client.close();
+interface ASRHttpClient {
+  startRecording(): Promise<void>; // 开始录音
+  stopRecording(): Promise<string>; // 停止录音并返回识别结果
+  recordAndRecognize(durationMs: number): Promise<string>; // 录音指定时长
+  recognizeFile(file: File | Blob): Promise<string>; // 识别音频文件
+  recognizeUrl(audioUrl: string): Promise<string>; // 识别音频 URL
+}
 ```
 
 ---
 
-## API 说明
+## 配合统一客户端使用
 
-### `createASRClient(config): ASRClient`
+推荐与 `@amaster.ai/client` 统一客户端一起使用，自动处理认证：
 
-#### `ASRClientConfig`
+```tsx
+import { createClient } from "@amaster.ai/client";
+
+const client = createClient({
+  baseURL: "https://api.amaster.ai",
+});
+
+// WebSocket ASR
+const asrClient = client.asr({
+  onTranscript(text, isFinal) {
+    console.log(isFinal ? "[最终]" : "[实时]", text);
+  },
+});
+
+await asrClient.connect();
+await asrClient.startRecording();
 
-| 参数              | 类型                                         | 说明             |
-| --------------- | ------------------------------------------ | -------------- |
-| `onReady`       | `() => void`                               | 会话创建完成         |
-| `onSpeechStart` | `() => void`                               | 检测到语音开始        |
-| `onSpeechEnd`   | `() => void`                               | 检测到语音结束        |
-| `onTranscript`  | `(text: string, isFinal: boolean) => void` | 转写回调           |
-| `onError`       | `(error: Error) => void`                   | 错误回调           |
-| `onClose`       | `() => void`                               | 连接关闭回调         |
+// HTTP ASR
+const asrHttpClient = client.asrHttp({
+  onResult(text) {
+    console.log("识别结果:", text);
+  },
+});
+
+await asrHttpClient.startRecording();
+// ... 用户说话 ...
+const result = await asrHttpClient.stopRecording();
+```
 
 ---
 
-### `ASRClient`
+## VAD 模式 vs Manual 模式
+
+| 特性     | VAD 模式（enableVAD: true）            | Manual 模式（enableVAD: false） |
+| -------- | -------------------------------------- | ------------------------------- |
+| 语音检测 | 服务端自动检测                         | 客户端手动控制                  |
+| 适用场景 | 连续对话、实时字幕                     | 按住说话、语音消息              |
+| 开始录音 | `startRecording()`                     | `startRecording()`              |
+| 停止录音 | 自动检测 / `stopRecording()`           | `stopRecording()` 触发识别      |
+| 事件触发 | `onSpeechStart` / `onSpeechEnd`        | `onAudioBufferCommitted`        |
+| 配置参数 | `vadThreshold`, `vadSilenceDurationMs` | 无需 VAD 配置                   |
+
+### VAD 配置建议
 
 ```ts
-interface ASRClient {
-  connect(): Promise<void>;
-  startRecording(): Promise<void>;
-  stopRecording(): void;
-  close(): void;
-}
+// 快速响应场景（如实时字幕）
+const client = createASRClient({
+  enableVAD: true,
+  vadThreshold: 0.0, // 最灵敏
+  vadSilenceDurationMs: 400, // 较短停顿即断句
+});
+
+// 长句输入场景（如文章朗读）
+const client = createASRClient({
+  enableVAD: true,
+  vadThreshold: 0.2, // 默认灵敏度
+  vadSilenceDurationMs: 1200, // 较长停顿才断句
+});
 ```
 
 ---
 
 ## 音频参数说明
 
-* **采样率**：16000 Hz
-* **声道**：单声道
-* **格式**：PCM16 → Base64
-* **缓冲大小**：4096 frames
+### WebSocket ASR
+
+- **采样率**：16000 Hz（推荐）或 8000 Hz
+- **声道**：单声道
+- **格式**：PCM16 → Base64
+- **缓冲大小**：4096 frames
+
+### HTTP ASR
+
+- **采样率**：自动检测（通常为 16000 Hz）
+- **声道**：单声道
+- **格式**：WAV（内部将 PCM 转为 WAV）
 
 ---
 
 ## 常见问题
 
+### Q: WebSocket 和 HTTP ASR 有什么区别？
+
+| 特性     | WebSocket ASR          | HTTP ASR            |
+| -------- | ---------------------- | ------------------- |
+| 实时性   | 实时流式返回           | 说完后一次性返回    |
+| 适用场景 | 语音输入、实时字幕     | 语音消息、语音搜索  |
+| 交互方式 | 开始 → 持续识别 → 停止 | 按住说话 → 松开识别 |
+| 网络开销 | 持续连接               | 每次请求独立        |
+
 ### Q: 为什么必须是 16kHz？
 
 ASR 服务通常要求 16kHz PCM 输入，否则会影响识别效果或直接报错。
 
----
-
 ### Q: 支持移动端吗？
 
 支持，但需注意：
 
-* iOS Safari 需用户手势触发录音
-* 后台会自动暂停音频采集
+- iOS Safari 需用户手势触发录音
+- 后台会自动暂停音频采集
+
+### Q: VAD 模式下为什么要等一段时间才返回最终结果？
+
+VAD 需要检测到静音（silence）才会认为一句话结束，然后返回最终结果。`vadSilenceDurationMs` 配置了这个静音时长阈值。
+
+### Q: 如何切换语言？
+
+```ts
+const client = createASRClient({
+  language: "en", // 英文识别
+});
+```
 
 ---
 
 ## 注意事项
 
-* WebSocket 必须在 HTTPS 页面下使用麦克风
-* 页面关闭前建议调用 `client.close()`
-* 不建议在多个 ASR Client 实例中共享麦克风
+- WebSocket 必须在 HTTPS 页面下使用麦克风
+- 页面关闭前建议调用 `await client.close()` 优雅关闭
+- 不建议在多个 ASR Client 实例中共享麦克风
+- HTTP ASR 会自动将录音转为 WAV 格式上传
+- 每个事件都会自动生成唯一的 `event_id`，符合协议规范
 
 ---