TRTC-ASR Node.js SDK

English | 中文 基于 TRTC 鉴权体系的语音识别（ASR）Node.js SDK，支持实时语音识别（WebSocket）、一句话识别（HTTP）和录音文件识别（异步 HTTP）三种模式。

本 SDK 面向新版 v3 协议：只需 SDKAppID + SecretKey（无需腾讯云 AppID），auth/params 分块、全 snake_case、扁平响应 + 数字错误码。v3 客户端位于 v3 命名空间（import { v3 } from "trtc-asr"）。

旧版 v2 / v1 协议客户端（包顶层导出）继续维护、存量可用，文档见 docs/v2_protocol.md。

其他语言 SDK：Go | Python | Java | Rust | C++

使用本 SDK 前，您需要准备两个凭证：SDKAppID、SecretKey（v3 协议以 SDKAppID 为唯一客户维度，不再需要腾讯云 AppID）。国内站与国际站的账号体系不同，请按您的站点参照官方快速接入指南完成注册、创建应用与服务开通：

• 国内站：快速接入指南 — 注册腾讯云账号并完成实名认证 → 在 TRTC 控制台创建应用 → 开通「AI 智能识别」（体验版可免费试用）
• 国际站：Quick Start — 在 trtc.io 注册（自动开通 Tencentcloud 账号，无需实名认证）→ 在 console.trtc.io 创建应用 → 开通「AI Speech Recognition」（仅 RTC Engine Lite 及以上包月套餐，Free Trial 不支持）

{host} 国内站为 asr.cloud-rtc.com，国际站为 asr-intl.cloud-rtc.com（credential.setSite(SITE_INTL)）。

v3 把请求拆成两个正交的块，字段全程 snake_case：

• auth：身份与签名，由网关鉴权层消费——在线与离线的字段不同，分别见下。
• params：业务识别参数（引擎、VAD、热词、过滤等），snake_case，字段与 v2 在线 query 同名。

两块共用同一套签名规则：

• 未调用 credential.setUserSig() 时，SDK 用 SDKAppID + SecretKey 本地生成，有效期 86400 秒，且每条连接 / 每次请求都重新生成——长跑服务无需自己管理过期。
• 调用 credential.setUserSig(sig) 传入固定签名后，SDK 不再生成也不再刷新：服务端用当前 identifier（在线 voice_id、离线 request_id）验签，因此签名必须用同一个 identifier 签发；固定签名场景（如浏览器端由业务后端下发签名）需自行处理过期与 identifier 对齐。
• 签名与站点绑定：credential.setSite(SITE_INTL) 决定 host 和验签集群，国际站的凭证不要用于国内站（反之亦然）。
• SecretKey 不会传输到网络，签名只用于服务端验签。

一条 WebSocket 连接 = 一条流，voice_id 既是流身份、也是签名 identifier（URL 与 params 都带它，auth 块里不再重复）。

• 在线没有 request_id：request_id 是离线「一次请求 = 一个事务」的概念（见下），流式协议里不存在。
• voice_id 同时出现在 URL ?voice_id= 与 params.voice_id（两者一致或省略），≤128 字符；SDK 默认生成 uuid，可用 setVoiceId 指定；与活跃流冲突会返回 4001。
• 一条流一个签名，随连接生成；重连即重签，不需要自己维护有效期。

WebSocket 建连后 3 秒内发送首帧 JSON：

{
  "type": "start",
  "auth": {"sdkappid": "1400000001", "usersig": "eJw..."},
  "params": {"engine_model_type": "bigmodel", "language": "zh", "voice_format": 1, "needvad": 1}
}

鉴权通过后服务端回 {"code":0,"message":"success","voice_id":"..."}，之后上行 binary 音频帧、结束发 {"type":"end"}。SDK 的 start() 会同步等待这个 ack，鉴权/参数错误直接从 start() 抛出。

每次 HTTP 请求是一个独立事务，request_id 既是单次请求 ID、也是签名 identifier（调用方无需自己生成）。

HTTP POST body 为对称的 {"auth":{...},"params":{...}}，响应扁平化（无 Response 外壳）：

{"code": 0, "message": "success", "request_id": "req-uuid", "result": "识别文本", "audio_duration": 1234}

注意：v3 离线鉴权失败是 HTTP 200 + {"code":4002}，判断结果请以 body 的 code 为准（SDK 已处理，code != 0 会抛出携带该 code 的 ASRError）。

