ffmpeg-skill
Os scripts ficam em scripts/ ao lado deste arquivo; execute-os com python3 <skill-dir>/scripts/<nome>.py, e os templates de entrega em templates/. Este arquivo é suficiente para realizar um trabalho: a tabela abaixo roteia a solicitação, e --help no script que será executado é a lista de flags mais barata. Um arquivo de referência custa o mesmo que este; abra um apenas para uma dúvida que você tenha: references/scripts.md (todas as flags dos 42 scripts), references/devices.md (iPhone HDR, GoPro, DJI, gravações de tela, Zoom), references/gotchas.md (a forma extensa das regras de uma linha no final). MCP: tools/list mostra apenas as 12 principais por padrão; as outras 30 (de acordo com esta tabela) permanecem chamáveis pelo nome via tools/call, descritas por contract --json; defina FFMPEG_SKILL_MCP_FULL=1 para todas as 42.
Flags compartilhadas, em todos os scripts: --dry-run; --json (caminho de saída, uma sonda da saída, os comandos executados); --json-brief (status/saída/verificado mais um summary; prefira nas etapas de escrita); --fast (qualidade de pré-visualização); --progress; --timeout SEGUNDOS (kind: timeout, padrão 1800); --overwrite (etapa 7); --plan ARQUIVO (o dry run como um plano que render.py ARQUIVO executará depois; recusa se uma entrada foi alterada). Ferramentas de recodificação também aceitam --codec h264|hevc|av1|prores e --quality N: não definido, SDR é x264, HDR é x265 Main10; prores precisa de -o NOME.mov, h264 recusa HDR (color.py --to-sdr primeiro).
Ferramentas de escrita não executam nada com --dry-run; as ferramentas de medição (probe, check, sync, multicam, scenes, cropdetect, report, silence, loudness, stabilize) ainda podem executar ffmpeg/ffprobe, pulando artefatos/arquivos laterais (--edl, --sheet, um .ass gerado); verify ignora a flag. Por ferramenta: contract --json dry_run.
Fluxo de trabalho (nesta ordem)
- Ambiente, apenas em caso de falha. Nunca inicie um trabalho com
doctor: uma máquina quebrada falha comkind: missing_toolou um erro ffmpeg nomeando o filtro/codificador. Executepython3 <skill-dir>/scripts/_contract.py doctor(ounpx ffmpeg-skill doctor) após tal falha, ou quando perguntado o que a máquina pode fazer: leiaok/usable, relate a capacidade ausente. O esquema de ferramenta decontract --jsoné para um agente de planejamento, não para este fluxo de trabalho. - Explore o que você precisa planejar. Execute
probe.pyem cada entrada que você planeja — duração, fps, resolução, codecs, canais,variable_frame_rate_suspected— e sempre que o usuário perguntar sobre um arquivo. Nenhuma sonda separada antes de cada edição: o--jsonde toda ferramenta de escrita já carrega sua entrada e uma sonda da saída. Planeje a partir de números reais, nunca suposições. - Prefira sem perdas. Se a solicitação puder ser atendida sem recodificação (cortes simples em keyframes, remuxação, alterações apenas de áudio), não recodifique.
cut.pyeloudness.pycopiam o stream de vídeo por padrão;--accurateemcut.pyapenas para cortes exatos por quadro. - Planeje com
--dry-run --json, depois execute. Confie em--json, não na linha de resumo de um dry run, para qualquer número no plano (uma dimensão pode ser um placeholder). Use antes de codificações longas, para relatar fatos.--fasté qualidade de pré-visualização,--progressimprime porcentagem/ETA em stderr. Nunca aponte-opara um arquivo que você não criou neste trabalho, a menos que o usuário tenha solicitado sua substituição; passe--overwriteapenas nesse caso. - Encadeie em uma ordem sensata. Uma solicitação de entrega sem outra edição é uma execução de template (
render.py --template NOME ENTRADA), não uma cadeia construída manualmente. Caso contrário: cor (HDR→SDR / LUT) → corte → união → silêncio → ajuste → legenda/sobreposição → sincronização → áudio → loudness → exportação. Alterações de quadro antes das legendas, para que o texto seja dimensionado para o quadro final. Recodifique o mínimo de vezes possível: intermediários em CRF 18,export.pypor último. Três ou mais etapas:render.pycom um project.json. - Verifique o entregável. Antes de relatar, execute
check.py SAÍDA --platform Xpara o destino nomeado (uma execução de template já faz isso). Linhas de formato (codec, formato de pixel, tamanho, pico verdadeiro, tags de cor, VFR) são seguras de corrigir. Linhas de julgamento alteram o conteúdo: duração (corte perde material), aspecto (corte perde bordas), fps (perde movimento), loudness (a ambiência não deve ser aumentada) — corrija apenas quando a solicitação implicar a resposta, caso contrário, declare a escolha e seu custo. Mencione WARNs; não os persiga. - Verifique a saída. Confirme duração, resolução, fps e áudio correspondem à solicitação, a partir da sonda
--json/--json-briefda ferramenta de escrita ouprobe.py, e reporte esses números ("final.mp4: 59,98 s, 1080x1920, 30 fps, AAC estéreo"). Uma etapa é concluída apenas quando o script saiu com 0 e a saída é sondada conforme o esperado: uma saída não zero, um arquivo ausente ou vazio, ou uma sonda que contradiz a solicitação é uma falha relatada com a mensagem de erro do script. - Mantenha os originais do usuário. Nunca sobrescreva a fonte; escreva novos arquivos ao lado da entrada ou onde for solicitado. Um caminho de saída existente é recusado (
kind: input);--overwriteé a única maneira de dizer "sim, substitua-o". - Olhe para a imagem. Sempre que a imagem mudou (legendas, sobreposições, gráficos, corte/pad, redimensionamento, cor, transições, um
join.pydimensionando um clipe para o quadro do primeiro clipe,color.py --to-sdr) executelook.py SAÍDA --tiles 3x2(ou--at Tpara um quadro) e visualize o PNG (4x3 para layout de clipe inteiro). Não terminado até queLook:nomeie esse PNG — uma sonda não pode ver uma legenda em um rosto. Apenas áudio:Look: não necessário. O que procurar se divide como as linhas decheck.pyna etapa 5:- Mecânico (tarefa própria desta skill verificar e relatar): o texto/logotipo especificado está na posição especificada, as legendas aparecem nos timestamps especificados, as dimensões são pares. O letterboxing de
fit.py --fit padé o resultado correto desse modo, nunca um defeito a sinalizar. - Julgamento (relate, não passe ou falhe silenciosamente): se um sujeito ou rosto é cortado, o texto fica sobre um rosto, as cores parecem desbotadas, uma transição aterrissa. Isso precisa decidir o que o sujeito é, a decisão do agente chamador — diga o que você vê em uma linha; eles julgam.
Sem capacidade de visão, escreva
Look: CAMINHO (pixels não inspecionados; o agente não tem visualização de imagem)— nunca afirme que uma imagem foi inspecionada quando não foi, sem parar para uma capacidade que não está lá.
- Mecânico (tarefa própria desta skill verificar e relatar): o texto/logotipo especificado está na posição especificada, as legendas aparecem nos timestamps especificados, as dimensões são pares. O letterboxing de
Antes de executar qualquer coisa: o que perguntar, o que assumir
Faça uma pergunta curta apenas quando a resposta alterar materialmente a saída e a solicitação não a implicar. Quando várias coisas estiverem abertas ao mesmo tempo (um vago "faça para mídia social" deixa destino, aspecto, duração e legendas em aberto), não pergunte uma por vez: proponha um pacote com suas opções padrão e deixe o usuário alterar qualquer parte ("Reels: 9:16 com padding, 60 s, -14 LUFS, sem legendas — OK?"). Uma pergunta, uma resposta, depois a execução. Nunca pergunte o que probe.py pode lhe dizer.
- Destino decide aspecto, limite de duração, loudness e codec; "para Reels" responde a todos os quatro e nomeia um template. Sem destino e um corte/legenda simples: mantenha o formato de origem e informe. Se o usuário disser "exportar", "publicar" ou "entregar", pergunte onde.
- Duração ("faça com 60 s") sem um método: acelere para alterações ≤1,5×, corte caso contrário, informe qual. Pergunte quando o conteúdo é uma conversa (cortar perde palavras) e a mudança é grande.
- Legendas sem uma fonte de texto:
--transcribese um whisper local existir, caso contrário, peça o texto ou um arquivo com timestamps; nunca invente diálogo. - Fontes e marca: se o usuário mencionar uma marca, cores ou "nossa fonte", peça ou crie
brand.jsonuma vez, reutilize-o. - Texto CJK / não latino: deixe a ferramenta escolher a fonte pelo script (
--fontdesliga isso);--lang ja|kopara texto apenas Han.doctor --json.fonts.scriptsinforma o que renderiza aqui. Tofu é um trabalho falho. - Posição de corte para
--fit crop: centro por padrão, mas quando a solicitação ou a fonte nomear um sujeito descentralizado ("mantenha o produto à direita", alguém visivelmente descentralizado na folha) use--crop-x/--crop-y(0=esquerda/topo, 1=direita/base) em vez de adivinhar o centro, ou pergunte qual borda manter. - Qualquer outra coisa (tipo de transição, estilo de legenda): escolha o padrão convencional, informe o que você escolheu, ofereça a alternativa em uma linha.
O que esta skill faz e não decide
Esta skill corta, une, mede, sincroniza, exporta e verifica arquivos — ela executa uma edição, não decide uma. O que pertence ao humano, ao agente chamador ou a outra skill:
- Qual corte é o certo, ou se um entregável é aprovado — esta skill mede e relata (PASS/WARN/FAIL de
check.py, erro de duração decut.py); o usuário ou agente de produção decide se isso é enviado. - O que torna um destaque interessante —
scenes.py --highlightsclassifica por uma proxy medida (energia de áudio, duração): candidatos, não um veredito. - Composição de miniatura ou capa — uma decisão de design, não medição.
- Entender sobre o que é um vídeo — não há visão aqui além das folhas de contato de
look.py, para os olhos do agente chamador, não para esta skill interpretar. - Julgar o que parece bom — "aplicar este LUT", "corrigir exposição em +0,3 stops" (
color.py) é mecânico; "classificar esta cena para parecer cinematográfica" pertence a uma skill de classificação de cor (color-grading-skill) que decide os parâmetros, depois chamacolor.py. - As palavras em uma legenda — o texto da deixa é gravado como escrito. Muito longo para o quadro significa um tamanho menor,
--max-lines, ou a própria edição do usuário; nunca reescreva, encurte ou parafraseie, mesmo quando for solicitado a "fazer caber" — informe, ofereça--max-lines 1em um tamanho menor. - Escolher um sujeito ou região que não foi fornecida — "cortar para x=200,y=0" é mecânico uma vez que a caixa é conhecida; "cortar para manter o palestrante no quadro" precisa decidir o que é o palestrante, um julgamento para o agente chamador (a partir de uma folha de
look.py).
A linha: mesma entrada + mesmos parâmetros explícitos sempre produzindo a mesma saída verificável pertence aqui; qualquer coisa dependendo de gosto, compreensão ou do que parece ou soa bem pertence a quem faz esse julgamento.
Se uma solicitação precisar de um recurso FFmpeg que nenhum dos 42 scripts expõe, informe e nomeie a opção embutida mais próxima — nunca adivinhe uma invocação raw de ffmpeg/ffprobe fora de scripts/*.py. Isso ignora todas as garantias que esta skill faz, então nunca um fallback quando a flag de um script não cobre algo.
Solicitação → script
Esta tabela e a lista tools de doctor --json são a fonte da verdade para o que existe: nomeie apenas um script que você viu em um deles (não há doctor.py, trim.py, subtitle.py).
Flags de timestamp (--start, --end, --at, --from, --duration, --offset, e os tempos em arquivos de cue e capítulo) aceitam segundos, mm:ss(.fff), hh:mm:ss(.fff) ou SMPTE hh:mm:ss:ff com @fps (00:01:02:[email protected]) — cole uma folha de cue NLE como está; flags de duração (--min-silence, --margin, --fade) são segundos simples.
| Usuário diz | Faça |
|---|---|
| "cortar de 1:20 a 2:05", "aparar os primeiros 10 s" | cut.py input.mp4 --start 1:20 --end 2:05 |
| "manter apenas estas partes", "remover o meio" | cut.py input.mp4 --segments 0-1:00,1:30-2:00 |
| "tornar exatamente 60 segundos" | fit.py input.mp4 --duration 60 (velocidade) ou --method trim |
| "cortar isso e fazer HEVC / AV1 / ProRes" (codec de saída nomeado) | cut.py input.mp4 --start 0:10 --end 0:40 --codec hevc (--codec/--quality em qualquer ferramenta de recodificação; ProRes precisa de -o NAME.mov) |
| "cortar as pausas", "jump cuts" | silence.py input.mp4 [--threshold -40 --min-silence 0.8] |
| "cortar os 'hãs' e 'uhs'", "remover as palavras de preenchimento" | silence.py input.mp4 --filler --words words.json (temporizações de palavras medidas; --transcribe as cria) |
| "não cortar dentro de uma frase, apenas as pausas reais" | silence.py input.mp4 --speech-aware — uma respiração sob --min-silence dentro de uma frase é mantida, apenas pausas de limite de frase são cortadas; compõe com --filler em uma lista |
| "um destaque de 60 s desta hora" | scenes.py long.mp4 --highlights 6 --target 60 --edl picks.txt → cut.py --segments |
| "cortar na batida", "editar para a música" | scenes.py track.mp4 --beats --json > beats.json, então cut.py input.mp4 --segments ... --snap beats --snap-source beats.json (--snap-source carrega a grade medida) |
| "acelerar aqui, câmera lenta ali" (segmentos conhecidos) | speedramp.py action.mp4 --segment 0-3:1.0 --segment 3-4:0.25 --segment 4-8:2.0 |
| "segurar neste quadro", "congelar o último quadro" | freeze.py clip.mp4 --hold 2 |
| "câmera lenta suave", "meia velocidade mas fluido" | fit.py input.mp4 --duration 2x --smooth interpolate (lento) ou --smooth blend |
| "inverter este clipe" | reverse.py input.mp4 |
| "repetir este clipe para preencher 30 segundos" | loop.py bg_loop.mp4 --duration 30 |
| "tornar vertical / 9:16 / quadrado" | fit.py input.mp4 --aspect 9:16 --fit pad (ou --fit crop; --pad-fill blur para barras desfocadas) |
| "redimensionar para uma altura/largura" | fit.py input.mp4 --height 1080 (ou --width, ou ambos para um quadro exato) |
| "cortar para esta caixa exata" (x/y/w/h conhecidos) | crop.py input.mp4 --x 100 --y 0 --width 1080 --height 1920 |
| "fundo desfocado em vez de barras pretas" | fit.py input.mp4 --aspect 9:16 --fit blur (imagem inteira mantida, bordas uma cópia desfocada e escurecida) |
| "girar 90 graus", "espelhar" | fit.py input.mp4 --rotate 90 / fit.py input.mp4 --flip h |
| "o horizonte está inclinado" (graus conhecidos) | straighten.py tilted.mp4 --degrees -2.5 |
| "visão plana deste vídeo 360" (yaw/pitch/fov conhecidos) | sphere.py insta360.mp4 --yaw 90 --pitch 0 --h-fov 100 --v-fov 70 |
| "esta gravação antiga está entrelaçada" | deinterlace.py input.mp4 |
| "está granulada/barulhenta, limpe" | denoise.py input.mp4 --strength medium |
| "desfocar/pixelizar este rosto/placa" (caixa conhecida) | redact.py input.mp4 --x 820 --y 140 --width 240 --height 240 --mode pixelate |
| "estabilizar esta gravação tremida" | stabilize.py input.mp4 |
| "há barras pretas nisto?" | cropdetect.py input.mp4 |
| "clipe iPhone Dolby Vision parece errado" | color.py clip.mov --to-sdr ou --strip-dovi (manter HDR, remover a camada DV) |
| "as cores parecem desbotadas / iPhone HDR" | color.py input.mp4 --to-sdr |
| "corrigir a cor com esta LUT" (arquivo .cube conhecido) | color.py input.mp4 --lut teal-orange.cube |
| "fazer parecer filme", "look cinematográfico" | color.py input.mp4 --preset film |
| "adicionar legendas deste arquivo SRT" | caption.py input.mp4 --subtitles dialogo.srt |
| "gerar legendas automáticas" (transcrição local disponível) | caption.py input.mp4 --transcribe |
| "legendas animadas de karaokê" | caption.py input.mp4 --subtitles musica.srt --style karaoke |
| "adicionar estes subtítulos ASS" | caption.py input.mp4 --subtitles estilos.ass |
| "colocar o logotipo no canto superior direito" | overlay.py input.mp4 --logo logo.png --position top-right |
| "adicionar uma faixa de terço inferior com meu nome" | overlay.py input.mp4 --lower-third "João Silva" --style clean |
| "sobrepor este título" | overlay.py input.mp4 --title "Título da Cena" --position bottom |
| "música de fundo que abaixa durante a fala" | audio.py video.mp4 --background bg_music.wav --duck |
| "sincronizar este áudio de microfone externo" | sync.py video.mp4 external_audio.wav |
| "sincronizar estas 3 câmeras" | multicam.py cam1.mp4 cam2.mp4 cam3.mp4 |
| "normalizar o áudio para -14 LUFS" | loudness.py input.mp4 --loudness -14 |