以下是基于 PyAV Side Data 模块整理的视频元数据 (SideData) 核心速查手册。该文档聚焦于 av.sidedata 在视频处理中的 HDR 信息提取、运动向量分析及显示矩阵解析，是进行高质量视频转码、渲染和智能分析的关键。
1. 核心概念：什么是 SideData？
SideData 是附加在 Frame（偶尔也在 Packet）上的非像素元数据。它不直接参与画面渲染，但携带了正确显示、后处理或分析视频所必需的上下文信息。
💡 黄金法则：HDR 渲染必看 MASTERING_DISPLAY + CONTENT_LIGHT_LEVEL；自动旋转必看 DISPLAYMATRIX；AI 分析可挖 MOTION_VECTORS。
2. 视频关键 SideData 类型速查
🎨 HDR 相关（最重要）
for sd in frame.side_data:
if sd.type == av.sidedata.Type.MASTERING_DISPLAY_METADATA:
print(f"Max Luminance: {sd.max_luminance}")
print(f"Min Luminance: {sd.min_luminance}")
print(f"Primaries: {sd.primaries}")
elif sd.type == av.sidedata.Type.CONTENT_LIGHT_LEVEL:
print(f"MaxCLL: {sd.MaxCLL}, MaxFALL: {sd.MaxFALL}")
📐 几何与显示
🤖 分析与编码辅助
3. MotionVectors 详解
MotionVectors 是唯一具有结构化高级 API 的 SideData 类型，继承自 Sequence，可直接迭代：
for sd in frame.side_data:
if sd.type == av.sidedata.Type.MOTION_VECTORS:
mvs = sd # MotionVectors instance
for mv in mvs:
print(f"src={mv.src}, dst={mv.dst}, "
f"motion_x={mv.motion_x}, motion_y={mv.motion_y}, "
f"flags={mv.flags}")
💡 应用场景：视频稳像、插帧质量评估、编码效率分析、基于运动的显著性检测。需在解码时启用
export_side_data='motion_vectors'。
4. 安全访问模式
防御性遍历
# ✅ 推荐：按类型过滤，避免索引越界
for sd in frame.side_data:
match sd.type:
case av.sidedata.Type.MASTERING_DISPLAY_METADATA:
process_hdr_mastering(sd)
case av.sidedata.Type.DISPLAYMATRIX:
apply_rotation(sd)
case _:
pass # 忽略未知类型，向前兼容
⚠️ 注意事项
5. 常见工作流示例
HDR → SDR Tone Mapping 前置检查
has_hdr = False
max_cll = 0
for sd in frame.side_data:
if sd.type == av.sidedata.Type.MASTERING_DISPLAY_METADATA:
has_hdr = True
if sd.type == av.sidedata.Type.CONTENT_LIGHT_LEVEL:
max_cll = sd.MaxCLL
if has_hdr and max_cll > 1000:
tonemap_filter = graph.add('tonemap', 'tonemap=hable:desat=0')
自动旋转校正
import numpy as np
for sd in frame.side_data:
if sd.type == av.sidedata.Type.DISPLAYMATRIX:
matrix = np.frombuffer(sd.to_memoryview(), dtype=np.int32).reshape(3, 3)
rotation = extract_rotation(matrix) # 0/90/180/270
if rotation != 0:
graph.add('transpose', f'{rotation // 90}')
break
6. 开发排查备忘
💡 核心记忆点
HDR 双件套：MASTERING_DISPLAY_METADATA + CONTENT_LIGHT_LEVEL 缺一不可
旋转靠矩阵：DISPLAYMATRIX 是移动端视频正确显示的唯一依据
MV 要导出：MotionVectors 默认关闭，需显式启用 export_side_data
遍历优于索引：SideData 数量和顺序不固定，永远用 for + type 匹配
缓存首帧元数据：HDR/ICC 等信息通常只出现一次，不要逐帧重复查找