sequenceDiagram
    autonumber
    participant C as 客户端（v3 SDK）
    participant S as ASR 服务端

    Note over C,S: ① 建联
    C->>S: WebSocket Upgrade /asr/v3?voice_id=xxx
    S-->>C: 101 Switching Protocols

    Note over C,S: ② 鉴权 + 参数下发（首帧，须在 3s 内）
    C->>S: {"type":"start","auth":{"sdkappid","usersig"},"params":{...}}
    alt 鉴权通过
        S-->>C: ack {"code":0,"message":"success","voice_id":"xxx"}
    else 鉴权/参数失败
        S-->>C: {"code":4002/4001,...} 错误帧，随后正常关闭连接
    end

    Note over C,S: ③ 识别（全双工）
    loop 按实时率推流（16k 每 40ms 1280B，单帧 ≤256KB）
        C->>S: binary 音频帧
    end
    S-->>C: result.slice_type=0（句开始）
    S-->>C: result.slice_type=1（中间结果）×N
    S-->>C: result.slice_type=2（句末稳定结果）
    Note right of S: 多句时 index 递增，重复 0→1→2

    C->>S: {"type":"end"}（音频发完）
    S-->>C: {"final":1}（整流结束）
    C->>S: 关闭连接

SDK 行为对应：start() = ①+②（同步等 ack，失败立即抛错）；write() = ③上行；下行经 listener 回调（onSentenceBegin / onRecognitionResultChange / onSentenceEnd / onRecognitionComplete）；stop() = 发 end 并等 final:1。空闲保护：15s 未发音频服务端会以 4008 断连。

needvad / vad_silence_time / vad_level / input_sample_rate / convert_num_mode / filter_empty_result / noise_threshold 为可选三态字段：未传走服务端缺省，显式传 0 有业务含义（v2 的 query 传参会吞掉显式 0，v3 已修正）。

context 消费方式与引擎能力相关：大模型类引擎可用 text/terms/general，传统引擎仅把 terms 降级为热词。speaker_diarization=1/3 时服务端会强制开启 VAD 并调整 word_info。

下行消息结构与 v2 完全一致（code / message / voice_id / message_id / result / final）：

sequenceDiagram
    participant C as 客户端（v3 SDK）
    participant S as ASR 服务端

    C->>S: POST /v3/transcribe {"auth":{"sdkappid","usersig","request_id"},"params":{...}}
    Note right of S: 鉴权（usersig 绑定 request_id）→ 同步识别
    alt 成功
        S-->>C: {"code":0,"result":"...","word_list":[...]}
    else 失败
        S-->>C: {"code":4xxx/5xxx,"message":"..."}（鉴权失败 4002 也是 HTTP 200）
    end

params 字段：

限制：音频时长 ≤ 60s，文件大小 ≤ 3MB。

响应（TranscribeResponse）：

异步任务：创建返回 transcription_id（24 小时有效），再用任务查询接口轮询。

sequenceDiagram
    participant C as 客户端（v3 SDK）
    participant S as ASR 服务端

    C->>S: POST /v3/create_transcription {"auth","params"}
    S-->>C: {"code":0,"transcription_id":"tid-..."}

    loop 轮询（SDK waitForResult 默认 1s 间隔）
        C->>S: POST /v3/describe_transcription {"auth","params":{"transcription_id":"tid-..."}}
        S-->>C: {"status":0/1}（排队 / 处理中）
    end
    S-->>C: {"status":2,"result":"...","result_detail":[...]}（成功）或 {"status":3,"error_msg":"..."}

    Note over S: 若创建时配置了 callback_url，任务完成后服务端会主动 POST 回调（见下表）

params 字段：

响应：{"code":0,"message":"success","request_id":"...","transcription_id":"..."}。

callback_url 回调（application/x-www-form-urlencoded，snake_case 字段）：

params 仅一个字段：transcription_id（创建任务返回的 ID；与 v1 RecTaskId 不通用）。

响应（TranscriptionStatus）：

result_detail[]（SentenceDetail）：

离线接口的 HTTP 状态码与 code 组合：参数错误 400、鉴权失败 200、并发超限 429、body 过大 413、调度失败 503——一律以 body 的 code 为准。

开启 speaker_diarization 后，说话人归属通过两个入口返回：

• result.speaker_segments[]：推荐入口。一个 result 可能包含多个说话人，句子级归属天然有歧义，因此协议按说话人切段返回。len(speaker_segments) == 1 即为单说话人句。
• result.word_list[].speaker_id：字级归属，需同时设置 word_info != 0。

