MiguDelay 架构 17：Aux 播单、Reader 与帧源

系列导航：系列总览 · 上一篇：MiguDelay 架构 16：输出模式 · 下一篇：MiguDelay 架构 18：Preview、九路 Surface 与首帧

扫描基线

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

1. 边界

Aux 域管理普通/应急播单、Reader、预热、跳转、进度和跨线程帧缓冲。最终输出模式由 OutputModeService 决定。

2. Runtime 私有组件

对象	真值或职责
AuxPlaylistStore	normal/emergency 播单、选择与结构
AuxProgramReaderAdapter	legacy Reader 适配
AuxPlaybackService	Reader 生命周期、current program、progress、generation
AuxFrameSourceAdapter	low/high video 与 audio buffer 跨线程 Port
AuxPlaybackPresentationSource	聚合只读展示状态
AuxPlaybackViewModel	QML command/projection
LegacyAuxPlaybackBinding	日志、Preview、复制等副作用

flowchart TD
    VM["AuxPlaybackViewModel"] --> S["AuxPlaybackService"]
    S --> STORE["AuxPlaylistStore"]
    S --> R["AuxProgramReaderAdapter"]
    S --> F["AuxFrameSourceAdapter"]
    S --> P["PresentationSource"]
    P --> VM
    B["LegacyAuxPlaybackBinding"] --> S
    OUT["Output"] --> F
    ROUTER["PreviewFrameRouter"] --> S

3. Reader 初始化

完整缓冲组一次性发布：

• low video queue，容量 25。
• high video queue，容量 25。
• audio buffer，10 KiB。
• attach 到 AuxFrameSourceAdapter 后才启动 Reader。

禁止发布半初始化组合。

4. 预热

sequenceDiagram
    participant Q as QML
    participant V as Aux ViewModel
    participant S as AuxPlaybackService
    participant W as QtConcurrent Worker
    participant R as Reader Adapter
    participant B as Legacy Aux Binding
    participant P as Preview Registry

    Q->>V: prepareProgram index
    V->>S: typed command
    S->>S: advance request generation
    S->>W: schedule captured program
    W->>W: lock reader operation mutex
    W->>S: verify request still current
    W->>R: set playlist and seek
    R-->>W: optional first frame
    W-->>S: watcher finished
    S->>S: verify type program generation
    S-->>B: previewFrameReady
    B->>P: update Aux surface

两次 currentness 检查分别阻止旧排队操作改共享 Reader，以及旧 completion 覆盖新预览。

5. 播单与 jump

Store 支持 insert、reset、remove、move、status、playback mode 和 clear。jumpToProgram() 只在 Aux mode、Reader running 且 index 有效时接受。

QML 与 replication 使用同一 executor；origin 决定是否展示错误及是否再次复制。

6. 帧流

AuxProgramReader
  -> low/high/audio buffers
  -> AuxFrameSourceAdapter
  -> Output tick
  -> Aux preview/output callbacks
  -> PreviewFrameRouter
  -> AuxPlaybackService.handleVideoFrame
  -> current program and progress

7. 主备与关闭

备机 Bound 时可观察 progress，但不本地推进播单；失主后只对仍 Prepared 的 current program 补偿一次。

关闭顺序：stop Reader → 同一 mutex 下 detach frame source → uninitialize → clear queues/state → generation 前进并等待 watcher → shutdown Binding/Service。

8. 源码证据

• src/code/module/playback/aux/*
• src/code/module/playback/runtime/detail/auxplaybackcomponents.*
• src/code/data/playback/auxplaybackviewmodel.*
• src/qml/pages/aux/*

---

系列导航：系列总览 · 上一篇：MiguDelay 架构 16：输出模式 · 下一篇：MiguDelay 架构 18：Preview、九路 Surface 与首帧