PyAV 视频处理核心模块速查手册

1. Bitstream Filters（视频比特流过滤器）

在不解码、不重编码的前提下，直接修改已压缩的视频 Packet 数据。封装自 FFmpeg AVBSFContext，是视频转封装（Remuxing）和流媒体推送的核心组件。

成员	说明
`BitStreamFilterContext(in_stream, out_stream)`	初始化过滤器，`out_stream` 的编解码参数会被自动覆盖
`filter(packet=None) -> list[Packet]`	处理单个 Packet，返回值始终是列表（1进N出）
`flush()`	重置内部状态，排空缓冲

av.buffer.Buffer 是所有支持 Python Buffer Protocol 对象的基类（如视频 Packet、Plane），提供 C 内存与 Python 数据世界之间的零拷贝桥梁。

成员	类型	说明
`buffer_ptr`	`int`	底层 C 内存指针地址
`buffer_size`	`int`	缓冲区字节大小
`update(input)`	method	零拷贝替换数据，接受 bytes / NumPy / memoryview / 其他 Buffer

GPU 加速管线：通过 buffer_ptr 将视频帧内存直接传给 CUDA / TensorRT / OpenCL，避免 CPU-GPU 数据中转。
NumPy 零拷贝交换：解码后的视频 Plane 直接转为 NumPy 数组供 AI 推理，或反向写入编码帧。
自定义 Packet 处理：在 Packet 级别做加密、混淆、水印注入等原位操作，比解包再打包快一个数量级。
内存池复用：流式处理中通过 update() 原地替换数据，减少 GC 压力。

问题现象	可能原因	解决方案
转封装后播放器花屏/无法识别	BSF 未正确应用或 out_stream 参数未更新	确认 `add_stream(template=out_stream)`；检查 BSF 是否匹配输入编码
Seek 后画面错乱/断流	跳转后未重置过滤器状态	Seek 后立即调用 `bsf.flush()`
GPU 推理结果全黑/错位	buffer_ptr 指向的内存已被释放或尺寸不匹配	确保 Frame/Packet 存活；校验 `buffer_size` 与模型输入一致
视频 Packet 处理后数量不对	遗漏 EOF 排空或误用索引取值	遍历 `filter()` 返回的列表；流结束传 `None` + `flush()`
NumPy 转 Frame 后编码失败	内存布局或尺寸不符合编码器要求	检查 Plane 对齐、stride；确认 format 为编码器支持的格式
自定义 Packet 修改无效	目标 Buffer 为只读	创建新 `av.Packet()` 并用 `update()` 写入修改后的数据

💡 核心原则：视频处理优先使用 BSF 做无损变换，用 Buffer Protocol 做零拷贝数据交换，两者结合可构建接近原生 C 性能的高吞吐视频管线。所有涉及 Packet/Frame 的操作，始终假设返回值为列表并完整遍历。