自定义帧源

实现 IVisionFrameSource，将自定义视频管线发布到 Convai，包括 Y 翻转要求、生命周期状态模式和自动发现规则。

实现 IVisionFrameSource 要发布任何自定义视频管线——视频文件、自定义渲染纹理或屏幕捕获工具——而无需修改发布层。一旦你的组件出现在场景中， ConvaiVisionPublisher 就会自动发现并开始流式传输。

接口契约

IVisionFrameSource 是通过以下方式进行视频流传输所需的最小契约 ConvaiVisionPublisher 以及通过以下方式进行实时画面显示 VisionDebugPreview.

public interface IVisionFrameSource
{
    bool IsCapturing { get; }
    long FrameCount { get; }
    (int Width, int Height) FrameDimensions { get; }
    float TargetFrameRate { get; }
    string SourceId { get; }
    RenderTexture CurrentRenderTexture { get; }
    bool IsFrameReady { get; }
    event Action FrameReady;
    void StartCapture();
    void StopCapture();
}

你的实现必须是一个 MonoBehaviour. ConvaiVisionPublisher 使用以下方式发现帧源 GetComponent 是位于 GetComponentsInChildren，而它们只能用于 Unity 组件。

Y 轴翻转要求

CurrentRenderTexture 必须为 自上而下的方向 (Y 轴相对于 Unity 默认的自下而上进行了翻转)。LiveKit 和标准视频格式都期望图像顶部的 Y=0。跳过这一步会导致接收端画面上下颠倒。

使用以下方式应用翻转： Graphics.Blit 调用，在将你的源纹理写入输出时 RenderTexture:

// sourceTexture：你的原始 Unity RenderTexture（自下而上）
// _outputRt：你通过 CurrentRenderTexture 暴露的 RenderTexture（自上而下）
Graphics.Blit(sourceTexture, _outputRt, new Vector2(1f, -1f), new Vector2(0f, 1f));

该 scale.y = -1 是位于 offset.y = 1 这两个参数合在一起会翻转垂直轴。将 _outputRt 到 CurrentRenderTexture.

最小实现

以下骨架实现了所有必需成员，并正确处理了 FrameReady 。请将 CaptureFrame 方法填入你的实际捕获逻辑。

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

public class MyCustomFrameSource : MonoBehaviour, IVisionFrameSource
{
    [SerializeField] private int _width = 1280;
    [SerializeField] private int _height = 720;
    [SerializeField] private float _targetFps = 15f;
    [SerializeField] private string _sourceId = "custom";

    private RenderTexture _outputRt;
    private long _frameCount;
    private float _captureInterval;
    private float _nextCaptureTime;

    // IVisionFrameSource

    public bool IsCapturing { get; private set; }
    public long FrameCount => _frameCount;
    public (int Width, int Height) FrameDimensions => IsCapturing ? (_width, _height) : (0, 0);
    public float TargetFrameRate => _targetFps;
    public string SourceId => _sourceId;
    public RenderTexture CurrentRenderTexture => _outputRt;
    public bool IsFrameReady => _frameCount > 0;
    public event Action FrameReady;

    public void StartCapture()
    {
        如果 IsCapturing，则直接返回；

        _outputRt = new RenderTexture(_width, _height, 24, RenderTextureFormat.ARGB32)
        {
            name = $"CustomFrameSource_{_sourceId}"
        };
        _outputRt.Create();

        _frameCount = 0;
        _captureInterval = _targetFps > 0f ? 1f / _targetFps : 1f / 15f;
        _nextCaptureTime = Time.realtimeSinceStartup;
        IsCapturing = true;
    }

    public void StopCapture()
    {
        如果未在捕获，则直接返回；

        IsCapturing = false;

        如果 _outputRt 不为空
        {
            _outputRt.Release();
            Destroy(_outputRt);
            _outputRt = null;
        }
    }

    private void Update()
    {
        如果未在捕获，则直接返回；

        float now = Time.realtimeSinceStartup;
        如果 now 小于 _nextCaptureTime，则直接返回；

        _nextCaptureTime = now + _captureInterval;
        CaptureFrame();
    }

    private void OnDestroy() => StopCapture();

    private void CaptureFrame()
    {
        // 用你的实际源纹理替换
        RenderTexture sourceTexture = GetYourSourceTexture();
        如果 sourceTexture 为空，则返回；

        // 将 Y 轴翻转写入输出 RenderTexture
        Graphics.Blit(sourceTexture, _outputRt, new Vector2(1f, -1f), new Vector2(0f, 1f));

        _frameCount++;
        FrameReady?.Invoke();
    }

    private RenderTexture GetYourSourceTexture()
    {
        // 返回你自定义管线中的 RenderTexture
        return null;
    }
}

FrameReady 必须在 Unity 主线程. ConvaiVisionPublisher 是位于 VisionDebugPreview 都假设所有 IVisionFrameSource 回调都在主线程执行。如果你的捕获逻辑运行在后台线程上，请使用在 中检查的标志将事件触发切回主线程， Update如上面的骨架所示。

公开生命周期状态

实现 IVisionFrameSourceStatusProvider 以及 IVisionFrameSource ，以公开更丰富的生命周期状态——权限流程、延迟初始化或结构化错误信息。这样发布器就可以在不轮询的情况下响应就绪状态的变化。

public class MyCustomFrameSource : MonoBehaviour, IVisionFrameSource, IVisionFrameSourceStatusProvider
{
    // --- IVisionFrameSourceStatusProvider ---

    public VisionSourceState State { get; private set; } = VisionSourceState.Idle;
    public VisionSourceErrorKind ErrorKind { get; private set; } = VisionSourceErrorKind.None;
    public string StatusMessage { get; private set; } = string.Empty;
    public bool HasUsableFrame => FrameCount > 0;
    public event Action StatusChanged;

    private void SetState(VisionSourceState state, VisionSourceErrorKind error = VisionSourceErrorKind.None, string message = "")
    {
        State = state;
        ErrorKind = error;
        StatusMessage = message;
        StatusChanged?.Invoke();
    }

    public void StartCapture()
    {
        SetState(VisionSourceState.Starting);
        // ... 初始化捕获 ...
        SetState(VisionSourceState.Ready);
    }

    public void StopCapture()
    {
        // ... 释放资源 ...
        SetState(VisionSourceState.Stopped);
    }

    // ... IVisionFrameSource 实现的其余部分
}

自动发现

一旦你的组件出现在场景中， ConvaiVisionPublisher 会按以下顺序自动发现它：

1. 该 来源 Inspector 中的字段（显式赋值）。
2. GetComponent<CameraVisionFrameSource>() 在同一个 GameObject 上（内置优先级）。
3. GetComponentsInChildren<MonoBehaviour>(true) ——首先是在 IVisionFrameSource 在同一个 GameObject 或子对象上找到的。

如果在步骤 3 中找到多个帧源，发布器会记录警告并选择第一个。显式分配 来源 字段以避免歧义。

下一步

Vision 调试预览Vision 脚本 API