typed-ffmpeg - FFmpeg向けの型付きインターフェースとビジュアルフィルターエディター

 (github.com/livingbio)
5 ポイント 投稿者 GN⁺ 2025-05-31 | 1件のコメント | WhatsAppで共有
  • typed-ffmpegは、PythonとTypeScriptでFFmpegを型安全に扱うためのインターフェースで、複雑なフィルターグラフに対する詳細な型とドキュメントを提供
  • ffmpeg-pythonに着想を得ているが、IDE補完、包括的な型付け、フィルターグラフのJSONシリアライズ、自動FFmpeg検証といった機能を追加
  • v4はFFmpeg 5.x〜8.x別のPyPIパッケージを提供し、デフォルトのtyped-ffmpegは最新のFFmpeg 8.xバインディングをインストール
  • Pythonパッケージは標準ライブラリだけで動作するが、グラフ可視化とCLIパースはそれぞれ[graph]、[parse]のオプションextraとしてインストールが必要
  • ブラウザ上でフィルターやコマンドを試し、リアルタイムでグラフを確認できるInteractive Playgroundが提供され、ローカル環境なしで学習とプロトタイピングが可能

typed-ffmpegが提供するFFmpegインターフェース

  • typed-ffmpegは、FFmpeg向けのモダンで型安全なインターフェースをPythonとTypeScriptに提供
  • 複雑なフィルターに対する詳細な型とドキュメントをサポートし、ffmpeg-pythonの一般的な限界とされるIDE統合の不足や包括的な型の欠如を補う
  • 新機能としてフィルターグラフのJSONシリアライズと自動FFmpeg検証を提供
  • ドキュメントはDocumentationで確認できる

主な機能

  • Zero Dependencies: Python標準ライブラリのみで構成され、互換性とセキュリティを高める
  • Pythonicなインターフェースでフィルターグラフの構築を簡素化
  • ほとんどのFFmpegフィルターを標準でサポートし、IDE補完を提供
  • インラインdocstringによりフィルターの使い方をすぐ参照できる
  • 静的・動的な型チェックを提供し、コードの信頼性と開発体験を向上
  • フィルターグラフをJSON形式で保存し、再読み込みできる
  • graphvizを活用したグラフ可視化により理解とデバッグを支援
  • フィルターグラフのエラー特定と修正支援機能を提供
  • 入出力オプション、追加コーデックやフォーマットを含む、より包括的なインターフェースを提供
  • 部分評価によりフィルターグラフをモジュール式に構成し、再利用できる
  • FFmpegのffprobeを使ったメディアファイル分析を組み込みでサポートし、辞書とdataclassインターフェースでメタデータを抽出

FFmpegバージョン別パッケージ構成

  • typed-ffmpeg v4は、FFmpegのメジャーバージョン別に個別のPyPIパッケージを提供
    • typed-ffmpeg: 最新版、FFmpeg 8.xバインディング
    • typed-ffmpeg-v5: FFmpeg 5.xバインディング
    • typed-ffmpeg-v6: FFmpeg 6.xバインディング
    • typed-ffmpeg-v7: FFmpeg 7.xバインディング
    • typed-ffmpeg-v8: FFmpeg 8.xバインディング
    • ffmpeg-core: 共有ランタイムで、自動的にインストールされる
  • すべてのパッケージは同じffmpeg名前空間を公開するため、どのバージョンのパッケージをインストールしてもコードの形は同じ
  • インストール済みのFFmpegバージョンに合わせるには、ffmpeg -version | head -1でバージョンを確認してから対応するパッケージをインストールする
  • v4のパッケージ構成はv4 Package Architectureドキュメントで確認できる
  • typed-ffmpeg 3.xからアップグレードする際はMigration Guideを参照

インストールとオプションextra

  • 最新のFFmpeg 8.xバインディングは次のコマンドでインストール
pip install typed-ffmpeg
  • 特定のFFmpegバージョン向けバインディングは個別パッケージでインストール
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
  • 選択機能はextraとしてインストール
    • [graph]: Graphvizベースのグラフ可視化
    • [parse]: CLIパースとcompile_as_python()サポート
  • [parse] extraは、ffmpeg.compile.compile_cli.parse()がFFmpegコマンドラインからフィルターグラフを再構成するために必要なバージョン別キャッシュデータffmpeg-data-v5からffmpeg-data-v8までをインストールする
  • ほとんどのユーザーに[parse] extraは不要
  • システムにFFmpegがインストールされている必要がある
  • ffmpeg-pythonと同時にインストールする必要がある場合は、typed-ffmpeg-compatibleをインストールしてモジュール名の衝突を避け、import typed_ffmpeg as ffmpegを使用する

TypeScriptバインディングと使用例

  • TypeScriptバインディングは実験的機能で、FFmpegのメジャーバージョン別npmパッケージを提供
    • @typed-ffmpeg/core: Node.jsとブラウザESM向けコアランタイム
    • @typed-ffmpeg/v5: FFmpeg 5.xバインディング
    • @typed-ffmpeg/v6: FFmpeg 6.xバインディング
    • @typed-ffmpeg/v7: FFmpeg 7.xバインディング
    • @typed-ffmpeg/v8: FFmpeg 8.xバインディング
  • 最新のFFmpegバインディングは次のコマンドでインストール
npm install @typed-ffmpeg/core @typed-ffmpeg/v8
  • TypeScript APIはPython APIを反映しつつ、キーワード引数の代わりにオプションオブジェクトのような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"]
  • @typed-ffmpeg/coreはCJS、ESM、ブラウザ安全なESMバンドルを含み、exportsフィールドで自動選択される
  • 各バージョンパッケージは、FFmpegバージョン別のフィルター利用可否を示すJSDocコメントを含む

