实时音视频 WebSocket 接入（新）

一、接口描述

注意：说明：

二、前提条件

需要准备两个凭证：SDKAppID 与 SecretKey。

三、接口要求

注意：说明：

注意：如你有更多并发需求，请 联系我们。

四、业务流程图

对应的 SDK 行为：Start() 完成 ①②（同步等待 ack，鉴权或参数错误立即返回 error）；Write() 对应 ③ 上行；下行经 listener 回调 OnSentenceBegin / OnRecognitionResultChange / OnSentenceEnd / OnRecognitionComplete；Stop() 发送 end 并等待 final:1。

五、接口调用流程

接口调用流程分为三个阶段：建立连接、鉴权、识别。鉴权与识别阶段后台均返回 text message，内容为 JSON 序列化字符串，以下是公共字段格式说明：

六、建连阶段

客户端发起 WebSocket 连接请求，请求 URL 格式为：wss://asr.cloud-rtc.com/asr/v3?voice_id=<voice_id>。

URL 上只携带 voice_id，不携带任何鉴权参数。voice_id 同时出现在 URL ?voice_id= 与首帧 params.voice_id 中，两者需一致，或在 params 中省略。SDK 默认生成 uuid，可通过 SetVoiceID 指定。

七、鉴权阶段

连接建立后，客户端需在 3秒内 发送首帧 text message，内容为 JSON，同时完成鉴权与参数下发：

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

type 固定为 start。首帧 JSON 非法或 type 非 start 时，服务端返回 4010；超过3秒未发送首帧，返回 4008。

鉴权通过后服务端返回 code 值为0的确认消息表示鉴权成功：

{"code": 0, "message": "success", "voice_id": "faab2b17-ba43-4ea4-be58-a03180ba26dd"}

鉴权或参数校验失败时，服务端返回 code 为非0值的错误帧（如 4002 鉴权失败、4001 参数不合法），随后正常关闭连接。

SDK 的 Start() 会同步等待该 ack，鉴权与参数错误直接从 Start() 返回。

八、auth 字段说明

一条 WebSocket 连接即一条流，voice_id 既是流身份、也是签名 identifier，因此 auth 块中不再重复携带。

注意：说明：

注意：在线协议没有 request_id。request_id 是离线接口 “一次请求 = 一个事务” 的概念，流式协议里不存在。

九、签名规则

1. 未调用 credential.SetUserSig() 时，SDK 使用 SDKAppID + SecretKey 本地生成签名，有效期 86400 秒，且每条连接都重新生成，长跑服务无需自行管理过期。

2. 调用 credential.SetUserSig(sig) 传入固定签名后，SDK 不再生成也不再刷新。服务端使用当前 identifier（在线为 voice_id）验签，因此签名必须用同一个 identifier 签发。固定签名场景（如浏览器端由业务后端下发签名）需自行处理过期与 identifier 对齐。

3. 签名与站点绑定。SetSite(common.SiteIntl) 决定 host 与验签集群，国际站凭证不可用于国内站，反之亦然。

4. SecretKey 不会传输到网络，签名只用于服务端验签。

十、params 参数说明

十二、上传数据

鉴权成功后，客户端持续上传 binary message 到后台，内容为音频流二进制数据。每 40ms 发送 40ms 时长（即 1:1 实时率）的数据包，对应 PCM 大小为：8k 采样率640字节，16k 采样率1280字节。单帧不超过256KB。音频数据包之间发送间隔超过15秒，后台将返回 4008 并主动断开连接。

音频流上传完成之后，客户端需发送以下内容的 text message，通知后台结束识别。

{"type": "end"}

十三、接收消息

客户端上传数据的过程中，需要同步接收后台返回的实时识别结果，结果示例：

{ "code": 0, "message": "success", "voice_id": "23c33398-4da0-4ba7-b0ec-7565b325301d", "message_id": "756d2992-5a23-488a-b391-9c9c0c36bedf", "result": { "slice_type": 0, "index": 0, "start_time": 0, "end_time": 6000, "voice_text_str": "欢迎来到 ASR。", "language": "zh", "word_size": 0, "word_list": [] }}

后台识别完所有上传的语音数据之后，最终返回 final 值为 1 的消息并断开连接。

{ "code": 0, "message": "success", "voice_id": "faab2b17-ba43-4ea4-be58-a03180ba26dd", "message_id": "8d9e6337-2c8a-49e2-aee9-9179d71ab7a8", "final": 1}

