> 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/features/vision/publishing-and-policies.md).

# 发布策略

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

### 检查器引用

检查器分为两个可折叠部分： **帧源** 和 **发布策略**.

#### 帧源

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

#### 发布策略

| 字段             | 类型                    | 默认值              | 描述                                                |
| -------------- | --------------------- | ---------------- | ------------------------------------------------- |
| **模式**         | `VisionPublishPolicy` | `AutoCompatible` | 控制客户端侧的帧率和比特率预算。请参见 [发布策略](#publish-policies) 下方。 |
| **最大发布 FPS**   | `int` （0–30）          | `0`              | 每个实例的帧率上限，单位为 fps。 `0` 使用所选策略的默认值。                |
| **最大比特率（bps）** | `int`                 | `0`              | 每个实例的最大比特率，单位为每秒比特数。 `0` 使用所选策略的默认值。              |

### 发布策略

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

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

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

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

### 从脚本控制发布

**在运行时切换策略**

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

```csharp
ConvaiVisionPublisher publisher = GetComponent<ConvaiVisionPublisher>();

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

// 切换回平衡模式
publisher.SetPublishPolicy(VisionPublishPolicy.AutoCompatible);
```

**使用 Manual 策略暂停和恢复**

`手动` 该策略适用于视觉上下文只在特定时刻相关的情况——例如，当玩家正在查看某个特定对象时。

`EnablePublishing` 只有在 **模式** 是 `手动`时才会生效。对于其他策略，发布会随房间连接一起开始和停止。若需要按需控制，请先调用 `SetPublishPolicy(VisionPublishPolicy.Manual)` 再调用 `EnablePublishing` 。

```csharp
ConvaiVisionPublisher publisher = GetComponent<ConvaiVisionPublisher>();

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

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

**检查发布状态**

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

```csharp
ConvaiVisionPublisher publisher = GetComponent<ConvaiVisionPublisher>();

if (publisher.IsPublishing)
    Debug.Log($"Publishing on track '{publisher.VideoTrackName}'");
else
    Debug.Log("Not publishing — check Connection Type and frame source state.");
```

`IsPublishing` 变为 `true` 在 `ConvaiRoomManager` 连接并且 **Connection Type** 设置为 **Video**后，帧源会达到 `就绪` 状态，协调器会成功打开 WebRTC 视频轨道。

### 自动发布行为

对于 `AutoCompatible`, `HighResponsiveness`，以及 `LowOverhead`，当房间连接时，发布会自动开始。发布器会等待帧源发出就绪信号后再打开轨道——无需脚本。

房间连接时的顺序：

1. `ConvaiRoomManager` 建立 Video 连接。
2. `ConvaiVisionPublisher` 启动并解析帧源。
3. 帧源开始采集并发出 `就绪`.
4. 协调器打开一个名为 `videoTrackName`.
5. `IsPublishing` 变为 `true` 的 WebRTC 视频轨道，并且 `视频轨道已发布` 域事件触发。

### 原始 RenderTexture 绕过方向处理

`ConvaiVisionPublisher` 通常通过一个 `IVisionFrameSource` — `CameraVisionFrameSource`, `WebcamVisionFrameSource`, `QuestVisionFrameSource`，或自定义实现来读取帧。接口约定要求每个 `IVisionFrameSource` 都公开一个 `RenderTexture` 该内容已经是自上而下的（相对于 Unity 默认的自下而上方向已做 Y 轴翻转），因为这正是 WebRTC 视频轨道所要求的。

{% hint style="warning" %}
**v4.4.0 移除了双重垂直翻转。** 在 v4.4.0 之前，LiveKit 纹理回读路径会在帧源已应用的方向之上再执行一次垂直翻转。绕过所有 `IVisionFrameSource` 并将一个原始 `RenderTexture` 直接分配给 LiveKit `TextureVideoSource` 的高级配置，必须预先对该纹理进行翻转，以抵消额外的翻转并保持发布后的画面正向显示。在 v4.4.0 中，回读不再进行第二次翻转，因此，之前为补偿旧 bug 而预先翻转的纹理现在会以下颠倒的方式到达。请移除该变通方案：提供一个 `RenderTexture` 已经是自上而下的纹理，并使用 `Graphics.Blit` ，参数为 `scale: Vector2(1, -1)` 和 `offset: Vector2(0, 1)`，或者改为通过 Convai 的 `IVisionFrameSource` 实现来传递帧。
{% endhint %}

此迁移说明仅涵盖完全跳过 `IVisionFrameSource` 并直接发布一个 `RenderTexture` 直接到 `TextureVideoSource`。 `ConvaiVisionPublisher` 配合一个 `CameraVisionFrameSource`, `WebcamVisionFrameSource`，或 `QuestVisionFrameSource` 分配给 **源** 无需更改——修复已包含在 SDK 内部，帧现在会自动正向到达。自定义 `IVisionFrameSource` 实现同样受到了这次双重翻转的影响；请参见 [自定义帧源](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/custom-frame-sources.md) 以查看该迁移说明。

### WebGL

在 WebGL 上，不需要也不会使用帧源组件。 `ConvaiVisionPublisher` 会通过 `canvas.captureStream()` 自动捕获可见的浏览器画布，一旦房间连接就会立即开始。所分配的 **源** 字段会被忽略。

{% hint style="danger" %}
**WebGL：需要 HTTPS。** 浏览器会阻止 `canvas.captureStream()` 在非 HTTPS 源上的访问。唯一的例外是 `http://localhost`。在生产环境测试 Vision 之前，请将你的 WebGL 构建部署到 HTTPS 主机上。
{% endhint %}

| 行为    | 详情                                 |
| ----- | ---------------------------------- |
| 帧源    | 不需要。WebGL 上会忽略所分配的帧源。              |
| 帧率    | 无论选择的策略如何，都限制为 15 fps。             |
| 比特率   | 适用策略比特率（不做额外限制）。                   |
| HTTPS | 生产环境必需。 `http://localhost` 是唯一的例外。 |

### 下一步

{% content-ref url="/pages/9ee175b12da238182d707abd778abdc3a8706c80" %}
[Vision 脚本 API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/scripting-api.md)
{% endcontent-ref %}

{% content-ref url="/pages/885a0e6676256e7738207107695532701ef9b1ec" %}
[Vision 调试预览](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/debug-preview.md)
{% endcontent-ref %}

{% content-ref url="/pages/86612bc613c5a299a468b71b3fb8a40e625ee1fe" %}
[排查视觉问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/troubleshooting-and-diagnostics.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/features/vision/publishing-and-policies.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.