TRTC-ASR Java SDK

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

本 SDK 面向新版 v3 协议：只需 SDKAppID + SecretKey（无需腾讯云 AppID），auth/params 分块、全 snake_case、扁平响应 + 数字错误码。v3 客户端位于 com.tencent.trtcasr.v3 包。

旧版 v2 / v1 协议客户端（com.tencent.trtcasr.asr 包）继续维护、存量可用，文档见 docs/v2_protocol.md。

其他语言 SDK：Go | Python | Node.js | 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(Credential.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(Credential.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 的 ASRException）。

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[]（TranscriptionStatus.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[] 字段：

Java 用法示例：

import com.tencent.trtcasr.asr.SpeechRecognitionListener;
import com.tencent.trtcasr.asr.SpeechRecognitionResponse;
import com.tencent.trtcasr.v3.SpeakerRole;
import com.tencent.trtcasr.v3.SpeechRecognizer;
import com.tencent.trtcasr.v3.Wire;

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

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

// 回调里读取：
class MyListener implements SpeechRecognitionListener {
    @Override
    public void onSentenceEnd(SpeechRecognitionResponse resp) {
        for (SpeechRecognitionResponse.SpeakerSegment seg : resp.getResult().getSpeakerSegments()) {
            String name = seg.getSpeakerName().isEmpty() ? "spk" + seg.getSpeakerId() : seg.getSpeakerName();
            System.out.println("[" + name + "] " + seg.getText());
        }
    }
}

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

pom.xml：

<dependency>
  <groupId>com.tencent</groupId>
  <artifactId>trtc-asr-sdk</artifactId>
  <version>1.2.5</version>
</dependency>

要求：Java 11+（java.net.http WebSocket 客户端）

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

import com.tencent.trtcasr.asr.SpeechRecognitionListener;
import com.tencent.trtcasr.asr.SpeechRecognitionResponse;
import com.tencent.trtcasr.common.ASRException;
import com.tencent.trtcasr.common.Credential;
import com.tencent.trtcasr.v3.SpeechRecognizer;
import com.tencent.trtcasr.v3.Wire;

// listener 接口与 v2 相同（下行消息结构两版一致）。
SpeechRecognitionListener listener = new SpeechRecognitionListener() {
    @Override
    public void onSentenceEnd(SpeechRecognitionResponse resp) {
        System.out.println("Sentence end: " + resp.getResult().getVoiceTextStr());
    }

    @Override
    public void onFail(SpeechRecognitionResponse resp, ASRException error) {
        System.err.println("Failed: " + error); // code 即服务端错误码
    }
};

// 第一个参数是 SDKAppID；v3 不需要腾讯云 AppID。
Credential credential = Wire.newCredential(1400000000, "your-sdk-secret-key");
// credential.setSite(Credential.SITE_INTL); // 国际站；不调用则走国内站

SpeechRecognizer recognizer = new SpeechRecognizer(credential, "bigmodel", listener);
recognizer.setLanguage("zh"); // bigmodel 建议显式指定语种

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

// recognizer.write(pcmChunk); ... 循环发送音频
recognizer.stop(); // 发送 {"type":"end"} 并等待 final

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

import com.tencent.trtcasr.common.Credential;
import com.tencent.trtcasr.v3.SentenceRecognizer;
import com.tencent.trtcasr.v3.TranscribeRequest;
import com.tencent.trtcasr.v3.TranscribeResponse;
import com.tencent.trtcasr.v3.Wire;

Credential credential = Wire.newCredential(1400000000, "your-sdk-secret-key");
SentenceRecognizer recognizer = new SentenceRecognizer(credential);

byte[] data = java.nio.file.Files.readAllBytes(java.nio.file.Path.of("audio.pcm"));
TranscribeRequest req = new TranscribeRequest();
req.engineModelType = "bigmodel";
req.voiceFormat = "pcm";
req.language = "zh";
TranscribeResponse resp = recognizer.recognizeDataWithOptions(data, req);
System.out.println(resp.result + " (" + resp.audioDuration + " ms)");

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

import com.tencent.trtcasr.common.Credential;
import com.tencent.trtcasr.v3.CreateTranscriptionRequest;
import com.tencent.trtcasr.v3.FileRecognizer;
import com.tencent.trtcasr.v3.TranscriptionStatus;
import com.tencent.trtcasr.v3.Wire;

Credential credential = Wire.newCredential(1400000000, "your-sdk-secret-key");
FileRecognizer recognizer = new FileRecognizer(credential);

CreateTranscriptionRequest req = new CreateTranscriptionRequest();
req.engineModelType = "bigmodel";
req.language = "zh";
req.sourceType = Wire.SOURCE_TYPE_URL;
req.url = "https://example.com/audio.wav";
String taskId = recognizer.createTask(req);
TranscriptionStatus status = recognizer.waitForResult(taskId); // 轮询直至完成
System.out.println(status.result + " (" + status.audioDuration + " s)");

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

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

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

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

完整示例请参见：

• 实时语音识别（v3）：V3RealtimeAsrExample
• 一句话识别（v3）：V3SentenceAsrExample
• 录音文件识别（v3）：V3FileAsrExample
• 实时语音识别（v2）：RealtimeAsrExample
• 一句话识别（v2）：SentenceAsrExample
• 录音文件识别（v2）：FileAsrExample

mvn compile exec:java -Dexec.mainClass="com.tencent.trtcasr.examples.V3RealtimeAsrExample" \
  -Dexec.args="audio.pcm bigmodel"

trtc-asr-sdk-java/
├── src/main/java/com/tencent/trtcasr/
│   ├── common/                 # 协议无关基建（v2/v3 共用）
│   │   ├── Credential.java     # 凭证管理
│   │   ├── UserSig.java        # TRTC UserSig 生成
│   │   ├── ASRException.java   # 错误定义
│   │   └── ...
│   ├── asr/                    # v2 / v1 客户端（存量形态）
│   │   ├── SpeechRecognizer.java
│   │   ├── SentenceRecognizer.java
│   │   └── FileRecognizer.java
│   └── v3/                     # v3 协议客户端（独立实现）
│       ├── Wire.java           # wire 工具与常量（auth/params/校验）
│       ├── SpeechRecognizer.java   # /asr/v3 首帧协议
│       ├── SentenceRecognizer.java # /v3/transcribe
│       ├── FileRecognizer.java     # /v3/create_transcription + describe
│       └── ...                 # wire 类型（TranscribeRequest/Response、
│                               #   CreateTranscriptionRequest、TranscriptionStatus…）
├── docs/
│   └── v2_protocol.md          # v2 / v1 旧版协议与客户端文档
├── src/test/                   # 测试（含 v3 mock server 端到端 wire 测试）
├── pom.xml
└── README.md

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

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

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

com.tencent.trtcasr.asr 包中的 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