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

• typed-ffmpeg é um wrapper moderno que permite usar o FFmpeg de forma intuitiva no Python
• Oferece forte suporte a tipos, documentação rica e autocompletar da IDE para melhorar a experiência de desenvolvimento e a estabilidade do código
• Facilita a criação de grafos de filtros complexos e oferece recursos avançados como visualização e serialização em JSON
• A instalação e a execução são simples, e também é possível experimentar no navegador por meio de um playground interativo
• Inspirado no ffmpeg-python, corrige limitações existentes e pretende ampliar o suporte a diferentes versões e filtros do FFmpeg no futuro

---

Visão geral e importância do typed-ffmpeg

• typed-ffmpeg é um pacote open source para controlar o FFmpeg de forma moderna e Pythonic
• Foi feito apenas com a biblioteca padrão do Python, portanto não tem dependências, oferecendo como vantagens alta segurança e compatibilidade
• Seu maior diferencial é o amplo suporte a tipos, a sintaxe simples, o autocompletar e a documentação inline, que permitem transformar tarefas complexas de filtros do FFmpeg em código de forma fácil e confiável
• Ele complementa limitações do ffmpeg-python, especialmente a falta de integração com IDE e de tipagem, e adiciona vários recursos novos, como serialização em JSON, validação automática de grafos de filtros e grafos visuais
• No processo real de wrapping e automação, GPT-3 e Copilot contribuíram para a produtividade de desenvolvimento, mas um ponto marcante do projeto é ter adotado uma abordagem de geração tradicional de código confiável como base central

Principais recursos (Features)

• Sem dependências: usa apenas a biblioteca padrão do Python
• Interface intuitiva: permite montar grafos de filtros do FFmpeg facilmente com código Python
• Suporte abrangente a filtros: oferece suporte à maioria dos filtros do FFmpeg e ao autocompletar da IDE
• Documentação integrada: usa docstrings inline para minimizar a necessidade de consultar documentação externa
• Suporte robusto a tipos: fornece checagem de tipos estática e dinâmica para reforçar a confiabilidade do código e facilitar o debugging
• Serialização de grafo de filtros: permite salvar e restaurar grafos de filtros em formato JSON
• Visualização de grafos: oferece geração de diagramas de grafos de filtros com graphviz
• Validação e correção automáticas: detecta erros dentro do grafo de filtros e faz correções automáticas
• Expansão de opções de entrada e saída: amplia o uso do FFmpeg com suporte a vários codecs e formatos
• Avaliação parcial: oferece suporte à modularização e à reutilização de grafos de filtros

Recursos planejados para o futuro

• Está previsto ampliar a compatibilidade ampla com versões além do FFmpeg 6.0
• Também está planejado o suporte a mais filtros complexos, com expansão contínua de funcionalidades

Exemplo rápido (Quick Usage)

import ffmpeg  
  
# Espelhar o vídeo horizontalmente e exportar  
f = (  
    ffmpeg  
    .input(filename='input.mp4')  
    .hflip()  
    .output(filename='output.mp4')  
)  
f  

• Em um exemplo mais complexo, é possível representar um grafo de filtros que corta vários trechos e adiciona overlay e drawbox

import ffmpeg.filters  
import ffmpeg  
  
in_file = ffmpeg.input("input.mp4")  
overlay_file = ffmpeg.input("overlay.png")  
  
f = (  
    ffmpeg.filters  
    .concat(  
        in_file.trim(start_frame=10, end_frame=20),  
        in_file.trim(start_frame=30, end_frame=40),  
    )  
    .video(0)  
    .overlay(overlay_file.hflip())  
    .drawbox(x="50", y="50", width="120", height="120", color="red", thickness="5")  
    .output(filename="out.mp4")  
)  
f  

• Mais exemplos e explicações detalhadas estão disponíveis na documentação

Playground interativo

• No navegador, é possível testar filtros e comandos do FFmpeg, visualizar resultados, experimentar diferentes opções de entrada e saída, aprender com exemplos interativos e compartilhar grafos de filtros
• É um ambiente muito eficaz para prototipar cadeias de filtros do FFmpeg e aprender, mesmo sem um ambiente local

Contexto do projeto e agradecimentos

