typed-ffmpeg - Interfaz tipada para FFmpeg y editor visual de filtros

 (github.com/livingbio)
5 puntos por GN⁺ 2025-05-31 | 1 comentarios | Compartir por WhatsApp
  • typed-ffmpeg es una interfaz con seguridad de tipos para trabajar con FFmpeg en Python y TypeScript, y ofrece tipos detallados y documentación para grafos de filtros complejos
  • Está inspirado en ffmpeg-python, pero añade funciones como autocompletado en el IDE, tipado integral, serialización JSON de grafos de filtros y validación automática de FFmpeg
  • La v4 ofrece paquetes de PyPI según la versión de FFmpeg 5.x~8.x, y typed-ffmpeg por defecto instala los bindings más recientes de FFmpeg 8.x
  • El paquete de Python funciona solo con la biblioteca estándar, pero la visualización de grafos y el parseo de CLI deben instalarse como extras opcionales [graph] y [parse], respectivamente
  • Se ofrece un Interactive Playground para probar filtros y comandos en el navegador y ver el grafo en tiempo real, lo que permite aprender y hacer prototipos sin entorno local

La interfaz de FFmpeg que ofrece typed-ffmpeg

  • typed-ffmpeg ofrece una interfaz moderna y con seguridad de tipos para FFmpeg en Python y TypeScript
  • Soporta tipos detallados y documentación para filtros complejos, y compensa limitaciones comunes de ffmpeg-python, como la falta de integración con el IDE y la ausencia de tipado integral
  • Entre sus nuevas funciones están la serialización JSON del grafo de filtros y la validación automática de FFmpeg
  • La documentación está disponible en Documentation

Funciones principales

  • Zero Dependencies: está construido solo con la biblioteca estándar de Python, lo que mejora la compatibilidad y la seguridad
  • La interfaz Pythonic simplifica la construcción de grafos de filtros
  • Soporta de forma nativa la mayoría de los filtros de FFmpeg y ofrece autocompletado en el IDE
  • Permite consultar de inmediato el uso de los filtros mediante docstrings inline
  • Ofrece verificación de tipos estática y dinámica para mejorar la confiabilidad del código y la experiencia de desarrollo
  • Permite guardar y volver a cargar grafos de filtros en formato JSON
  • La visualización de grafos con graphviz ayuda a entenderlos y depurarlos
  • Ofrece funciones de apoyo para identificar y corregir errores en grafos de filtros
  • Proporciona una interfaz más integral que incluye opciones de entrada y salida, además de códecs y formatos adicionales
  • Mediante evaluación parcial, permite construir y reutilizar grafos de filtros de forma modular
  • Incluye soporte integrado para analizar archivos multimedia con ffprobe de FFmpeg y extraer metadatos mediante interfaces de diccionario y dataclass

Estructura de paquetes por versión de FFmpeg

  • typed-ffmpeg v4 ofrece paquetes separados de PyPI según la versión principal de FFmpeg
    • typed-ffmpeg: versión más reciente, bindings para FFmpeg 8.x
    • typed-ffmpeg-v5: bindings para FFmpeg 5.x
    • typed-ffmpeg-v6: bindings para FFmpeg 6.x
    • typed-ffmpeg-v7: bindings para FFmpeg 7.x
    • typed-ffmpeg-v8: bindings para FFmpeg 8.x
    • ffmpeg-core: runtime compartido que se instala automáticamente
  • Todos los paquetes exponen el mismo namespace ffmpeg, por lo que la forma del código es la misma sin importar qué paquete de versión se instale
  • Para ajustarlo a la versión de FFmpeg instalada, primero hay que comprobarla con ffmpeg -version | head -1 y luego instalar el paquete correspondiente
  • La estructura de paquetes de v4 puede consultarse en v4 Package Architecture
  • Al actualizar desde typed-ffmpeg 3.x, conviene consultar la Migration Guide

