typed-ffmpeg - une interface typée pour FFmpeg avec éditeur visuel de filtres

 (github.com/livingbio)
5 points par GN⁺ 2025-05-31 | 1 commentaires | Partager sur WhatsApp
  • typed-ffmpeg est une interface type-safe pour manipuler FFmpeg en Python et en TypeScript, avec des types détaillés et une documentation pour les graphes de filtres complexes
  • Inspiré de ffmpeg-python, le projet ajoute des fonctions comme l’autocomplétion IDE, un typage complet, la sérialisation JSON des graphes de filtres et la validation automatique de FFmpeg
  • La v4 fournit des paquets PyPI distincts selon les versions FFmpeg 5.x à 8.x, et le paquet typed-ffmpeg par défaut installe les bindings les plus récents pour FFmpeg 8.x
  • Le paquet Python fonctionne uniquement avec la bibliothèque standard, mais la visualisation des graphes et le parsing CLI doivent être installés séparément via les extras [graph] et [parse]
  • Un Interactive Playground permet d’expérimenter des filtres et des commandes dans le navigateur, avec visualisation du graphe en temps réel, pour apprendre et prototyper sans environnement local

L’interface FFmpeg proposée par typed-ffmpeg

  • typed-ffmpeg fournit une interface moderne et type-safe pour FFmpeg en Python et en TypeScript
  • Il prend en charge des types détaillés et une documentation pour les filtres complexes, et corrige les limites souvent attribuées à ffmpeg-python, comme le manque d’intégration avec les IDE et l’absence de typage complet
  • Parmi les nouvelles fonctions figurent la sérialisation JSON des graphes de filtres et la validation automatique de FFmpeg
  • La documentation est disponible sur Documentation

Principales fonctionnalités

  • Zero Dependencies : repose uniquement sur la bibliothèque standard Python, ce qui améliore la compatibilité et la sécurité
  • Une interface Pythonic qui simplifie la composition des graphes de filtres
  • Prise en charge native de la plupart des filtres FFmpeg, avec autocomplétion IDE
  • Des docstrings inline pour consulter immédiatement l’usage des filtres
  • Vérifications de types statiques et dynamiques pour améliorer la fiabilité du code et l’expérience de développement
  • Possibilité d’enregistrer et de recharger les graphes de filtres au format JSON
  • Visualisation des graphes avec graphviz pour faciliter la compréhension et le débogage
  • Aides à l’identification et à la correction des erreurs dans les graphes de filtres
  • Une interface plus complète incluant options d’entrée et de sortie, codecs supplémentaires et formats
  • Évaluation partielle pour composer et réutiliser les graphes de filtres de manière modulaire
  • Prise en charge intégrée de l’analyse des fichiers média via ffprobe de FFmpeg, avec extraction des métadonnées via des interfaces dictionnaire et dataclass

Structure des paquets selon la version de FFmpeg

  • typed-ffmpeg v4 fournit des paquets PyPI séparés pour chaque version majeure de FFmpeg
    • typed-ffmpeg : dernière version, bindings FFmpeg 8.x
    • typed-ffmpeg-v5 : bindings FFmpeg 5.x
    • typed-ffmpeg-v6 : bindings FFmpeg 6.x
    • typed-ffmpeg-v7 : bindings FFmpeg 7.x
    • typed-ffmpeg-v8 : bindings FFmpeg 8.x
    • ffmpeg-core : runtime partagé, installé automatiquement
  • Tous les paquets exposent le même namespace ffmpeg, donc la forme du code reste identique quelle que soit la version installée
  • Pour l’aligner avec la version de FFmpeg installée, il faut vérifier la version avec ffmpeg -version | head -1, puis installer le paquet correspondant
  • La structure des paquets v4 est détaillée dans v4 Package Architecture
  • Pour une mise à niveau depuis typed-ffmpeg 3.x, voir le Migration Guide

Installation et extras optionnels

  • Les bindings les plus récents pour FFmpeg 8.x s’installent avec la commande suivante
