发布策略

Vision 发布策略参考，包括 FPS 和码率预算、运行时控制方法、自动发布行为以及 WebGL 特定行为。

ConvaiVisionPublisher 管理承载从 Unity 到 Convai 的摄像头画面的 WebRTC 视频轨道。发布策略控制客户端的帧率和比特率预算；它不会配置任何 AI 模型或后端视觉提供方。

检查器参考

检查器分为两个可折叠部分： 帧源 是位于 发布策略.

帧源

字段	类型	默认值	说明
来源	MonoBehaviour	（自动发现）	该 IVisionFrameSource 用于发布。留空可从同一 GameObject、子对象或场景中自动发现。存在多个帧源时请显式分配。
轨道名称	string	"unity-scene"	WebRTC 轨道在 LiveKit 房间中显示的名称。仅在后端路由需要特定名称时更改。

发布策略

字段	类型	默认值	说明
模式	VisionPublishPolicy	自动兼容	控制客户端帧率和比特率预算。请参见 发布策略 如下。
最大发布 FPS	int （0–30）	0	每个实例的帧率上限，单位 fps。 0 使用所选策略的默认值。
最大比特率（bps）	int	0	每个实例的最大比特率，单位为每秒比特数。 0 使用所选策略的默认值。

发布策略

发布策略是客户端的传输预算。它控制每秒发送多少帧，以及分配给视频轨道的最大比特率。

策略	FPS	最大比特率	适用场景
自动兼容	10	750 kbps	默认。与当前后端处理速率兼容的平衡预算。除非有特殊理由更改，否则请使用此项。
高响应	15	1 000 kbps	视觉更新更快能提升 AI 响应质量的场景（快速移动的物体、手势识别）。网络开销更高。
低开销	5	350 kbps	大规模部署、带宽受限的移动设备，或视觉上下文变化缓慢的场景。
Manual	（无）	（无）	在连接房间时不会自动开始发布。调用 EnablePublishing(true) 即可从脚本启动。用于会话门控或基于触发器的采集。

若要在不更改策略的情况下为特定实例覆盖策略默认值，请设置 最大发布 FPS 或 最大比特率（bps） 在检查器中。值为 0 表示“使用策略默认值”。

// 通过脚本在运行时覆盖
ConvaiVisionPublisher publisher = GetComponent<ConvaiVisionPublisher>();
publisher.publishFrameRateOverride = 12;
publisher.publishBitrateOverride = 600_000;

从脚本控制发布

在运行时切换策略

调用 SetPublishPolicy 即可在会话运行时更改传输预算。更改会在下一帧发布时生效。

ConvaiVisionPublisher publisher = GetComponent<ConvaiVisionPublisher>();

// 为带宽受限的用户切换为低开销
publisher.SetPublishPolicy(VisionPublishPolicy.LowOverhead);

// 切回平衡
publisher.SetPublishPolicy(VisionPublishPolicy.AutoCompatible);

使用手动策略暂停和恢复

Manual 当视觉上下文只在特定时刻相关时，此策略很有用——例如，当玩家正在看某个特定对象时。

EnablePublishing 仅在以下情况下才有效： 模式 为 Manual。对于其他策略，发布会随着房间连接自动开始和停止。调用 SetPublishPolicy(VisionPublishPolicy.Manual) ，然后再调用 EnablePublishing 如果你需要按需控制。

ConvaiVisionPublisher publisher = GetComponent<ConvaiVisionPublisher>();

// 当玩家聚焦在某个对象上时开始发布
void OnPlayerLookAt(GameObject target)
{
    publisher.EnablePublishing(true);
}

// 当失去焦点时停止发布
void OnPlayerLookAway()
{
    publisher.EnablePublishing(false);
}

检查发布状态

读取 IsPublishing 以确认视频轨道正在发送。

ConvaiVisionPublisher publisher = GetComponent<ConvaiVisionPublisher>();

if (publisher.IsPublishing)
    Debug.Log($"正在发布轨道 '{publisher.VideoTrackName}'");
else
    Debug.Log("未在发布 — 请检查 Connection Type 和帧源状态。");

IsPublishing 变为 true 在 ConvaiRoomManager 连接为 连接类型 设置为 视频，帧源达到 就绪 状态，并且协调器成功打开 WebRTC 视频轨道。

自动发布行为

对于 自动兼容, 高响应，以及 低开销，在房间连接时发布会自动开始。发布器会等待帧源发出就绪信号后再打开轨道——无需脚本。

房间连接时的顺序：

1. ConvaiRoomManager 建立视频连接。
2. ConvaiVisionPublisher 启动并解析帧源。
3. 帧源开始采集并发出 就绪.
4. 协调器打开名为 videoTrackName.
5. IsPublishing 变为 true 以及 VideoTrackPublished 域事件触发。

WebGL

在 WebGL 中，不需要也不会使用帧源组件。 ConvaiVisionPublisher 通过以下方式自动捕获可见的浏览器画布： canvas.captureStream() 在房间连接后立即。分配的 来源 字段会被忽略。

WebGL：需要 HTTPS。 浏览器会阻止 canvas.captureStream() 在非 HTTPS 来源上。唯一的例外是 http://localhost。在生产环境测试 Vision 之前，请将你的 WebGL 构建部署到 HTTPS 主机上。

行为	详情
帧源	无需任何内容。WebGL 中分配的帧源会被忽略。
帧率	无论选择何种策略，都会限制为 15 fps。
比特率	应用策略比特率（不再额外限制）。
HTTPS	生产环境中必需。 http://localhost 是唯一的例外。

下一步

Vision 脚本 APIVision 调试预览排查视觉问题