展示字幕
2026-03-12
功能介绍
本文介绍如何基于ZEGO的客户端的字幕组件，实现在语音通话、视频通话中，流式（打字机式）展示对应用户/音频流的字幕。
- 字幕组件可以展示的类型：
- 用户说话字幕：流式展示用户说话文字内容，并支持前向纠错。
- 翻译字幕：展示翻译文字结果。
- 字幕组件展示的范围：
- 房间级别所有用户/音频流的字幕
- 用户/流级别的字幕
核心说明
字幕组件中，涉及的核心字段说明如下：
| 字段 | 类型 | 描述 |
|---|---|---|
| Timestamp | Number | 时间戳，秒级别 |
| SeqId | Number | 包序列号，可能乱序，请根据序列号对消息进行排序。极端情况下 Id 可能不连续。 |
| Round | Number | 对话轮次，每次用户主动说话轮次增加 |
| Cmd | Number | 201: ASR 语音识别的文本 202: LLM 翻译的文本 |
| Data | Object | 具体内容，各 Cmd 对应不同 Data |
Cmd 不同对应的 Data 也不同，具体如下：
字幕组件使用说明
前提条件
- 已按照 快速开始 文档实现基础功能：
- 集成 ZEGO Express SDK 实现基本的语音通话功能。
- 基于云端实时语音识别，开启云端实时语音识别，并配置
SubtitleType为1，2或3，从而将字幕通过房间信令下发。
注意
必须使用 下载 SDK 及 Demo 页面针对 Cloud ASR 优化的 ZEGO Express SDK 版本，否则无法正常显示字幕。
使用字幕组件
仅展示部分字幕（可选）
可以通过筛选UserId等，实现仅展示某些用户或某些流的字幕。 以仅显示其他人翻译后的字幕为例。
自定义实现字幕（不推荐）
注意
建议您默认使用字幕组件实现。
客户端可通过监听 onRecvExperimentalAPI 回调获取 method 为 liveroom.room.on_recive_room_channel_message 的房间自定义消息。
根据 Cmd 字段判断消息类型，并根据 Data 字段获取消息内容。
注意事项
- 消息排序处理：通过房间自定义消息收到的数据可能会乱序，需要根据 SeqId 字段进行排序。
- 流式文本处理：
- ASR 文本每次下发的是全量文本，同一个 MessageId 的消息需要完全替换之前的内容。
- LLM 文本每次下发的是增量文本，同一个 MessageId 的消息需要在排序后累加显示。
- 内存管理：请及时清理已完成的消息缓存，特别是当用户进行长时间对话时。