MiguDelay 架构 18：Preview、九路 Surface 与首帧

系列导航：系列总览 · 上一篇：MiguDelay 架构 17：Aux 播单、Reader 与帧源 · 下一篇：MiguDelay 架构 19：监看音频

扫描基线

• 项目：MiguDelay（DDLive）
• 分支：refactor/video-frame-provider
• HEAD：d28ec061406e4e3df93e3d1a92478d71a9ad4908
• 工作树：clean
• 扫描日期：2026-08-04
• 说明：内容以当前 HEAD 源码为准；仓库旧架构文档只作为检索线索。

1. 九路 channel

Channel	画面
Input	主输入
InDelay	入延时
Delay	主延时输出
Aux	垫片预览
Program	最终节目
BackupInput	备输入
BackupOutput	备输出
AuxInput	Aux 页面输入
AuxOutput	Aux 页面输出

2. 核心对象

对象	责任
PreviewSurfaceRegistry	channel → QPointer<YuvVideoItem>
adaptPreviewFrame()	raw std::any → typed event
PreviewFrameRouter	generation 校验和按 source/mode 路由
FrameAvailabilityTracker	readiness、input index、Delay return gate
FirstFrameTrigger	每 task generation 一次首帧
YuvVideoItem	Qt Quick 渲染终点

3. Surface 生命周期

sequenceDiagram
    participant Q as QML Page
    participant B as PreviewSurfaceBinding
    participant R as PreviewSurfaceRegistry
    participant I as YuvVideoItem

    Q->>B: set registry channel item
    B->>R: attach
    R->>R: replace QPointer and destroyed token
    I-->>R: destroyed
    R->>R: clear only when token matches
    Q->>B: destroy binding
    B->>R: matching detach

旧 Item 晚析构不会清除替换后的新 Item。

4. raw frame 适配

激活 receive 时冻结 task generation、frame source 和 media kind。适配结果包含 generation、source、Video/Audio/AudioLevel/Reset、typed payload 和可选 DelayConfigurationGeneration。

5. 路由

• CurrentInput → Input、AuxInput，并更新 input readiness。
• DelayedOutput → Delay；按 mode 可能进入 Program、AuxOutput；首个视频触发 push。
• InDelay → InDelay。
• Aux → Aux；Aux mode 下进入 Program、AuxOutput；视频更新 Aux Service progress。
• Backup → 各自 backup channel。

sequenceDiagram
    participant M as Media Callback
    participant A as Preview Adapter
    participant R as PreviewFrameRouter
    participant T as Frame Tracker
    participant G as Surface Registry
    participant I as YuvVideoItem

    M->>A: raw frame and frozen metadata
    A-->>R: PreviewFrameEvent
    R->>R: queue to owner thread and verify
    R->>T: update readiness first
    R->>G: publish selected channels
    G->>I: dispatch frame

Tracker 在 Item delivery 前更新，页面不存在也不影响 capability。

6. 首帧

sequenceDiagram
    participant O as Delayed Output
    participant R as PreviewFrameRouter
    participant F as FirstFrameTrigger
    participant T as TaskOrchestrator

    O-->>R: current generation video
    R->>F: consume generation
    alt first delayed video
        F-->>T: firstOutputFrame
    else stale duplicate audio or other source
        F->>F: ignore
    end

7. Delay return gate

必须同时匹配 current task generation、armed delay operation generation、source=DelayedOutput、kind=Video，才设置 allowDelayReturn=true。

8. 其他消费者

MonitorAudio 观察 Surface attach/detach；ShieldSnapshot 从 Delay Surface grabToImage；Aux prewarm frame 更新 Aux Surface。

9. 源码证据

• src/code/module/playback/preview/*
• src/code/controls/yuvvideoitem.*
• src/qml/components/PreviewSurfaceBinding.qml
• tests/preview_domain/*

---

系列导航：系列总览 · 上一篇：MiguDelay 架构 17：Aux 播单、Reader 与帧源 · 下一篇：MiguDelay 架构 19：监看音频