typed-ffmpeg: Type-Safe FFmpeg Bindings for Python and TypeScript

Introduction

typed-ffmpeg provides a modern, type-safe interface for interacting with FFmpeg in both Python and TypeScript. Inspired by ffmpeg-python, this project significantly enhances functionality by offering comprehensive typing, improved IDE integration, and new features such as JSON serialization of filter graphs and automatic FFmpeg validation. It supports multiple FFmpeg major versions through separate, dedicated packages, ensuring compatibility and flexibility for developers working with various FFmpeg environments. Additionally, an interactive playground is available for hands-on experimentation.

Installation

To get started with typed-ffmpeg, you can install the Python package via pip. Ensure FFmpeg is already installed on your system.

Python Installation:

Install the latest version (bindings for FFmpeg 8.x):

pip install typed-ffmpeg

Or install bindings for a specific FFmpeg version:

pip install typed-ffmpeg-v5   # FFmpeg 5.x
pip install typed-ffmpeg-v6   # FFmpeg 6.x
pip install typed-ffmpeg-v7   # FFmpeg 7.x
pip install typed-ffmpeg-v8   # FFmpeg 8.x

With optional extras:

pip install 'typed-ffmpeg[graph]'          # graph visualization
pip install 'typed-ffmpeg[parse]'          # CLI parsing support
pip install 'typed-ffmpeg-v7[parse]'       # CLI parsing for FFmpeg 7.x

If you need to install ffmpeg-python simultaneously, use pip install typed-ffmpeg-compatible to prevent module name conflicts. Then, use import typed_ffmpeg as ffmpeg.

TypeScript Installation (Experimental):

TypeScript bindings are available as npm packages for each FFmpeg major version.

npm install @typed-ffmpeg/core @typed-ffmpeg/v8   # latest FFmpeg bindings

Example TypeScript usage:

import { input } from "@typed-ffmpeg/v8";

const cmd = input("input.mp4")
  .video
  .scale({ w: 1280, h: 720 })
  .output("output.mp4")
  .overwriteOutput()
  .compile();
// => ["-i", "input.mp4", "-filter_complex", "...", "output.mp4"]

Examples

Here's how to quickly start using typed-ffmpeg in Python:

import ffmpeg

# Analyze a media file
info = ffmpeg.probe("video.mp4")
print(f"Duration: {float(info['format']['duration']):.2f} seconds")
print(f"Streams: {len(info['streams'])}")

# Flip video horizontally and output
f = (
    ffmpeg
    .input(filename='input.mp4')
    .hflip()
    .output(filename='output.mp4')
)
f

For a more complex example involving filter graphs:

import ffmpeg.filters
import ffmpeg

# Complex filter graph example
in_file = ffmpeg.input("input.mp4")
overlay_file = ffmpeg.input("overlay.png")

f = (
    ffmpeg.filters
    .concat(
        in_file.trim(start_frame=10, end_frame=20),
        in_file.trim(start_frame=30, end_frame=40),
    )
    .video(0)
    .overlay(overlay_file.hflip())
    .drawbox(x="50", y="50", width="120", height="120", color="red", thickness="5")
    .output(filename="out.mp4")
)
f

For more examples and detailed guides, refer to the official documentation.

Why Use typed-ffmpeg?

typed-ffmpeg offers a robust set of features that make it an excellent choice for media processing tasks:

Zero Dependencies: Built purely with the Python standard library, ensuring maximum compatibility and security.
User-Friendly: Simplifies the construction of filter graphs with an intuitive Pythonic interface.
Comprehensive FFmpeg Filter Support: Out-of-the-box support for most FFmpeg filters, complete with IDE auto-completion and in-line docstrings for immediate reference.
Robust Typing: Provides static and dynamic type checking, significantly enhancing code reliability and development experience.
Filter Graph Serialization: Enables saving and reloading of filter graphs in JSON format for ease of use and repeatability.
Graph Visualization: Leverages graphviz for visual representation, aiding in understanding and debugging complex filter chains.
Validation and Auto-correction: Assists in identifying and fixing errors within filter graphs, streamlining development.
Input and Output Options Support: Offers a comprehensive interface for input and output options, including support for additional codecs and formats.
Partial Evaluation: Enhances the flexibility of filter graphs by enabling modular construction and reuse.
Media File Analysis: Built-in support for analyzing media files using FFmpeg's ffprobe utility, providing detailed metadata extraction.