Pythonの利用フローとプレイグラウンド

  • 基本的な使用例は、ffmpeg.probe()でメディアファイルを分析し、input.mp4を水平反転してoutput.mp4へ出力する流れ
  • 複雑な例では、trim、concat、overlay、drawboxを組み合わせてフィルターグラフを構築
  • より多くの例はUsageドキュメントで確認できる
  • Interactive Playgroundは、ブラウザ上でtyped-ffmpegを直接試せる環境を提供
    • FFmpegフィルターとコマンドの実験
    • フィルターグラフのリアルタイム可視化
    • 入出力構成のテスト
    • インタラクティブな例で学習
    • フィルターグラフの共有
  • プレイグラウンドは、ローカル環境設定なしでFFmpegフィルターチェーンを学習し、プロトタイピングするのに適している

開発手法と背景

  • 初期のアイデアは、GPT-3でFFmpegドキュメントからFFmpegフィルターSDKを直接生成することだった
  • 開発過程でGPT-3だけで作業を完全に自動化するには限界があり、SDK完成のために従来のコード生成手法へ移行
  • GitHub CopilotとGPT-3は開発速度を高め、時間を節約するのに役立った
  • ffmpeg-pythonプロジェクトのAPIスタイルと設計アイデアがtyped-ffmpeg開発に影響を与えた
  • 開発依存関係はpyproject.tomlとuv.lockで管理され、開発環境は次のコマンドでインストール
uv pip install --group dev

関連記事

1件のコメント

 
GN⁺ 2025-05-31
Hacker Newsの意見

  • すべてのコマンドラインオプションのパーサー/ツールは、実質的にはそれぞれ完全な設定言語であり、個々のツールはその言語で書かれた「プログラム/設定」だと見るべきなのに、この点は過小評価されている
    Unixシェルが最終的な argv の解釈前に単語分割を行ってくれるため、多くの方言が表面的には似て見えるだけで、実際にはめまいがするほど多様
    以前 /usr/bin のすべてのプログラムに対して --help と -h を実行してみたが、有用なヘルプが得られなかった割合はかなり高かった
    だから ffmpeg のような複雑なツールに型を付けることには実用上の利点もあり、こうした現実をよりよく浮き彫りにする助けにもなる

    • 意図した核心ではないかもしれないが、foo --help や foo -h よりも man foo のほうが信頼できて有用だと感じる
    • 初心者の立場としては、どこで衝突があったのか気になる

  • 興味深く、活発に開発されている点は良いが、ffmpeg-python と似た問題が一部あるように見える
    "color" のような入力のないフィルタを指定する方法がなさそうで、subprocess.CREATE_NO_WINDOW のようにWindows GUIアプリでCMDウィンドウが表示されないよう Popen にフラグを渡す方法もなさそう
    ffmpeg 自体は ffmpeg.compile() 後に直接実行すればよいが、ffmpeg.probe() を使う ffprobe ではそうするのが難しい
    修正: ソースフィルタは ffmpeg.sources.color で解決した。通常のフィルタで vfilter/afilter を使うように、任意のソースフィルタを使う方法もあるのか気になる

  • Pythonでスクリプトベースの動画処理をするなら、むしろVapoursynthに直行することを強く勧める
    最初からその目的に合わせて作られており、活発にメンテナンスされ、コミュニティやツールも悪くなく、ffmpeg のコマンドラインインターフェースに縛られない
    https://www.vapoursynth.com/

  • typed-ffmpeg は「完全な型安全性、オートコンプリート、検証」を中核として掲げているが、ここで幅と高さ、または x/y 座標を文字列として渡すのがなぜ妥当なのか説明してもらえる？

    .drawbox(x="50", y="50", width="120", height="120", color="red", thickness="5")

    出典: https://github.com/livingbio/typed-ffmpeg?tab=readme-ov-file...

    • それらの値は整数ではなく、整数に評価されるffmpeg式だからだと思う
      たとえばffmpegのドキュメントにはこんな例がある: drawbox=x=-t:y=0.5*(ih-iw/2.4)-t:w=iw+t*2:h=iw/2.4+t*2:t=2:c=red
      これを適切に型チェックするには、ある種のDSLが必要になりそう

  • 良いアイデア。個人的にはTypeScript版に期待している

    • Julesプレビューにやらせてみたら、実装はかなり素朴だった
      思いつくもっと読みやすいアプローチはいくつかあるが、ごく短いプロンプトで作ったことを考えると、そこまで悪くはない
      気になるなら変更点はこのブランチにある: https://github.com/matt-hensley/typed-ffmpeg/tree/feature/mu...
    • TypeScriptはどこにも言及されていない

  • 複数の言語向けに生成できるように、ffmpegコマンドラインを機械可読な形式で記述した資料が必要になりそう

  • ビジュアルツールが特に素晴らしく見える。FFMPEG は提供されている部品をすべて把握するのが難しいので、モジュール式/ビジュアルプログラミングが本当に役立ち得る例に見える
    小さなUXメモとして、Win11/ChromeではDELキーでノードやエッジを削除できると思っていた
    全体的には良い出来

    • ようやくMSの DirectShow GraphEdit に似たものが出てきたわけだ

  • 素晴らしいが、コマンド全体の間でフレームのパイプ接続をサポートしているのか気になる
    個人的には、そこからFFMpegのフローで最も興味深い形が開け始めると思っている

  • 良い。動画を視覚的に編集したいなら、私が作ったツールも試せる: https://newbeelearn.com/tools/videoeditor/
    ffmpegコマンドを生成してくれる