FFmpeg Binaries (matteoh2o1999/ffmpeg-binaries)

FFmpeg Binaries

https://github.com/matteoh2o1999/ffmpeg-binaries
Admin
FFmpeg Binaries is a Python package that provides static builds of FFmpeg and FFprobe, enabling easy...

Tokens:4,294
Snippets:28
Trust Score:7.3
Update:2 months ago
Show doc for...
Context Summary (auto-generated)
Raw
# ffmpeg-binaries

ffmpeg-binaries is a Python package that provides static builds of FFmpeg for seamless integration into Python projects. It eliminates the need for manual FFmpeg installation by automatically downloading and managing platform-specific FFmpeg binaries (Windows, macOS, and Linux) directly within your Python environment. The package bundles FFmpeg 6.0.0 and supports Python 3.9 through 3.13.

The library offers a simple API to initialize FFmpeg binaries, execute FFmpeg and FFprobe commands directly from Python, and integrate the binaries with other Python modules or add them to your system PATH. It handles cross-platform compatibility automatically and includes PyInstaller hooks for packaging applications that depend on FFmpeg.

## Installation

```bash
pip install ffmpeg-binaries
```

For projects with import name conflicts (e.g., when using typed-ffmpeg or ffmpeg-python):

```bash
pip install ffmpeg-binaries-compat
```

## ffmpeg.init()

Initializes the FFmpeg module by downloading binaries if they are not already present. This function sets the global `FFMPEG_PATH`, `FFPROBE_PATH`, and `FFMPEG_FOLDER` variables. Call this function before using any FFmpeg functionality if binaries were not found during import.

```python
import ffmpeg

# Initialize and download binaries if needed
ffmpeg.init()

# After init(), these global variables are available:
print(f"FFmpeg path: {ffmpeg.FFMPEG_PATH}")
print(f"FFprobe path: {ffmpeg.FFPROBE_PATH}")
print(f"Binaries folder: {ffmpeg.FFMPEG_FOLDER}")

# Output:
# FFmpeg path: /path/to/site-packages/ffmpeg/binaries/ffmpeg
# FFprobe path: /path/to/site-packages/ffmpeg/binaries/ffprobe
# Binaries folder: /path/to/site-packages/ffmpeg/binaries
```

## ffmpeg.run_as_ffmpeg(command)

Executes an FFmpeg command directly from Python. Takes a command string as input and returns the process exit code. This provides a simple way to run FFmpeg operations without subprocess boilerplate.

```python
import ffmpeg

# Initialize if needed
ffmpeg.init()

# Get help information
exit_code = ffmpeg.run_as_ffmpeg("-h")
print(f"Exit code: {exit_code}")

# Convert video format (example command)
exit_code = ffmpeg.run_as_ffmpeg("-i input.mp4 -c:v libx264 output.avi")
print(f"Conversion exit code: {exit_code}")

# Output:
# ffmpeg version 6.0 Copyright (c) 2000-2023 the FFmpeg developers
# ...
# Exit code: 0
```

## ffmpeg.run_as_ffprobe(command)

Executes an FFprobe command directly from Python. Takes a command string as input and returns the process exit code. FFprobe is used for analyzing multimedia streams and extracting metadata.

```python
import ffmpeg

# Initialize if needed
ffmpeg.init()

# Get ffprobe help
exit_code = ffmpeg.run_as_ffprobe("-h")
print(f"Exit code: {exit_code}")

# Analyze a video file (example)
exit_code = ffmpeg.run_as_ffprobe("-v quiet -print_format json -show_format -show_streams video.mp4")
print(f"Analysis exit code: {exit_code}")

# Output:
# ffprobe version 6.0 Copyright (c) 2007-2023 the FFmpeg developers
# ...
# Exit code: 0
```

## ffmpeg.add_to_path()

Adds the FFmpeg binaries folder to the system PATH environment variable. This allows other tools and subprocesses to find FFmpeg without specifying the full path. The function prepends `FFMPEG_FOLDER` to PATH.

```python
import ffmpeg
import subprocess

# Initialize and add to PATH
ffmpeg.init()
ffmpeg.add_to_path()

# Now ffmpeg is available system-wide for subprocesses
result = subprocess.run(["ffmpeg", "-version"], capture_output=True, text=True)
print(result.stdout)

# Verify it's on path
print(f"FFmpeg on PATH: {ffmpeg.is_on_path()}")

# Output:
# ffmpeg version 6.0 Copyright (c) 2000-2023 the FFmpeg developers
# ...
# FFmpeg on PATH: True
```

