ffmpeg-studio

ffmpeg-studio is a Pythonic interface to FFmpeg for building and running FFmpeg commands programmatically, including complex filter graphs. It targets Python developers who need video/audio transcoding, overlays, subtitles, audio mixing, and batch media processing without hand-writing long shell commands or raw filter_complex strings.

ffmpeg-studio wraps ffmpeg, ffprobe, and ffplay with a chainable, type-hinted API. It automatically handles safe quoting/escaping, input/output stream mapping, and progress tracking via callbacks. Unlike simpler wrappers, it has first-class support for building long, multi-stage filter graphs (scaling, overlay, mixing, etc.) as composable Python objects instead of string concatenation.

Install: pip install ffmpeg-studio (requires FFmpeg installed separately and available on PATH).

Docs

• Home: Overview, key features, and why developers use ffmpeg-studio.
• Installation: How to install the package and FFmpeg itself on Windows, macOS, and Linux.
• Getting Started: First steps and a minimal working example.
• Basics: Core concepts and the general workflow for building FFmpeg pipelines.
• FAQ: Frequently asked questions about installation, filter graphs, async support, and comparisons to alternatives.
• ffmpeg-studio vs ffmpeg-python: Feature-by-feature comparison of filter graphs, escaping, type hints, async support, and maintenance status.
• Troubleshooting: Fixes for common errors — FFmpeg not found, missing filters, filter reuse bugs, "Argument list too long" on very large filter graphs, thread-safety, async ffprobe calls, and ffmpeg-python import conflicts.

Tutorials

• Input Types: The different ways to create inputs.
• Input: Working with video input files.
• Subclip: Trimming/subclipping media.
• Stream Selection: Selecting specific audio/video streams from inputs.
• Iterating Video Streams: Iterating over multiple streams in a file.
• Duration & Size: Reading media metadata via ffprobe.
• Global Flags: Setting global FFmpeg command flags.
• Outputs: Configuring outputs, mapping, and per-output flags.

Examples

• Conversion: Simple format/container conversion.
• Merge Streams: Combining a video stream from one file with an audio stream from another.
• Mosaic: Building a video mosaic/grid layout with overlays.
• Graph Diagram: Visualizing generated filter graphs.
• Progress Bar: Tracking encode progress with callbacks.
• Text Fuzzing: Simple text fuzzer to test escaping.

API Reference

• Index: API reference overview.
• Inputs: Input classes (InputFile, VideoFile, AudioFile, ImageFile, etc.).
• Filters: Filter classes and the apply/apply2 helpers for building filter graphs.

Repository

• GitHub: Source code, issues, and releases.
• PyPI: Package releases and install instructions.

Optional

• License: GPL-3.0.
• Related terms: FFmpeg Python wrapper, Python FFmpeg complex filter graph, FFmpeg command builder Python, ffprobe Python wrapper, ffplay Python wrapper.