ffmpeg-skill

O que ffmpeg-skill faz?

Os scripts residem em scripts/ próximo a este arquivo; execute-os com python3 <skill-dir>/scripts/<name>.py, e os modelos 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 completa mais barata. Um arquivo de referência custa o mesmo que este; abra um apenas para uma pergunta 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 longa das regras de uma linha no final). MCP: tools/list mostra apenas os 12 principais por padrão; os outros 30 (por esta tabela) permanecem chamáveis pelo nome via tools/call, descritos por contract --json; defina FFMPEG_SKILL_MCP_FULL=1 para todos os 42.

Flags compartilhadas (todo script)

--dry-run; --json (caminho de saída, sua sondagem, os comandos executados); --json-brief (status/saída/verificado + um summary; prefira ao escrever etapas); --fast (qualidade de pré-visualização); --progress (porcentagem/ETA); --timeout SEGUNDOS (kind: timeout, padrão 1800); --overwrite (etapa 7); --plan ARQUIVO (uma execução a seco render.py ARQUIVO executada depois; recusa se uma entrada foi alterada). Ferramentas de re-codificação também usam --hw (GPU Apple Silicon, arquivos grandes; FFMPEG_SKILL_HW=1 = padrão, não exportação), --codec h264|hevc|av1|prores e --quality N: não definido, SDR é x264 (cut.py --keep-hevc: fonte HEVC permanece HEVC), 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; overlay para um --text de múltiplas linhas no FFmpeg 8.0-8.1.0) podem ainda executar ffmpeg/ffprobe, ignorando artefatos/arquivos laterais (--edl, --sheet, um .ass gerado); verify ignora a flag. Por ferramenta: contract --json dry_run.

Fluxo de trabalho (nesta ordem)

