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

# 发布策略

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

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

### 检查器参考

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

#### 帧源

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

#### 发布策略

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

### 发布策略

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

| 策略     | FPS   | 最大比特率      | 何时使用                                                                |
| ------ | ----- | ---------- | ------------------------------------------------------------------- |
| `自动兼容` | 10    | 750 kbps   | 默认。与当前后端处理速率兼容的均衡预算。除非有特定原因，否则请使用此项。                                |
| `高响应`  | 15    | 1,000 kbps | 在更快的视觉更新能提升 AI 响应质量的场景中使用（快速移动的物体、手势识别）。网络开销更高。                     |
| `低开销`  | 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);
```

**使用手动策略暂停和恢复**

`手动` 当视觉上下文只在特定时刻相关时，此策略很有用——例如，当玩家正在看某个特定物体时。

`EnablePublishing` 在所有策略下都生效，而不仅仅是 `手动`。在自动发布策略下，发布通常会随房间连接而开始和停止，而 `EnablePublishing(false)` 仍然会将其停止。

只调用一次就是一个持久的决定：从那一刻起，你显式设置的值会优先生效，策略将不再决定是否运行发布。之后切换到其他策略会改变帧率和比特率，但不会改变开启或关闭状态。请使用 `手动` 当你希望按需控制在检查器中体现为明确意图时。

```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` 与以下项连接： **连接类型** 设置为 **视频**，帧源达到 `Ready` 状态，协调器成功打开 WebRTC 视频轨道。

### 自动发布行为

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

房间连接时的顺序：

1. `ConvaiRoomManager` 建立视频连接。
2. `ConvaiVisionPublisher` 启动并解析帧源。
3. 帧源开始捕获并发出 `Ready`.
4. 协调器打开一个名为以下名称的 WebRTC 视频轨道： `videoTrackName`.
5. `IsPublishing` 变为 `true` 以及 `视频轨道已发布` 域事件触发。

### 原始 RenderTexture 绕过方向

`ConvaiVisionPublisher` 通常通过以下方式读取帧： `IVisionFrameSource` — `CameraVisionFrameSource`, `WebcamVisionFrameSource`, `QuestVisionFrameSource`，或自定义实现。接口约定要求每个 `IVisionFrameSource` 都公开一个 `RenderTexture` 它已经是自上而下的（相对于 Unity 默认的自下而上方向进行了 Y 翻转），因为 WebRTC 视频轨道要求如此。

绕过所有 `IVisionFrameSource` 并直接分配一个原始 `RenderTexture` 直接给 LiveKit `TextureVideoSource` 必须提供已经是自上而下的纹理：请使用 `Graphics.Blit` 使用 `scale: Vector2(1, -1)` 和 `offset: Vector2(0, 1)`，或者将帧通过 Convai `IVisionFrameSource` 实现进行传递。参见 [自定义帧源](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/custom-frame-sources.md) 了解 `Graphics.Blit` 模式。

### WebGL

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

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

| 行为    | 详情                                                           |
| ----- | ------------------------------------------------------------ |
| 帧源    | 无需任何内容。WebGL 上会忽略所分配的帧源。                                     |
| 帧率    | 策略自身的帧率被限制为 15 fps。显式设置的 **最大发布 FPS** 高于 `0` 的值将按原样使用，不会被限制。 |
| 比特率   | 应用策略比特率（不额外限制）。                                              |
| 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" %}
[视觉调试预览](/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 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/features/vision/publishing-and-policies.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.