Communitygithub.com

top110341/ffmpeg

Edite vídeo e áudio com FFmpeg local a partir de comandos em linguagem natural: corte, ajuste, união, redimensionamento/requadro (9:16, 1:1), alteração de velocidade, legendas e subtítulos (SRT/ASS, animados, karaokê), sobreposição de logotipos e texto, retângulos inferiores e títulos, remoção de silêncio, sincronização multicâmera e de microfone externo, normalização de loudness, HDR/Dolby Vision para SDR, LUTs, música de fundo com ducking, exportação para plataformas (YouTube, Reels, TikTok, X), verificações de conformidade, detecção de cenas e resumos de destaques, folhas de contato para inspecionar resultados e arquivos de projeto de edição completa.

O que é ffmpeg?

Esta skill capacita agentes de IA (como Claude Code, Cursor, Codex) a editar arquivos de áudio e vídeo localmente usando FFmpeg, tudo por meio de comandos em linguagem natural. Ela oferece 42 scripts Python especializados que lidam com operações como corte, união, redimensionamento, legendas, sobreposições, sincronização, normalização de loudness e exportação para plataformas (YouTube, Reels, TikTok). A skill é projetada para execução puramente local, usando apenas a biblioteca padrão do Python 3.9, sem depender de serviços em nuvem ou chaves de API. Ela segue um fluxo de trabalho rigoroso que prioriza operações sem perdas, planejamento com dry-run, verificação de conformidade e inspeção visual, garantindo resultados confiáveis e reproduzíveis. A skill também abrange casos de uso complexos, como detecção de cenas, remoção de silêncio, correção de cor (HDR para SDR) e integração com MCP (Model Context Protocol) para ferramentas.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/top110341/ffmpeg/tree/HEAD/.claude/skills/ffmpeg-skill

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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)

  1. 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 ferramenta de contract --json é para um agente de planejamento, não para este fluxo de trabalho.
  2. Explore 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 sonda separada antes de cada edição: o --json de toda ferramenta de escrita já carrega sua entrada e uma sonda da saída. Planeje a partir de números reais, nunca suposições.
  3. 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.py e loudness.py copiam o stream de vídeo por padrão; --accurate em cut.py apenas para cortes exatos por quadro.
  4. 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, --progress imprime porcentagem/ETA em stderr. Nunca aponte -o para um arquivo que você não criou neste trabalho, a menos que o usuário tenha solicitado sua substituição; passe --overwrite apenas nesse caso.
  5. 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.py por último. Três ou mais etapas: render.py com um project.json.
  6. Verifique o entregável. Antes de relatar, execute check.py SAÍDA --platform X para 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.
  7. Verifique a saída. Confirme duração, resolução, fps e áudio correspondem à solicitação, a partir da sonda --json/--json-brief da ferramenta de escrita ou probe.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.
  8. 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".
  9. Olhe para a imagem. Sempre que a imagem mudou (legendas, sobreposições, gráficos, corte/pad, redimensionamento, cor, transições, um join.py dimensionando 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 visualize o PNG (4x3 para layout de clipe inteiro). Não terminado até que Look: 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 de check.py na 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á.

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: --transcribe se 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.json uma vez, reutilize-o.
  • Texto CJK / não latino: deixe a ferramenta escolher a fonte pelo script (--font desliga isso); --lang ja|ko para texto apenas Han. doctor --json .fonts.scripts informa 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 de 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 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 chama color.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 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 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 dizFaç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

Habilidades Relacionadas