Show HN: Typed-FFmpeg 3.0 – FFmpegへの型付きインターフェースとビジュアルフィルターエディタ

概要

typed-ffmpeg は、PythonからFFmpegの複雑なフィルタグラフを型安全かつ直感的に操作できるライブラリ。 IDE補完 や 詳細な型情報、 ドキュメント統合 など、ffmpeg-pythonの課題を解決。 JSONシリアライズ や 自動バリデーション など独自機能も搭載。 インストールや基本的な使い方 もシンプル。 インタラクティブなPlayground で実験・学習も可能。

typed-ffmpeg 概要

typed-ffmpeg は、FFmpegの強力な機能を Pythonicなインターフェース で提供するパッケージ
ffmpeg-python を参考にしつつ、 IDE統合 や 型安全性 を強化
複雑なフィルタグラフ の構築や、 直感的な記法 を実現
フィルタグラフのJSON保存・復元 や 自動バリデーション など独自機能を搭載
Python標準ライブラリのみ で動作、追加依存なし

主な特徴

ゼロ依存性 ・Python標準ライブラリのみで構成、互換性・セキュリティ向上
ユーザーフレンドリー ・直感的な記法でフィルタグラフ作成を簡素化
FFmpegフィルタ網羅 ・ほとんどのフィルタに対応、 IDEの補完機能 も充実
統合ドキュメント ・インラインdocstringで即座に使用方法を確認可能
堅牢な型付け ・静的・動的型チェックで コード信頼性 と開発体験を向上
フィルタグラフのシリアライズ ・JSON形式で保存・再利用が可能
グラフ可視化 ・graphviz連携でフィルタグラフを視覚的に表示
バリデーション＆自動修正 ・フィルタグラフ内のエラー検出・修正支援
入出力オプション対応 ・多様なコーデック・フォーマットも柔軟に指定可能
部分評価 ・フィルタグラフのモジュール化・再利用性向上

今後の開発予定

FFmpegバージョン拡張 ・現状はFFmpeg 6.0対応、他バージョン対応も順次強化予定
フィルタ追加対応 ・より多様で複雑なフィルタへの対応を拡充予定

インストール方法

基本インストール
```
pip install typed-ffmpeg
```
・システムに FFmpeg本体 のインストールが必要
ffmpeg-pythonとの共存
```
pip install typed-ffmpeg-compatible
```
・モジュール名競合回避用
グラフ可視化サポート
```
pip install 'typed-ffmpeg[graph]'
```
・ Graphviz のシステムインストールが必要

クイック使用例

シンプルな動画反転例

import ffmpeg
f = (
    ffmpeg.input(filename='input.mp4')
    .hflip()
    .output(filename='output.mp4')
)
f

複雑なフィルタグラフ例

import ffmpeg.filters
import ffmpeg
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

詳細な使い方やサンプルは公式ドキュメント参照

インタラクティブPlayground

ブラウザ上でtyped-ffmpegを体験可能なPlayground ・FFmpegフィルタやコマンドの実験・フィルタグラフのリアルタイム可視化・入出力設定のテスト・インタラクティブな学習例・作成したフィルタグラフの共有
ローカル環境構築不要で学習・プロトタイピングが可能
Playgroundリンク ・https://livingbio.github.io/typed-ffmpeg-playground/

開発背景・謝辞

GPT-3による自動SDK生成 を目指し開発を開始
途中で 従来のコード生成手法 へシフトし、より堅牢なツール化を実現
GitHub CopilotやGPT-3 の活用で開発効率向上
ffmpeg-python のAPI設計・思想に大きく影響を受けている
本プロジェクトは 開発者の息子Austin への誕生日プレゼントとして捧げられている

v3.0の新機能

ソースフィルタ対応 （例：color, testsrc等）
入力ストリーム選択 （例：[0:a], [1:v]等）
新しいインタラクティブPlayground ・フィルタグラフのビジュアル構築・FFmpeg CLI・型付きPythonコードの自動生成・既存のFFmpegコマンドの逆解析・グラフ化
CLI→グラフ→型付きコード変換 にも対応・教育ツールやFFmpeg IDE、ビジュアルエディタ開発にも有用

フィードバック・今後の展望

バグ報告・アイデア提案 は随時歓迎
FFmpeg CLIの複雑さに悩む方や教育用途 にも最適
詳細は公式ドキュメント・Playground参照

ハクソク