实现原理 · videoparse

1. 为什么这样拆

全帧解码是 CPU / 内存密集操作。若全部放在主线程，页面滚动、按钮响应都会被卡住。因此本项目把 解封装 + 解码放进 Module Worker，主线程只做：

• 读取本地文件或 CORS 拉取远程 MP4，得到可结构化克隆的 Blob
• 用 <video> 展示预览与浏览器侧元数据
• 接收 Worker 消息：进度、容器信息、逐帧 bitmap、完成 / 错误
• 把 bitmap 画到 Canvas 再导出 PNG 缩略图，并维护帧数与耗时

2. 总体架构

一次解析任务对应一个独立的 Module Worker 实例。停止或结束时主线程会 postMessage({ type: "cancel" }) 并 terminate()，避免残留解码占用内存。

flowchart LR
    subgraph Main["主线程 · index.html"]
        UI["控件 / 状态 / 耗时"]
        Preview["<video> 预览"]
        Frames["帧缩略图网格"]
        Queue["frameQueue 串行渲染"]
    end

    subgraph Worker["Module Worker · worker.js"]
        Feed["分片喂入 Blob"]
        MP4["mp4box 解封装"]
        Pump["pendingSamples 队列"]
        VD["VideoDecoder"]
        BM["createImageBitmap"]
    end

    CDN["mp4box@2.3.0 CDN ESM"] --> Worker
    UI -->|start + Blob| Feed
    Feed --> MP4
    MP4 -->|Encoded samples| Pump
    Pump --> VD
    VD -->|VideoFrame| BM
    BM -->|frame + Transferable| Queue
    Queue --> Frames
    MP4 -->|mp4-metadata / progress| UI
    VD -.->|done / error| UI
                    

3. 端到端时序

从点击「解析全部帧」到展示缩略图，大致经过以下阶段：

sequenceDiagram
    actor User as 用户
    participant Main as 主线程
    participant W as worker.js
    participant M as mp4box
    participant D as VideoDecoder

    User->>Main: 选择文件 / URL 并开始
    Main->>Main: loadSource → Blob
loadPreviewMetadata
    Main->>W: start + Blob
    W->>M: 按 2MB 分片 appendBuffer
    M-->>W: onReady(info)
    W->>D: configure(codec, description…)
    W-->>Main: mp4-metadata
    M-->>W: onSamples(samples)
    loop 背压泵送
        W->>D: decode(EncodedVideoChunk)
        D-->>W: output(VideoFrame)
        W->>W: createImageBitmap
        W-->>Main: frame + ImageBitmap
        Main->>Main: Canvas → PNG → DOM
    end
    W->>D: flush
    W-->>Main: done
                    

4. Worker 内部流水线

4.1 分片喂入容器

Worker 不会一次性把整个文件读进 ArrayBuffer。它按 CHUNK_SIZE = 2MB 对 Blob 切片，每次 arrayBuffer() 后写入 buffer.fileStart = offset，再交给 mp4File.appendBuffer。 偏移必须正确，mp4box 才能把离散块拼回完整 ISO BMFF 结构。

4.2 选轨与配置解码器

onReady 时在 info.tracks 中找第一条带 video 的轨道，提取 codec / 宽高，并从 sample entry 写出 AVC/HVC 等初始化数据作为 WebCodecs 的 description，然后 VideoDecoder.configure。

4.3 样本提取与解码背压

mp4box 按批（EXTRACTION_BATCH_SIZE = 24）回调 onSamples，样本先进入 pendingSamples。 pumpDecodeQueue 仅在 decodeQueueSize < 8 时继续 decode，避免把编码器队列撑爆。解码输出后先 createImageBitmap(frame)，再以 Transferable 发出 frame 消息，并立刻 frame.close()。

