> 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 模型或后端视觉提供商。

### Inspector 参考

Inspector 分为两个可折叠的部分： **帧源** 和 **发布策略**.

#### 帧源

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

#### 发布策略

| 字段            | 类型                    | 默认值              | 说明                                               |
| ------------- | --------------------- | ---------------- | ------------------------------------------------ |
| **模式**        | `VisionPublishPolicy` | `AutoCompatible` | 控制客户端的帧率和码率预算。请参阅下方的 [发布策略](#publish-policies) 。 |
| **最大发布帧率**    | `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   | 适用于大规模部署、带宽有限的移动设备，或视觉内容变化缓慢的场景。                                           |
| `Manual`             | *（无）* | *（无）*      | 连接房间时不会自动开始发布。请从脚本中调用 `EnablePublishing(true)` 以开始发布。适用于由会话状态控制或基于触发条件的采集。 |

要在不更改策略的情况下覆盖特定实例的策略默认值，请在 Inspector 中设置 **最大发布帧率** 或 **最大码率（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 策略暂停和恢复**

`Manual` 策略适用于仅在特定时刻才需要视觉上下文的情况，例如玩家正在注视某个特定物体时。

`EnablePublishing` 在所有策略下都会生效，而不仅限于 `Manual`。在自动发布策略下，发布操作通常会随房间连接的建立和断开而启动和停止，而 `EnablePublishing(false)` 无论如何都会停止发布。

调用一次后，该设置便会持续生效：从那时起，发布是否运行由你明确设置的值决定，不再由策略决定。之后切换到其他策略会更改帧率和比特率，但不会改变发布的开关状态。如果希望在 Inspector 中明确体现按需控制的意图，请使用 `Manual` 。

```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($"正在发布到轨道 '{publisher.VideoTrackName}'");
else
    Debug.Log("未在发布 — 请检查 Connection Type 和帧源状态。");
```

`IsPublishing` 会变为 `true` 此时 `ConvaiRoomManager` 建立连接，且 **Connection Type** 设置为 **Video**，帧源达到 `Ready` 状态，且协调器成功打开 WebRTC 视频轨道。

### 自动发布行为

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

房间连接时的流程：

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

### 原始 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` 实现来传递帧。请参阅 [自定义帧源](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/custom-frame-sources.md) 用于 `Graphics.Blit` 模式。

### WebGL

在 WebGL 中，无需也不会使用帧源组件。 `ConvaiVisionPublisher` 会在房间连接后立即自动通过 `canvas.captureStream()` 捕获浏览器中可见的画布。指定的 **Source** 字段会被忽略。

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

| 行为    | 详细信息                                                          |
| ----- | ------------------------------------------------------------- |
| 帧源    | 无需设置。在 WebGL 中，指定的帧源会被忽略。                                     |
| 帧率    | 策略自身的帧率会限制在 15 fps。显式设置的 **最大发布帧率** 高于 `0` 该值时，将按原值使用，不会受到限制。 |
| 比特率   | 应用策略比特率（不额外限制）。                                               |
| HTTPS | 生产环境中必须使用。 `http://localhost` 是唯一的例外。                         |

### 后续步骤

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

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

{% content-ref url="/pages/86612bc613c5a299a468b71b3fb8a40e625ee1fe" %}
[排查视觉问题](https://docs.convai.com/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.