## ffmpeg.is_on_path()

Checks whether the FFmpeg binaries folder is currently on the system PATH. Returns `True` if `FFMPEG_FOLDER` is found in the PATH environment variable, `False` otherwise.

```python
import ffmpeg

ffmpeg.init()

# Check before adding to PATH
print(f"Before: {ffmpeg.is_on_path()}")  # Output: False

# Add to PATH
ffmpeg.add_to_path()

# Check after adding to PATH
print(f"After: {ffmpeg.is_on_path()}")  # Output: True
```

## ffmpeg.use_ffmpeg(ffmpeg_path, ffprobe_path)

Configures the module to use custom FFmpeg and FFprobe executables instead of the bundled binaries. Both executables must exist, be valid files, and reside in the same folder. Useful when you need to use a specific FFmpeg version or a system-installed FFmpeg.

```python
import ffmpeg

# Use system-installed FFmpeg instead of bundled binaries
ffmpeg.use_ffmpeg(
    ffmpeg_path="/usr/local/bin/ffmpeg",
    ffprobe_path="/usr/local/bin/ffprobe"
)

# Global variables are now updated
print(f"FFmpeg path: {ffmpeg.FFMPEG_PATH}")
print(f"FFprobe path: {ffmpeg.FFPROBE_PATH}")
print(f"FFmpeg folder: {ffmpeg.FFMPEG_FOLDER}")

# Use the custom FFmpeg
exit_code = ffmpeg.run_as_ffmpeg("-version")

# Output:
# FFmpeg path: /usr/local/bin/ffmpeg
# FFprobe path: /usr/local/bin/ffprobe
# FFmpeg folder: /usr/local/bin
```

## Global Variables: FFMPEG_PATH, FFPROBE_PATH, FFMPEG_FOLDER

These module-level variables provide direct access to the FFmpeg binary paths after initialization. They can be used to integrate FFmpeg with other Python libraries that require the path to FFmpeg executables.

```python
import ffmpeg

# Initialize to ensure paths are set
ffmpeg.init()

# Access paths for integration with other libraries
print(f"FFmpeg executable: {ffmpeg.FFMPEG_PATH}")
print(f"FFprobe executable: {ffmpeg.FFPROBE_PATH}")
print(f"Binaries directory: {ffmpeg.FFMPEG_FOLDER}")

# Example: Pass to another library
# moviepy.config.FFMPEG_BINARY = str(ffmpeg.FFMPEG_PATH)
# pydub.AudioSegment.converter = str(ffmpeg.FFMPEG_PATH)

# Example: Use with subprocess for advanced control
import subprocess
result = subprocess.run(
    [str(ffmpeg.FFMPEG_PATH), "-i", "input.mp4", "-c:v", "libx264", "output.mp4"],
    capture_output=True,
    text=True
)
print(f"Return code: {result.returncode}")
```

## Using the Mirror Package (ffmpeg-binaries-compat)

When the `ffmpeg` import name conflicts with other packages like typed-ffmpeg or ffmpeg-python, use the mirror package with the `ffmpeg_binaries` import name.

```python
# Install: pip install ffmpeg-binaries-compat
import ffmpeg_binaries as ffmpeg

# All functionality is identical
ffmpeg.init()
ffmpeg.run_as_ffmpeg("-h")
ffmpeg.run_as_ffprobe("-h")
ffmpeg.add_to_path()

# Use with other ffmpeg libraries
import ffmpeg as typed_ffmpeg  # typed-ffmpeg library

# Both can coexist
print(f"Binaries path: {ffmpeg.FFMPEG_PATH}")
```

## Summary

ffmpeg-binaries is ideal for Python applications that need FFmpeg functionality without requiring users to manually install FFmpeg on their systems. Common use cases include video/audio conversion tools, media processing pipelines, video editing applications, streaming services, and any Python project that wraps FFmpeg functionality. The automatic binary management makes it particularly useful for distributing desktop applications with PyInstaller.

Integration with other Python media libraries is straightforward through the exposed path variables. Libraries like MoviePy, PyDub, and imageio-ffmpeg can be configured to use the bundled FFmpeg binaries by setting their configuration to `ffmpeg.FFMPEG_PATH`. The `add_to_path()` function enables integration with tools that expect FFmpeg to be available system-wide. For production deployments, consider calling `ffmpeg.init()` during application startup to ensure binaries are downloaded before they're needed.