> 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` 用于在世界空间中渲染同一组件的 `Canvas` ——例如挂在角色或终端亭上方的面板。两个预制体都会在 `Start` 上订阅持久时间线（并在 `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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
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 optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.