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

This repository profile is provided by osrepos.com, an open source repository discovery platform.

Source: osrepos.com
Repository profile: https://osrepos.com/repo/livingbio-typed-ffmpeg
Generated for open source discovery and AI-assisted research.

typed-ffmpeg offers a modern, type-safe interface to FFmpeg for both Python and TypeScript. It provides extensive support for complex filters with detailed typing, documentation, and features like JSON serialization of filter graphs and automatic FFmpeg validation. This project enhances functionality by addressing common limitations found in similar tools, ensuring a robust development experience.

GitHub: https://github.com/livingbio/typed-ffmpeg
OSRepos URL: https://osrepos.com/repo/livingbio-typed-ffmpeg

## Summary

typed-ffmpeg offers a modern, type-safe interface to FFmpeg for both Python and TypeScript. It provides extensive support for complex filters with detailed typing, documentation, and features like JSON serialization of filter graphs and automatic FFmpeg validation. This project enhances functionality by addressing common limitations found in similar tools, ensuring a robust development experience.

## Topics

- ffmpeg
- python
- typescript
- media-processing
- type-safe
- bindings
- developer-tools
- npm

## Repository Information

Last analyzed by OSRepos: Sat Apr 11 2026 20:28:24 GMT+0100 (Western European Summer Time)
Detail views: 5
GitHub clicks: 6

## Safety Notice

OSRepos shares public repositories for knowledge and discovery only. Review source code, dependencies, licenses, and security implications before running or installing anything.

## Content

## 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):

bash
pip install typed-ffmpeg


Or install bindings for a specific FFmpeg version:

bash
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:

bash
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.

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


Example TypeScript usage:

typescript
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:

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:

python
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](https://livingbio.github.io/typed-ffmpeg/).

## 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.

## Links

*   **GitHub Repository:** [https://github.com/livingbio/typed-ffmpeg](https://github.com/livingbio/typed-ffmpeg)
*   **Official Documentation:** [https://livingbio.github.io/typed-ffmpeg/](https://livingbio.github.io/typed-ffmpeg/)
*   **PyPI Package:** [https://pypi.org/project/typed-ffmpeg/](https://pypi.org/project/typed-ffmpeg/)
*   **npm Packages:** `@typed-ffmpeg/core`, `@typed-ffmpeg/v5` through `@typed-ffmpeg/v8`
*   **Interactive Playground:** [https://livingbio.github.io/typed-ffmpeg-playground/](https://livingbio.github.io/typed-ffmpeg-playground/)