ffmpeg-python

For detailed information on using ffmpeg-python, refer to the following resources:

• API Reference: Comprehensive documentation of the Python bindings.
• Examples: A collection of usage examples located in the repository's examples directory.
• Filters: A list of supported FFmpeg filters defined in ffmpeg/_filters.py.
• FFmpeg Documentation: Official documentation for the underlying FFmpeg tool and its filters.

To use this library, you must install both the Python wrapper and the FFmpeg binary itself.

1. Install the Python wrapper

Install via pip:

pip install ffmpeg-python

Alternatively, install from source:

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

2. Install FFmpeg

ffmpeg-python is a pure-Python wrapper and does not install the FFmpeg binary. You must install FFmpeg on your system and ensure it is accessible via your $PATH.

• Debian/Ubuntu: sudo apt install ffmpeg
• OS X: brew install ffmpeg
• Other: Use official download links.

Verify installation by running ffmpeg in your terminal. If you see ffmpeg: command not found, FFmpeg is not properly installed or in your PATH.

The library allows you to build complex directed-acyclic signal graphs using Python syntax, which is more readable than FFmpeg's command-line -filter_complex arguments.

Example of a graph that trims two segments of an input, concatenates them, overlays a flipped image, and draws a box:

import ffmpeg

in_file = ffmpeg.input('input.mp4')
overlay_file = 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_file.hflip())
    .drawbox(50, 50, 120, 120, color='red', thickness=5)
    .output('out.mp4')
    .run()
)

You can use ffmpeg-python using a standard procedural style or a fluent interface.

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

# Fluent interface
(
    ffmpeg
    .input('input.mp4')
    .hflip()
    .output('output.mp4')
    .run()
)

If a filter does not have a shorthand method, use the .filter() operator. You can pass arguments as keyword arguments.

import ffmpeg

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

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

Special option names

For arguments with colons like -qscale:v or -b:v, pass them as a dictionary using unpacking (**):

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

Multiple inputs

Pass an array of input streams to ffmpeg.filter():

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

Multiple outputs

Use .filter_multi_output() (or the shorthand .split()) for filters that produce multiple streams:

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

String expressions

You can pass string expressions that reference FFmpeg variables directly as parameters:

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