typed-ffmpeg – Typisierte Schnittstelle und visueller Filter-Editor für FFmpeg

 (github.com/livingbio)
5 Punkte von GN⁺ 2025-05-31 | 1 Kommentare | Auf WhatsApp teilen
  • typed-ffmpeg ist eine typsichere Schnittstelle für den Umgang mit FFmpeg in Python und TypeScript und bietet detaillierte Typen und Dokumentation für komplexe Filtergraphen
  • Inspiriert von ffmpeg-python, ergänzt aber Funktionen wie IDE-Autovervollständigung, umfassende Typisierung, JSON-Serialisierung von Filtergraphen und automatische FFmpeg-Validierung
  • v4 stellt PyPI-Pakete für FFmpeg 5.x bis 8.x bereit; das Standardpaket typed-ffmpeg installiert Bindings für das aktuelle FFmpeg 8.x
  • Das Python-Paket funktioniert nur mit der Standardbibliothek, Graph-Visualisierung und CLI-Parsing müssen jedoch jeweils als optionale Extras [graph] und [parse] installiert werden
  • Ein Interactive Playground ermöglicht es, Filter und Befehle im Browser auszuprobieren und Graphen in Echtzeit anzusehen, sodass Lernen und Prototyping ohne lokale Umgebung möglich sind

Die von typed-ffmpeg bereitgestellte FFmpeg-Schnittstelle

  • typed-ffmpeg stellt eine moderne, typsichere Schnittstelle für FFmpeg in Python und TypeScript bereit
  • Es unterstützt detaillierte Typen und Dokumentation für komplexe Filter und gleicht typische Grenzen von ffmpeg-python aus, etwa fehlende IDE-Integration und keine umfassende Typisierung
  • Als neue Funktionen bietet es JSON-Serialisierung von Filtergraphen und automatische FFmpeg-Validierung
  • Die Dokumentation ist unter Documentation verfügbar

Hauptfunktionen

  • Zero Dependencies: Besteht nur aus der Python-Standardbibliothek und erhöht dadurch Kompatibilität und Sicherheit
  • Vereinfacht den Aufbau von Filtergraphen mit einer pythonic Schnittstelle
  • Unterstützt die meisten FFmpeg-Filter nativ und bietet IDE-Autovervollständigung
  • Filterverwendung kann direkt über Inline-Docstrings nachgeschlagen werden
  • Statische und dynamische Typprüfung verbessern Code-Zuverlässigkeit und Developer Experience
  • Filtergraphen können im JSON-Format gespeichert und erneut geladen werden
  • Graph-Visualisierung mit graphviz hilft beim Verstehen und Debugging
  • Bietet Unterstützung beim Identifizieren und Beheben von Fehlern in Filtergraphen
  • Bietet eine umfassendere Schnittstelle inklusive Eingabe- und Ausgabeoptionen sowie zusätzlicher Codecs und Formate
  • Durch partielle Auswertung lassen sich Filtergraphen modular aufbauen und wiederverwenden
  • Integrierte Unterstützung zur Analyse von Mediendateien mit FFmpegs ffprobe; Metadaten werden über Dictionary- und dataclass-Schnittstellen extrahiert

Paketstruktur nach FFmpeg-Version

  • typed-ffmpeg v4 stellt separate PyPI-Pakete nach FFmpeg-Hauptversion bereit
    • typed-ffmpeg: aktuelle Version, Bindings für FFmpeg 8.x
    • typed-ffmpeg-v5: Bindings für FFmpeg 5.x
    • typed-ffmpeg-v6: Bindings für FFmpeg 6.x
    • typed-ffmpeg-v7: Bindings für FFmpeg 7.x
    • typed-ffmpeg-v8: Bindings für FFmpeg 8.x
    • ffmpeg-core: gemeinsame Runtime, wird automatisch installiert
  • Alle Pakete exponieren denselben ffmpeg-Namespace, daher bleibt die Codeform unabhängig vom installierten Versionspaket gleich
  • Um zur installierten FFmpeg-Version zu passen, prüft man die Version mit ffmpeg -version | head -1 und installiert anschließend das entsprechende Paket
  • Die Paketstruktur von v4 ist in der Dokumentation v4 Package Architecture beschrieben
  • Beim Upgrade von typed-ffmpeg 3.x sollte der Migration Guide beachtet werden

Installation und optionale Extras

  • Die aktuellen Bindings für FFmpeg 8.x werden mit folgendem Befehl installiert
