> 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` 管理将摄像头画面从 Unity 传送到 Convai 的 WebRTC 视频轨道。发布策略控制客户端的帧率和比特率预算；它不会配置任何 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   | 大规模部署、带宽受限的移动设备，或视觉上下文变化较慢的场景。                                     |
| `Manual`             | *(无)* | *(无)*      | 房间连接时不会自动开始发布。请调用 `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 策略暂停和恢复**

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

`EnablePublishing` 仅在 **模式** 为 `Manual`时才会生效。对于其他策略，发布会随着房间连接开始和停止。请调用 `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($"正在轨道 '{publisher.VideoTrackName}' 上发布");
else
    Debug.Log("未在发布——请检查连接类型和帧源状态。");
```

`IsPublishing` 变为 `true` 在……之后 `ConvaiRoomManager` 与 **连接类型** 设置为 **视频**，帧源会到达 `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 视频轨道所要求的。

{% 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" %}
[视觉脚本 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 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.