帧源

为您的平台选择并配置合适的帧源。涵盖所有检查器字段、捕获预设、平台要求和源状态诊断。

选择并配置视觉帧源

帧源是负责捕获图像并将其以 Y 轴翻转的形式提供给发布器的组件 RenderTexture. Convai SDK 附带三个内置帧源——一个用于 Unity 场景摄像机，一个用于物理网络摄像头，一个用于 Meta Quest 透视摄像头——每个都针对其目标平台进行了优化。本页介绍如何添加、配置和排查这三者。

选择帧源

帧源	适用于	平台
CameraVisionFrameSource	可流式传输任意 Unity 场景摄像机——主摄像机、安防摄像机、俯视视角	PC、Mac、Android、iOS、主机
WebcamVisionFrameSource	流式传输连接到玩家电脑或移动设备的物理摄像头设备	PC、Mac、Android、iOS
QuestVisionFrameSource	在 Meta Quest 头显上流式传输现实世界透视画面	Meta Quest（需要 Meta XR SDK）

通过以下方式添加帧源： 添加组件 并输入类名，或者导航到以下菜单路径中的组件菜单： Convai → 视觉.

---

CameraVisionFrameSource

CameraVisionFrameSource 捕获 Unity 的 摄像机的输出到一个 RenderTexture 并在每一帧将其提供给发布器。当处于活动渲染管线（内置或 SRP/URP）时，它会自动选择正确的捕获后端，前提是 摄像机捕获模式 被设置为 自动.

组件菜单路径： Convai/视觉/摄像机视觉帧源

检查器参考

捕获设置

字段	类型	默认值	描述
捕获预设	CapturePreset	均衡	选择预配置的分辨率和帧率组合。设置为 自定义 即可手动输入值。
捕获宽度	int	—	输出宽度（像素）。仅在预设为 自定义.
捕获高度	int	—	输出高度（像素）。仅在预设为 自定义.
目标 FPS	int	—	目标捕获帧率。仅在预设为 自定义.
摄像机捕获模式	CameraCaptureMode	自动	选择渲染管线捕获策略。保持为 自动 ，除非另有指示。

摄像机

字段	类型	默认值	描述
目标摄像机	摄像机	（自动解析）	要捕获的摄像机。如果留空，将解析为 Camera.main ，在运行时。

调试

字段	类型	默认值	描述
源 ID	字符串	"camera"	用于领域事件和多源场景的标识符。
启用诊断帧健康探测	bool	false	执行同步的逐帧像素回读以验证帧内容。仅在诊断黑屏问题时使用；每一帧都会带来 GPU 回读开销。

捕获预设值

预设	宽度	高度	FPS	使用场景
低开销	640	480	10	大规模部署、移动端或带宽受限环境
均衡	1280	720	15	通用用途——大多数场景的默认值
高细节	1920	1080	30	对 AI 理解而言细微视觉细节很重要的场景
自定义	（手动设置）	（手动设置）	（手动设置）	完全控制尺寸和帧率

摄像机捕获模式值

模式	何时使用
自动	默认。检测活动渲染管线并自动选择合适的后端。
BuiltInHooks	强制使用 Camera.onPreRender / Camera.onPostRender 回调。仅兼容内置渲染管线。
SrpNative	强制使用 SRP/URP 显式渲染路径（TargetCamera.Render() 在 LateUpdate）。在以下情况使用 自动 无法正确检测 SRP 时。
ExplicitRenderCompatibility	一种兼容性回退方案，显式渲染摄像机。适用于高度定制的渲染设置。

保持 摄像机捕获模式 在 自动 除非你有特定理由覆盖它。为渲染管线选择错误的后端会导致黑屏或空白视频流。

启用诊断帧健康探测 每一帧都会执行同步的 GPU 到 CPU 像素回读。仅在调试期间启用，并在发布前禁用它。在生产环境中，SDK 会在内部执行更轻量级的帧健康检查。

---

WebcamVisionFrameSource

WebcamVisionFrameSource 使用 Unity 的 WebCamTexture API 捕获物理摄像头设备，并将输出转换为一个 RenderTexture。它处理设备选择、权限请求（在 Android 和 iOS 上）、自动旋转校正以及分辨率限制。

组件菜单路径： Convai/视觉/网络摄像头视觉帧源

检查器参考

网络摄像头设置

字段	类型	默认值	描述
网络摄像头设备名称	字符串	""	要打开的网络摄像头设备名称。空字符串会选择第一个可用设备。
请求宽度	int	640	发送给驱动的请求捕获宽度。实际分辨率可能不同。
请求高度	int	480	发送给驱动的请求捕获高度。
请求 FPS	int	15	发送给驱动的请求帧率。
最大输出宽度	int	1280	输出的最大宽度 RenderTexture。宽于此值的帧会被缩小。设置为 0 可禁用缩放。
最大输出高度	int	720	输出的最大高度 RenderTexture.

