TRTC-ASR C++ SDK

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

本 SDK 面向新版 v3 协议：只需 SDKAppID + SecretKey（无需腾讯云 AppID），auth/params 分块、全 snake_case、扁平响应 + 数字错误码。v3 客户端位于 trtc_asr::v3 命名空间（#include "trtc_asr/v3.h"）。

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

其他语言 SDK：Go | Python | Node.js | Java | Rust

使用本 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.set_site(kSiteIntl)）。

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

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

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

• 未调用 credential.set_user_sig() 时，SDK 用 SDKAppID + SecretKey 本地生成，有效期 86400 秒，且每条连接 / 每次请求都重新生成——长跑服务无需自己管理过期。
• 调用 credential.set_user_sig(sig) 传入固定签名后，SDK 不再生成也不再刷新：服务端用当前 identifier（在线 voice_id、离线 request_id）验签，因此签名必须用同一个 identifier 签发；固定签名场景（如浏览器端由业务后端下发签名）需自行处理过期与 identifier 对齐。
• 签名与站点绑定：credential.set_site(kSiteIntl) 决定 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[] 字段：

C++ 用法示例：

#include "trtc_asr/v3.h"

class MyListener : public trtc_asr::SpeechRecognitionListener {
 public:
  void OnSentenceEnd(const trtc_asr::SpeechRecognitionResponse& resp) override {
    for (const auto& seg : resp.result.speaker_segments) {
      const std::string name =
          seg.speaker_name.empty() ? "spk" + std::to_string(seg.speaker_id) : seg.speaker_name;
      std::cout << "[" << name << "] " << seg.text << "\n";
    }
  }
};

MyListener listener;
trtc_asr::v3::SpeechRecognizer recognizer(
    trtc_asr::v3::NewCredential(1400000000, "your-sdk-secret-key"), "bigmodel", &listener);
recognizer.SetLanguage("zh");                                               // bigmodel 建议显式指定语种
recognizer.SetWordInfo(1);                                                  // 需要字级说话人时开启
recognizer.SetSpeakerDiarization(trtc_asr::v3::kSpeakerDiarizationCluster); // 1：匿名聚类

// 声纹角色认证（返回角色名）：
// recognizer.SetSpeakerDiarization(trtc_asr::v3::kSpeakerDiarizationVoiceprint); // 3
// recognizer.SetSpeakerRoles({trtc_asr::v3::SpeakerRole{"teacher", "https://example.com/teacher.wav"}});
// recognizer.SetVoiceprintIds({"vp-1"}); // 已注册声纹
// recognizer.SetSpeakerNumber(2);        // 0 = 自动检测；两种分离模式都生效

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

CMake（FetchContent 或 add_subdirectory）：

add_subdirectory(trtc-asr-sdk-cpp)
target_link_libraries(your_app PRIVATE trtc_asr)

要求：C++17，OpenSSL（TLS），libcurl（HTTP）。WebSocket 与 JSON 已内置，无额外依赖。

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

#include "trtc_asr/v3.h"

class MyListener : public trtc_asr::SpeechRecognitionListener {
 public:
  void OnSentenceEnd(const trtc_asr::SpeechRecognitionResponse& resp) override {
    std::cout << "Sentence end: " << resp.result.voice_text_str << "\n";
  }
  void OnFail(const trtc_asr::SpeechRecognitionResponse*,
              const trtc_asr::ASRError& err) override {
    std::cerr << "Failed: " << err.what() << "\n"; // code 即服务端错误码
  }
};

// 第一个参数是 SDKAppID；v3 不需要腾讯云 AppID。
MyListener listener;
trtc_asr::v3::SpeechRecognizer recognizer(
    trtc_asr::v3::NewCredential(1400000000, "your-sdk-secret-key"),
    "bigmodel", &listener);
recognizer.SetLanguage("zh"); // bigmodel 建议显式指定语种

// Start() 同步等待服务端 ack；鉴权/参数错误在这里抛出。
recognizer.Start();

// recognizer.Write(pcm.data(), pcm.size()); ... 循环发送音频
recognizer.Stop(); // 发送 {"type":"end"} 并等待 final

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

#include "trtc_asr/v3.h"

trtc_asr::v3::SentenceRecognizer recognizer(
    trtc_asr::v3::NewCredential(1400000000, "your-sdk-secret-key"));

