FFmpeg Python Bindings

0.2.0 · active · verified Mon Apr 06

ffmpeg-python is a Python wrapper for the powerful FFmpeg multimedia framework, enabling developers to programmatically build and execute FFmpeg command-line arguments. It simplifies complex media manipulation tasks such as format conversion, video editing, and audio extraction within Python applications. The library's current PyPI version is 0.2.0, and while its own releases are infrequent, it remains actively used and functional due to its reliance on the externally maintained FFmpeg binary. Users should ensure their underlying FFmpeg installation is up-to-date.

Warnings

gotcha The `ffmpeg-python` library is a wrapper for the external FFmpeg binary. You *must* install FFmpeg separately on your system and ensure its executables are available in your system's PATH environment variable for `ffmpeg-python` to work. `ffmpeg-python` does not install FFmpeg for you.
Fix: Install FFmpeg for your operating system (e.g., `sudo apt install ffmpeg` on Debian/Ubuntu, `brew install ffmpeg` on macOS, or download from the official FFmpeg website for Windows and add to PATH).
gotcha Some FFmpeg filters inherently drop audio or video streams if not explicitly handled. If you encounter missing audio or video in your output, you may need to explicitly select and re-combine streams using `.audio` and `.video` operators.
Fix: Use `stream.audio` and `stream.video` to reference and process audio/video portions separately, then use `ffmpeg.concat()` or similar to re-combine them if needed. Refer to FFmpeg's official documentation for specific filter behaviors.
gotcha Abruptly terminating the underlying FFmpeg process (e.g., by killing the Python process) can lead to corrupted output files.
Fix: Implement graceful termination by sending a signal to the FFmpeg process (e.g., `process.terminate()`) and allowing a short sleep period for FFmpeg to finalize the output file. Avoid `taskkill` or similar abrupt methods.
gotcha While `ffmpeg-python` (version 0.2.0) has not been updated since 2019, it remains widely used and functional because it acts as a thin wrapper around the underlying FFmpeg command-line tool. The core FFmpeg binary itself is actively maintained and frequently updated (e.g., FFmpeg 8.1 released March 2026). The stability of your media processing largely depends on keeping your *FFmpeg binary* up-to-date, not necessarily the `ffmpeg-python` wrapper.
Fix: Regularly update your system's FFmpeg binary to benefit from the latest features, bug fixes, and security patches. Check the FFmpeg project's official news for new releases. This library's lack of recent updates does not imply it is broken or incompatible with newer FFmpeg binaries, though very recent, significant breaking changes in FFmpeg's CLI syntax *could* potentially affect it.
gotcha Some media players or platforms require specific pixel formats (e.g., `yuv420p`) for maximum compatibility. Omitting this can lead to playback issues.
Fix: When encoding video, consider adding the `-pix_fmt yuv420p` option to your FFmpeg command via `ffmpeg-python`. Example: `ffmpeg.output(stream, output_filename, pix_fmt='yuv420p').run()`.

Install

pip install ffmpeg-python Install from PyPI

Imports

ffmpeg
```
import ffmpeg
```
ffmpeg
```
pip install ffmpeg-python
```
Installing 'ffmpeg' or 'python-ffmpeg' from PyPI will install a different, unrelated library. Ensure you install 'ffmpeg-python' for these bindings and use 'import ffmpeg' in your code.

Quickstart

This quickstart demonstrates how to convert a video file from one format (e.g., MP4) to another (e.g., AVI) using `ffmpeg-python`. It creates a stream from an input file, specifies an output file, and then executes the FFmpeg command. For this example to function correctly, an `input.mp4` file must exist, and the FFmpeg binary must be installed and accessible on your system.

import ffmpeg
import os

# Create dummy input file for demonstration
# In a real scenario, 'input.mp4' would be an existing video file.
# For a runnable example without actual FFmpeg, this part would be mocked or use a very small, pre-existing file.
# For this example, we assume 'input.mp4' exists.
# To make it runnable for demonstration, let's create a placeholder.
# WARNING: This part is for demonstration. FFmpeg needs a valid input file.
# In a production environment, ensure 'input.mp4' is a real video file.

input_filename = 'input.mp4'
output_filename = 'output.avi'

# This block is a placeholder to ensure the file exists for a 'runnable' check, 
# but FFmpeg still requires a proper media file.
if not os.path.exists(input_filename):
    print(f"Please create a dummy video file named '{input_filename}' for this example to fully run with FFmpeg.")
    print("Example will proceed by trying to convert, but might fail if FFmpeg can't find/process the file.")
    # Example of how you might generate a minimal dummy file if FFmpeg was installed and functional:
    # import subprocess
    # try:
    #     subprocess.run(['ffmpeg', '-f', 'lavfi', '-i', 'testsrc=duration=1:size=128x72:rate=10', input_filename], check=True)
    # except FileNotFoundError:
    #     print("FFmpeg command-line tool not found. Please install FFmpeg.")
    # except subprocess.CalledProcessError as e:
    #     print(f"Error creating dummy input file: {e}")



try:
    stream = ffmpeg.input(input_filename)
    stream = ffmpeg.output(stream, output_filename)
    ffmpeg.run(stream, overwrite_output=True)
    print(f"Successfully converted {input_filename} to {output_filename}")
except ffmpeg.Error as e:
    print(f"FFmpeg error: {e.stderr.decode('utf8')}")
except FileNotFoundError:
    print("FFmpeg command not found. Please ensure FFmpeg is installed and in your system's PATH.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

view raw JSON →