speaker_id 语义：会话内有效，从 1 开始编号，-1 表示未知，0 为保留值。

speaker_segments[] 字段：

Node.js 用法示例：

import { v3 } from "trtc-asr";

const recognizer = new v3.SpeechRecognizer(credential, "bigmodel", listener);
recognizer.setLanguage("zh");                                     // bigmodel 建议显式指定语种
recognizer.setWordInfo(1);                                        // 需要字级说话人时开启
recognizer.setSpeakerDiarization(v3.SPEAKER_DIARIZATION_CLUSTER); // 1：匿名聚类

// 声纹角色认证（返回角色名）：
// recognizer.setSpeakerDiarization(v3.SPEAKER_DIARIZATION_VOICEPRINT); // 3
// recognizer.setSpeakerRoles([
//   { role_name: "teacher", audio_url: "https://example.com/teacher.wav" },
// ]);
// recognizer.setVoiceprintIds(["vp-1"]); // 已注册声纹
// recognizer.setSpeakerNumber(2);        // 0 = 自动检测；两种分离模式都生效

// 回调里读取：
const listener: v3.SpeechRecognitionListener = {
  onSentenceEnd(resp) {
    for (const seg of resp.result?.speaker_segments ?? []) {
      const name = seg.speaker_name || `spk${seg.speaker_id}`;
      console.log(`[${name}] ${seg.text}`);
    }
  },
};

两者都是三态语义：只有显式调用 setter 才会下发，因此显式传 0 与「不配置」可以区分（服务端 vad_level 默认是 1）。超出范围会在 start() 阶段本地报错，不会浪费一次连接。

npm install trtc-asr

要求：Node.js >= 16

start() 同步等服务端 ack，鉴权/参数错误立即返回：

import {
  v3,
  SpeechRecognitionListener,
  SpeechRecognitionResponse,
} from "trtc-asr";
import * as fs from "fs";

// 只需实现关心的回调；其余事件可以省略。listener 类型与 v2 相同
// （下行消息结构两版一致）。
const listener: v3.SpeechRecognitionListener = {
  onSentenceEnd(resp: SpeechRecognitionResponse) {
    console.log(`Sentence end: ${resp.result?.voice_text_str}`);
  },
  onFail(resp, error) {
    console.error(`Failed: ${error}`); // ASRError，code 即服务端错误码
  },
};

async function main() {
  // 1. 创建凭证（第一个参数是 SDKAppID；v3 不需要腾讯云 AppID）
  const credential = v3.newCredential(1400000000, "your-sdk-secret-key");
  // credential.setSite(SITE_INTL); // 国际站；不调用则走国内站

  // 2. 创建识别器
  const recognizer = new v3.SpeechRecognizer(credential, "bigmodel", listener);
  recognizer.setLanguage("zh"); // bigmodel 建议显式指定语种

  // 3. 启动识别（同步等待服务端 ack；鉴权/参数错误在这里抛出）
  await recognizer.start();

  // 4. 发送音频数据
  const fileData = fs.readFileSync("audio.pcm");
  const SLICE_SIZE = 6400; // 200ms of 16kHz 16bit mono PCM
  for (let offset = 0; offset < fileData.length; offset += SLICE_SIZE) {
    await recognizer.write(Buffer.from(fileData.subarray(offset, offset + SLICE_SIZE)));
    await new Promise((resolve) => setTimeout(resolve, 200)); // 模拟实时
  }

  // 5. 停止识别（发送 {"type":"end"} 并等待 final）
  await recognizer.stop();
}

main().catch(console.error);

POST /v3/transcribe，请求/响应均为 snake_case 扁平结构：

import { v3 } from "trtc-asr";
import * as fs from "fs";

async function main() {
  const credential = v3.newCredential(1400000000, "your-sdk-secret-key");
  const recognizer = new v3.SentenceRecognizer(credential);

  const data = fs.readFileSync("audio.pcm");
  const result = await recognizer.recognizeDataWithOptions(Buffer.from(data), {
    engine_model_type: "bigmodel",
    voice_format: "pcm",
    source_type: 1,
    language: "zh",
  });

  console.log(`识别结果: ${result.result}`);
  console.log(`音频时长: ${result.audio_duration} ms`);
}

main().catch(console.error);

create_transcription + describe_transcription，任务 ID 为 transcription_id，24 小时有效：

import { v3 } from "trtc-asr";