• O projeto começou inspirado na ideia de geração automática de SDK com base na documentação do FFmpeg pelo GPT-3
• Para garantir confiabilidade, a geração central foi migrada para um método manual de geração de código
• Durante o desenvolvimento, GitHub Copilot e GPT-3 contribuíram para aumentar a eficiência do trabalho
• ffmpeg-python influenciou fortemente o projeto ao inspirar o estilo e o design da API
• O projeto é dedicado ao filho do desenvolvedor, Austin

Documentação e referência

• Informações mais detalhadas e recursos avançados podem ser consultados na Documentation oficial
• Além da instalação do pacote principal, recursos extras como visualização de grafos podem ser habilitados com suporte adicional ao graphviz
• Há também uma versão separada (typed-ffmpeg-compatible) para compatibilidade com ffmpeg-python

[GN⁺]

Comentários do Hacker News

• As pessoas subestimam demais o fato de que todo parser de opções de linha de comando ou toolkit é, por si só, uma linguagem de configuração completa e independente; é preciso reconhecer cada ferramenta como um programa ou configuração individual que roda nessa linguagem. No shell Unix, por causa das regras de divisão de palavras e de uma sintaxe aparentemente parecida, existe na prática uma diversidade enorme, mas muita gente a entende de forma uniforme demais. Pessoalmente, quando tentei executar todos os programas em /usr/bin com as opções --help e -h, a taxa de falha em obter a ajuda esperada foi consideravelmente alta. A introdução de informação de tipos em uma ferramenta complexa como o ffmpeg ajuda a perceber esse problema de diversidade e também pode trazer benefícios práticos reais.
  • Pela minha experiência, man foo é muito mais confiável e útil do que foo --help ou foo -h.
  • Como iniciante, fico curioso para saber especificamente onde ocorreram os conflitos e em que ponto exato estava essa oposição.
• É impressionante que o projeto esteja em desenvolvimento ativo, mas parece ter alguns problemas parecidos com os do ffmpeg-python. Por exemplo, não vejo como especificar filtros como color, que funcionam sem entrada; também não há uma forma de definir flags do Popen, como subprocess.CREATE_NO_WINDOW, para impedir que uma janela CMD apareça em apps com GUI. Dá para contornar no ffmpeg executando manualmente após ffmpeg.compile(), mas isso não se aplica ao ffmpeg.probe(). Além disso, entendi a questão dos filtros de origem como ffmpeg.sources.color, mas queria saber se existe uma forma de usar filtros de origem arbitrários como vfilter/afilter.
• Se você vai fazer processamento de vídeo por script em Python, recomendo fortemente usar Vapoursynth. É uma ferramenta projetada desde o início para processamento de vídeo, com manutenção ativa, comunidade e um ecossistema de ferramentas bem completo. Você pode usá-la livremente sem ficar preso à CLI do ffmpeg. Link do site do Vapoursynth.
• Ideia realmente muito legal. Pessoalmente, estou esperando uma versão em typescript deste projeto.
  • Fiz um teste rápido com a ferramenta de preview Jules para ver como poderia ficar uma versão em typescript. A implementação é bem simples, mas consigo imaginar uma forma mais legível. Pelo tamanho minúsculo do prompt, o resultado não ficou ruim. Para quem tiver curiosidade, aqui está o código no branch multi-language-codegen.
  • Seria realmente ótimo se uma versão em typescript também fosse lançada.
  • Piada comparando typescript à “linguagem de Deus”.
  • Observação de que a menção a typescript não estava na documentação oficial.
• Acho que a forma da linha de comando do ffmpeg deveria ser descrita de um jeito legível por máquina, para permitir geração automática de código em várias linguagens.
• A ferramenta visual é especialmente impressionante. O FFMPEG parece um caso claro em que programação modular/visual pode melhorar bastante a acessibilidade. Muita gente não conhece todos os recursos, então essa abordagem pode ajudar. Em termos de UX, senti falta da possibilidade de apagar nós/arestas com a tecla DEL, mas, no geral, a experiência é excelente.
  • Finalmente apareceu uma ferramenta parecida com o GraphEdit do DirectShow da MS.
• Acho este projeto realmente interessante. Se também suportasse passar frames por pipe entre comandos individuais, isso abriria a verdadeira escalabilidade do uso do FFMpeg.
• Acho este projeto muito legal, então também queria apresentar a ferramenta de editor de vídeo da newbeelearn, que permite editar vídeo visualmente e também gerar comandos ffmpeg automaticamente.
• Breve incentivo dizendo que é um bom trabalho.
• Exclamação de que o projeto parece muito legal.