以下是基于 PyAV Utilities 模块整理的日志与调试 (Logging & Debugging) 核心速查手册。该文档专为视频开发者设计，聚焦于解决“报错信息缺失”、“FFmpeg 噪声控制”及“多线程日志安全”三大痛点。
1. 核心痛点：为什么你的异常没有消息？
PyAV 默认关闭所有 FFmpeg 日志。这导致一个严重副作用：当 FFmpegError (即 AVError) 被抛出时，往往只包含错误码而缺少详细的上下文描述。
⚡ 快速启用开发日志
import av
import logging
# 1. 初始化 Python logging（否则日志无处输出）
logging.basicConfig(level=logging.DEBUG)
# 2. 设置 PyAV 日志级别为 VERBOSE
av.logging.set_level(av.logging.VERBOSE)
💡 关键记忆点：遇到不明原因的
FFmpegError，第一步永远是开启VERBOSE日志重跑，90% 的问题会直接暴露原因。
2. 日志系统架构与切换
PyAV 提供两套日志后端，可根据场景动态切换：
多线程安全方案
# ❌ 多线程下 Python logging hook 可能出问题
av.logging.set_level(av.logging.VERBOSE)
# ✅ 多线程工作流：恢复 FFmpeg 原生回调
av.logging.restore_default_callback()
av.logging.set_libav_level(av.logging.VERBOSE) # 用 libav 级别控制原生输出
⚠️ 注意：
restore_default_callback()后，set_level()不再生效，必须改用set_libav_level()控制终端输出级别。
3. 日志捕获与程序化分析
当需要在代码中检查特定错误而非依赖人工看日志时：
Capture 上下文管理器
from av.logging import Capture
# ✅ 仅捕获当前线程日志（默认）
with Capture(local=True) as logs:
container.demux(video=0)
# ✅ 捕获所有线程日志（多线程场景）
with Capture(local=False) as logs:
process_multi_threaded()
# 程序化分析
for log in logs:
if log.level >= av.logging.ERROR:
print(f"[{log.name}] {log.message}")
获取最近一次错误
# ✅ 快速获取最后一条 ERROR 及以上级别的日志
last_err = av.logging.get_last_error()
if last_err:
print(f"Last FFmpeg error: {last_err.message}")
4. API 速查表
5. 开发排查备忘
💡 核心记忆点
开发必开 VERBOSE：这是 PyAV 调试的第一原则，默认静默是报错无详情的根源
多线程用原生回调：Python logging hook 不是线程安全的，并发场景务必
restore_default_callback()Capture 用于自动化：单元测试/监控中用
Capture程序化检查日志，而非解析 stderr两套级别互斥：
set_level控制 Python hook，set_libav_level控制原生输出，切换后端后需用对应 APIAVError = FFmpegError：两者完全等价，catch 任一即可