pip install typed-ffmpeg
  • Bindings für eine bestimmte FFmpeg-Version werden als separates Paket installiert
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
  • Optionale Funktionen werden als Extras installiert
    • [graph]: Graph-Visualisierung auf Basis von Graphviz
    • [parse]: CLI-Parsing und Unterstützung für compile_as_python()
  • Das Extra [parse] installiert die versionsspezifischen Cache-Daten ffmpeg-data-v5 bis ffmpeg-data-v8, die ffmpeg.compile.compile_cli.parse() benötigt, um Filtergraphen aus FFmpeg-Befehlszeilen zu rekonstruieren
  • Die meisten Nutzer benötigen das Extra [parse] nicht
  • FFmpeg muss auf dem System installiert sein
  • Wenn es gleichzeitig mit ffmpeg-python installiert werden muss, installiert man typed-ffmpeg-compatible, um Modulnamenskonflikte zu vermeiden, und verwendet import typed_ffmpeg as ffmpeg

TypeScript-Bindings und Nutzungsbeispiel

  • Die TypeScript-Bindings sind ein experimentelles Feature und stellen npm-Pakete je FFmpeg-Hauptversion bereit
    • @typed-ffmpeg/core: Core-Runtime für Node.js und Browser-ESM
    • @typed-ffmpeg/v5: Bindings für FFmpeg 5.x
    • @typed-ffmpeg/v6: Bindings für FFmpeg 6.x
    • @typed-ffmpeg/v7: Bindings für FFmpeg 7.x
    • @typed-ffmpeg/v8: Bindings für FFmpeg 8.x
  • Die aktuellen FFmpeg-Bindings werden mit folgendem Befehl installiert
npm install @typed-ffmpeg/core @typed-ffmpeg/v8
  • Die TypeScript-API spiegelt die Python-API wider, verwendet aber TypeScript-typische Muster wie Optionsobjekte statt Keyword-Argumenten
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 enthält CJS-, ESM- und browsersichere ESM-Bundles, die über das Feld exports automatisch ausgewählt werden
  • Jedes Versionspaket enthält JSDoc-Kommentare, die die Verfügbarkeit von Filtern je FFmpeg-Version angeben

Python-Nutzungsablauf und Playground

  • Das grundlegende Nutzungsbeispiel analysiert eine Mediendatei mit ffmpeg.probe() und gibt input.mp4 horizontal gespiegelt als output.mp4 aus
  • Komplexe Beispiele kombinieren trim, concat, overlay und drawbox, um Filtergraphen aufzubauen
  • Weitere Beispiele finden sich in der Dokumentation Usage
  • Der Interactive Playground bietet eine Umgebung, in der typed-ffmpeg direkt im Browser ausgeführt werden kann
    • Experimente mit FFmpeg-Filtern und Befehlen
    • Echtzeit-Visualisierung von Filtergraphen
    • Testen von Eingabe- und Ausgabekonfigurationen
    • Lernen anhand interaktiver Beispiele
    • Teilen von Filtergraphen
  • Der Playground eignet sich zum Lernen und Prototyping von FFmpeg-Filterketten ohne Einrichtung einer lokalen Umgebung

Entwicklungsansatz und Hintergrund

  • Die ursprüngliche Idee war, mit GPT-3 direkt aus der FFmpeg-Dokumentation ein FFmpeg-Filter-SDK zu generieren
  • Während der Entwicklung zeigte sich, dass es Grenzen gab, die Arbeit allein mit GPT-3 vollständig zu automatisieren; zur Fertigstellung des SDK wurde auf einen traditionellen Codegenerierungsansatz umgestellt
  • GitHub Copilot und GPT-3 halfen, die Entwicklung zu beschleunigen und Zeit zu sparen
  • API-Stil und Designideen des Projekts ffmpeg-python beeinflussten die Entwicklung von typed-ffmpeg
  • Entwicklungsabhängigkeiten werden über pyproject.toml und uv.lock verwaltet; die Entwicklungsumgebung wird mit folgendem Befehl installiert
uv pip install --group dev

Verwandte Beiträge