Instalación y extras opcionales

  • Los bindings más recientes para FFmpeg 8.x se instalan con el siguiente comando
pip install typed-ffmpeg
  • Los bindings para versiones específicas de FFmpeg se instalan como paquetes separados
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
  • Las funciones opcionales se instalan como extras
    • [graph]: visualización de grafos basada en Graphviz
    • [parse]: parseo de CLI y soporte para compile_as_python()
  • El extra [parse] instala los datos de caché por versión, desde ffmpeg-data-v5 hasta ffmpeg-data-v8, necesarios para que ffmpeg.compile.compile_cli.parse() reconstruya grafos de filtros a partir de la línea de comandos de FFmpeg
  • La mayoría de los usuarios no necesitan el extra [parse]
  • FFmpeg debe estar instalado en el sistema
  • Si se necesita instalarlo junto con ffmpeg-python, hay que usar typed-ffmpeg-compatible para evitar conflictos de nombre de módulo, e importar con import typed_ffmpeg as ffmpeg

Bindings de TypeScript y ejemplo de uso

  • Los bindings de TypeScript son una función experimental y ofrecen paquetes npm según la versión principal de FFmpeg
    • @typed-ffmpeg/core: runtime principal para Node.js y ESM de navegador
    • @typed-ffmpeg/v5: bindings para FFmpeg 5.x
    • @typed-ffmpeg/v6: bindings para FFmpeg 6.x
    • @typed-ffmpeg/v7: bindings para FFmpeg 7.x
    • @typed-ffmpeg/v8: bindings para FFmpeg 8.x
  • Los bindings más recientes de FFmpeg se instalan con el siguiente comando
npm install @typed-ffmpeg/core @typed-ffmpeg/v8
  • La API de TypeScript refleja la API de Python, pero usa patrones idiomáticos de TypeScript, como objetos de opciones, en lugar de argumentos con nombre
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 incluye bundles CJS, ESM y ESM seguro para navegador, con selección automática mediante el campo exports
  • Cada paquete de versión incluye anotaciones JSDoc que muestran la disponibilidad de filtros según la versión de FFmpeg

Flujo de uso en Python y playground

  • El ejemplo básico de uso consiste en analizar un archivo multimedia con ffmpeg.probe() y luego reflejar horizontalmente input.mp4 para generar output.mp4
  • Los ejemplos complejos construyen grafos de filtros combinando trim, concat, overlay y drawbox
  • Hay más ejemplos disponibles en Usage
  • Interactive Playground ofrece un entorno en el navegador para ejecutar typed-ffmpeg directamente
    • Experimentar con filtros y comandos de FFmpeg
    • Visualización en tiempo real del grafo de filtros
    • Pruebas de configuración de entrada y salida
    • Aprendizaje con ejemplos interactivos
    • Compartir grafos de filtros
  • El playground es ideal para aprender cadenas de filtros de FFmpeg y hacer prototipos sin configurar un entorno local

Forma de desarrollo y contexto

  • La idea inicial era generar directamente un SDK de filtros de FFmpeg a partir de la documentación de FFmpeg usando GPT-3
  • Durante el desarrollo, se encontraron límites para automatizar todo el trabajo solo con GPT-3, por lo que se cambió a un enfoque tradicional de generación de código para completar el SDK
  • GitHub Copilot y GPT-3 ayudaron a acelerar el desarrollo y ahorrar tiempo
  • El estilo de API y las ideas de diseño del proyecto ffmpeg-python influyeron en el desarrollo de typed-ffmpeg
  • Las dependencias de desarrollo se gestionan con pyproject.toml y uv.lock, y el entorno de desarrollo se instala con el siguiente comando
uv pip install --group dev

Lecturas relacionadas