源标识

字段	类型	默认值	描述
源 ID	字符串	"webcam"	用于领域事件和多源场景的标识符。

列出可用设备

要在运行时枚举已连接的网络摄像头设备：

string[] deviceNames = WebcamVisionFrameSource.GetAvailableDeviceNames();
foreach (string name in deviceNames)
    Debug.Log(name);

在运行时切换设备

若要在不中断会话的情况下切换到其他网络摄像头：

// Requires a reference to the WebcamVisionFrameSource component
WebcamVisionFrameSource webcam = GetComponent<WebcamVisionFrameSource>();
IConvaiOperation<Unit> op = webcam.SwitchWebcamAsync("Front Camera");

权限流程（Android / iOS）

在 Android 和 iOS 上，组件会在以下情况异步请求摄像头权限：当 StartCapture() 被调用时。 状态 属性会经历以下状态转换：

空闲 → 等待权限 → 启动中 → 就绪

如果用户拒绝权限， 状态 变为 失败 和 错误类型 被设置为 权限被拒绝。你可以通过以下方式监控它： IVisionFrameSourceStatusProvider.StatusChanged ——参见 高级主题 了解详情。

在 Android 和 iOS 上，系统摄像头权限对话框会在以下情况首次出现： StartCapture() 运行时。请确保你的应用清单或 Info.plist 在发布前声明摄像头使用说明。

---

QuestVisionFrameSource

QuestVisionFrameSource 从 Meta Quest 头显流式传输现实世界透视画面，使 Convai 角色能够实时查看用户所处的物理环境。该组件通过反射绑定到 Meta 的 PassthroughCameraAccess API，因此 SDK 不会对 Meta XR 包产生强编译期依赖。

组件菜单路径： Convai/视觉/Quest 视觉帧源

检查器参考

Quest 摄像头访问

字段	类型	默认值	描述
透视摄像头访问	MonoBehaviour	（自动发现）	对以下项的引用： PassthroughCameraAccess 场景中的组件。留空可自动查找。

输出设置

字段	类型	默认值	描述
源 ID	字符串	"quest-passthrough"	用于领域事件的标识符。
最大输出宽度	int	1280	输出的最大宽度 RenderTexture.
最大输出高度	int	720	输出的最大高度 RenderTexture.
目标帧率	int	15	捕获的目标每秒帧数。
翻转 Y 轴	bool	true	垂直翻转透视纹理。为确保视频方向正确而必需；仅当 Meta SDK 更改其坐标约定时才禁用。

QuestVisionFrameSource 需要 Meta XR SDK 已安装。在非 Quest 平台上，组件会进入 失败 状态，且 错误类型 设为 不支持的平台 ，并且不产生任何帧。

与 PassthroughCameraAccess 的绑定在运行时通过反射建立。如果 Meta XR 包更新且 PassthroughCameraAccess 其 API 发生变化，组件将记录错误并进入 失败 状态。在这种情况下请检查 SDK 更新。

---

源状态参考

这三种帧源都实现了 IVisionFrameSourceStatusProvider，它提供一个 状态 属性和一个 StatusChanged 事件。

VisionSourceState

状态	含义
空闲	捕获尚未开始。
AwaitingPermission	等待用户授予摄像头权限（Android / iOS）。
Starting	捕获正在初始化——设备正在打开，RenderTexture 正在创建。
Ready	捕获正在运行并生成帧。
Degraded	捕获正在运行，但帧健康检查检测到问题（例如连续空白帧）。
Stopped	捕获已正常停止。
失败	捕获失败且无法继续。请检查 错误类型 和 StatusMessage 了解详情。

VisionSourceErrorKind

错误类型	原因
无	无错误。
超时	源未在预期时间窗口内产生可用帧。
权限被拒绝	摄像头权限被用户或操作系统拒绝。
不支持的平台	此平台不支持该源（例如 QuestVisionFrameSource 在 PC 上）。
DeviceUnavailable	无法打开请求的摄像头设备。
InvalidConfiguration	某个字段值超出范围或不一致（请检查 StatusMessage).
未知	发生了意外错误。

有关针对这些状态进行脚本编写以及响应 StatusChanged 事件，请参见 高级主题.

结论

每种帧源都面向特定平台和捕获场景——请使用 CameraVisionFrameSource 用于 Unity 场景摄像机， WebcamVisionFrameSource 用于桌面和移动端的物理设备，以及 QuestVisionFrameSource 用于 Meta Quest 透视画面。随着帧源已配置并处于 Ready 状态，请继续到 发布与策略 以控制帧何时以及如何发送到 Convai 后端。