Repository files navigation

typed-ffmpeg offers a modern, Pythonic interface to FFmpeg, providing extensive support for complex filters with detailed typing and documentation. Inspired byffmpeg-python, this package enhances functionality by addressing common limitations, such as lack of IDE integration and comprehensive typing, while also introducing new features like JSON serialization of filter graphs and automatic FFmpeg validation.

• Features
• Installation
• Quick Usage
• Documentation
• Interactive Playground
• Acknowledgements

• 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, with IDE auto-completion.
• Integrated Documentation: In-line docstrings provide immediate reference for filter usage, reducing the need to consult external documentation.
• Robust Typing: Offers static and dynamic type checking, 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: Leveragesgraphviz for visual representation, aiding in understanding and debugging.
• Validation and Auto-correction: Assists in identifying and fixing errors within filter graphs.
• Input and Output Options Support: Provide a more comprehensive interface for input and output options, including support for additional codecs and formats.
• Partial Evaluation: Enhance the flexibility of filter graphs by enabling partial evaluation, allowing for modular construction and reuse.
• Media File Analysis: Built-in support for analyzing media files using FFmpeg's ffprobe utility, providing detailed metadata extraction with both dictionary and dataclass interfaces.

Please note that the following features are under consideration or development for future releases:

• Extended FFmpeg Version Support: Whiletyped-ffmpeg is currently built with FFmpeg version 6.0 in mind, we are working to ensure compatibility across different FFmpeg versions. Feedback and issue reports are welcome to improve version support.
• Additional Filter Support: We aim to expand the range of FFmpeg filters supported bytyped-ffmpeg. Continuous updates will be made to include more complex and varied filters.

To installtyped-ffmpeg, simply use pip:

pip install typed-ffmpeg

Note: FFmpeg must be installed on your system.

Note: If you need to installffmpeg-python at the same time, usepip install typed-ffmpeg-compatible to prevent conflicts with the module name.​

To enable graph visualization features:

pip install'typed-ffmpeg[graph]'

Note: This requires Graphviz to be installed on your system.

Here's how to quickly start usingtyped-ffmpeg:

importffmpeg# Analyze a media fileinfo=ffmpeg.probe("video.mp4")print(f"Duration:{float(info['format']['duration']):.2f} seconds")print(f"Streams:{len(info['streams'])}")# Flip video horizontally and outputf= (ffmpeg    .input(filename='input.mp4')    .hflip()    .output(filename='output.mp4'))f

For a more complex example:

importffmpeg.filtersimportffmpeg# Complex filter graph examplein_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

See theUsage section in our documentation for more examples and detailed guides.

Try outtyped-ffmpeg directly in your browser with ourInteractive Playground! The playground provides a live environment where you can:

• Experiment with FFmpeg filters and commands
• Visualize filter graphs in real-time
• Test different input/output configurations
• Learn through interactive examples
• Share your filter graphs with others

The playground is perfect for learning and prototyping FFmpeg filter chains without setting up a local environment.

This project was initially inspired by the capabilities of GPT-3, with the original concept focusing on using GPT-3 to generate an FFmpeg filter SDK directly from the FFmpeg documentation. However, during the development process, I encountered limitations with GPT-3's ability to fully automate this task.

As a result, I shifted to traditional code generation methods to complete the SDK, ensuring a more robust and reliable tool. Despite this change in approach, both GitHub Copilot and GPT-3 were instrumental in accelerating the development process, providing valuable insights and saving significant time.

I would also like to extend my gratitude to theffmpeg-python project, which inspired this project significantly. The API style and design ideas fromffmpeg-python have been influential, and I have utilized these aspects to shape the development of our SDK.

This project is dedicated to my son, Austin, on his seventh birthday (February 24, 2024), whose curiosity and zest for life continually inspire me.

Feel free to check theDocumentation for detailed information and more advanced features.

Install all development dependencies:

uv pip install --group dev

No need to use requirements.in or requirements.txt anymore. All dependencies are managed inpyproject.toml and locked inuv.lock.