ffmpeg-python：用 Python 拼装 FFmpeg 链路

ffmpeg-python：用 Python 拼装 FFmpeg 链路

ffmpeg-python 在 GitHub 上已经拿到 10,993 Star 了。

它做的事情很直接：把 FFmpeg 的命令行调用包装成 Python API。你不需要记一堆 -filter_complex 参数，直接用 Python 对象和链式调用来拼接视频、音频的处理流程。

对于习惯用 Python 做数据处理和自动化的人来说，这个包装器省掉了很多查文档和拼字符串的时间。

1、 这玩意儿是干嘛的

FFmpeg 本身功能极强，但命令行写起来很痛苦。稍微复杂一点的信号图，参数就长成一团乱麻，调试和复用都不方便。

ffmpeg-python 提供了一套流式 API，把输入、滤镜、输出都变成 Python 对象。你声明好数据流怎么连，它帮你生成对应的 FFmpeg 命令并执行。核心思路是把命令行里的管道和图层关系，映射成 Python 里的对象和方法链。

比如把视频水平翻转：

import ffmpeg

ffmpeg.input('input.mp4').hflip().output('output.mp4').run()

就这一行，比写命令行直观得多。

2、 为什么不用裸命令行

FFmpeg 的复杂滤镜图参数非常难读。README 里举了一个例子：两段视频裁剪后拼接，再叠加上翻转过的图片，最后画个红框。命令行版本要写成：

ffmpeg -i input.mp4 -i overlay.png -filter_complex \
  "[0]trim=start_frame=10:end_frame=20[v0];[0]trim=start_frame=30:end_frame=40[v1];\
   [v0][v1]concat=n=2[v2];[1]hflip[v3];[v2][v3]overlay=eof_action=repeat[v4];\
   [v4]drawbox=50:50:120:120:red:t=5[v5]" -map [v5] output.mp4

这种写法能跑，但可读性差，改起来也费劲。参数顺序、引号嵌套、图层命名，任何一个小改动都要重新检查整串命令。用 ffmpeg-python 可以写成：

import ffmpeg

in_file = ffmpeg.input('input.mp4')
overlay = ffmpeg.input('overlay.png')

ffmpeg.concat(
    in_file.trim(start_frame=10, end_frame=20),
    in_file.trim(start_frame=30, end_frame=40)
).overlay(overlay.hflip()).drawbox(50, 50, 120, 120, color='red', thickness=5) \
 .output('out.mp4').run()

逻辑结构一目了然，后续调整顺序或参数也容易。

3、 复杂滤镜图也能接

ffmpeg-python 支持任意规模的有向无环图。多输入、多输出、分支、合并都能表达。

比如自定义滤镜：

ffmpeg.input('in.mp4').filter('fps', fps=25, round='up').output('out.mp4').run()

多输入滤镜：

main = ffmpeg.input('main.mp4')
logo = ffmpeg.input('logo.png')
ffmpeg.filter([main, logo], 'overlay', 10, 10).output('out.mp4').run()

多输出滤镜：

split = ffmpeg.input('in.mp4').filter_multi_output('split')
ffmpeg.concat(split[0], split[1].reverse()).output('out.mp4').run()

特殊参数名可以用字典传，比如 **{'qscale:v': 3}。字符串表达式也可以直接写进参数里，保留 FFmpeg 原生的计算能力。

4、 安装与使用

Python 包直接装：

pip install ffmpeg-python

注意它只是纯 Python 包装器，不包含 FFmpeg 本体。你需要先在系统里装好 FFmpeg，并确保能在命令行直接调用。

装完后检查环境：

ffmpeg

能看到版本信息就说明环境对了。如果你用的是虚拟环境，记得在激活环境后安装，避免包冲突。

5、 适合哪些人用

• 经常用 Python 做视频处理、又不想背 FFmpeg 命令行参数的开发者
• 需要拼装复杂滤镜图、希望代码能复用和维护的人
• 在 Jupyter 或 AI 流程里集成视频预处理步骤的用户

项目里还提供了大量示例，包括视频转 numpy 数组、生成缩略图、PCM 音频管道、Jupyter 流式编辑器，以及 TensorFlow 流式处理。不确定怎么写的时候，翻一遍 examples 目录基本能找到参考。

ffmpeg-python 没有改变 FFmpeg 的能力边界，只是换了一种更适合 Python 开发者的方式去调用它。如果你已经熟悉 FFmpeg 的滤镜逻辑，迁移到这个库几乎没有门槛。