ffmpeg-python

What it is and what it does

ffmpeg-python is a pure-Python wrapper that translates Python code into FFmpeg command-line arguments, designed to make complex audio and video filter graphs readable and maintainable. Instead of constructing unwieldy shell commands with filter_complex strings, you build a signal graph in Python using method chaining or explicit filter calls, and the library generates the corresponding FFmpeg invocation. It handles arbitrarily large directed-acyclic graphs, multiple inputs and outputs, and supports both shorthand notation for common filters (like concat, hflip, overlay) and a generic .filter() operator for any FFmpeg filter.

The package depends only on future for Python 2/3 compatibility and requires FFmpeg to be installed separately on the system. It has been dormant since 2019-07-06 but remains widely used and has no known security vulnerabilities. The main trade-off is that you are responsible for understanding FFmpeg's filter semantics—ffmpeg-python merely translates your Python calls into the correct command-line form.

Use it for:

• Build complex video editing pipelines with multiple inputs, overlays, and filters without writing shell commands
• Generate thumbnails or convert video formats with simple Python code instead of constructing ffmpeg CLI strings
• Stream audio or video through processing chains (e.g., reading raw PCM or piping to machine learning models)
• Programmatically compose filter graphs that would be impractical to write by hand in ffmpeg's filter_complex syntax
• Preserve audio streams while applying video filters by referencing .audio and .video portions separately

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

ffmpeg-python provides a Python interface to FFmpeg that translates complex filter graphs into command-line arguments, supporting both simple operations and arbitrarily large directed-acyclic signal graphs.

Yes, with caution. The package is stable and widely used for translating complex FFmpeg operations into readable Python code, with low install friction and permissive licensing. However, dormancy since 2019-07-06 means no active maintenance and potential compatibility issues with recent FFmpeg releases. Install it if you need to programmatically build FFmpeg filter graphs and can accept that bugs or incompatibilities may not be fixed upstream.

Install

ffmpeg-python on PyPI

pip install ffmpeg-python

uv add ffmpeg-python

poetry add ffmpeg-python

Installing ffmpeg-python

Before you install

Low install friction with a single pure-Python dependency (future). However, the package is dormant—last release was 2019-07-06, over 2596 days ago, with no updates despite an active repository (last commit 2024-08-04). It remains popular (top 5000 on PyPI with approximately 10 million monthly downloads) but receives no active maintenance.

License in practice

Licensed under Apache License (permissive), which allows commercial and private use with minimal restrictions—suitable for most projects.

Quickstart

pip install ffmpeg-python

import ffmpeg
stream = ffmpeg.input('input.mp4')
stream = ffmpeg.hflip(stream)
stream = ffmpeg.output(stream, 'output.mp4')
ffmpeg.run(stream)

FFmpeg must be installed separately and accessible via $PATH; ffmpeg-python is a wrapper only and does not bundle FFmpeg itself.

Verify before relying

• Whether the package works reliably with modern Python versions beyond those listed in classifiers
• Whether dormancy affects compatibility with recent FFmpeg releases or introduces undiscovered bugs
• Whether the future dependency is actively maintained or itself dormant

Package facts

Evidence: ffmpeg_python-0.2.0-py3-none-any.whl

Keywords: -vf, a/v, audio, dsp, FFmpeg, ffmpeg, ffprobe, filtering, filter_complex, movie, render, signals, sound, streaming, streams, vf, video, wrapper, aac, ac3, avi, bmp, flac, gif, mov, mp3, mp4, png, raw, rawvideo, wav, .aac, .ac3, .avi, .bmp, .flac, .gif, .mov, .mp3, .mp4, .png, .raw, .rawvideo, .wav

Tags

More Graphics packages