MediaSource API 不处理视频元数据，需预先确保初始化段（如 fMP4 的 moov box）完整有效；元数据缺失会导致黑屏、静音或 MEDIA_ERR_DECODE 错误，应通过校验 init segment、使用 hls.js 或 mp4box.js 封装等手段补全，并避免重复 append 或非法状态操作。
MediaSource API 本身不直接处理视频元数据（如时长、宽高、编码参数等），它只负责将二进制媒体片段（如 MP4 片段、ISO BMFF、WebM 或 MPEG-TS）追加到 SourceBuffer 中供播放器解码渲染。当元数据丢失（例如首帧缺失 moov box、fMP4 初始化段未加载、或 WebM 的 Header 块缺失），<video> 将无法初始化解码器，表现为静音、黑屏、readyState === 0、或抛出 MEDIA_ERR_DECODE 错误。
确认元数据是否缺失的关键信号
在调用 mediaSource.addSourceBuffer() 后，需主动验证初始化段（init segment）是否已正确写入：
- 监听
sourceBuffer.updating变为false后，检查sourceBuffer.buffered.length === 0—— 若为真，大概率 init segment 无效或缺失 - 调用
video.duration返回NaN或Infinity，且video.readyState < 1，说明时间轴未建立 - 控制台出现
Failed to execute 'appendBuffer' on 'SourceBuffer': The HTMLMediaElement's readyState is not HAVE_METADATA类错误
补全元数据的可行路径
MediaSource 不提供“读取/修复/注入元数据”的能力，必须在 JS 层预先获取并构造合法媒体片段：
anything-to-html
下载
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
- 对 fMP4 流：确保 fetch 到的第一个响应是完整的 init segment（含
moov），不能截断；可用mp4box.js解析并校验moov是否存在且结构完整 - 对 HLS/m3u8 场景：使用
hls.js等成熟库，它会自动解析#EXT-X-MAP指向的 init segment 并注入 MediaSource，避免手动拼接出错 - 若只有无头 video 数据（如裸 H.264 Annex-B NALU 流）：必须用 WASM 工具（如
mp4box.js或自研 muxer）封装成带moov的 fMP4 片段再 append，不可直传原始帧
降级与容错策略
当检测到元数据异常时，不应仅重试 append，而应分层干预：
立即学习“前端免费学习笔记（深入）”；
- 立即暂停
sourceBuffer.updating，调用sourceBuffer.abort()清理失败状态 - 对 init segment 发起独立 fetch，并用
response.arrayBuffer()+new Uint8Array()检查前 12 字节是否为moovbox 签名（0x6D6F6F76） - 若服务端支持，改用
<video src="xxx.mp4">直链方式加载——浏览器原生逻辑会自动解析并缓存元数据，比 MediaSource 更鲁棒 - 记录错误类型（如
NO_INIT_SEGMENT）、URL、UA，用于后端定位 CDN 缓存或转码服务缺陷
避免常见陷阱
很多“元数据丢失”实际源于开发误用，而非媒体本身问题：
- 不要对同一
SourceBuffer多次appendBuffer(initSegment)—— 会导致解析冲突，只应在addSourceBuffer()后 append 一次 init，再 append media segments - 不要在
mediaSource.readyState !== 'open'时调用addSourceBuffer()，否则创建的 SourceBuffer 不可用 - 禁止用
URL.createObjectURL(new Blob([arrayBuffer]))生成 blob URL 替代 MediaSource —— 此方式无法动态注入缺失元数据，且无法做流式控制
