ffmpeg-python-integration-reference

Python-FFmpeg 集成参考

当 Python 代码构建 FFmpeg 命令、滤镜、ASS 字幕或原始帧管道，且存在类型、单位、颜色或流映射错误风险时，请使用此技能。此 SKILL 是一个精简的协调器；详细表格和完整代码示例位于 references/python-ffmpeg-reference.md。

适用场景

• ffmpeg-python 流图和滤镜参数
• 使用 Python subprocess 调用 FFmpeg
• drawtext、ASS/SSA、卡拉 OK 和动画字幕参数映射
• RGB/BGR/ASS 颜色转换错误
• 秒、厘秒和毫秒混淆
• 使用 NumPy/OpenCV 进行原始帧管道 I/O
• 执行命令前的范围／类型验证

关键规则

1. 传递参数前先验证类型。 fontsize 和 crf 是整数；比特率是带单位的字符串，例如 5M 或 192k；FFmpeg 表达式是字符串。
2. 在 Python 中为 FFmpeg 表达式加引号。 使用 x="(w-tw)/2"，不要使用名为 w 或 tw 的 Python 变量。
3. 明确处理音频。 在 ffmpeg-python 中，视频滤镜链通常会丢弃音频，除非将 input_file.audio 映射到输出。
4. 了解颜色上下文。 FFmpeg drawtext 颜色是 RGB／命名字符串；OpenCV 数组是 BGR；ASS 颜色格式为 &HAABBGGRR。
5. 了解时间上下文。 FFmpeg 滤镜使用秒；ASS 卡拉 OK 标签使用厘秒；ASS 动画标签使用毫秒。

快速参考

FFmpeg / ASS 参数	Python 类型	格式／范围	常见错误
-crf	int 或 str	H.264/H.265 0-51	传入 18.5
-b:v、-b:a	str	5M、1000k、192k	传入没有单位的整数
fontsize	int	实用范围 12-200	传入 '24'
fontcolor	str	white、#FFFFFF、0xFFFFFF	RGB 元组／列表
ASS 颜色	str	&HAABBGGRR	使用 RGB 字节顺序
x、y、alpha、enable	表达式使用 str	'(w-tw)/2、between(t,1,5)	未加引号的表达式

核心工作流程

1. 探测输入或元数据来源，以确定宽度、高度、fps、时长和流的可用情况。
2. 选择集成层：使用 ffmpeg-python 构建命令图，使用 subprocess 实现完整 CLI 对应行为和管道，使用 PyAV 访问帧级库接口。
3. 在 Python 边界处统一颜色和时间单位。
4. 构建命令前验证参数和范围。
5. 有意映射音频／字幕流。
6. 先用短样本运行；捕获 stderr，以便获取可用于处理问题的 FFmpeg 错误信息。

参考索引

• references/python-ffmpeg-reference.md - 完整保留的参考资料：颜色转换函数、ASS 样式结构、卡拉 OK／动画辅助函数、drawtext 参数表、ffmpeg-python 示例、subprocess 管道模式、注意事项、验证辅助函数和完整可运行示例。

相关技能

• ffmpeg-opencv-integration - OpenCV/NumPy 帧处理管道和 BGR/RGB 交接
• ffmpeg-pyav-integration - PyAV 帧级 API 模式
• ffmpeg-captions-subtitles - 字幕提取、烧录和样式设置
• ffmpeg-animation-timing-reference - 时间单位、可读性、缓动和同步