0. Ambiente, apenas em caso de falha. Nunca inicie um trabalho com doctor: uma máquina quebrada falha com kind: missing_tool ou um erro ffmpeg nomeando o filtro/codificador. Execute python3 <skill-dir>/scripts/_contract.py doctor (ou npx ffmpeg-skill doctor) após tal falha, ou quando perguntado o que a máquina pode fazer: leia ok/usable, relate a capacidade ausente. O esquema de ferramentas de contract --json é para um agente de planejamento, não para este fluxo de trabalho.
1. Sonde o que você precisa planejar. Execute probe.py em 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 sondagem separada antes de cada edição: o --json de toda ferramenta de escrita já carrega sua entrada e uma sondagem da saída. Planeje a partir de números reais, nunca de suposições.
2. Prefira sem perdas. Se a solicitação puder ser atendida sem re-codificação (cortes simples em keyframes, remux, alterações apenas de áudio), não re-codifique. cut.py e loudness.py copiam o stream de vídeo por padrão; --accurate no cut.py apenas para cortes exatos por quadro.
3. Planeje com --dry-run --json, depois execute. Confie em --json, não na linha de resumo de uma execução a seco, para qualquer número no plano (uma dimensão lá pode ser um espaço reservado). Use antes de longas codificações, para relatar fatos. Nunca aponte -o para um arquivo que você não criou neste trabalho, a menos que o usuário tenha pedido para substituí-lo; passe --overwrite apenas nesse caso.
4. Encadeie em uma ordem sensata. Uma solicitação de entrega sem outra edição é uma execução de modelo único (render.py --template NOME ENTRADA), não uma cadeia construída manualmente. Caso contrário: cor (HDR→SDR / LUT) → corte → junção → silêncio → ajuste → legenda/overlay → sincronização → áudio → loudness → exportação. Altere os quadros antes das legendas, para que o texto seja dimensionado para o quadro final. Re-codifique o mínimo possível: intermediários em CRF 18, export.py por último. Três ou mais etapas: render.py com um project.json.
5. Verifique o entregável. Antes de relatar, execute check.py SAÍDA --platform X para o destino nomeado (uma execução de modelo já faz isso). Linhas de formato (codec, formato de pixel, tamanho, true peak, 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 (ambiente não deve ser aumentado) — corrija apenas quando a solicitação implicar a resposta, caso contrário, informe a escolha e seu custo. Mencione AVISOS; não os persiga.
6. Verifique a saída. Confirme duração, resolução, fps e áudio correspondentes à solicitação, a partir da --json/--json-brief da ferramenta de escrita ou probe.py, e relate esses números ("final.mp4: 59.98 s, 1080x1920, 30 fps, AAC estéreo"). Uma etapa só é concluída quando o script saiu com 0 e a saída é sondada conforme o esperado: uma saída diferente de zero, um arquivo ausente ou vazio, ou uma sondagem que contradiz a solicitação é uma falha relatada com a mensagem de erro do script.
7. 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".
8. Olhe para a imagem. Sempre que a imagem mudar (legendas, sobreposições, gráficos, corte/pad, redimensionamento, cor, transições, um join.py redimensionando um clipe para o quadro do primeiro clipe, color.py --to-sdr) execute look.py SAÍDA --tiles 3x2 (ou --at T para um quadro) e veja o PNG (4x3 para layout de clipe inteiro). Não termine até que Look: nomeie esse PNG — uma sondagem não pode ver uma legenda em um rosto. Apenas áudio: Look: not needed. O que procurar se divide como as linhas de check.py na etapa 5:
   • Mecânico (trabalho deste 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 cobre um rosto, as cores parecem desbotadas, uma transição cai. Isso requer decidir o que o sujeito é — 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; agente não tem visualização de imagem) — nunca afirme que uma imagem foi inspecionada quando não foi, sem travar para uma capacidade que não existe.

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 em aberto 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 turno: proponha um pacote com seus padrões 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 todas as quatro e nomeia um modelo. Sem destino e um corte/legenda simples: mantenha o formato de origem e diga isso. Se o usuário disser "exporte", "poste" ou "entregue", pergunte onde.
• Duração ("faça com 60 s") sem um método: acelere para alterações ≤1.5×, corte caso contrário, diga qual. Pergunte quando o conteúdo for uma palestra (cortar perde palavras) e a alteração for grande.
• Legendas sem uma fonte de texto: --transcribe se um mecanismo local existir, caso contrário peça o texto ou um arquivo com tempos; nunca invente diálogo.
• Fontes e marca: se o usuário mencionar uma marca, cores ou "nossa fonte", peça ou crie brand.json uma vez, reutilize.
• Texto CJK / não latino: deixe a ferramenta escolher a fonte por script (--font desliga); --lang ja|ko para texto apenas Han. doctor --json .fonts.scripts diz o que renderiza aqui. Tofu é um trabalho falho.
• Posição de corte para --fit crop: centralizado 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, diga o que você escolheu, ofereça a alternativa em uma linha.

O que este skill faz e não decide

Este skill corta, une, mede, sincroniza, exporta e verifica arquivos — ele executa uma edição, não a decide. O que pertence ao humano, ao agente chamador ou a outro skill:

• Qual corte é o certo, ou se um entregável é aprovado — este skill mede e relata (PASS/WARN/FAIL do check.py, erro de duração do cut.py); o usuário ou agente de produção decide se isso é enviado.
• O que torna um destaque interessante — scenes.py --highlights classifica por um proxy medido (energia de áudio, duração): candidatos, não um veredito.
• Composição de miniatura ou capa — uma decisão de design, não uma medição.
• Entender sobre o que é um vídeo — não há visão aqui além das folhas de contato do look.py, para os olhos do agente chamador, não para este skill interpretar.
• Julgar o que parece bom — "aplique este LUT", "corrija exposição em +0.3 stops" (color.py) é mecânico; "graduar esta cena para parecer cinematográfica" pertence a um skill de gradação de cor (color-grading-skill) que decide os parâmetros, depois chama color.py.
• As palavras em uma legenda — o texto do cue é 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 solicitado a "fazer caber" — diga isso, ofereça --max-lines 1 em 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 orador no quadro" precisa decidir o que o orador é, um julgamento para o agente chamador (a partir de uma folha do look.py).

A linha: a mesma entrada + os 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, diga isso e nomeie a opção interna mais próxima — nunca adivinhe uma invocação ffmpeg/ffprobe bruta fora de scripts/*.py. Isso ignora todas as garantias que este skill faz, então nunca é um fallback.

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).

As flags de timestamp (--start, --end, --at, --from, --duration, --offset, e os tempos em arquivos de cue e capítulo) usam 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 comprimento (--min-silence, --margin, --fade) são segundos simples.

Usuário diz	Faça
"corte de 1:20 a 2:05", "apare os primeiros 10 s"	cut.py input.mp4 --start 1:20 --end 2:05
"mantenha apenas estas partes", "remova o meio"	cut.py input.mp4 --segments 0-1:00,1:30-2:00
"faça exatamente 60 segundos"	fit.py input.mp4 --duration 60 (velocidade) ou --method trim
"corte isso e faça HEVC / AV1 / ProRes" (codec de saída nomeado)	cut.py input.mp4 --start 0:10 --end 0:40 --codec hevc (ProRes precisa de -o NOME.mov)
"corte as pausas", "jump cuts"	silence.py input.mp4 [--threshold -40 --min-silence 0.8]
"corte os 'ums' e 'uhs'", "remova as palavras de preenchimento"	silence.py input.mp4 --filler --words words.json (tempos de palavras medidos; --transcribe os cria)
"não corte 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
"corte na batida", "edite para a música"	scenes.py track.mp4 --beats --json > beats.json, depois cut.py input.mp4 --segments ... --snap beats --snap-source beats.json (--snap-source carrega a grade medida)
"acelere 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
"segure neste quadro", "congele 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
"inverta este clipe"	reverse.py input.mp4
"repita este clipe para preencher 30 segundos"	loop.py bg_loop.mp4 --duration 30
"faça vertical / 9:16 / quadrado"	fit.py input.mp4 --aspect 9:16 --fit pad (ou --fit crop; --pad-fill blur para barras desfocadas)
"redimensione para uma altura/largura"	fit.py input.mp4 --height 1080 (ou --width, ou ambos para um quadro exato)
"corte 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)
"gire 90 graus", "espelhe"	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 filmagem antiga está entrelaçada"	deinterlace.py input.mp4
"está granulada/ruidosa, limpe"	denoise.py input.mp4 --strength medium
"desfoque/pixelize este rosto/placa" (caixa conhecida)	redact.py input.mp4 --x 820 --y 140 --width 240 --height 240 --mode pixelate
"remova este logotipo fixo" (caixa conhecida)	redact.py input.mp4 --x 40 --y 20 --width 180 --height 60 --mode delogo
"estabilize esta filmagem tremida"	stabilize.py input.mp4
"há barras pretas nisto?"	cropdetect.py input.mp4
"clipe iPhone Dolby Vision parece errado"	color.py caminho --to-sdr
"aplique este LUT" (caminho conhecido)	color.py caminho --lut /path/to/cube
"corrija a cor branca" / "faça parecer mais quente"	color.py caminho --white-balance 6500 / --temperature 5500
"ajuste o brilho/contraste/saturação"	color.py caminho --brightness 0.1 --contrast 1.2 --saturation 0.9
"faça parecer filme antigo" / "preto e branco sépia"	color.py caminho --preset vintage / --preset sepia
"adicione um logotipo no canto superior direito" (caminho conhecido)	overlay.py input.mp4 --logo /path/to/logo.png --position top-right
"adicione texto no canto inferior esquerdo"	overlay.py input.mp4 --text "Título" --position bottom-left
"adicione uma vinheta (lower third) com nome e cargo"	overlay.py input.mp4 --lower-third "Nome" "Cargo"
"adicione uma vinheta subtítulo abaixo do nome"	overlay.py input.mp4 --lower-third "Nome" "Cargo" --subtitle "Subtítulo"
"adicione um título centralizado que desaparece"	overlay.py input.mp4 --text "Título" --position center --fade-out 0.5
"adicione uma caixa de texto com fundo"	overlay.py input.mp4 --text "Legenda" --box 1 --box-color black --box-opacity 0.7
"adicione legendas automáticas (SRT/ASS)" (com arquivo)	subtitle.py input.mp4 --file captions.srt
"adicione legendas com estilo e animação"	subtitle.py input.mp4 --file captions.ass --style fancy --animation typewriter
"adicione legendas do tipo karaokê"	subtitle.py input.mp4 --file karaoke.ass --karaoke
"transcreva e adicione legendas queimadas"	subtitle.py input.mp4 --transcribe --burn
"adicione legendas e também um arquivo SRT separado"	subtitle.py input.mp4 --transcribe --output-srt captions.srt
"mude a fonte, cor e tamanho da legenda"	subtitle.py input.mp4 --file captions.srt --font Arial --font-size 24 --font-color white
"adicione borda/sombra às legendas"	subtitle.py input.mp4 --file captions.srt --border 2 --border-color black --shadow 1
"sincronize o áudio do clipe A com o clipe B"	sync.py input_a.mp4 input_b.mp4 --output synced.mp4
"sincronize esta gravação de microfone externo com o vídeo"	sync.py video.mp4 audio.wav --output synced.mp4
"alineie vários clipes com o primeiro clipe"	multicam.py cam1.mp4 cam2.mp4 cam3.mp4 --output aligned/
"normalize o áudio para -14 LUFS"	loudness.py input.mp4 --loudness -14
"aumente/diminua o volume em 3 dB"	loudness.py input.mp4 --gain 3
"adicione música de fundo com ducking (redução automática) quando alguém fala"	audio.py video.mp4 background.mp3 --duck --duck-threshold -20
"adicione música de fundo a um volume fixo"	audio.py video.mp4 background.mp3 --volume 0.3
"misture duas faixas de áudio"	audio.py video.mp4 voiceover.wav --mix
"substitua o áudio por esta faixa"	audio.py video.mp4 new_audio.wav --replace
"remova o som de fundo / isole a voz"	audio.py video.mp4 --denoise
"altere a taxa de amostragem para 44100"	audio.py video.mp4 --sample-rate 44100
"converta para mono/estéreo"	audio.py video.mp4 --channels 1
"exporte para YouTube" (formato, loudness, etc.)	render.py input.mp4 --template youtube
"exporte para Instagram Reels"	render.py input.mp4 --template reels
"exporte para TikTok"	render.py input.mp4 --template tiktok
"exporte para X/Twitter"	render.py input.mp4 --template x
"exporte como GIF animado"	export.py input.mp4 --format gif
"me dê uma folha de contato 4x4 deste vídeo"	look.py input.mp4 --tiles 4x4
"verifique se este vídeo atende aos requisitos do YouTube"	check.py input.mp4 --platform youtube
"detecte cenas neste vídeo"	scenes.py input.mp4 --json
"crie um vídeo de melhores momentos a partir daqui"	scenes.py input.mp4 --highlights 5 --target 30 --edl picks.txt
"relate todos os metadados deste arquivo"	probe.py input.mp4 --json
"este vídeo é adequado para Instagram?"	check.py input.mp4 --platform instagram
"converta este arquivo para MP4 H.264"	export.py input.mov --format mp4 --codec h264
"extraia o áudio como MP3"	export.py input.mp4 --format mp3
"crie um arquivo de projeto para esta edição"	render.py --save project.json
"carregue este arquivo de projeto e renderize"	render.py project.json
"aumente a resolução para 4K usando IA" (upscale)	upscale.py input.mp4 --scale 2
"melhore a qualidade / reduza o ruído com IA"	enhance.py input.mp4
"adicione transição de fade/crossfade entre clipes"	transition.py clip1.mp4 clip2.mp4 --type crossfade --duration 1
"adicione efeito Ken Burns (zoom lento)"	kenburns.py input.mp4 --zoom-in 1.2 --duration 10
"adicione efeito de paralaxe (movimento sutil)"	parallax.py input.mp4 --pan-right 0.1 --duration 8
"adicione borda / moldura ao redor do vídeo"	border.py input.mp4 --width 10 --color white
"crie um vídeo em câmera lenta de 0.5x"	fit.py input.mp4 --duration 2x
"crie um lapso de tempo (time-lapse)"	fit.py input.mp4 --duration 0.5x
"adicione uma introdução de 5 segundos"	concat.py intro.mp4 input.mp4 --output combined.mp4
"adicione um outro vídeo no final"	concat.py input.mp4 outro.mp4 --output combined.mp4
"sobreponha um vídeo menor em um canto" (overlay de vídeo, tipo PiP)	overlay.py main.mp4 --video pip.mp4 --position top-right --size 0.25
"faça a correção de cor automática"	color.py input.mp4 --auto
"remova o croma-key / fundo verde"	chroma.py input.mp4 --color green --replace background.jpg
"crie uma moldura congelada do quadro atual"	freeze.py input.mp4 --at 5 --duration 2
"adicione moldura congelada no início/fim"	freeze.py input.mp4 --hold-start 2 --hold-end 3
"conte quantos quadros existem"	probe.py input.mp4 --frames
"obtenha os metadados EXIF deste vídeo"	probe.py input.mp4 --metadata
"mostre-me o waveform / forma de onda do áudio"	waveform.py input.mp4 --output waveform.png
"crie um espectrograma do áudio"	waveform.py input.mp4 --spectrogram --output spectrogram.png
"remova as bordas cortadas deste vídeo"	cropdetect.py input.mp4 --crop
"detecte movimento / cenas silenciosas"	scenes.py input.mp4 --motion
"detecte rostos neste vídeo"	(sem script dedicado; use --json com ferramenta externa ou relate que não está disponível)
"faça a imagem parecer mais nítida"	denoise.py input.mp4 --sharpen
"aplique um filtro vintage / retrô"	color.py input.mp4 --preset vintage
"adicione um brilho / efeito de luz"	(não disponível; use --text com cor e opacidade ou relate)
"crie um vídeo em 360 graus"	sphere.py equirectangular.mp4 --output 360.mp4
"crie uma edição multi-câmera"	multicam.py cam1.mp4 cam2.mp4
"sincronize clipes de diferentes câmeras"	multicam.py cam1.mp4 cam2.mp4 --sync
"eu quero fazer uma live"	(não suportado; foque em edição de arquivo)
"eu quero fazer streaming"	(não suportado; foque em edição de arquivo)

Regras de uma linha (curta e grossa)

• Sem re-encode desnecessário. Prefira stream copy sempre que possível.
• Nunca invoque ffmpeg/ffprobe diretamente. Use apenas scripts/*.py.
• Sempre verifique a saída. check.py e look.py são obrigatórios antes de relatar.
• Nunca substitua arquivos de origem. Escreva novos arquivos ao lado ou no diretório de saída.
• Nunca use --overwrite a menos que o usuário peça explicitamente para substituir.
• Sempre use --dry-run --json para planejar antes de executar grandes codificações.
• Prefira render.py --template em vez de construir cadeias manuais para entregas.
• Nunca adivinhe parâmetros não solicitados (texto de legenda, posição de corte, valor de duração, etc.). Pergunte ou use padrões sensatos e informe.
• Nunca ignore uma falha de script. Um código de saída diferente de zero = trabalho falho.
• Relate números exatos da sondagem, não suposições.
• Mantenha o agente chamador informado sobre o que você fez, por que e quaisquer avisos.