O que ffmpeg-pipeline faz?
A skill de cola. Ela transforma imagens geradas (ou fornecidas) em um MP4 animado com narração, e faz as tarefas comuns de mídia que um agente encontra constantemente.
Requer ffmpeg + ffprobe. Precisa de anon-image para modo prompt e
anon-audio para --narration; ambos são descobertos automaticamente como irmãos, e ambos
são opcionais se você passar --images / --audio no lugar.
Comandos
| Comando | O que faz |
|---|---|
video | imagens estáticas (geradas ou de --images) → MP4 com movimento zoompan + crossfades, narração e fundo musical opcionais |
slideshow | imagens existentes → MP4 |
mux | anexar uma faixa de áudio a um vídeo, repetindo/preenchendo para caber |
frames | extrair quadros a cada N segundos |
sheet | folha de contato (N quadros espaçados uniformemente com carimbos de tempo) |
gif | GIF otimizado em paleta, recortado, de qualquer seção |
normalize | normalizar loudness do áudio para −16 LUFS |
speed | alterar velocidade do áudio sem distorção de tom (atempo em cadeia) |
info | resumo de uma linha do ffprobe |
probe | verificação de dependências |
Início rápido
# todo o pipeline em uma chamada: 3 takes gerados, 4 s cada, narrados
vidkit.py video "um farol em um penhasco de basalto ao entardecer, cinematográfico" -o story.mp4 \
--shots 3 --seconds 4 --ratio 16:9 \
--narration "Em algum lugar em uma costa fria, um farol mantém sua vigília." \
--voice en-GB-RyanNeural
# reutilizar imagens que você já tem
vidkit.py video --images shots/ -o out.mp4 --seconds 3 --music bed.mp3
# cirurgia de mídia
vidkit.py mux clip.mp4 voiceover.mp3 -o final.mp4
vidkit.py sheet final.mp4 -o preview.jpg --cols 4 --count 8
vidkit.py gif final.mp4 -o teaser.gif --start 1 --dur 2.5 --width 480
vidkit.py normalize voiceover.mp3 -o clean.mp3
vidkit.py info final.mp4
Matemática de tempo (para você prever a saída)
Com N takes de S segundos e um crossfade de 0,8 s:
duração = N*S - (N-1)*0,8
3 × 4 s → 10,4 s. Se a narração for mais longa que a imagem, o vídeo repete
para cobri-la (-stream_loop). Se for mais curta, o áudio é preenchido com
silêncio para que você nunca perca o final. Ambos os casos são tratados — não adicione
-shortest você mesmo.
Regras de decisão
- Proporção:
16:9para YouTube/web,9:16para Shorts/Reels/TikTok,1:1para feeds e miniaturas. Tudo é redimensionado para cobrir e depois cortado, então imagens de origem de qualquer formato sobrevivem sem letterbox. - Segundos por take: 3–4 s é adequado para uma imagem estática; mais de 6 s de uma imagem estática parece morto. Se precisar de mais tempo de execução, adicione takes, não segundos.
- Fundo musical: passe
--musice ele será mixado a 12% abaixo da voz. Não misture duas fontes altas; normalize primeiro. - GIF: mantenha largura ≤ 480 e duração ≤ 3 s ou o arquivo excede os limites do chat.
Modos de falha
| Sintoma | Causa | Correção |
|---|---|---|
missing dependency: ffmpeg | não instalado | apt install ffmpeg (ou brew install ffmpeg) |
ffmpeg failed: … Invalid argument no zoompan | dimensões ímpares da origem | o filtro já redimensiona para W*2; se você o editou, mantenha números pares |
| saída silenciosa | arquivo de narração ausente/vazio | verifique o caminho; --narration aceita texto ou um caminho de áudio |
| saída muito mais curta que o esperado | áudio mais curto que o vídeo e algo adicionou -shortest | remova-o; vidkit.py preenche como alternativa |
contact sheet needs Pillow | sem Pillow | pip install pillow, ou use frames + sua própria folha |
Notas para o agente
- Renderize em 720p a menos que o usuário peça mais. É 4× mais rápido e ninguém percebe em uma tela de laptop.
- Sempre execute
infono artefato final e cite a duração real, resolução e tamanho de volta para o usuário — isso detecta falhas silenciosas. - Entregue o caminho do MP4; não incorpore. O arquivo é o artefato.