展示字幕

本文介绍如何展示用户在与智能体进行语音通话的过程中的字幕。如下：

用户说话内容：流式展示用户正在说的话（语音识别（ASR）的实时结果）
智能体说话内容：流式展示智能体输出的内容（大语言模型（LLM）实时的输出结果）

前提条件

已按照快速开始文档集成 ZEGO Express SDK 和 AI Agent 并实现基本的语音通话功能。

快速实现

用户与智能体进行语音对话期间，AI Agent 服务端通过 RTC 房间自定义消息下发 ASR 识别文本和 LLM 回答的文本。客户端可以监听房间自定义消息，解析对应的状态事件来渲染 UI 。

RTC 房间自定义消息的处理流程如下：

监听房间自定义消息

客户端可通过监听 recvExperimentalAPI 回调获取 method 为 onRecvRoomChannelMessage 的房间自定义消息。以下是监听回调的示例代码：

// 注意！！！：通过房间自定义消息收到的数据可能会乱序，需要根据 SeqId 字段进行排序。
// !mark
zg.on("recvExperimentalAPI", (result) => {
  const { method, content } = result;
// !mark
  if (method === "onRecvRoomChannelMessage") {
    try {
      // 解析消息
      const recvMsg = JSON.parse(content.msgContent);
      const { Cmd, SeqId, Data, Round } = recvMsg;
    } catch (error) {
      console.error("解析消息失败:", error);
    }
  }
});
// 启用 onRecvRoomChannelMessage 实验性 API
// !mark
zg.callExperimentalAPI({ method: "onRecvRoomChannelMessage", params: {} });

// 注意！！！：通过房间自定义消息收到的数据可能会乱序，需要根据 SeqId 字段进行排序。
// !mark
zg.on("recvExperimentalAPI", (result) => {
  const { method, content } = result;
// !mark
  if (method === "onRecvRoomChannelMessage") {
    try {
      // 解析消息
      const recvMsg = JSON.parse(content.msgContent);
      const { Cmd, SeqId, Data, Round } = recvMsg;
    } catch (error) {
      console.error("解析消息失败:", error);
    }
  }
});
// 启用 onRecvRoomChannelMessage 实验性 API
// !mark
zg.callExperimentalAPI({ method: "onRecvRoomChannelMessage", params: {} });

房间自定义消息协议

房间自定义消息的各字段说明如下：

字段	类型	描述
Timestamp	Number	时间戳，秒级别
SeqId	Number	包序列号，可能乱序，请根据序列号对消息进行排序。极端情况下 Id 可能不连续。
Round	Number	对话轮次，每次用户主动说话轮次增加
Cmd	Number	3: 语音识别（ASR）的文本 4: LLM 文本
Data	Object	具体内容，各Cmd对应不同Data

Cmd 不同对应的 Data 也不同，具体如下：

处理逻辑

根据 Cmd 字段判断消息类型，并根据 Data 字段获取消息内容。

使用字幕组件

如果您是 Vue 项目，可以直接下载字幕处理hook到您的项目中直接使用。

Vue 项目字幕处理hook使用示例

// 使用字幕组件示例代码
// 在页面中引入chatHook
import { useChat } from "useChat";
import { onMounted, onBeforeUnmount } from 'vue';

// 调用useChat方法，传入 Express SDK 实例，messages为消息列表，放入你的字幕组件中进行渲染
const { messages, setupEventListeners, clearMessages } = useChat(zg);

onMounted(() => {
  // 页面加载时，注册事件监听
  setupEventListeners()
})

onBeforeUnmount(() => {
 // 页面销毁时，清空消息
 clearMessages()
})

// 使用字幕组件示例代码
// 在页面中引入chatHook
import { useChat } from "useChat";
import { onMounted, onBeforeUnmount } from 'vue';

// 调用useChat方法，传入 Express SDK 实例，messages为消息列表，放入你的字幕组件中进行渲染
const { messages, setupEventListeners, clearMessages } = useChat(zg);

onMounted(() => {
  // 页面加载时，注册事件监听
  setupEventListeners()
})

onBeforeUnmount(() => {
 // 页面销毁时，清空消息
 clearMessages()
})

注意事项

消息排序处理：通过房间自定义消息收到的数据可能会乱序，需要根据 SeqId 字段进行排序。
流式文本处理：

ASR 文本每次下发的是全量文本，同一个 MessageId 的消息需要完全替换之前的内容。

LLM 文本每次下发的是增量文本，同一个 MessageId 的消息需要在排序后累加显示。

内存管理：请及时清理已完成的消息缓存，特别是当用户进行长时间对话时。