typed-ffmpeg - Interface tipada e editor visual de filtros para FFmpeg

 (github.com/livingbio)
5 pontos por GN⁺ 2025-05-31 | 1 comentários | Compartilhar no WhatsApp
  • typed-ffmpeg é uma interface type-safe para usar o FFmpeg em Python e TypeScript, oferecendo tipos detalhados e documentação para grafos de filtros complexos
  • Foi inspirado em ffmpeg-python, mas adiciona recursos como autocompletar na IDE, tipagem abrangente, serialização JSON de grafos de filtros e validação automática do FFmpeg
  • A v4 fornece pacotes PyPI separados para FFmpeg 5.x a 8.x, e o pacote padrão typed-ffmpeg instala os bindings mais recentes do FFmpeg 8.x
  • O pacote Python funciona apenas com a biblioteca padrão, mas visualização de grafos e parsing de CLI precisam ser instalados separadamente com os extras opcionais [graph] e [parse]
  • Há um Interactive Playground para testar filtros e comandos no navegador e ver o grafo em tempo real, permitindo aprender e prototipar sem ambiente local

A interface FFmpeg oferecida pelo typed-ffmpeg

  • typed-ffmpeg oferece uma interface moderna e type-safe para FFmpeg em Python e TypeScript
  • Suporta tipos detalhados e documentação para filtros complexos, suprindo limitações comuns do ffmpeg-python, como falta de integração com IDE e ausência de tipagem abrangente
  • Entre os novos recursos estão a serialização JSON de grafos de filtros e a validação automática do FFmpeg
  • A documentação pode ser consultada em Documentation

Principais recursos

  • Zero Dependencies: construído apenas com a biblioteca padrão do Python, aumentando compatibilidade e segurança
  • Interface pythônica para simplificar a composição de grafos de filtros
  • Suporte nativo à maioria dos filtros do FFmpeg, com autocompletar na IDE
  • Docstrings inline para consultar rapidamente o uso dos filtros
  • Verificação de tipos estática e dinâmica para melhorar a confiabilidade do código e a experiência de desenvolvimento
  • Possibilidade de salvar e recarregar grafos de filtros em formato JSON
  • Visualização de grafos com graphviz para facilitar entendimento e depuração
  • Recursos para ajudar a identificar e corrigir erros em grafos de filtros
  • Interface mais abrangente, incluindo opções de entrada e saída, codecs adicionais e formatos
  • Avaliação parcial para compor e reutilizar grafos de filtros de forma modular
  • Suporte embutido à análise de arquivos de mídia com ffprobe do FFmpeg, extraindo metadados por meio de interfaces de dicionário e dataclass

Estrutura de pacotes por versão do FFmpeg

  • O typed-ffmpeg v4 fornece pacotes PyPI separados por versão principal do FFmpeg
    • typed-ffmpeg: versão mais recente, 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 compartilhado, instalado automaticamente
  • Todos os pacotes expõem o mesmo namespace ffmpeg, então o formato do código é o mesmo independentemente do pacote de versão instalado
  • Para combinar com a versão do FFmpeg instalada, verifique a versão com ffmpeg -version | head -1 e instale o pacote correspondente
  • A estrutura de pacotes da v4 pode ser consultada em v4 Package Architecture
  • Ao atualizar a partir do typed-ffmpeg 3.x, consulte o Migration Guide

Instalação e extras opcionais

  • Os bindings mais recentes do FFmpeg 8.x podem ser instalados com o comando abaixo
pip install typed-ffmpeg
  • Bindings para versões específicas do FFmpeg são instalados como pacotes 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
  • Recursos opcionais são instalados como extras
    • [graph]: visualização de grafos baseada em Graphviz
    • [parse]: parsing de CLI e suporte a compile_as_python()
  • O extra [parse] instala os dados de cache por versão necessários para que ffmpeg.compile.compile_cli.parse() reconstrua grafos de filtros a partir da linha de comando do FFmpeg, de ffmpeg-data-v5 até ffmpeg-data-v8
  • A maioria dos usuários não precisa do extra [parse]
  • É necessário que o FFmpeg esteja instalado no sistema
  • Se precisar instalar junto com ffmpeg-python, use typed-ffmpeg-compatible para evitar conflito no nome do módulo e faça import typed_ffmpeg as ffmpeg

Bindings TypeScript e exemplo de uso

  • Os bindings TypeScript são experimentais e oferecem pacotes npm separados por versão principal do FFmpeg
    • @typed-ffmpeg/core: runtime central para Node.js e ESM no 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
  • Os bindings mais recentes do FFmpeg podem ser instalados com o comando abaixo
npm install @typed-ffmpeg/core @typed-ffmpeg/v8
  • A API TypeScript espelha a API Python, mas usa padrões idiomáticos de TypeScript, como objetos de opções, no lugar de argumentos nomeados
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 inclui bundles CJS, ESM e ESM seguro para navegador, com seleção automática pelo campo exports
  • Cada pacote de versão inclui anotações JSDoc que indicam a disponibilidade de filtros por versão do FFmpeg

