typed-ffmpeg - FFmpeg向けの型付きインターフェースと視覚的フィルターエディタ

• typed-ffmpeg は、Python で FFmpeg を直感的に使えるようにする モダンなラッパーです
• 強力な型サポート、充実したドキュメント、IDE の自動補完により、開発体験とコードの安定性を向上させます
• 複雑な フィルターグラフ構成 を簡単に作成でき、可視化 や JSON シリアライズなどの高度な機能もサポートします
• インストールと実行が簡単で、インタラクティブなプレイグラウンド によりブラウザ上でも試せます
• ffmpeg-python に着想を得て既存の問題点を補い、今後さらに多くの FFmpeg バージョンとフィルターをサポートする予定です

---

typed-ffmpeg の概要と重要性

• typed-ffmpeg は、FFmpeg をモダンで Pythonic な方法 で制御できるオープンソースパッケージです
• Python 標準ライブラリだけで作られているため 依存関係がなく、高い安全性と互換性を備えているのが特長です
• 最大の利点 は、豊富な型サポートと簡潔な文法、自動補完、インラインドキュメントにより、複雑な FFmpeg フィルター作業を 簡単かつ安全にコード化 できることです
• 従来の ffmpeg-python の制約、特に IDE 連携や型不足を補い、JSON シリアライズ、フィルターグラフの自動検証、視覚的グラフなど多くの新機能を提供します
• 実際のラッピングや自動化の過程では GPT-3 と Copilot が開発生産性に貢献しましたが、コード生成の中核では 信頼性の高い従来型のコード生成 を採用した点も特徴です

主な機能(Features)

• 依存関係なし: Python 標準ライブラリのみを使用
• 直感的なインターフェース: Python コードで FFmpeg フィルターグラフを簡単に構成可能
• 包括的なフィルター対応: ほとんどの FFmpeg フィルターと IDE 自動補完をサポート
• 統合ドキュメント: インライン docstring により外部ドキュメント参照の必要性を最小化
• 堅牢な型サポート: 静的・動的型チェックでコードの信頼性とデバッグ容易性を強化
• フィルターグラフのシリアライズ: JSON 形式でフィルターグラフの保存・復元が可能
• グラフ可視化: graphviz によるフィルターグラフの図式化を提供
• 自動検証と補正: フィルターグラフ内のエラー検出と自動修正機能
• 入出力オプション拡張: 多様な codec/フォーマット対応で FFmpeg の活用範囲を拡大
• 部分評価機能: フィルターグラフのモジュール化と再利用性の向上を支援

今後予定されている機能

• FFmpeg 6.0 以外のバージョンに対する 幅広い互換性 を拡大予定です
• より多くの複雑なフィルター への対応を予定しており、継続的な機能拡張を進めています

クイック例(Quick Usage)

import ffmpeg  
  
# 動画を左右反転して出力  
f = (  
    ffmpeg  
    .input(filename='input.mp4')  
    .hflip()  
    .output(filename='output.mp4')  
)  
f  

• 複雑な例として、複数区間を切り出して overlay と drawbox を追加するフィルターグラフも表現できます

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  

• さらに多くの例と詳細な説明はドキュメントで確認できます

インタラクティブプレイグラウンド

• ブラウザ上で FFmpeg フィルターやコマンドを試し、結果の可視化、さまざまな入出力オプションのテスト、インタラクティブなサンプル学習、フィルターグラフの共有などが可能です
• ローカル環境がなくても、FFmpeg フィルターチェーンのプロトタイピングや学習に非常に効果的な環境です

プロジェクト背景と謝辞

• GPT-3 の FFmpeg ドキュメントをもとにした SDK 自動生成のアイデアから着想を得て始まったプロジェクトです
• コア生成は信頼性確保のため、手作業によるコード生成方式へ切り替えました
• 開発過程では GitHub Copilot と GPT-3 が開発効率向上に貢献しました
• ffmpeg-python は API スタイルとデザインの着想源となり、設計に大きな影響を与えました
• このプロジェクトは開発者の子ども Austin に捧げられています

ドキュメントと参考情報

