转录 UI

了解 Convai Unity SDK 如何将持久聊天历史与与语音对齐的字幕分开，以及哪个内置组件显示哪一类内容。

ConvaiManager.ActiveManager.Transcripts 是 Convai Unity SDK 中转录数据的唯一入口。它并排提供两个用途——一条持久的逐轮聊天历史，以及一条与语音对齐的字幕流——因此你的场景 UI 可以显示对话历史和实时字幕，而无需你自己构建这两条管线。自定义转录显示可直接通过 ConvaiManager.ActiveManager.Transcripts 进行订阅——见下方的持久历史和字幕路径。

转录数据如何到达你的场景 UI

运行时内部的转录引擎维护房间状态，并通过 ConvaiTranscripts 位于 ConvaiManager.ActiveManager.Transcripts的门面向外暴露。该门面分成两条独立的读取路径。

这两条路径都读取同一个房间会话，因此角色的发言总会出现在历史中，并且如果存在字幕 UI，也会同时作为字幕显示。

这两条路径都不限定于单个角色。对于绑定到某个 ConvaiCharacter自己的发言线——例如在场景 UI 之外，由凝视或手势触发——请参见 ConvaiCharacter.OnTranscriptReceived 中的 转录 API.

持久聊天历史 vs. 与语音对齐的字幕

CurrentTimeline, Subscribe以及 SubscribeCommitted 为你提供转录的持久一侧：一条已提交对话轮次的时间线，会在房间生命周期内持续存在，适合用于可回溯聊天面板、会话后审阅和导出。 ChatTranscriptUI 基于这条路径构建。

CurrentCaptions 和 SubscribeCaptions 为你提供临时的一侧：与当前正在说的话对齐的文本，一旦下一段开始就会被替换。字幕文本从不会写入持久聊天历史——它只用于驱动字幕样式的覆盖层。 SubtitleTranscriptUI 基于这条路径构建。

当读者需要看到或查询所说内容时，选择持久路径。当读者需要看到当前正在说什么时，选择字幕路径。

内置展示组件

ChatTranscriptUI 随附两个预制体，可直接使用，位于 com.convai.convai-sdk-for-unity 包中： Prefabs/TranscriptUI/TranscriptUI_Chat.prefab 用于屏幕空间聊天面板，另有 Prefabs/TranscriptUI/TranscriptUI_Chat_WorldSpace.prefab 用于在世界空间中渲染同一组件的 Canvas ——例如挂在角色或终端亭上方的面板。两个预制体都会在 Start 上订阅持久时间线（并在 OnEnable时重新订阅），并将已提交和进行中的轮次渲染为消息气泡。

SubtitleTranscriptUI 以示例参考代码的形式提供，路径为 SamplesShared/Scripts/UI/Transcript/Subtitle/SubtitleTranscriptUI.cs 而不是即插即用的预制体。它订阅字幕，并在可配置的延迟后自动隐藏当前说话者的文本，旨在复制到你的项目中并进行适配。

这两个组件都不是唯一选择。任何脚本都可以直接调用 Subscribe, SubscribeCommitted，或 SubscribeCaptions 来驱动自定义显示。

在不丢失历史的情况下隐藏展示

IsPresentationEnabled 以及 PresentationEnabledChanged 事件让随附的展示组件在展示内容被禁用时隐藏其渲染内容——例如在过场动画或菜单显示时——而不会停止房间记录。 ChatTranscriptUI 和 SubtitleTranscriptUI 在展示被禁用时，两者都会清空其渲染内容；当展示重新开启时，则会在启用回放的情况下重新订阅，因此 UI 被隐藏期间不会丢失持久历史中的任何轮次。

下一步

你已经了解了持久路径和字幕路径如何分流，以及各个随附组件分别读取哪一路径。接下来可以继续了解如何从代码中查询持久时间线、配置两种内置显示模式，或从设置面板控制转录可见性。

转录历史与查询聊天和字幕模式设置面板