pip install typed-ffmpeg
  • Les bindings pour une version spécifique de FFmpeg s’installent via des paquets distincts
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
  • Les fonctions optionnelles s’installent via des extras
    • [graph] : visualisation de graphes basée sur Graphviz
    • [parse] : parsing CLI et prise en charge de compile_as_python()
  • L’extra [parse] installe les données de cache versionnées nécessaires, de ffmpeg-data-v5 à ffmpeg-data-v8, pour permettre à ffmpeg.compile.compile_cli.parse() de reconstruire un graphe de filtres à partir d’une ligne de commande FFmpeg
  • La plupart des utilisateurs n’ont pas besoin de l’extra [parse]
  • FFmpeg doit être installé sur le système
  • En cas d’installation conjointe avec ffmpeg-python, il faut installer typed-ffmpeg-compatible pour éviter les conflits de nom de module, puis utiliser import typed_ffmpeg as ffmpeg

Bindings TypeScript et exemple d’utilisation

  • Les bindings TypeScript sont expérimentaux et fournis sous forme de paquets npm distincts par version majeure de FFmpeg
    • @typed-ffmpeg/core : runtime principal pour Node.js et ESM navigateur
    • @typed-ffmpeg/v5 : bindings FFmpeg 5.x
    • @typed-ffmpeg/v6 : bindings FFmpeg 6.x
    • @typed-ffmpeg/v7 : bindings FFmpeg 7.x
    • @typed-ffmpeg/v8 : bindings FFmpeg 8.x
  • Les bindings pour la dernière version de FFmpeg s’installent avec la commande suivante
npm install @typed-ffmpeg/core @typed-ffmpeg/v8
  • L’API TypeScript reflète l’API Python, mais utilise des idiomes TypeScript comme les objets d’options au lieu des arguments nommés
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 inclut des bundles CJS, ESM et ESM sûr pour le navigateur, sélectionnés automatiquement via le champ exports
  • Chaque paquet de version inclut des annotations JSDoc indiquant la disponibilité des filtres selon la version de FFmpeg

Flux d’utilisation Python et playground

  • L’exemple d’utilisation de base suit un flux où ffmpeg.probe() analyse un fichier média, puis applique un miroir horizontal à input.mp4 pour produire output.mp4
  • Les exemples plus complexes combinent trim, concat, overlay et drawbox pour construire un graphe de filtres
  • Davantage d’exemples sont disponibles dans la documentation Usage
  • L’Interactive Playground permet d’exécuter directement typed-ffmpeg dans le navigateur
    • Expérimentation avec les filtres et les commandes FFmpeg
    • Visualisation en temps réel des graphes de filtres
    • Test des configurations d’entrée et de sortie
    • Apprentissage via des exemples interactifs
    • Partage de graphes de filtres
  • Le playground est adapté à l’apprentissage et au prototypage de chaînes de filtres FFmpeg sans configuration locale

Méthode de développement et contexte

  • L’idée initiale était de générer directement un SDK de filtres FFmpeg à partir de la documentation FFmpeg avec GPT-3
  • Au fil du développement, les limites de GPT-3 pour automatiser complètement ce travail sont apparues, ce qui a conduit à un basculement vers une approche traditionnelle de génération de code pour finaliser le SDK
  • GitHub Copilot et GPT-3 ont aidé à accélérer le développement et à gagner du temps
  • Le style d’API et les idées de conception du projet ffmpeg-python ont influencé le développement de typed-ffmpeg
  • Les dépendances de développement sont gérées via pyproject.toml et uv.lock, et l’environnement de développement s’installe avec la commande suivante
uv pip install --group dev

À lire aussi

