ASR Realtime WebSocket Client SDK

基于 Web Audio + WebSocket 的 实时语音识别（ASR）客户端 SDK，用于将浏览器麦克风音频实时发送到 ASR 服务（如 Qwen ASR Realtime），并接收实时/最终转写结果。

遵循 Qwen-ASR Realtime API 协议实现，完整支持会话管理、VAD 模式、手动模式等全部功能。

特性

• 🎙 浏览器麦克风实时采集（16kHz / 单声道）
• 🔁 实时音频流式发送（Base64 PCM16）
• 🧠 支持 VAD 模式（自动检测语音开始/结束）和 Manual 模式（手动控制）
• 🌍 支持 25 种语言识别
• ✍️ 支持中间结果与最终转写结果
• 📡 完整的会话生命周期管理（session.update、session.finish）
• 🔌 事件 ID 自动生成，符合协议规范
• 🌐 同时支持 WebSocket 实时识别和 HTTP 按压识别

安装与环境要求

安装

# 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 模式（推荐）

自动检测语音开始和结束：

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）

手动控制识别时机，适合按住说话、松开识别的场景：

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（一句话识别）

适合按住说话、松开识别的场景，如语音消息、语音搜索等。

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>
  );
}

API 说明

createASRClient(config): ASRClient

WebSocket 实时 ASR 客户端。

ASRClientConfig

支持的语言 (ASRLanguage)

ASRClient

interface ASRClient {
  /** 建立 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;
}

createASRHttpClient(config): ASRHttpClient

HTTP 按压式 ASR 客户端。

ASRHttpClientConfig

ASRHttpClient

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
}

配合统一客户端使用

推荐与 @amaster.ai/client 统一客户端一起使用，自动处理认证：

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 配置建议

// 快速响应场景（如实时字幕）
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 有什么区别？

Q: 为什么必须是 16kHz？

ASR 服务通常要求 16kHz PCM 输入，否则会影响识别效果或直接报错。

Q: 支持移动端吗？

支持，但需注意：

• iOS Safari 需用户手势触发录音
• 后台会自动暂停音频采集

Q: VAD 模式下为什么要等一段时间才返回最终结果？

VAD 需要检测到静音（silence）才会认为一句话结束，然后返回最终结果。vadSilenceDurationMs 配置了这个静音时长阈值。

Q: 如何切换语言？

const client = createASRClient({
  language: "en", // 英文识别
});

注意事项

• WebSocket 必须在 HTTPS 页面下使用麦克风
• 页面关闭前建议调用 await client.close() 优雅关闭
• 不建议在多个 ASR Client 实例中共享麦克风
• HTTP ASR 会自动将录音转为 WAV 格式上传
• 每个事件都会自动生成唯一的 event_id，符合协议规范

License

MIT