async function main() {
  const credential = v3.newCredential(1400000000, "your-sdk-secret-key");
  const recognizer = new v3.FileRecognizer(credential);

  const taskId = await recognizer.createTask({
    engine_model_type: "bigmodel",
    channel_num: 1,
    res_text_format: 1,
    source_type: 0,
    url: "https://example.com/audio.wav",
    language: "zh",
  });
  const status = await recognizer.waitForResult(taskId); // 轮询直至完成

  console.log(`识别结果: ${status.result}`);
  console.log(`音频时长: ${status.audio_duration.toFixed(2)} s`);
}

main().catch(console.error);

v2 旧版协议还需要腾讯云 AppID，见 docs/v2_protocol.md。

实时语音识别（v3.SpeechRecognizer），setter 命名与 v2 保持一致：

v3 在线不支持 v2 的 customization_id / replace_text_id（v3 协议未包含）。

bigmodel 的 language 不只是提示：服务端按它选择后端模型（zh 走自研大模型，留空走通用链路）。示例默认 bigmodel + zh。

完整示例请参见：

• 实时语音识别（v3）：examples/v3-realtime-asr.ts
• 一句话识别（v3）：examples/v3-sentence-asr.ts
• 录音文件识别（v3）：examples/v3-file-asr.ts
• 实时语音识别（v2）：examples/realtime-asr.ts
• 一句话识别（v2）：examples/sentence-asr.ts
• 录音文件识别（v2）：examples/file-asr.ts

npm install
npx ts-node examples/v3-realtime-asr.ts -f examples/test.pcm -e bigmodel

trtc-asr-sdk-nodejs/
├── src/                            # TypeScript 源码
│   ├── index.ts                    # 包入口（顶层 = v2/v1，v3 命名空间导出）
│   ├── credential.ts               # 凭证管理（v2/v3 共用）
│   ├── usersig.ts                  # TRTC UserSig 生成
│   ├── signature.ts                # v2 URL 请求参数构建
│   ├── speech-recognizer.ts        # v2 实时语音识别器
│   ├── sentence-recognizer.ts      # v2 一句话识别器
│   ├── file-recognizer.ts          # v2 录音文件识别器
│   ├── errors.ts                   # 错误定义（共用）
│   └── v3/                         # v3 协议客户端（独立实现）
│       ├── wire.ts                 # wire 类型（auth/params/扁平响应，全 snake_case）
│       ├── speech-recognizer.ts    # /asr/v3 首帧协议
│       ├── sentence-recognizer.ts  # /v3/transcribe
│       └── file-recognizer.ts      # /v3/create_transcription + describe
├── docs/
│   └── v2_protocol.md              # v2 / v1 旧版协议与客户端文档
├── examples/                       # 示例代码
├── tests/                          # 测试（含 v3 mock server 端到端 wire 测试）
├── dist/                           # 编译输出（npm 发布内容）
├── package.json
└── README.md

• 新接入：推荐 v3（import { v3 } from "trtc-asr"）——只需 SDKAppID + SecretKey，协议更干净（auth/params 分块、扁平响应、数字错误码），start() 同步返回鉴权/参数错误。
• 存量：v2（包顶层导出）继续全量可用，无需任何改动，文档见 docs/v2_protocol.md。

v3 全部使用数字错误码：参数非法 4001、鉴权失败 4002、并发超限 4006、超时 4008、服务端错误 5000。 SDK 返回的错误是 ASRError，其 code 即服务端错误码（SDK 本地错误用 10xx 区间，如 1001 本地参数错误、1002 连接失败）。注意离线接口鉴权失败也是 HTTP 200，请以 body 的 code 为准（SDK 已处理）。

不能。v1 RecTaskId 与 v3 transcription_id 是两套任务空间，互不通用。

包顶层导出的 v2 / v1 客户端继续维护，文档见 docs/v2_protocol.md。v2 与 v3 的下行消息结构一致， listener 用法相同，切换协议版本只需改 import 与构造方式。

UserSig 是基于 SDKAppID 和 SDK 密钥计算的签名，用于 TRTC 服务鉴权。SDK 会自动生成（identifier 在线绑定 voice_id、离线绑定 request_id），无需手动计算。详见鉴权文档。

• 实时语音识别：支持 PCM 格式（voice_format=1），建议 16kHz、16bit、单声道
• 一句话识别：支持 wav、pcm、ogg-opus、mp3、m4a，音频时长 ≤ 60s，文件 ≤ 3MB
• 录音文件识别：支持 wav、ogg-opus、mp3、m4a，本地文件 ≤ 5MB，URL ≤ 1GB / ≤ 12h

MIT License