Fluxo de uso em Python e playground

  • O exemplo de uso básico segue o fluxo de analisar um arquivo de mídia com ffmpeg.probe() e gerar output.mp4 espelhando horizontalmente input.mp4
  • Exemplos mais complexos compõem grafos de filtros combinando trim, concat, overlay e drawbox
  • Mais exemplos podem ser consultados em Usage
  • O Interactive Playground oferece um ambiente para executar o typed-ffmpeg diretamente no navegador
    • Experimentar filtros e comandos do FFmpeg
    • Visualização em tempo real do grafo de filtros
    • Testes de configuração de entrada e saída
    • Aprendizado com exemplos interativos
    • Compartilhamento de grafos de filtros
  • O playground é adequado para aprender cadeias de filtros do FFmpeg e fazer prototipagem sem configurar um ambiente local

Forma de desenvolvimento e contexto

  • A ideia inicial era gerar diretamente um SDK de filtros do FFmpeg a partir da documentação do FFmpeg com GPT-3
  • Durante o desenvolvimento, ficou claro que havia limites para automatizar completamente o trabalho só com GPT-3, e por isso o projeto migrou para uma abordagem tradicional de geração de código para concluir o SDK
  • GitHub Copilot e GPT-3 ajudaram a acelerar o desenvolvimento e economizar tempo
  • O estilo de API e as ideias de design do projeto ffmpeg-python influenciaram o desenvolvimento do typed-ffmpeg
  • As dependências de desenvolvimento são gerenciadas com pyproject.toml e uv.lock, e o ambiente de desenvolvimento pode ser instalado com o comando abaixo
uv pip install --group dev

Leituras relacionadas

1 comentários

 
GN⁺ 2025-05-31
Opiniões no Hacker News

  • Todos os parsers/ferramentas de opções de linha de comando são, na prática, linguagens completas de configuração próprias, e cada ferramenta individual deve ser vista como um “programa/configuração” nessa linguagem — algo que é subestimado
    Como o shell Unix faz a separação de palavras antes da interpretação final de argv, inúmeros dialetos parecem parecidos por fora, mas na prática são variados a ponto de dar vertigem
    Há algum tempo executei --help e -h em todos os programas de /usr/bin, e a proporção dos que não retornavam ajuda útil era bem alta
    Por isso, adicionar tipos a uma ferramenta complexa como ffmpeg tem vantagens práticas e também ajuda a expor melhor essa realidade

    • Talvez não seja o ponto principal pretendido, mas sinto que man foo é mais confiável e útil do que foo --help ou foo -h
    • Do ponto de vista de um iniciante, fico curioso para saber onde houve conflito

  • É interessante e bom ver que está em desenvolvimento ativo, mas parece ter alguns problemas parecidos com os do ffmpeg-python
    Não parece haver uma forma de especificar um filtro sem entrada, como "color", nem uma forma de passar flags para o Popen, como subprocess.CREATE_NO_WINDOW, para impedir que uma janela do CMD apareça em apps GUI no Windows
    No caso do próprio ffmpeg, dá para chamar ffmpeg.compile() e executar diretamente, mas com o ffprobe, que usa ffmpeg.probe(), isso é difícil
    Edit: resolvi filtros de origem com ffmpeg.sources.color. Fico curioso se também há uma forma de usar filtros de origem arbitrários, assim como se usa vfilter/afilter para filtros comuns

  • Se você vai fazer processamento de vídeo baseado em scripts em Python, recomendo fortemente ir direto para o Vapoursynth
    Ele foi criado desde o início para esse propósito, é mantido ativamente, tem uma comunidade e ferramentas decentes, e não fica preso à interface de linha de comando do ffmpeg
    https://www.vapoursynth.com/

  • O typed-ffmpeg apresenta como pontos centrais “segurança total de tipos, autocomplete e validação”; alguém pode explicar por que faz sentido passar largura e altura, ou coordenadas x/y, como strings aqui?

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

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

    • Parece que esses valores não são inteiros, mas expressões do ffmpeg que são avaliadas como inteiros
      Por exemplo, a documentação do ffmpeg tem este exemplo: 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 fazer checagem de tipos direito nisso, provavelmente seria necessária alguma espécie de DSL

  • Boa ideia. Pessoalmente, estou esperando uma versão em TypeScript

    • Pedi ao preview do Jules para fazer isso, e a implementação foi bem ingênua
      Consigo imaginar abordagens mais legíveis, mas, considerando que foi feita com um prompt bem curto, não ficou tão ruim
      Se tiver curiosidade, as mudanças estão neste branch: https://github.com/matt-hensley/typed-ffmpeg/tree/feature/mu...
    • TypeScript não é mencionado em lugar nenhum

  • Acho que deveria haver algum material que descrevesse a linha de comando do ffmpeg em um formato legível por máquina, para que fosse possível gerar bindings em várias linguagens

  • A ferramenta visual parece especialmente excelente. Como é difícil conhecer todas as peças que o FFMPEG oferece, este parece um caso em que programação modular/visual pode ajudar de verdade
    Uma pequena observação de UX: no Win11/Chrome, eu esperava conseguir apagar nós ou arestas com a tecla DEL
    No geral, está bem legal

    • Agora finalmente temos algo parecido com o DirectShow GraphEdit da MS

  • Legal, mas fico curioso se há suporte a conexões de pipe de frames entre comandos inteiros
    Pessoalmente, acho que é a partir daí que começam a se abrir as formas mais interessantes nos fluxos com FFMpeg

  • Gostei. Se quiser editar vídeos visualmente, você também pode experimentar uma ferramenta que criei: https://newbeelearn.com/tools/videoeditor/
    Ela gera comandos ffmpeg