# @amaster\.ai/asr-client 中文文档 规范地址：https://npmcn.com/package/%40amaster.ai/asr-client/ 版本：1\.1\.72 npm 元数据更新时间：2026-11-05T13:04:05.810Z 中文译文更新时间：2026-11-08T08:31:52.002Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40amaster.ai/asr-client 原文对照：https://npmcn.com/package/%40amaster.ai/asr-client/?lang=original ## 关键信息（来自 npm 元数据） - 包体积（解压后）：153 kB，9 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：1 个 - 首次发布：2026-02-02T03:34:19.243Z - 最新版本发布：2026-11-05T13:04:05.610Z - 近 30 天下载量：1854（2026-10-06 至 2026-11-04，npm 官方下载统计） - 已发布版本数：203（近 12 个月 203 个） ## 中文简介 有麦克风录音的 Quen ASR 实时 WebSocket 客户端 ## 安装 ```sh npm install @amaster.ai/asr-client ``` 也可以使用：`pnpm add @amaster.ai/asr-client`、`yarn add @amaster.ai/asr-client`、`bun add @amaster.ai/asr-client` ## README # ASR Realtime WebSocket Client SDK 基于 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 种语言识别 - ✍️ 支持中间结果与最终转写结果 - 📡 完整的会话生命周期管理（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` - 支持 `AudioContext` - 支持 `WebSocket` 推荐使用 **Chrome / Edge 最新版本**。 * * * ## 快速开始 ### 方式一：WebSocket 实时 ASR（流式识别） 适合需要实时看到识别结果的场景，如语音输入、实时字幕等。 #### 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 连接成功，会话已配置"); }, onSpeechStart() { console.log("🎤 检测到说话开始"); }, onSpeechEnd() { console.log("🛑 检测到说话结束"); }, onTranscript(text, isFinal) { console.log(isFinal ? "✅ 最终结果：" : "📝 实时结果：", text); }, onSessionFinished() { console.log("👋 会话已结束"); }, onError(err) { console.error("❌ ASR 错误", err); }, onClose() { 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） 手动控制识别时机，适合按住说话、松开识别的场景： ```ts const client = createASRClient({ language: "zh", enableVAD: false, // 关闭 VAD，使用手动模式 onReady() { console.log("准备就绪"); }, onTranscript(text, isFinal) { if (isFinal) { console.log("识别结果：", text); } }, onAudioBufferCommitted() { console.log("音频已提交，等待识别结果..."); }, }); 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(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 (
识别结果：
{text || "（暂无）"}
{error &&
错误：{error}
}
); } ``` * * * ## 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 interface ASRClient { /** 建立 WebSocket 连接并发送 session.update */ connect(): Promise; /** 开始录音并流式发送音频 */ startRecording(): Promise; /** * 停止录音 * - VAD 模式：停止发送音频 * - 非 VAD 模式：停止发送音频并触发识别（发送 input_audio_buffer.commit） */ stopRecording(): Promise; /** * 关闭连接 * - 发送 session.finish * - 等待 session.finished * - 关闭 WebSocket */ close(): Promise; /** 是否正在录音 */ isRecording(): boolean; /** 是否已连接到服务器 */ isConnected(): boolean; } ``` * * * ### `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 interface ASRHttpClient { startRecording(): Promise; // 开始录音 stopRecording(): Promise; // 停止录音并返回识别结果 recordAndRecognize(durationMs: number): Promise; // 录音指定时长 recognizeFile(file: File | Blob): Promise; // 识别音频文件 recognizeUrl(audioUrl: string): Promise; // 识别音频 URL } ``` * * * ## 配合统一客户端使用 推荐与 `@amaster.ai/client` 统一客户端一起使用，自动处理认证： ```tsx import { createClient } from "@amaster.ai/client"; const client = createClient(); // WebSocket ASR const asrClient = client.asr({ onTranscript(text, isFinal) { console.log(isFinal ? "[最终]" : "[实时]", text); }, }); await asrClient.connect(); await asrClient.startRecording(); // HTTP ASR const asrHttpClient = client.asrHttp({ onResult(text) { console.log("识别结果:", text); }, }); await asrHttpClient.startRecording(); // ... 用户说话 ... 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（推荐）或 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 需用户手势触发录音 - 后台会自动暂停音频采集 ### Q: VAD 模式下为什么要等一段时间才返回最终结果？ VAD 需要检测到静音（silence）才会认为一句话结束，然后返回最终结果。`vadSilenceDurationMs` 配置了这个静音时长阈值。 ### Q: 如何切换语言？ ```ts const client = createASRClient({ language: "en", // 英文识别 }); ``` * * * ## 注意事项 - WebSocket 必须在 HTTPS 页面下使用麦克风 - 页面关闭前建议调用 `await client.close()` 优雅关闭 - 不建议在多个 ASR Client 实例中共享麦克风 - HTTP ASR 会自动将录音转为 WAV 格式上传 - 每个事件都会自动生成唯一的 `event_id`，符合协议规范 * * * ## License MIT ## 常见问题 ### @amaster\.ai/asr-client 是什么？ 有麦克风录音的 Quen ASR 实时 WebSocket 客户端 ### 如何安装 @amaster\.ai/asr-client？ 在项目目录运行 npm install @amaster\.ai/asr-client，或使用 pnpm add / yarn add / bun add。 ### @amaster\.ai/asr-client 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @amaster\.ai/asr-client 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @amaster\.ai/asr-client 可以商用吗？ @amaster\.ai/asr-client 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @amaster\.ai/asr-client 的下载量有多少？ 根据 npm 官方下载统计，@amaster\.ai/asr-client 在 2026/10/06 – 2026/11/04 这 30 天内被下载 1,854 次，日均约 62 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @amaster\.ai/asr-client 还在维护吗？ 最新版本 1\.1\.72 发布于 2026/11/05（2 天前）；至今共发布 203 个版本，其中过去 12 个月发布了 203 个；首次发布于 2026/02/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。