flowchart TB
    Blob["source Blob"] --> Slice["slice(offset, offset+2MB)"]
    Slice --> Append["appendBuffer + fileStart"]
    Append --> Ready{"onReady?"}
    Ready -->|是| Track["选视频轨 + description"]
    Track --> Config["VideoDecoder.configure"]
    Ready --> Samples["onSamples → pendingSamples"]
    Config --> Pump["pumpDecodeQueue"]
    Samples --> Pump
    Pump --> Chunk["EncodedVideoChunk
key / delta"]
    Chunk --> Decode["videoDecoder.decode"]
    Decode --> VF["VideoFrame"]
    VF --> IBM["ImageBitmap"]
    IBM --> Post["postMessage frame
transfer bitmap"]
                    

4.4 moov 在文件尾部时的二次喂入

不少 MP4 把 moov 放在文件末尾。首轮从偏移 0 读完并 flush 后，可能已经 onReady，但还没有真正抽出媒体样本。 此时用 mp4File.seek(0, true) 得到建议的媒体数据起始偏移，再从该偏移 feedBlob 一次，才能继续 onSamples。

5. 主线程与消息协议

双方通过结构化消息通信，方向与语义如下：

5.1 帧展示保序

Worker 可能较快连续投递多帧。主线程用 frameQueue = frameQueue.then(() => appendFrame(...)) 把 PNG 编码与 DOM 插入串起来，保证缩略图按到达顺序稳定追加，并在 done / error 前 await frameQueue，避免「状态已完成但图还没画完」。

5.2 任务世代号

activeRunId 在每次开始或停止时递增。过期任务的回调若仍带着旧 runId，会丢弃消息并 close() 残留 bitmap，防止旧 Worker 污染新一轮结果。

5.3 基本信息里的帧率怎么算

页面「帧率」不是浏览器 <video> 直接给出的，也不是逐帧测速得到的。 Worker 解析出视频轨后，通过 mp4-metadata 把 selectedVideoTrack 传回主线程；主线程的 getTrackFrameRate(track) 用 mp4box 轨道字段做平均帧率估算。

用到的三个字段：

换算关系：

• 真实时长（秒）= duration / timescale
• 平均帧率（fps）= nb_samples / 真实时长 = (nb_samples × timescale) / duration

flowchart LR
    Meta["mp4-metadata
selectedVideoTrack"] --> Fields["nb_samples
duration
timescale"]
    Fields --> Check{"三者均有限
且 > 0？"}
    Check -->|否| Unknown["显示「未知」"]
    Check -->|是| Formula["fps = nb_samples × timescale / duration"]
    Formula --> Display["toFixed(3) +「fps（平均）」"]
                    

6. 关键设计点小结

mindmap
  root((videoparse))
    隔离
      Module Worker
      主线程只渲染
    吞吐
      2MB 分片喂入
      decodeQueue 背压
      批提取 samples
    零拷贝倾向
      ImageBitmap Transferable
      及时 close VideoFrame
    容器兼容
      moov 尾部二次 feed
      fileStart 偏移
    UI 正确性
      frameQueue 保序
      activeRunId 防串扰
                    

1. 解耦：重计算在 Worker，UI 保持可响应。
2. 背压：限制 WebCodecs 队列深度，样本与解码速度匹配。
3. 转移所有权：bitmap 用 Transferable 传到主线程，减少像素拷贝。
4. 容器边角：显式处理「moov 在尾部」导致的首轮无样本问题。
5. 可取消：cancel + terminate + runId，保证停止后无幽灵更新。

7. 文件职责

8. MP4Box 解析结果字段说明

主线程元数据面板展示的是一次解析任务汇总后的结构： source、browserMetadata、以及 Worker 回传的 mp4box（内含 mp4boxInfo、selectedVideoTrack、 decoderConfig）。下面以一份真实样例数值说明常见字段含义。

8.1 顶层结构

8.2 mp4boxInfo · 文件级信息

8.3 tracks · 轨道信息

视频轨道（track id: 1）

音频轨道（track id: 2）

8.4 关键差异对比

8.5 nb_samples 字段总结