> 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

`ConvaiManager.ActiveManager.Transcripts` 是 Convai Unity SDK 中转录数据的唯一入口。它并列提供两个用途——持久的逐轮聊天历史和语音对齐字幕流——因此你的场景 UI 可以同时显示对话历史和实时字幕，而无需自行构建任一管线。

{% hint style="warning" %}
**SDK 4.4.0 中的破坏性变更。** `ITranscriptUI`, `ITranscriptListener`, `TranscriptViewModel`, `TranscriptUIController`，以及 `ITranscriptPresentationStrategy` 已被移除。自定义转录显示现在直接通过 `ConvaiManager.ActiveManager.Transcripts` ——请参见下面的持久路径和字幕路径。
{% endhint %}

### 转录数据如何到达你的场景 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，也会同时作为字幕显示。

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

`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` 而不是作为可直接插入的 prefab。它订阅字幕，并在可配置延迟后自动隐藏地渲染当前说话者的文本，其目的是复制到你的项目中并加以适配。

这两个组件都不是唯一选择。任何脚本都可以直接调用 `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=<question>&goal=<endgoal>
```

`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.