For the complete documentation index, see llms.txt. This page is also available as Markdown.

转录 API

ConvaiTranscripts 的拉取式 API 参考——从 C# 脚本中查询、筛选并订阅实时内存中的转录时间线。

ConvaiTranscripts 为你提供基于拉取的、可快照访问房间完整转录时间线的能力。与事件中继组件不同,后者会在各个更新到达时逐个推送更新,而 ConvaiTranscripts 该门面维护着一个实时的内存时间线,你可以按需查询。这使它非常适合用于转录历史回放、自定义聊天 UI 构建、会后导出,以及任何需要一次读取多轮内容的功能。通过以下方式访问该门面: ConvaiManager.ActiveManager.Transcripts.


推送 vs. 拉取

事件中继 / ConvaiEvents

ConvaiTranscripts

传递

推送——每次更新都会调用你的回调

拉取——你需要时随时读取时间线

历史

每个回调仅返回最近一次更新

完整历史:活动轮次 + 已提交轮次

使用场景

字幕渲染、实时动画触发

会后导出、自定义聊天记录、评估回顾

访问

ConvaiSessionEventRelay, ConvaiEvents

ConvaiManager.ActiveManager.Transcripts


ConvaiTranscripts 门面

属性

成员
类型
说明

CurrentTimeline

TranscriptTimelineSnapshot

访问时刻整个转录时间线的快照

方法

方法
返回
说明

GetTurns(TranscriptQuery?)

IReadOnlyList<TranscriptTurnSnapshot>

返回所有与可选查询匹配的轮次。传入 null 以获取所有轮次。

GetTurn(string turnId)

TranscriptTurnSnapshot

按 ID 获取特定轮次。若未找到则返回 null

GetLatestTurn(TranscriptParticipantRef)

TranscriptTurnSnapshot

返回给定参与者的最近一次轮次。若没有则返回 null

Dispose()

void

取消订阅内部变更事件。如果你订阅了该事件,请在组件销毁时调用 已更改.

事件

事件
参数
触发时

已更改

TranscriptUpdateBatch

时间线发生变化——轮次被添加、更新、完成、中断或移除


TranscriptQuery — 过滤轮次

字段
类型
默认值
说明

参与者类型

TranscriptParticipantKind?

null (全部)

过滤到 玩家角色 回合

PlayerOrCharacterId

string

null (全部)

过滤到特定玩家或角色 ID

ParticipantId

string

null (全部)

过滤到特定房间参与者 ID

包含活动回合

bool

true

包含仍在流式传输中的轮次

包含已提交回合

bool

true

包含已最终确定并提交的轮次


TranscriptTurnSnapshot

属性
类型
说明

TurnId

string

此轮次的唯一标识符(与 MessageId)

MessageId

string

别名 TurnId

RoomSequence

long

房间内单调递增的序列号

参与者

TranscriptParticipantRef

创建此轮次的是谁

StartedAtUtc

DateTime

回合开始的 UTC 时间

LastUpdatedAtUtc

DateTime

最近一次更新的 UTC 时间

CompletedAtUtc

DateTime?

轮次被提交的 UTC 时间; null 在活动期间

生命周期

TranscriptLifecycle

此轮次当前的生命周期阶段

CommittedText

string

不会再更改的最终文本

InterimText

string

来自当前流式片段的进行中文本

DisplayText

string

CommittedText + InterimText ——用于实时显示

WasInterrupted

bool

当轮次因中断而结束时为 True

HasText

bool

DisplayText 非空时为 True

Segments

IReadOnlyList<TranscriptSegmentSnapshot>

此轮次中的各个转录片段

ConversationTargetCharacterId

string

如果已知,则为此玩家轮次所针对的角色

使用 DisplayText 用于实时字幕或聊天渲染。它结合了 CommittedText 是位于 InterimText 因此无论生命周期阶段如何,你总是显示可用的最完整文本。


TranscriptLifecycle enum

说明

流式传输 (0)

轮次正在积极接收文本; InterimText 正在更新

稳定 (1)

流式传输已暂停;文本稳定,但轮次尚未提交

已完成 (2)