1 commentaires

 
GN⁺ 2025-05-31
Avis sur Hacker News

  • On sous-estime le fait que tous les parseurs/outils d’options en ligne de commande constituent en réalité chacun un langage de configuration complet, et que chaque outil doit être vu comme un « programme/une configuration » écrit dans ce langage.
    Comme le shell Unix effectue le découpage en mots avant l’interprétation finale de argv, une multitude de dialectes se ressemblent en surface, alors qu’en pratique ils sont d’une diversité vertigineuse.
    Il y a quelque temps, j’ai lancé --help et -h sur tous les programmes de /usr/bin, et la proportion de cas où je n’ai pas obtenu d’aide utile était assez élevée.
    Donc ajouter des types à un outil complexe comme ffmpeg a des avantages pratiques, et aide aussi à mieux mettre en évidence cette réalité.

    • Ce n’est sans doute pas le point principal visé, mais j’ai l’impression que man foo est plus fiable et utile que foo --help ou foo -h.
    • Du point de vue d’un débutant, je me demande où se situaient les conflits.

  • C’est intéressant, et le développement actif est un bon point, mais cela semble avoir en partie les mêmes problèmes que ffmpeg-python.
    Il ne semble pas y avoir de moyen de spécifier un filtre sans entrée comme "color", ni de passer des flags à Popen pour éviter qu’une fenêtre CMD ne s’ouvre dans une application GUI Windows, comme avec subprocess.CREATE_NO_WINDOW.
    Pour ffmpeg lui-même, on peut faire ffmpeg.compile() puis l’exécuter directement, mais c’est plus difficile avec ffprobe lorsqu’on utilise ffmpeg.probe().
    Modification : j’ai résolu le cas des filtres source avec ffmpeg.sources.color. Je me demande s’il existe aussi un moyen d’utiliser un filtre source arbitraire, comme on utilise vfilter/afilter pour les filtres ordinaires.

  • Si vous faites du traitement vidéo piloté par scripts en Python, je recommande fortement de passer directement à Vapoursynth.
    Il a été conçu dès le départ pour cet usage, est activement maintenu, dispose d’une communauté et d’outils corrects, et n’est pas lié à l’interface en ligne de commande de ffmpeg.
    https://www.vapoursynth.com/

  • typed-ffmpeg met en avant comme points clés une « sécurité de type complète, l’autocomplétion et la validation » ; quelqu’un peut-il expliquer pourquoi il est pertinent de passer la largeur et la hauteur, ou les coordonnées x/y, sous forme de chaînes ?

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

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

    • Ces valeurs ne sont sans doute pas des entiers, mais des expressions ffmpeg évaluées en entiers.
      Par exemple, la documentation de ffmpeg donne cet exemple : 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
      Pour vraiment vérifier cela au niveau des types, il faudrait probablement une sorte de DSL.

  • Bonne idée. Personnellement, j’attends une version TypeScript.

    • J’ai demandé à Jules preview de s’en charger, et l’implémentation était assez naïve.
      J’ai en tête des approches plus lisibles, mais vu que cela a été produit avec un prompt très court, ce n’est pas si mauvais.
      Si ça vous intéresse, les changements sont sur cette branche : https://github.com/matt-hensley/typed-ffmpeg/tree/feature/mu...
    • TypeScript n’est mentionné nulle part.

  • Il faudrait probablement une description lisible par machine de la ligne de commande ffmpeg, afin de pouvoir générer cela pour plusieurs langages.

  • L’outil visuel a l’air particulièrement excellent. FFMPEG me semble être un cas où la programmation modulaire/visuelle peut vraiment aider, car il est difficile de connaître toutes les briques qu’il propose.
    Petite remarque UX : sous Win11/Chrome, je m’attendais à pouvoir supprimer un nœud ou une arête avec la touche SUPPR.
    Dans l’ensemble, c’est impressionnant.

    • On a donc enfin quelque chose qui ressemble au DirectShow GraphEdit de MS.

  • C’est chouette, mais je me demande s’il prend en charge les connexions de frames par pipe entre commandes complètes.
    À mon avis, c’est à partir de là que les formes les plus intéressantes de flux FFMpeg commencent à s’ouvrir.

  • Bien. Si vous voulez éditer des vidéos visuellement, vous pouvez aussi essayer l’outil que j’ai créé : https://newbeelearn.com/tools/videoeditor/
    Il génère des commandes ffmpeg.