MiguDelay 架构 19：监看音频

MiguDelay（DDLive）项目架构系列文档：监看音频。内容基于 2026-08-04 对指定重构分支的源码扫描结果整理。

发表于 2026/08/05

作者 李正博

2 分钟阅读

系列导航：系列总览 · 上一篇：MiguDelay 架构 18：Preview、九路 Surface 与首帧 · 下一篇：MiguDelay 架构 20：运行中流重配置

扫描基线

项目：MiguDelay（DDLive）

分支：refactor/video-frame-provider

HEAD：d28ec061406e4e3df93e3d1a92478d71a9ad4908

工作树：clean

扫描日期：2026-08-04

说明：内容以当前 HEAD 源码为准；仓库旧架构文档只作为检索线索。

1. 问题模型

用户控制、Surface 中的 PcmPlayer2 attachment 和任务音频 format 可能乱序到达。MonitorAudioService 汇合三者；只有 Player 与 format 都具备才异步初始化，但控制值始终保留。

2. 核心类

类	职责
`MonitorAudioService`	控制、attachment、format、readiness 真值
`LegacyMonitorAudioBinding`	观察 Preview Registry，转发 format/frame
`PcmPlayerAdapter`	适配 `PcmPlayer2`
`MonitorAudioViewModel`	QML read-only state/control
`PcmPlayer2`	PCM 设备与播放线程

3. 七路 Surface

MainInput、Delay、InDelay、Aux、Program、BackupInput、BackupOutput。主流 format 配置前五路，两个备路只配置各自 Surface。

4. 状态机

stateDiagram-v2
    [*] --> WaitingPlayer
    WaitingPlayer --> WaitingFormat: playerAttached
    WaitingPlayer --> Initializing: playerAndFormat
    WaitingFormat --> Initializing: formatArrived
    Initializing --> Ready: currentInitSuccess
    Initializing --> Failed: currentInitFailure
    Ready --> Initializing: replacement
    Failed --> Initializing: newPlayerOrFormat
    Ready --> WaitingPlayer: playerDetached

5. 三重 generation

init completion 必须匹配 task generation、attachment generation 和 configuration generation。页面重建、任务替换或 format 变化都会让旧 completion stale。

6. 控制链

sequenceDiagram
    participant Q as QML
    participant V as Monitor ViewModel
    participant S as MonitorAudioService
    participant A as PcmPlayerAdapter

    Q->>V: set mute tracks or volume
    V->>S: typed control
    S->>S: update authoritative control state
    alt player attached
        S->>A: apply latest controls
    else player unavailable
        S->>S: retain controls
    end
    S-->>V: state snapshot

默认 input/output muted、左右 track [0,1]、volume 50，volume clamp 0–100。

7. format 与帧调用

ReceiveReadySnapshot
  -> LegacyTaskStartBinding
  -> MonitorAudioService.configureStream
  -> async player initialization

Preview audio event
  -> LegacyMonitorAudioBinding
  -> current surface adapter
  -> PcmPlayerAdapter.playAudio
  -> PcmPlayer2
  -> AudioPlaybackThread or PulseAudio

Service 不保存 PCM 帧。

8. shutdown

关闭 Service gate、使 generations 失效、关闭 Adapter callback gate、停止 player、清 attachments/formats/readiness。Runtime 在清 Preview Registry 前先关闭 Monitor。

9. 源码证据

src/code/module/playback/monitoraudio/*
src/code/controls/audio/pcmplayer2.*
src/code/data/playback/monitoraudioviewmodel.*