kajisho5/remotion-ffmpeg-skill

O que remotion-ffmpeg-skill faz?

ffmpeg-skill mede → Remotion desenha → ffmpeg-skill verifica e entrega. Os scripts ficam em scripts/ ao lado deste arquivo; execute-os com python3 <skill-dir>/scripts/<nome>.py. --help em um script mostra a lista completa de flags; references/timeline.md contém o formato da linha do tempo e as opções que cada composição aceita.

Este skill depende do ffmpeg-skill (encontrado ao lado deste skill, em ~/.claude/skills/ffmpeg-skill, ou via FFMPEG_SKILL_DIR). Ele nunca executa um comando ffmpeg/ffprobe bruto por conta própria: medição, verificação e entrega passam pelos scripts do ffmpeg-skill, então suas garantias são herdadas.

Flags compartilhadas (todo script): --json (um objeto JSON em stdout; prefira-o), --dry-run (planeja, não escreve nada), --overwrite (a única forma de substituir uma saída existente), --timeout SEGUNDOS.

Fluxo de trabalho (nesta ordem)

1. Projetar uma vez. Nenhum projeto Remotion ainda: init.py ./motion --install (copia o template, executa npm install; o navegador headless do Remotion é baixado no primeiro render). Um projeto existente deste skill: reutilize-o.
2. Medir. analyze.py FONTE [--captions FILE.srt] [--beats] -o FONTE.timeline.json. Leia o resumo e os warnings: uma fonte VFR ou HDR deve ser corrigida com ffmpeg-skill antes de desenhar (color.py --to-sdr, uma exportação com taxa de quadros constante) — Remotion renderiza SDR em uma grade fixa de quadros. Nunca escreva ou edite números da linha do tempo manualmente; em vez disso, meça novamente (--threshold, --min-silence para uma sala silenciosa).
3. Pré-visualizar frames. still.py --project ./motion --comp NOME --timeline TL --at 1.5 --at 6 e veja os PNGs: posicionamento das legendas, zoom (punch-in), cores. Barato; faça antes de um render completo.
4. Renderizar. render.py --project ./motion --comp NOME --timeline TL [--options look.json] -o OUT.mp4 (--fast = prévia com metade do tamanho, --frames 0-89 = um intervalo, --codec prores -o master.mov = um master). Ele verifica a saída contra a linha do tempo (contagem de quadros, FPS, tamanho, áudio) e sai com código de erro diferente de zero em caso de incompatibilidade.
   • Proporção: desenhe na proporção em que será entregue. --aspect 9:16 para Reels / TikTok / Shorts (1:1, 4:5, 16:9 também); --fit blur (padrão quando a proporção muda: contido sobre uma cópia desfocada), contain (barras) ou cover (corte — verifique o assunto no still primeiro). Nunca renderize 16:9 e deixe um template 9:16 cortar: as legendas perdem as bordas. pipeline.py --platform escolhe a proporção do template do ffmpeg-skill para você.
   • Fontes: legendas em Japonês / Chinês / Coreano recebem automaticamente a fonte CJK que o ffmpeg-skill encontra na máquina (instalada no projeto, sem tofu); --font-file F.ttf usa uma fonte específica; a linha de relatório font: informa qual foi usada, ou que nenhuma foi encontrada.
   • Camada para aplicativos de edição: --overlay --keep-graphics (Captioned / PeakPulse, proporção da fonte) desenha apenas os gráficos como um ProRes 4444 transparente .graphics.mov e o compõe sobre a fonte intocada com ffmpeg-skill overlay.py; entregue o .mov para alguém finalizando no Premiere / Resolve / Final Cut. Não é mais rápido que um render normal.
5. Entregar. deliver.py OUT.mp4 --platform youtube|reels|tiktok|shorts|x|... executa o template de entrega do ffmpeg-skill e sua tabela check.py. Linhas de formato são seguras de corrigir; linhas de julgamento (duração, proporção) alteram conteúdo — pergunte. Mencione WARNs, não os persiga. Nenhum destino nomeado: pule esta etapa e avise.
6. Avaliar. Não está finalizado até a resposta nomear a folha de contato que render.py escreveu (Look: CAMINHO) e dizer o que ela mostra. Mecânico (verifique e relate): o texto está onde foi pedido, as marcações aparecem em seus tempos, nada é cortado pelo frame. Julgamento (diga o que vê, o usuário decide): texto sobre um rosto, um corte que cai mal. Nenhuma imagem visível: Look: CAMINHO (pixels não inspecionados) — nunca afirme que olhou. Nenhuma folha de contato (look_error no resultado, ex.: um FFmpeg sem drawtext): veja os frames do still.py e repasse o erro que o problema nomeia.

Arquivos de opções são verificados antes de renderizar: uma chave desconhecida ou tipo errado é recusado (kind: input) em vez de silenciosamente não fazer nada.

MCP: mcp/server.py expõe as mesmas ferramentas (esquemas de scripts/_contract.py, contract --json os imprime).

