Jay Taylor's notes

back to listing index

kkroening/ffmpeg-python: Python bindings for FFmpeg - with complex filtering support

[web search]
Original source (github.com)
Tags: python video-editing ffmpeg
Clipped on: 2019-12-30

Skip to content
Python bindings for FFmpeg - with complex filtering support
Python
Branch: master
New pull request
Clone or download
Latest commit 4cb7d26 12 hours ago
Type Name Latest commit message Commit time
doc Update docs 7 months ago
examples Merge pull request #247 from kylemcdonald/patch-1 12 hours ago
ffmpeg Merge pull request #283 from magnusvmt/master 12 hours ago
.gitignore Add input/output support in `run` command; update docs 2 years ago
.travis.yml Travis CI: Add Python 3.7 to the tests 5 months ago
LICENSE Update LICENSE with full license text 2 years ago
MANIFEST Update readme; bump version; ignore errors in `git rev-parse` 3 years ago
README Update readme filename 3 years ago
README.md Update README.md 6 months ago
pytest.ini Add overlay, hflip, and drawbox operators; use a more real-world exam… 3 years ago
requirements.txt Use Black formatter 7 months ago
setup.cfg Make `setup.py test` work 3 years ago
setup.py Release 0.2.0 6 months ago
tox.ini tox.ini: Add py37 to the testing 5 months ago

README.md

ffmpeg-python: Python bindings for FFmpeg

Image (Asset 4/10) alt=Overview

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.

Quickstart

Flip a video horizontally:

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

Or if you prefer a fluent interface:

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

API reference

Complex filter graphs

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

Take for example a signal graph that looks like this:

Image (Asset 5/10) alt=Installation

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

pip install ffmpeg-python

Or the source can be cloned and installed from locally:

git clone git@github.com:kkroening/ffmpeg-python.git
pip install -e ./ffmpeg-python

Examples

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:

Image (Asset 6/10) alt=Custom Filters

Don't see the filter you're looking for? While ffmpeg-python includes shorthand notation for some of the most commonly used filters (such as concat), all filters can be referenced via the .filter operator:

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

Or fluently:

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

Special option names:

Arguments with special names such as -qscale:v (variable bitrate), -b:v (constant bitrate), etc. can be specified as a keyword-args dictionary as follows:

(
    ffmpeg
    .input('in.mp4')
    .output('out.mp4', **{'qscale:v': 3})
    .run()
)

Multiple inputs:

Filters that take multiple input streams can be used by passing the input streams as an array to ffmpeg.filter:

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

Multiple outputs:

Filters that produce multiple outputs can be used with .filter_multi_output:

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

(In this particular case, .split() is the equivalent shorthand, but the general approach works for other multi-output filters)

String expressions:

Expressions to be interpreted by ffmpeg can be included as string parameters and reference any special ffmpeg variable names:

(
    ffmpeg
    .input('in.mp4')
    .filter('crop', 'in_w-2*10', 'in_h-2*20')
    .input('out.mp4')
)

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

Frequently asked questions

Why do I get an import/attribute/etc. error from import ffmpeg?

Make sure you ran pip install ffmpeg-python and not pip install ffmpeg or pip install python-ffmpeg.

Why did my audio stream get dropped?

Some ffmpeg filters drop audio streams, and care must be taken to preserve the audio in the final output. The .audio and .video operators can be used to reference the audio/video portions of a stream so that they can be processed separately and then re-combined later in the pipeline.

This dilemma is intrinsic to ffmpeg, and ffmpeg-python tries to stay out of the way while users may refer to the official ffmpeg documentation as to why certain filters drop audio.

As usual, take a look at the examples (Audio/video pipeline in particular).

How do I do XYZ?

Take a look at each of the links in the Additional Resources section at the end of this README. If you look everywhere and can't find what you're looking for and have a question that may be relevant to other users, you may open an issue asking how to do it, while providing a thorough explanation of what you're trying to do and what you've tried so far.

Issues not directly related to ffmpeg-python or issues asking others to write your code for you or how to do the work of solving a complex signal processing problem for you that's not relevant to other users will be closed.

That said, we hope to continue improving our documentation and provide a community of support for people using ffmpeg-python to do cool and exciting things.

Contributing

Image (Asset 7/10) alt=Running tests

git clone git@github.com:kkroening/ffmpeg-python.git
cd ffmpeg-python
virtualenv venv
. venv/bin/activate  # (OS X / Linux)
venv\bin\activate    # (Windows)
pip install -e .[dev]
pytest

Special thanks

Additional Resources