// Raw audio bytes; base64 encoding is applied internally (like v2).
trtc_asr::v3::TranscribeRequest req;
req.engine_model_type = "bigmodel";
req.voice_format = "pcm";
req.language = "zh";
auto resp = recognizer.RecognizeDataWithOptions(pcm_bytes, &req);
std::cout << resp.result << " (" << resp.audio_duration << " ms)\n";

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

#include "trtc_asr/v3.h"

trtc_asr::v3::FileRecognizer recognizer(
    trtc_asr::v3::NewCredential(1400000000, "your-sdk-secret-key"));

trtc_asr::v3::CreateTranscriptionRequest req;
req.engine_model_type = "bigmodel";
req.language = "zh";
req.source_type = trtc_asr::v3::kSourceTypeUrl;
req.url = "https://example.com/audio.wav";
std::string task_id = recognizer.CreateTask(req);
auto status = recognizer.WaitForResult(task_id); // 轮询直至完成
std::cout << status.result << " (" << status.audio_duration << " s)\n";

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.cc
• 一句话识别（v3）：examples/v3_sentence_asr.cc
• 录音文件识别（v3）：examples/v3_file_asr.cc
• 实时语音识别（v2）：examples/realtime_asr.cc
• 一句话识别（v2）：examples/sentence_asr.cc
• 录音文件识别（v2）：examples/file_asr.cc

cmake -B build && cmake --build build -j
TRTC_ASR_SDK_APP_ID=1400000000 TRTC_ASR_SECRET_KEY=... \
  ./build/v3_realtime_asr examples/test.pcm bigmodel

trtc-asr-sdk-cpp/
├── include/trtc_asr/
│   ├── credential.h            # 凭证管理（v2/v3 共用）
│   ├── usersig.h               # TRTC UserSig 生成
│   ├── signature_params.h      # v2 URL 请求参数构建
│   ├── speech_recognizer.h     # v2 实时语音识别器（共享状态机，v3 复用）
│   ├── sentence_recognizer.h   # v2 一句话识别器
│   ├── file_recognizer.h       # v2 录音文件识别器
│   ├── types.h                 # 下行响应类型（两版共用）+ 校验
│   ├── errors.h                # 错误定义（共用）
│   ├── sigpipe.h               # SIGPIPE 说明 + 可选的进程级忽略开关
│   └── v3.h                    # v3 协议客户端（wire 类型 + 三个识别器）
├── src/
│   ├── *.cc                    # v2 实现与内部工具（WsClient / HttpPost）
│   └── v3.cc                   # v3 实现
├── docs/
│   └── v2_protocol.md          # v2 / v1 旧版协议与客户端文档
├── examples/                   # 示例代码
├── tests/                      # 测试（含 v3 mock server 端到端 wire 测试）
├── CMakeLists.txt
└── README.md

• 新接入：推荐 v3（#include "trtc_asr/v3.h"，trtc_asr::v3 命名空间）——只需 SDKAppID + SecretKey，协议更干净（auth/params 分块、扁平响应、数字错误码），Start() 同步返回鉴权/参数错误。
• 存量：v2（trtc_asr:: 顶层 API）继续全量可用，无需任何改动，文档见 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 是两套任务空间，互不通用。

trtc_asr:: 顶层 API 继续维护，文档见 docs/v2_protocol.md。v2 与 v3 的下行消息结构一致， listener 用法相同，切换协议版本只需改 include 与构造方式。

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

不会，默认无需任何配置。

向对端已关闭的 socket 写入会触发 SIGPIPE，其默认行为是终止进程（表现为退出码 141 = 128 + 13）。SDK 对自己建立的连接做了完整防护，且不改动进程级信号处理：

第三种做法只影响 SDK 自己的线程、且会还原现场：宿主原本 pending 的 SIGPIPE 不会被吞掉，宿主为自己的 socket 安装的 SIGPIPE handler 也继续有效。

如果你更希望采用「全进程永不收到 SIGPIPE」的简单策略（libcurl、多数服务端程序的做法），SDK 提供一个显式的开关，默认不会被调用：

#include "trtc_asr/sigpipe.h"

int main() {
  trtc_asr::IgnoreSigpipeProcessWide();  // 可选；会改变全进程的 SIGPIPE 处理
  // ...
}

仅在宿主自己没有安装 SIGPIPE handler 时使用，并且只在启动时调用一次。

MIT License