> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ui-and-presentation/transcript-ui.md).
# 转录 UI
了解 Convai Unity SDK 如何将持久聊天历史与与语音对齐的字幕分开，以及哪个内置组件显示哪一类内容。
`ConvaiManager.ActiveManager.Transcripts` 是 Convai Unity SDK 中转录数据的单一入口。它并排提供两个用途——持久化的逐轮聊天历史和语音对齐字幕流——因此你的场景 UI 无需自行构建任一管道，就能显示对话历史和实时字幕。自定义转录显示可直接通过 `ConvaiManager.ActiveManager.Transcripts` ——请参见下方的持久化路径和字幕路径。
### 转录数据如何到达你的场景 UI
运行时内部的转录引擎维护房间状态，并通过以下方式暴露它： `ConvaiTranscripts` 位于 `ConvaiManager.ActiveManager.Transcripts`。该外观层分为两条独立的读取路径。
```mermaid
graph TD
A[房间转录引擎] --> B[ConvaiTranscripts 外观层]
B -->|CurrentTimeline / Subscribe / SubscribeCommitted| C[持久化聊天历史]
B -->|CurrentCaptions / SubscribeCaptions| D[语音对齐字幕]
C --> E[ChatTranscriptUI]
D --> F[SubtitleTranscriptUI]
E --> G[场景 UI]
F --> G[场景 UI]
```
两条路径都读取同一个房间会话，因此角色的发言总会出现在历史记录中，并且如果存在字幕 UI，也会同时作为字幕显示。
这两条路径都不限定于单个角色。对于绑定到某一个 `ConvaiCharacter`某个角色自身的发言——在场景 UI 之外，例如由注视或手势触发——请参见 `ConvaiCharacter.OnTranscriptReceived` 在 [转录 API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/scripting-reference/transcript-api.md).
### 持久化聊天历史 vs. 语音对齐字幕
`CurrentTimeline`, `Subscribe`，以及 `SubscribeCommitted` 提供转录内容的持久化一侧：一个已提交对话轮次的时间线，会在房间生命周期内持续存在，适用于回滚聊天面板、会后回顾和导出。 `ChatTranscriptUI` 建立在这条路径之上。
`CurrentCaptions` 和 `SubscribeCaptions` 提供转录内容的临时一侧：文本与当前正在说的话对齐，一旦下一个片段开始就会被替换。字幕文本绝不会写入持久化聊天历史——它只用于驱动字幕样式的覆盖层。 `SubtitleTranscriptUI` 建立在这条路径之上。
当读取者需要查看或查询已经说过的内容时，选择持久化路径。当读取者需要看到此刻正在说什么时，选择字幕路径。
### 内置展示组件
`ChatTranscriptUI` 随附一个可直接使用的组件，并在以下位置提供两个预制件： space.vars.sdk\_package\_id 包： `Prefabs/TranscriptUI/TranscriptUI_Chat.prefab` 用于屏幕空间聊天面板，以及 `Prefabs/TranscriptUI/TranscriptUI_Chat_WorldSpace.prefab` 用于在世界空间中渲染相同组件的 `画布` ——例如悬挂在角色或信息亭上方的面板。两个预制件都会订阅位于以下位置的持久化时间线： `开始` （并在以下情况下重新订阅： `OnEnable`）
`SubtitleTranscriptUI` 作为示例参考代码提供于 `SamplesShared/Scripts/UI/Transcript/Subtitle/SubtitleTranscriptUI.cs` 而不是即插即用的预制件。它订阅字幕，并在可配置的延迟后自动隐藏当前说话者的文本，旨在复制到你的项目中并加以调整。
这两个组件都不是唯一的选择。任何脚本都可以直接调用 `Subscribe`, `SubscribeCommitted`，或 `SubscribeCaptions` 来驱动自定义显示。
### 隐藏展示而不丢失历史记录
`IsPresentationEnabled` 以及 `PresentationEnabledChanged` 事件可让随附的展示组件隐藏其渲染内容——例如在过场动画或菜单显示时——而不会停止房间的记录。 `ChatTranscriptUI` 和 `SubtitleTranscriptUI` 两者都会在展示被禁用时清空其渲染内容，然后在重新启用时以回放模式重新订阅，因此在 UI 隐藏期间不会有任何轮次从持久化历史中丢失。
### 下一步
你已经了解持久化路径和字幕路径如何分流，以及各自由哪个随附组件读取。接下来可以继续学习如何从代码查询持久化时间线、配置两种内置显示模式，或从设置面板控制转录可见性。
{% content-ref url="/pages/b846767a1ed5a04b3cfb93646c3c8472baf91067" %}
[转录历史与查询](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ui-and-presentation/transcript-ui/transcript-history-and-queries.md)
{% endcontent-ref %}
{% content-ref url="/pages/6695eb978b08dbf5023b367d38af0912574c4f52" %}
[聊天和字幕模式](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ui-and-presentation/transcript-ui/chat-and-subtitle-modes.md)
{% endcontent-ref %}
{% content-ref url="/pages/dddf624ca0ae7ec32afa0c9e601f2cb7c7ab2b6a" %}
[设置面板](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ui-and-presentation/settings-panel.md)
{% endcontent-ref %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ui-and-presentation/transcript-ui.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.