media-analyzer

media-analyzer 架构与逻辑

本文档整理当前项目的模块边界、统一数据模型和主要解析流程，方便后续继续扩展容器、编码格式和浏览器侧分析能力。

项目定位

media-analyzer 是一个纯前端可用的媒体解析与浏览器侧分析工具集合。项目不依赖 npm 构建，源码以原生 ESM 组织，示例页通过静态服务直接加载 lib/ 下的模块。

核心目标是把不同输入格式解析成同一个分析结果形态：

{
  format: {},          // 容器级信息：格式名、时长、码率、文件大小等
  streams: [],         // 流级信息：音频/视频/字幕轨，codec、分辨率、采样率等
  frames: [],          // 帧/样本/PES/tag 级时间线
  formatSpecific: {}   // 容器专有数据、原始 fileData、PAT/PMT、box tree、fieldOffsets 等
}

浏览器 UI、十六进制视图、帧详情、解码播放都围绕这个统一模型工作。

目录边界

主流程

flowchart TD
    A["Uint8Array bytes"] --> B["detectContainerFormat"]
    B --> C{"format"}
    C -->|flv| D["parseFlvFileForAnalysis"]
    C -->|mpeg-ts| E["parseMpegTsForAnalysis"]
    C -->|ps| F["parseMpegPsForAnalysis"]
    C -->|mp4| G["parseIsoBmffForAnalysis"]
    C -->|wav/mp3/flac/opus| H["parseMinimalAudioByFormat"]
    C -->|unknown| I["empty unsupported result"]
    D --> J["buildMediaOverview"]
    E --> J
    F --> J
    G --> J
    H --> J
    I --> J
    J --> K["统一分析结果"]
    K --> L["examples / browser models"]

统一入口是 lib/codec/analyzeByDetectedFormat.js：

  1. 用文件头特征识别容器：FLV、MPEG-TS、PS、MP4、WAV、FLAC、Ogg Opus、MP3。
  2. 分发到对应 parser，得到统一结果。
  3. 追加 formatSpecific.mediaOverview，给总览页面直接消费。
  4. 保留 formatSpecific.fileData，给 frame slicing、hex view、播放解码继续使用。

统一数据契约

format

容器级摘要，常见字段有：

streams[]

流级摘要，常见字段有：

frames[]

时间线项，按容器映射为 frame/sample/tag/PES：

浏览器播放依赖 offset、size、formatSpecific.fileData 或 _assembledESData 取出真实帧数据。

formatSpecific

容器和 UI 辅助数据的挂载点：

各格式解析逻辑

FLV

FLV 的核心链路是：

parseFlvFileForAnalysis
  -> parseFlvFileHeader
  -> parseFlvTagAt
  -> parseFlvAudioTagBody / parseFlvVideoTagBody / parseFlvScriptTagBody
  -> buildFlvMetadataSummary
  -> buildFlvAnalysisResult

关键点：

MPEG-TS

TS 的核心链路是：

detectMpegTsPacketSize / iterateTsTransportPackets
  -> parseMpegTsPatAndPmts
  -> pushTsPacketToPesAssembler
  -> TsFrameAssembler
  -> mergeFrameUnits
  -> buildMpegTsAnalysisResult

关键点：

MPEG-PS

PS 的核心链路是：

findNextPsStartCode
  -> parsePsPacketAt
  -> parsePesPacket
  -> buildMpegPsAnalysisResult

关键点：

MP4 / fMP4

MP4 的核心链路是：

MP4Parser.parse
  -> parseBox / parseChildren / parseSTSD / parseBoxData
  -> parseIsoBmffForAnalysis

关键点：

纯音频

audioMinimalAnalysis.js 提供 WAV、FLAC、MP3、Ogg Opus 的轻量 header 级分析，返回音频流信息；目前不生成逐音频帧时间线。

浏览器侧逻辑

flowchart LR
    A["analysis result"] --> B["multiFormatFrameAdapter"]
    B --> C["frame list / filter / sort"]
    C --> D["frameInspectorModel"]
    C --> E["hexDataViewModel"]
    C --> F["frameReferenceModel"]
    C --> G["framePlayback"]
    G --> H["videoDecodeOrchestrator"]
    H --> I["WebCodecs"]
    H --> J["tinyh264 worker fallback"]
    G --> K["WebAudio"]

示例页数据流

media-overview-demo.html

file / http(s) / ws
  -> Uint8Array
  -> analyzeByDetectedFormat(bytes, { fileMeta })
  -> result.formatSpecific.mediaOverview
  -> General / Video / Audio / Subtitle cards

frame-analysis-demo.html

file / http(s) / ws
  -> Uint8Array
  -> analyzeByDetectedFormat
  -> resultMap = { [formatName]: result }
  -> getFrames / getFilteredFrames
  -> frame table + selected detail + hex view + stats + decode/playback

扩展新格式的建议步骤

  1. 在对应目录实现纯数据 parser，输出统一 { format, streams, frames, formatSpecific }。
  2. 在 detectContainerFormat 增加格式探测。
  3. 在 analyzeByDetectedFormat 增加分发，并保证 formatSpecific.fileData 存在。
  4. 如需要帧列表展示，确认 frames[] 至少有 index、mediaType、pts/dts 或 ptsTime/dtsTime、offset、size。
  5. 如需要 inspector 高亮，解析时记录 fieldOffsets。
  6. 如需要播放/解码，补充 framePlayback 的 payload 提取、codec config 和浏览器 API 适配。
  7. 在示例页用真实样本验证 overview、frame list、hex view、decode/playback。

当前边界