Python bindings for FFmpeg - with complex filtering support
Clone or download
kkroening Merge pull request #126 from RPing/master
small fix for document
Latest commit e0eb332 Sep 17, 2018

ffmpeg-python: Python bindings for FFmpeg

Build status

ffmpeg-python logo


There are tons of Python FFmpeg wrappers out there but they seem to lack complex filter support. ffmpeg-python works well for simple as well as complex signal graphs.


Flip a video horizontally:

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

Or if you prefer a fluent interface:

import ffmpeg

Complex filter graphs

FFmpeg is extremely powerful, but its command-line interface gets really complicated really quickly - especially when working with signal graphs and doing anything more than trivial.

Take for example a signal graph that looks like this:

Signal graph

The corresponding command-line arguments are pretty gnarly:

ffmpeg -i input.mp4 -i overlay.png -filter_complex "[0]trim=start_frame=10:end_frame=20[v0];\
    -map [v5] output.mp4

Maybe this looks great to you, but if you're not an FFmpeg command-line expert, it probably looks alien.

If you're like me and find Python to be powerful and readable, it's easy with ffmpeg-python:

import ffmpeg

in_file = ffmpeg.input('input.mp4')
overlay_file = ffmpeg.input('overlay.png')
        in_file.trim(start_frame=10, end_frame=20),
        in_file.trim(start_frame=30, end_frame=40),
    .drawbox(50, 50, 120, 120, color='red', thickness=5)

ffmpeg-python takes care of running ffmpeg with the command-line arguments that correspond to the above filter diagram, and it's easy to see what's going on and make changes as needed.


Real-world signal graphs can get a heck of a lot more complex, but ffmpeg-python handles them with ease.


The latest version of ffmpeg-python can be acquired via pip:

pip install ffmpeg-python

It's also possible to clone the source and put it on your python path ($PYTHONPATH, sys.path, etc.):

$ git clone
$ export PYTHONPATH=${PYTHONPATH}:ffmpeg-python
$ python
>>> import ffmpeg


When in doubt, take a look at the examples to see if there's something that's close to whatever you're trying to do.

Here are a few:

jupyter demo

See the Examples README for additional examples.

API Reference

API documentation is automatically generated from python docstrings and hosted on github pages:

Alternatively, standard python help is available, such as at the python REPL prompt as follows:

>>> import ffmpeg
>>> help(ffmpeg)

Custom Filters

Don't see the filter you're looking for? ffmpeg-python includes shorthand notation for some of the most commonly used filters (such as concat), but it's easy to use any arbitrary ffmpeg filter:

stream = ffmpeg.input('dummy.mp4')
stream = ffmpeg.filter(stream, 'fps', fps=25, round='up')
stream = ffmpeg.output(stream, 'dummy2.mp4')

Or fluently:

    .filter('fps', fps=25, round='up')

Arguments with special names such as -qscale:v can be specified as a keyword-args dictionary as follows:

    .output('dummy2.mp4', **{'qscale:v': 3})

When in doubt, refer to the existing filters, examples, and/or the official ffmpeg documentation.


ffmpeg-python logo

Feel free to report any bugs or submit feature requests.

It's generally straightforward to use filters that aren't explicitly built into ffmpeg-python but if there's a feature you'd like to see included in the library, head over to the issue tracker.

Pull requests are welcome as well.

Special thanks

Additional Resources