• より詳細な情報と高度な機能は公式 Documentation で確認できます
• 単一パッケージのインストールに加えて、グラフ可視化などの追加機能のために別オプションで graphviz を利用できます
• ffmpeg-python との互換性のため、別バージョン (typed-ffmpeg-compatible) も提供されています

[GN⁺]

Hacker Newsのコメント

• すべてのコマンドラインオプションのパーサーやツールキットは、それぞれ独立した完全な構成言語だという現実認識が、人々にあまりにも過小評価されているという指摘であり、各ツールはその言語上で動く個別のプログラムや設定として認識する必要があることを強調している。Unixシェルでは単語分割規則や表面的に似た構文のせいで、実際には非常に多様であるにもかかわらず、人々が過度に一様だと誤解している現象も説明している。個人的には、/usr/bin 内のすべてのプログラムを --help、-h オプション付きで試したとき、期待したヘルプを得られなかった失敗率がかなり高かったという経験も共有している。ffmpeg のように複雑なツールに型情報を導入すれば、こうした多様性の問題への認識を深めると同時に、実用的な利点ももたらせるはずだという励ましのメッセージでもある。
  • man foo のほうが foo --help や foo -h よりも、はるかに信頼できて有用だったという経験の共有。
  • 初学者として、具体的にどこで衝突が起きたのか、その対立点がどこだったのか気になるという反応。
• プロジェクトが活発に開発されている点は印象的だが、ffmpeg-python と似た問題をいくつか抱えているようにも見える。たとえば、入力なしで動作する color のようなフィルタをどう指定するのかが見当たらない。また、GUI アプリで CMD ウィンドウが開くのを防ぐための subprocess.CREATE_NO_WINDOW のような Popen フラグを指定する方法もない。ffmpeg.compile() 後に手動実行することで ffmpeg 側は回避できるが、ffmpeg.probe() ではその方法が使えない点にも触れている。さらに、ソースフィルタの問題は ffmpeg.sources.color で把握したものの、任意のソースフィルタを vfilter / afilter のように使う方法があるのか知りたいとしている。
• Python でスクリプトベースの動画処理を進めるなら、Vapoursynth の利用を強く勧めるという意見。動画処理を目的に最初から設計されたツールであり、活発なメンテナンスとコミュニティ、ツールのエコシステムも充実している。ffmpeg の CLI に縛られず自由に使えるとして、Vapoursynth のホームページ へのリンクも共有している。
• 本当に素晴らしいアイデアで、個人的にはこのプロジェクトの TypeScript 版を期待しているというコメント。
  • Jules のプレビューツールで TypeScript 版がどうなるか簡単に試してみた。実装はかなり単純だが、もっと読みやすい形も思いつく。ごく短いプロンプトにしては結果は悪くなく、興味のある人向けに multi-language-codegen ブランチのコード を共有している。
  • TypeScript 版も出たら本当にうれしいという意見。
  • TypeScript を「神の言語」にたとえるユーモア。
  • TypeScript への言及が公式ドキュメントにはなかったという指摘。
• ffmpeg のコマンドラインの形を機械可読に記述し、さまざまな言語向けコードを自動生成できるようにすべきだという考え。
• ビジュアルツールが特に印象的で、FFMPEG はモジュール化 / ビジュアルプログラミングによって確実にアクセシビリティが向上しそうな題材に見えるという意見。すべての機能を把握していないユーザーが多いため、この方式が助けになる好例だとしている。UX 面では DEL キーでノード / エッジを削除できることを期待していたが、それが効かなかったのは少し残念だったとも述べている。全体としては素晴らしい体験だったとのこと。
  • ついに MS の DirectShow GraphEdit に似たツールが現れたのがうれしいという反応。
• 本当に興味深いプロジェクトで、個々のコマンド間でフレームをパイプで受け渡す機能まで対応すれば、FFMpeg 活用の真の拡張性が開けるだろうという意見。
• このプロジェクトがあまりに素晴らしいので、視覚的に動画編集ができる newbeelearn のビデオエディターツール もあわせて紹介したいというコメント。そのツールでも ffmpeg コマンドを自動生成できるという。
• 良い仕事だ、という短い応援。
• プロジェクトがとても素晴らしく見えるという感想。