1. 背景

RTC-ASR 原子能力提供实时语音转写：客户端将采集到的音频流实时推送，服务端实时返回转写文本。适用于语音输入、实时字幕、通话转写、质检合规等需要「边说边出字」的场景。

该能力通过统一 WebSocket 协议对外提供，一条连接内支持三类输入帧（START / AUDIO / FINISH），输出 result / silence / echo / error 四类事件帧。对外统一供应商标识为 baidurtc-asr，具体识别引擎由 START 帧的 app_id 在部署侧映射决定，客户端无需感知。

接入链路如下：

1客户端 ──WS──> 网关 /v1/asr ──WS──> ASR Server ──WS──> 识别引擎

网关只做鉴权、限流、连接管理与透明转发，不解析 ASR 语义；帧协议由 ASR Server 处理。

2. 能力总览

在基础转写之上，可选能力共 5 个，全部在 START 帧 data 内按对象独立开启：

3. 接入准备

3.1 申请凭证

向平台申请 app_id 与对应的 apikey（bce-v3/ALTAK-xxx 形式），一个 app_id 对应一个 apikey。

3.2 接入端点

WebSocket 端点：wss://rtc-aiagent.baidubce.com/v1/asr

3.3 鉴权方式

WebSocket 握手时携带请求头 Authorization: Bearer bce-v3/ALTAK-xxx（只认 header，不接受 URL query 携带 token）。

注意：app_id 是 START 帧 data 的顶层字段，须与鉴权所用 apikey 的归属一致，否则网关以 403 拒绝。它同时用于三处——网关越权校验、ASR Server 引擎路由（asr.app_route 映射）、声纹索引（app_id::user_id）。

4. 接入流程

最小接入流程如下：

（1）建立 WebSocket 连接（携带 Authorization: Bearer bce-v3/ALTAK-xxx 请求头）。

（2）发送 START 帧，声明供应商与业务 app_id：

1{"type":"START","data":{"provider":"baidurtc-asr","app_id":"your-app-id"}}

（3）持续发送 AUDIO 帧（base64 编码的 PCM 音频）：

1{"type":"AUDIO","data":{"audio":"<base64 编码的 PCM 字节流>","seq":1}}

（4）实时接收 result 帧：

1{"type":"result","text":"你好","is_final":false}
2{"type":"result","text":"你好，今天天气不错","is_final":true}

（5）发送 FINISH 帧结束，服务端 drain 完剩余结果后主动以 close(1000) 关闭连接：

1{"type":"FINISH"}

5. 可选能力

5.1 云端 3A（3a）

功能说明：对音频做噪声抑制（ANS）、自动增益（AGC）前处理，提升嘈杂环境下的识别准确率。两个子功能各自 enable 控制，任何子功能都可缺省。

5.2 声纹识别（voiceprint）

功能说明：识别说话人身份，结果随 result 帧的 extra_info.speaker 回传，用于多说话人场景下区分「谁在说话」。

声纹注册走独立 REST 接口，不进转写协议；user_id 为声纹注册时输入的 user_id，注册说明见 https://cloud.baidu.com/doc/RTC/s/hm8zjic1q#注册用户声纹信息。

5.3 输入安全审核（security_review）

功能说明：对断句（is_final=true）文本做安全审核，结果回 extra_info.security_review.is_blocked，用于合规/敏感内容拦截（不阻断转写，只标记）。

审核策略模板（template_id）由部署侧配置，不进 START 帧。

5.4 VAD 断句参数（vad）

功能说明：调整「多长静音算一句话说完」（断句）与「断句后粘句窗口」（防止一句话被切碎），适配不同说话人的语速与停顿习惯。

两参数非法/超范围时回退默认值（不拒绝连接）。

5.5 ASR 引擎参数（asr）

功能说明：配置热词，提升特定领域、专有名词的识别率。

6. 场景与参数配置示例

6.1 纯转写（不启用任何可选能力）

1{"type":"START","data":{"provider":"baidurtc-asr","app_id":"your-app-id"}}

6.2 多说话人 + 安全合规（声纹 + 审核）

1{"type":"START","data":{
2  "provider":"baidurtc-asr",
3  "app_id":"your-app-id",
4  "voiceprint":{"enable":true,"user_id":"u123"},
5  "security_review":{"enable":true}
6}}

6.3 嘈杂环境 + 中距离对话（3A + VAD）

1{"type":"START","data":{
2  "provider":"baidurtc-asr",
3  "app_id":"your-app-id",
4  "3a":{
5    "ans":{"enable":true,"pre_mode":"M","mid_gain_db":6,"df_limit_db":30},
6    "agc":{"enable":true,"max_volume":70}
7  },
8  "vad":{"vad_ms":800}
9}}

6.4 热词（ASR 引擎参数）

1{"type":"START","data":{
2  "provider":"baidurtc-asr",
3  "app_id":"your-app-id",
4  "asr":{"hot_words":["BRTC","智能体"]}
5}}

7. 注意事项

1. 云端 3A

   1. 自动增益建议与噪声抑制搭配使用，不要单独开启（嘈杂环境下人声已被降噪抹掉，增益无益）。
   2. max_volume 建议不超过 90，非必要不启用 extra_gain（避免过度增益、削峰失真）。
   3. echo=true 时服务端回传音频处理前后帧（echo 帧：处理前 raw + 处理后 final），仅调试场景开启，生产建议关闭（额外带宽开销）。

2. 声纹识别

   1. 结果字段 speaker（speaker_id/speaker_name/score）为稀疏字段，无匹配/未启用/超时时整段省略，客户端需按「可能缺失」处理。
   2. speaker_id 为 person_id（稳定唯一），speaker_name 为展示名（可重名）。
   3. final 句同步等声纹结果（带超时兜底），中间结果只带「最近一次已知说话人」。

3. 输入安全审核

   1. 只审断句（is_final=true）文本，中间结果直接透传、不带 security_review。
   2. 审核拦截时文本照发 + is_blocked:true 标记，不阻断连接、不发 error。

4. VAD

   1. vad_ms 越小断句越灵敏（停顿短就断句），越大越能容忍长停顿；语速快、停顿短可调小，语速慢可调大。
   2. vad_wait_ms 控制「断句后粘句」，说话人停顿频繁又不想句子被切碎时可调大。

5. ASR 引擎参数

   1. hot_words 按当前绑定识别引擎映射到各自的热词机制或忽略。

6. 静音检测

   1. 静音状态通过独立 silence 帧反馈，成对边沿触发（is_silence:true 进入 / false 恢复），中间不重复。
   2. 静音检测输出自带，无需在输入声明。

7. 转写文本前缀标记

   服务端复用对话链路的断句/粘句语义，result.text 开头可能带内部标记，接入方需剥前缀显示并按语义消费：

   text 形态	出现时机	消费语义
   [M]:xxx	中间结果（is_final=false）	中间态，同一句可能多条，取最后一条为最终
   [M]:[C]:xxx	粘句后的中间结果	同上，xxx 已拼接上一句
   [C]:xxx	粘句续写的最终结果（is_final=true）	xxx 已含上一句，应替换上一条 final 而非追加
   xxx	正常断句的最终结果	无前缀，正常追加

   粘句由 vad.vad_wait_ms 控制：断句后 vad_wait_ms 窗口内新句到达时拼回上一句、带 [C]: 前缀。