1 Kommentare

 
GN⁺ 2025-05-31
Meinungen auf Hacker News

  • Es wird unterschätzt, dass im Grunde jeder Parser/jedes Tool für Kommandozeilenoptionen eine eigene vollständige Konfigurationssprache ist und einzelne Tools als „Programme/Konfigurationen“ in dieser Sprache betrachtet werden sollten.
    Weil die Unix-Shell vor der abschließenden Interpretation von argv die Worttrennung übernimmt, sehen unzählige Dialekte äußerlich nur ähnlich aus; tatsächlich sind sie aber schwindelerregend vielfältig.
    Ich habe früher einmal für alle Programme in /usr/bin --help und -h ausgeführt, und der Anteil, bei dem man keine nützliche Hilfe bekam, war ziemlich hoch.
    Deshalb hat es nicht nur praktische Vorteile, ein so komplexes Tool wie ffmpeg mit Typen zu versehen, sondern es hilft auch, diese Realität besser sichtbar zu machen.

    • Auch wenn das wohl nicht der eigentliche Kernpunkt ist: man foo wirkt auf mich zuverlässiger und nützlicher als foo --help oder foo -h.
    • Aus Sicht von Einsteigern wäre interessant, wo es zu Konflikten kam.

  • Es ist interessant und schön zu sehen, dass es aktiv entwickelt wird, aber es scheint einige ähnliche Probleme wie ffmpeg-python zu haben.
    Es scheint keine Möglichkeit zu geben, einen Filter ohne Eingabe wie "color" anzugeben, und offenbar auch keine Möglichkeit, Flags an Popen zu übergeben, etwa subprocess.CREATE_NO_WINDOW, um in einer Windows-GUI-App zu verhindern, dass ein CMD-Fenster erscheint.
    Bei ffmpeg selbst kann man nach ffmpeg.compile() direkt ausführen, aber bei ffprobe, das ffmpeg.probe() verwendet, ist das schwierig.
    Edit: Den Source-Filter habe ich mit ffmpeg.sources.color gelöst. Ich frage mich, ob es auch eine Möglichkeit gibt, beliebige Source-Filter zu verwenden, so wie man für normale Filter vfilter/afilter nutzt.

  • Wenn man in Python skriptbasierte Videoverarbeitung machen will, würde ich dringend empfehlen, stattdessen direkt zu Vapoursynth zu gehen.
    Es wurde von Anfang an genau für diesen Zweck gebaut, wird aktiv gepflegt, hat eine ordentliche Community und gute Tools und ist nicht an das Kommandozeileninterface von ffmpeg gebunden.
    https://www.vapoursynth.com/

  • typed-ffmpeg stellt „vollständige Typsicherheit, Autovervollständigung und Validierung“ in den Mittelpunkt. Kann jemand erklären, warum es hier sinnvoll ist, Breite und Höhe bzw. x/y-Koordinaten als Strings zu übergeben?

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

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

    • Vermutlich, weil diese Werte keine Integer sind, sondern ffmpeg-Ausdrücke, die zu Integern ausgewertet werden.
      In der ffmpeg-Dokumentation gibt es zum Beispiel dieses Beispiel: 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
      Um das ordentlich typzuprüfen, bräuchte man wohl eine Art DSL.

  • Gute Idee. Persönlich hoffe ich auf eine TypeScript-Version.

    • Ich habe es mit der Jules-Vorschau ausprobiert, und die Implementierung war ziemlich naiv.
      Mir fallen lesbarere Ansätze ein, aber wenn man bedenkt, dass es mit einem sehr kurzen Prompt erstellt wurde, ist es gar nicht so schlecht.
      Falls es jemanden interessiert: Die Änderungen sind in diesem Branch: https://github.com/matt-hensley/typed-ffmpeg/tree/feature/mu...
    • TypeScript wird nirgendwo erwähnt.

  • Es bräuchte wohl eine maschinenlesbare Beschreibung der ffmpeg-Kommandozeile, damit man sie für mehrere Sprachen generieren kann.

  • Das visuelle Tool sieht besonders großartig aus. FFMPEG wirkt wie ein gutes Beispiel dafür, wo modulare/visuelle Programmierung wirklich helfen kann, weil es schwer ist, alle angebotenen Bausteine zu kennen.
    Kleine UX-Anmerkung: Unter Win11/Chrome hätte ich erwartet, Knoten oder Kanten mit der Entf-Taste löschen zu können.
    Insgesamt cool.

    • Damit gibt es nun endlich etwas Ähnliches wie Microsofts DirectShow GraphEdit.

  • Cool, aber ich frage mich, ob es Frame-Pipe-Verbindungen zwischen ganzen Befehlen unterstützt.
    Meiner Meinung nach beginnen ab da die interessantesten Formen von FFMpeg-Flows.

  • Gut. Wenn du Videos visuell bearbeiten möchtest, kannst du auch mein Tool ausprobieren: https://newbeelearn.com/tools/videoeditor/
    Es erzeugt ffmpeg-Befehle.