Tudo de uma vez: pipeline.py FONTE --project ./motion --comp NOME [--captions F] [--platform P] executa 2→4→5 com as mesmas verificações e para no primeiro passo que falhar.

Solicitação → script / composição

Solicitação	Execute
"legendas animadas / legendas ocultas neste vídeo"	analyze.py --captions → render.py --comp Captioned
"cortar os silêncios / jump cut / apertar esta palestra" (com movimento)	analyze.py → render.py --comp Jumpcut (legendas reajustadas se fornecidas)
"gráficos que reagem ao áudio / batem na batida / nos cortes"	analyze.py [--beats] → render.py --comp PeakPulse (pulsos nas batidas quando a grade foi medida)
"legendas karaokê / palavras acendem enquanto são faladas"	analyze.py --words WORDS.json [--captions F.srt] → render.py --comp Karaoke (tempos de palavras de um motor de fala local, whisper JSON; sem SRT as marcações são agrupadas das palavras)
"lower thirds / títulos de nomes / títulos de capítulos"	render.py --comp Titled --options com lowerThirds / sceneTitles — o texto vem do usuário; peça, nunca invente nomes
"reel de melhores momentos / destaques"	analyze.py --highlights N [--target S] → render.py --comp Highlights (classificação por energia de áudio: candidatos, avise)
"cortar na batida / montagem musical"	analyze.py --beats [--highlights N] → render.py --comp BeatMontage (áudio ininterrupto, imagem corta a cada beatsPerCut batidas medidas; cortes de cena se não houver grade confiável)
"para YouTube / Reels / TikTok ..."	pipeline.py --platform (renderiza na proporção do template, depois entrega e verifica), ou render.py --aspect + deliver.py --platform
"vertical / 9:16 / quadrado"	render.py --aspect 9:16 (ou 1:1, 4:5)
"legendas em japonês" / uma fonte específica	nada extra para CJK (fonte automática); --font-file para uma fonte escolhida
"me dê os gráficos como camada separada"	render.py --overlay --keep-graphics
"mudar cor / fonte / tamanho da legenda / zoom"	um --options JSON (references/timeline.md), re-renderize
vários clipes ("introdução + palestra + encerramento")	analyze.py A.mp4 B.mov C.mp4 (ou pipeline.py com várias entradas): ffmpeg-skill join.py normaliza e une, depois tudo é medido no arquivo unido
"pré-visualizar" / "mostre-me um frame"	still.py
um novo tipo de gráfico	adicione uma composição a src/ do projeto que leia Props de src/timeline.ts; renderize com --comp SeuId (render.py então relata números medidos sem expectativa embutida)
corte simples / cortar / redimensionar / loudness sem gráficos	não é este skill: use ffmpeg-skill diretamente
algo quebrou	doctor.py [--project DIR]

O que este skill decide e o que não decide

• Decide (mecânico): duração da composição, FPS e tamanho (da sonda); onde os cortes caem (dos silêncios medidos); quando as marcações aparecem (do arquivo de legenda); quando os pulsos ocorrem (dos picos medidos); se um render corresponde à sua linha do tempo.
• Não decide: nomes, títulos e nomes de capítulos (lower thirds e títulos de cena são texto do usuário — pergunte), quais palavras uma legenda diz — o texto da marcação é desenhado exatamente como escrito, nunca encurtado ou parafraseado, nem mesmo para "caber" (ofereça um captionSize menor); o que conta como destaque; se um visual é bom. Isso pertence ao usuário ou ao agente chamador.
• Nunca inventa dados. Sem legendas sem um arquivo de legenda temporizado do usuário ou um motor de fala local; sem grade de batidas que --beats não mediu.

Regras que evitam falhas de jobs

• Licença Remotion: gratuita para indivíduos e organizações com fins lucrativos com até 3 funcionários; empresas maiores precisam de uma licença Remotion corporativa (https://www.remotion.dev/license). Se o usuário é claramente uma empresa maior, avise uma vez.
• Mantenha os originais do usuário: fontes são linkadas em public/media/ do projeto, nunca modificadas; saídas nunca sobrescrevem um arquivo existente sem --overwrite.
• Legendas CJK: a fonte automática vem da detecção de fontes do ffmpeg-skill; quando o relatório diz que nenhuma fonte foi encontrada, instale uma (Noto Sans CJK) ou passe --font-file — tofu na folha de contato é um job falho. Linhas em japonês quebram entre frases, não dentro de palavras.
• Velocidade (medida em uma máquina Linux de 2 núcleos, todos os núcleos — padrão do render.py): cerca de 2,6× o comprimento do clipe para 1080p30 (30 s levou 80 s). Pré-visualize com still.py e --fast antes de um render completo de metragem longa; informe ao usuário o tempo esperado antes de iniciar um render longo. --concurrency acima do número de núcleos é recusado pelo Remotion.
• Os pacotes Remotion em um projeto devem ser todos da mesma versão; o template os fixa. Não misture uma versão diferente de remotion.
• Um render que falha na verificação é uma falha: relate as linhas com falha de --json, não o entregue.