> 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](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/scripting-reference/transcript-api.md).

### 持久化聊天记录与语音同步字幕

`CurrentTimeline`, `Subscribe`和 `SubscribeCommitted` 提供转录的持久化部分：由已提交的对话轮次组成的时间线，在房间生命周期内持续保存，适用于可回看聊天面板、会话后查看和导出。 `ChatTranscriptUI` 基于此路径构建。

`CurrentCaptions` 和 `SubscribeCaptions` 提供转录的临时部分：与当前正在说出的内容同步的文本会在下一个片段开始时立即替换。字幕文本不会写入持久化聊天记录，只用于驱动字幕样式的叠加层。 `SubtitleTranscriptUI` 基于此路径构建。

如果用户需要查看或查询已说过的内容，请选择持久化路径；如果用户需要查看此刻正在说的内容，请选择字幕路径。

### 内置显示组件

`ChatTranscriptUI` 提供开箱即用的组件，并在 <code class="expression">space.vars.sdk\_package\_id</code> 包中附带两个预制件： `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" %}
[转录历史与查询](https://docs.convai.com/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" %}
[聊天和字幕模式](https://docs.convai.com/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" %}
[设置面板](https://docs.convai.com/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=<question>&goal=<user_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.
