MiguDelay 架构 13：长延时文件链与 DelayFileReader

MiguDelay（DDLive）项目架构系列文档：长延时文件链与 DelayFileReader。内容基于 2026-08-04 对指定重构分支的源码扫描结果整理。

发表于 2026/08/05

作者 李正博

3 分钟阅读

系列导航：系列总览 · 上一篇：MiguDelay 架构 12：Output 实时延时与时钟 · 下一篇：MiguDelay 架构 14：录制、编码与原始复用

扫描基线

项目：MiguDelay（DDLive）

分支：refactor/video-frame-provider

HEAD：d28ec061406e4e3df93e3d1a92478d71a9ad4908

工作树：clean

扫描日期：2026-08-04

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

1. 目的

长延时时，系统将收录文件作为中间介质。DelayFileReader 读取视频数据、索引和音频文件，解码视频后送入 OutputWithLocalFileReader。

2. 核心类

类	职责
`DelayFileReader`	跨分片读取视频索引、视频数据和音频数据
`FileReader`	底层文件读
`MultiThreadIFrameDecoderSync`	编码视频帧同步解码
`OutputWithLocalFileReader`	InDelay/Delay 队列、音频 buffer、本地 tick
legacy reconfiguration session	运行中替换 reader 与输出链

3. Reader 初始化

DelayFileReaderInfo 包含视频文件、代理/索引文件、音频文件、decoder thread count 和 delay seconds。

sequenceDiagram
    participant B as Start or Reconfiguration Binding
    participant R as DelayFileReader
    participant F as FileReader
    participant D as MultiThread Decoder
    participant O as OutputWithLocalFileReader

    B->>R: initReader paths and delay
    R->>F: open video index and audio files
    R->>D: initialize decoder
    R->>O: set delayed video queue
    B->>R: startReader
    R->>R: readFileThreadFunc
    R->>D: submit encoded video
    D-->>R: decoded frame
    R-->>O: enqueue video and audio

4. 跨文件读取

Reader 维护 current file/proxy/audio path、suffix index、视频/音频位置和 packet/fragment 计数。handleCrossFile() 切换分片，视频根据索引定位 packet，音频按对应位置读取。

5. 读速监控

最近五秒 bucket 记录视频读取帧数，并依据期望帧率计算低速阈值。该机制用于诊断和恢复，不直接改任务 phase。

6. File Output

flowchart LR
    REC["Record files"] --> R["DelayFileReader"]
    R --> ID["InDelay queues"]
    R --> DD["Delayed queues"]
    ID --> O["OutputWithLocalFileReader tick"]
    DD --> O
    AUX["IAuxFrameSource"] --> O
    MODE["IOutputModeSource"] --> O
    O --> PRE["Preview callbacks"]
    O --> ENC["Push encoders"]

OutputWithLocalFileReader 有独立本地 tick、InDelay/Delayed 视频队列、音频 buffer、同步 YUV converter 和 cache readiness。AuxVideoOnly 模式下视频缓存缺口会生成静音音频切片，维持时钟连续。

7. 长延时重配置

新 reader 使用当前 record-version 路径初始化。
新链初始化成功后才释放旧 reader。
失败保留旧链。
operation generation 写入 Output pending generation。
只有新版本 delayed video 到达后才允许返回 Delay。

8. 关闭

停止 read thread、decoder 和 FileReader，detach Output queue/buffer，最后 OutputWithLocalFileReader::uninit() 停止 tick 与 converter。

9. 源码证据

src/code/module/filereader/delayfilereader/DelayFileReader.*
src/code/module/filereader/FileReader.*
src/code/module/output/OutputWithLocalFileReader.*
src/code/module/decoder/video/ffmpeg/MultiThreadIFrameDecoderSync.*