轮次已完全提交; CommittedText 是最终的,并且 InterimText 为空


TranscriptTimelineSnapshot

属性
类型
说明

光标

long

单调递增的值;每次时间线更新都会变化

ActiveTurns

IReadOnlyList<TranscriptTurnSnapshot>

当前正在流式传输或稳定的轮次——尚未提交

CommittedTurns

IReadOnlyList<TranscriptTurnSnapshot>

已完全最终确定的轮次

TurnsById

IReadOnlyDictionary<string, TranscriptTurnSnapshot>

所有轮次按 TurnId 索引,可实现 O(1) 查找

LatestTurnByParticipant

IReadOnlyDictionary<string, TranscriptTurnSnapshot>

按参与者索引的每位参与者最近一次轮次,按 ParticipantId

TranscriptTimelineSnapshot.Empty 在没有活动会话时是安全的默认值。


TranscriptUpdateBatch

属性
类型
说明

时间线

TranscriptTimelineSnapshot

此批更改后的时间线完整快照

光标

long

便捷访问器,用于 Timeline.Cursor

已更改回合

IReadOnlyList<TranscriptTurnSnapshot>

此批中发生变化的所有轮次

新增回合 ID

IReadOnlyList<string>

在此批中首次添加的轮次 ID

已更新回合 ID

IReadOnlyList<string>

接收到新文本或新状态的轮次 ID

已完成回合 ID

IReadOnlyList<string>

已转换为 已完成 的轮次 ID

被中断回合 ID

IReadOnlyList<string>

因中断而结束的轮次 ID

已移除回合 ID

IReadOnlyList<string>

从时间线中移除的轮次 ID


TranscriptParticipantRef struct

属性
类型
说明

种类

TranscriptParticipantKind

此参与者是否为 玩家角色

PlayerOrCharacterId

string

与此参与者关联的角色 ID 或玩家 ID

DisplayName

string

人类可读名称

ParticipantId

string

房间级参与者标识符

IsEmpty

bool

PlayerOrCharacterId 为 null 或空白字符

支持相等比较和 ==/!= 运算符。

TranscriptParticipantKind enum

说明

玩家 (0)

人类玩家参与者

角色 (1)

AI 角色参与者


使用示例

示例 1——会后转录导出

一次医疗培训模拟会在会话结束后将整场会话的完整转录导出为 JSON,供主管审阅。

示例 2——在完成时追加的响应式聊天记录

一次企业入职模拟构建了一个可滚动的聊天历史,仅在轮次提交时追加消息——避免临时更新造成的闪烁。

示例 3——带历史回放的自定义实时聊天 UI

一次工业安全演练构建了完整的聊天 UI,在启用时回放所有已提交的转录历史——因此后加入的观众也能看到完整对话——然后监听实时变化。


故障排查

症状
可能原因
修复

GetTurns() 返回空列表

尚不存在任何轮次,或者 IncludeActiveTurns = false 且当前所有轮次都仍在流式传输中

省略 TranscriptQuery 即可获取所有轮次,或者设置 IncludeActiveTurns = true 以包含进行中的轮次

已更改 会触发,但 batch.CompletedTurnIds 为空

轮次仍然处于活动状态——该批次反映的是对流式轮次的更新,而不是完成

检查 batch.ChangedTurns 用于活动轮次更新; 已完成回合 ID 仅在轮次结束时填充

TranscriptTurnSnapshot.CommittedText 为空

轮次仍然 流式传输 ——文本在轮次完成前不会被提交

使用 DisplayText 获取进行中文本,或等待轮次出现在 batch.CompletedTurnIds

已更改 连接后从不触发

订阅太晚,或者 Dispose() 在连接之前调用

订阅 已更改 在之前或紧接着之后 ConnectAsync;不要调用 Dispose() 直到组件被销毁


下一步

若要在不查询时间线的情况下进行事件驱动的转录响应,请使用 ConvaiCharacterEventRelayConvaiTranscriptEventRelay 监控这一点——参见 角色事件。如需完整的角色脚本 API,请参见 Character & Player API.

最后更新于

这有帮助吗?