ffmpeg-wrap

A typed Python wrapper for FFmpeg and ffprobe CLI tools. Build FFmpeg commands with a fluent API and parse ffprobe output into typed data structures.

Requirements

• Python 3.10+
• FFmpeg and ffprobe installed and available on PATH
• filter_complex_script() emits the ffmpeg 7.0+ -/filter_complex file syntax by default; pass legacy=True on ffmpeg 6.1 and older

Installation

With uv:

uv add ffmpeg-wrap

With pip:

pip install ffmpeg-wrap

Quick start

import ffmpeg_wrap as ffmpeg

# Probe a file into typed structures
result = ffmpeg.probe("video.mkv")
for stream in result.streams:
    print(stream.codec_name, stream.codec_type, stream.bit_depth())

# Build and run a command with the fluent builder
ffmpeg.input("input.mkv").output("output.mp4", c="copy").overwrite_output().run()

# Bound the wall-clock time; FFmpegTimeoutError is raised after ffmpeg is killed
ffmpeg.input("input.mkv").output("output.mp4", c="copy").overwrite_output().run(timeout=60)

Async

The asynchronous mirror of the API ships as an optional extra. With uv:

uv add "ffmpeg-wrap[async]"

With pip:

pip install "ffmpeg-wrap[async]"

import anyio

from ffmpeg_wrap import aio, input


async def main():
    await input("input.mkv").output("output.mp4", c="copy").overwrite_output().arun()
    result = await aio.probe("output.mp4")
    print(result.format.format_name if result.format else None)


anyio.run(main)

Documentation

Full documentation, including guides and the complete API reference, is hosted at gitbib.github.io/ffmpeg-wrap:

• Guide — a walkthrough of the synchronous API: probing files, building and running commands, mapping streams, complex filtergraphs, validation, encoder discovery, timeouts, and error handling.
• Async API — the AnyIO-backed asynchronous mirror, backend choice (asyncio or trio), timeouts, and bounding concurrency.
• API Reference — the auto-generated reference for every public function, builder method, and model.

Development

Install the locked development environment and run the complete local checks:

uv sync --all-extras --dev
uv run ty check
uv run pytest
prek run --all-files

CI additionally runs make test (downloads the real media fixtures once and runs the integration tests) and make test-platform (the timeout suites, which fail if any test is skipped).