识别过程中如果出现错误，后台返回 code 为非 0 值的消息并断开连接。

{ "code": 4008, "message": "后台识别服务器音频分片等待超时", "voice_id": "faab2b17-ba43-4ea4-be58-a03180ba26dd", "message_id": "8d9e6337-2c8a-49e2-aee9-9179d71ab7a8"}

十四、识别结果

十五、Word 结构体

十六、说话人分离

开启 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 字段

十八、VAD 调优

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

20、安装

go get github.com/Tencent-RTC/trtc-asr-sdk-go@latest

要求 Go 1.21 及以上。

21、SDK

·Tencent-RTC SDK for Go：Github

·Tencent-RTC SDK for Python：Github

·Tencent-RTC SDK for nodejs：Github

·Tencent-RTC SDK for Java：Github

·Tencent-RTC SDK for Rust：Github

·Tencent-RTC SDK for cpp：Github

22、SDK 调用示例

单击查看 Golang 示例。

23、初始化凭证

import ( v3 "github.com/Tencent-RTC/trtc-asr-sdk-go/asr/v3"`// "github.com/Tencent-RTC/trtc-asr-sdk-go/common"`)// 第一个参数是 SDKAppID（如 1400xxxxxx）；v3 不需要腾讯云 AppID。credential := v3.NewCredential(sdkAppID, "your-sdk-secret-key")// credential.SetSite(common.SiteIntl) // 国际站；不调用则走国内站

24、发起实时识别

type MyListener struct{ v3.UnimplementedSpeechRecognitionListener }func (l *MyListener) OnSentenceEnd(resp *v3.SpeechRecognitionResponse) { log.Printf("Sentence end: %s", resp.Result.VoiceTextStr)}func (l *MyListener) OnFail(resp *v3.SpeechRecognitionResponse, err error) { log.Printf("Failed: %v", err) // err 为 *common.ASRError，Code 即服务端错误码}recognizer := v3.NewSpeechRecognizer(credential, "bigmodel", &MyListener{})recognizer.SetLanguage("zh") // bigmodel 建议显式指定语种if err := recognizer.Start(); err != nil { log.Fatal(err) // 鉴权失败/参数非法在这里同步返回}// recognizer.Write(pcmChunk) … 循环发送音频recognizer.Stop() // 发送 {"type":"end"} 并等待 final

25、开启说话人分离

recognizer := v3.NewSpeechRecognizer(credential, "bigmodel", &MyListener{})recognizer.SetLanguage("zh")recognizer.SetWordInfo(1) // 需要字级说话人时开启recognizer.SetSpeakerDiarization(v3.SpeakerDiarizationCluster) // 1：匿名聚类// 声纹角色认证（返回角色名）：// recognizer.SetSpeakerDiarization(v3.SpeakerDiarizationVoiceprint) // 3// recognizer.SetSpeakerRoles([]v3.SpeakerRole{// {RoleName: "teacher", AudioURL: "https://example.com/teacher.wav"},// })// recognizer.SetVoiceprintIDs([]string{"vp-1"}) // 已注册声纹// 回调中读取分段结果：func (l *MyListener) OnSentenceEnd(resp *v3.SpeechRecognitionResponse) { for _, seg := range resp.Result.SpeakerSegments { name := seg.SpeakerName // speaker_diarization=3 才有 if name == "" { name = fmt.Sprintf("spk%d", seg.SpeakerID) } log.Printf("[%s] %s", name, seg.Text) }}

26、运行示例

# 获取示例代码（examples 目录在 SDK 仓库中）git clone https://github.com/Tencent-RTC/trtc-asr-sdk-go.gitcd trtc-asr-sdk-gocd examples/v3_realtime_asrgo run main.go -e bigmodel -f ../test.pcm# 说话人分离（匿名聚类 + 字级说话人）go run main.go -e bigmodel -f ../test.pcm -diarization 1 -word-info 1# 说话人分离（声纹角色认证，返回角色名）go run main.go -e bigmodel -f ../test.pcm -diarization 3 \\ -roles "teacher=https://example.com/teacher.wav,student=https://example.com/student.wav"# 查看所有选项go run main.go -h

27、配置项

28、错误码

SDK 本地错误码：SDK 返回的 error 为 *common.ASRError，其 Code 即服务端错误码。SDK 本地错误使用 10xx 区间，如 1001 本地参数错误、1002 连接失败。