1 comentarios

 
GN⁺ 2025-05-31
Opiniones de Hacker News

  • Se subestima que todas las herramientas/parsers de opciones de línea de comandos son, en la práctica, lenguajes de configuración completos por derecho propio, y que cada herramienta debe verse como un “programa/configuración” escrito en ese lenguaje.
    Como el shell de Unix hace la separación de palabras antes de la interpretación final de argv, muchos dialectos parecen similares por fuera, pero en realidad son vertiginosamente diversos.
    Hace un tiempo ejecuté --help y -h en todos los programas de /usr/bin, y la proporción en la que no obtuve ayuda útil fue bastante alta.
    Por eso, ponerle tipos a una herramienta compleja como ffmpeg tiene ventajas prácticas y también ayuda a exponer mejor esta realidad.

    • Quizá no sea el punto central que se buscaba, pero siento que man foo es más confiable y útil que foo --help o foo -h.
    • Desde el punto de vista de alguien que recién empieza, me da curiosidad dónde estuvieron los conflictos.

  • Es interesante y está bien que se desarrolle activamente, pero parece tener algunos problemas similares a ffmpeg-python.
    No parece haber una forma de especificar un filtro sin entrada como "color", ni una forma de pasarle flags a Popen, como subprocess.CREATE_NO_WINDOW, para evitar que se abra una ventana de CMD en una app GUI de Windows.
    Con ffmpeg en sí se puede usar ffmpeg.compile() y luego ejecutarlo directamente, pero con ffprobe, que usa ffmpeg.probe(), es difícil hacerlo así.
    Edición: resolví lo de los filtros fuente con ffmpeg.sources.color. Me pregunto si también hay una forma de usar un filtro fuente arbitrario, así como se usa vfilter/afilter para filtros generales.

  • Si vas a hacer procesamiento de video basado en scripts en Python, recomiendo fuertemente ir directo por Vapoursynth.
    Fue creado desde el inicio para ese propósito, se mantiene activamente, tiene una comunidad y herramientas decentes, y no está atado a la interfaz de línea de comandos de ffmpeg.
    https://www.vapoursynth.com/

  • typed-ffmpeg presenta como puntos clave “seguridad de tipos completa, autocompletado y validación”; entonces, ¿alguien puede explicar por qué tiene sentido pasar el ancho y alto, o las coordenadas x/y, como cadenas?

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

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

    • Parece que esos valores no son enteros, sino expresiones de ffmpeg que se evalúan como enteros.
      Por ejemplo, en la documentación de ffmpeg hay un ejemplo como este: 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
      Para comprobar tipos correctamente en eso, probablemente haría falta algún tipo de DSL.

  • Es una buena idea. Personalmente, espero una versión en TypeScript.

    • Probé pedirle a la vista previa de Jules que lo hiciera, y la implementación fue bastante ingenua.
      Se me ocurren enfoques más legibles, pero considerando que salió de un prompt muy corto, no está tan mal.
      Si te da curiosidad, los cambios están en esta rama: https://github.com/matt-hensley/typed-ffmpeg/tree/feature/mu...
    • TypeScript no se menciona en ninguna parte.

  • Creo que debería existir una descripción de la línea de comandos de ffmpeg en un formato legible por máquina para poder generarla en varios lenguajes.

  • La herramienta visual se ve especialmente excelente. Como es difícil conocer todas las piezas que ofrece FFMPEG, parece un ejemplo donde la programación modular/visual realmente puede ayudar.
    Como pequeño comentario de UX, en Win11/Chrome esperaba poder borrar nodos o aristas con la tecla DEL.
    En general, está genial.

    • Por fin salió algo parecido a DirectShow GraphEdit de MS.

  • Se ve genial, pero me pregunto si admite conexión de frames por tuberías entre comandos completos.
    Personalmente, creo que a partir de ahí se empiezan a abrir las formas más interesantes de los flujos de FFMpeg.

  • Bien. Si quieres editar videos visualmente, también puedes probar una herramienta que hice: https://newbeelearn.com/tools/videoeditor/
    Genera comandos de ffmpeg.