高级主题

脚本 API 参考、自定义帧源实现、域事件、WebGL 平台行为以及跨平台兼容性。

高级视觉配置与自定义集成

本页涵盖以下内容的完整脚本 API： ConvaiVisionPublisher、实现自定义帧源的约定、在 Vision 生命周期中发出的领域事件、平台特定行为以及跨平台兼容性矩阵。本文面向需要超出 Inspector 所能提供的程序化控制的开发者。

ConvaiVisionPublisher 脚本 API

成员

签名

说明

IsPublishing

bool IsPublishing { get; }

true 当视频轨道正在发布到房间时。

FrameSource

IVisionFrameSource FrameSource { get; }

当前活动的帧源。 null 在 WebGL 上。

PublishPolicy

VisionPublishPolicy PublishPolicy { get; }

当前发布策略。

VideoTrackName

string VideoTrackName { get; }

正在使用的 WebRTC 视频轨道名称。

SetPublishPolicy

void SetPublishPolicy(VisionPublishPolicy policy)

更改发布策略。如果发布处于活动状态，轨道会立即以新配置文件重启。

EnablePublishing

void EnablePublishing(bool enabled)

在不更改策略的情况下开始或停止发布。当策略为 Manual；适用于所有策略。

条件策略选择示例

using Convai.Modules.Vision;
using Convai.Runtime.Vision.Publishing;

ConvaiVisionPublisher publisher = GetComponent<ConvaiVisionPublisher>();

bool isHighBandwidthNetwork = /* 你的网络质量检查 */;
VisionPublishPolicy chosen = isHighBandwidthNetwork
    ? VisionPublishPolicy.HighResponsiveness
    : VisionPublishPolicy.LowOverhead;

publisher.SetPublishPolicy(chosen);

实现自定义帧源

如果没有任何内置源适合你的用例——例如，你想发布由自定义后处理管线生成的渲染纹理，或者从第三方 SDK 进行流式传输——请实现 IVisionFrameSource.

接口约定

namespace Convai.Runtime.Vision.Sources
{
    public interface IVisionFrameSource
    {
        bool IsCapturing { get; }
        long FrameCount { get; }
        (int Width, int Height) FrameDimensions { get; }
        float TargetFrameRate { get; }
        string SourceId { get; }

        // 必须是 Y 翻转（自上而下）的 RenderTexture
        RenderTexture CurrentRenderTexture { get; }

        bool IsFrameReady { get; }
        event Action FrameReady;

        void StartCapture();
        void StopCapture();
    }
}

Y 翻转要求

CurrentRenderTexture 必须是 自上而下 （相对于 Unity 默认自下而上的约定进行了 Y 翻转）。未能翻转纹理会在后端产生上下颠倒的视频流。请使用 Graphics.Blit 配合翻转后的缩放向量：

// 将源翻转到 outputTexture 中（自上而下方向）
Graphics.Blit(sourceTexture, outputTexture, new Vector2(1f, -1f), new Vector2(0f, 1f));

最小自定义实现

using System;
using UnityEngine;
using Convai.Runtime.Vision.Sources;

public class MyCustomFrameSource : MonoBehaviour, IVisionFrameSource
{
    [SerializeField] RenderTexture _sourceTexture;

    RenderTexture _outputTexture;
    bool _isCapturing;
    long _frameCount;

    public bool IsCapturing => _isCapturing;
    public long FrameCount => _frameCount;
    public (int Width, int Height) FrameDimensions =>
        _outputTexture != null ? (_outputTexture.width, _outputTexture.height) : (0, 0);
    public float TargetFrameRate => 15f;
    public string SourceId => "custom";
    public RenderTexture CurrentRenderTexture => _outputTexture;
    public bool IsFrameReady => _outputTexture != null && _frameCount > 0;

    public event Action FrameReady;

    public void StartCapture()
    {
        _outputTexture = new RenderTexture(
            _sourceTexture.width, _sourceTexture.height, 24, RenderTextureFormat.ARGB32);
        _isCapturing = true;
    }

    public void StopCapture()
    {
        _isCapturing = false;
        if (_outputTexture != null) { _outputTexture.Release(); _outputTexture = null; }
    }

    void Update()
    {
        if (!_isCapturing || _sourceTexture == null || _outputTexture == null) return;

        // 将源纹理进行 Y 翻转并写入输出
        Graphics.Blit(_sourceTexture, _outputTexture, new Vector2(1f, -1f), new Vector2(0f, 1f));
        _frameCount++;
        FrameReady?.Invoke();
    }
}

可选：IVisionFrameSourceStatusProvider

为了公开详细的状态信息（由 VisionDebugPreview 以及协调器的健康检查使用），还要实现 IVisionFrameSourceStatusProvider:

using Convai.Runtime.Vision.Sources;

public class MyCustomFrameSource : MonoBehaviour, IVisionFrameSource, IVisionFrameSourceStatusProvider
{
    public VisionSourceState State { get; private set; } = VisionSourceState.Idle;
    public VisionSourceErrorKind ErrorKind { get; private set; } = VisionSourceErrorKind.None;
    public string StatusMessage { get; private set; }
    public bool HasUsableFrame { get; private set; }
    public event Action StatusChanged;

    // ...
}

将你的自定义组件赋给 ConvaiVisionPublisher的 帧源组件 字段。发布器接受任何 MonoBehaviour ，实现了 IVisionFrameSource.

领域事件

Vision 通过 SDK 的 IEventHub发布所有重要状态变化。可从任何持有 IEventHub 引用的组件订阅这些事件，或通过 ConvaiManager 的事件基础设施订阅。

事件参考

事件类型

命名空间

关键字段

VisionCaptureStarted