O que Editor de Vídeo FFmpeg faz?
Edite vídeo, áudio e imagens do terminal usando ffmpeg e o script auxiliar fftools.py.
Ferramenta CLI
Todas as operações passam pelo script auxiliar. Encontre-o em relação a onde você clonou o repositório, ou em:
SCRIPT="~/.claude/skills/ffmpeg/scripts/fftools.py"
Toda a saída é em JSON.
Referência de Comandos
# INFO — Obtém detalhes do arquivo (duração, resolução, codecs, tamanho)
python3 $SCRIPT info input.mp4
# CUT — Extrai um segmento
python3 $SCRIPT cut input.mp4 output.mp4 --start 00:01:30 --end 00:02:45
python3 $SCRIPT cut input.mp4 output.mp4 --start 00:01:30 --duration 30
# MERGE — Concatena vários vídeos
python3 $SCRIPT merge video1.mp4 video2.mp4 video3.mp4 -o merged.mp4
python3 $SCRIPT merge video1.mp4 video2.mp4 -o merged.mp4 --reencode # codecs diferentes
# EXTRACT AUDIO — Extrai faixa de áudio
python3 $SCRIPT extract-audio input.mp4 output.mp3
python3 $SCRIPT extract-audio input.mp4 output.opus --bitrate 128k
# SUBTITLES — Grava legendas no vídeo
python3 $SCRIPT subtitles input.mp4 output.mp4 --srt subs.srt
# RESIZE — Altera a resolução
python3 $SCRIPT resize input.mp4 output.mp4 --width 1280 --height 720
python3 $SCRIPT resize input.mp4 output.mp4 --width 1920 --height -1 # altura automática
# GIF — Vídeo para GIF animado (dois passos, alta qualidade)
python3 $SCRIPT gif input.mp4 output.gif --fps 15 --width 480
python3 $SCRIPT gif input.mp4 output.gif --start 00:00:05 --duration 3
# THUMBNAIL — Extrai um único quadro
python3 $SCRIPT thumbnail input.mp4 thumb.jpg --time 00:00:30
# THUMBNAILS — Extrai N quadros uniformemente espaçados
python3 $SCRIPT thumbnails input.mp4 --count 10 --output-dir ./thumbs/
# COMPRESS — Reduz o tamanho do arquivo
python3 $SCRIPT compress input.mp4 output.mp4 --crf 28 --preset medium
python3 $SCRIPT compress input.mp4 small.mp4 --crf 32 --preset fast # agressivo
# SPEED — Altera a velocidade de reprodução
python3 $SCRIPT speed input.mp4 fast.mp4 --factor 2.0 # 2x mais rápido
python3 $SCRIPT speed input.mp4 slow.mp4 --factor 0.5 # metade da velocidade (câmera lenta)
# WATERMARK — Adiciona sobreposição de imagem
python3 $SCRIPT watermark input.mp4 output.mp4 --watermark logo.png --position bottom-right
# TEXT — Grava sobreposição de texto
python3 $SCRIPT text input.mp4 output.mp4 --text "Capítulo 1" --position center --size 72 --border
python3 $SCRIPT text input.mp4 output.mp4 --text "Promoção!" --position top-left --start 5 --end 15
# CONVERT — Altera o formato
python3 $SCRIPT convert input.avi output.mp4
python3 $SCRIPT convert input.mp4 output.webm --video-codec libvpx-vp9
# FRAMES — Extrai quadros como imagens
python3 $SCRIPT frames input.mp4 --output-dir ./frames/
python3 $SCRIPT frames input.mp4 --output-dir ./frames/ --every 30 # a cada 30 quadros
# AUDIO REPLACE — Substitui faixa de áudio
python3 $SCRIPT audio-replace input.mp4 output.mp4 --audio music.mp3
# VOLUME — Ajusta o nível de áudio
python3 $SCRIPT volume input.mp4 output.mp4 --level 2.0 # dobra o volume
python3 $SCRIPT volume input.mp4 output.mp4 --level 0.5 # reduz o volume pela metade
python3 $SCRIPT volume input.mp4 output.mp4 --level 10dB # aumenta 10dB
# FADE — Adiciona efeitos de fade in/out
python3 $SCRIPT fade input.mp4 output.mp4 --fade-in 2 --fade-out 3
# STABILIZE — Corrige vídeo tremido (requer filtro vidstab)
python3 $SCRIPT stabilize input.mp4 output.mp4 --shakiness 7 --smoothing 15
# TRANSCRIBE — Fala para texto COM identificação de falantes (offline; veja seção Transcrição)
python3 $SCRIPT transcribe meeting.mp4 # → meeting.json/.srt/.txt
python3 $SCRIPT transcribe meeting.mp4 --speakers 3 # informa o número de falantes
python3 $SCRIPT transcribe meeting.mp4 --no-diarize # apenas transcrição, sem falantes
Transcrição e Análise — entenda o que é dito em um vídeo
Use o comando transcribe para transformar uma gravação de reunião, entrevista ou qualquer
áudio/vídeo com fala em uma transcrição com carimbo de tempo e identificação de falantes. Esta é a
ferramenta para perguntas como "o que foi discutido?", "quem disse o quê?", "resuma esta
reunião" ou "encontre onde falaram sobre X".
Ela roda 100% local e offline — o áudio nunca sai da máquina, sem API em nuvem. Por dentro: WhisperX (large-v3) para transcrição + carimbos de tempo no nível da palavra, e sherpa-onnx para diarização de falantes (livre de tokens, modelos ONNX abertos).
Configuração única (precisa de rede uma vez)
Execute o comando de barra /setup-transcribe, ou diretamente:
bash ~/.claude/skills/ffmpeg/scripts/install-transcribe.sh
Por padrão, isso baixa um pacote pré-compilado do release do GitHub (rápido: sem
gating de modelo, sem construção torch) e o instala totalmente offline; se isso não estiver disponível
(release ausente ou uma plataforma cujas rodas não correspondem) ele volta automaticamente
para uma construção do zero. Cria um ambiente virtual Python 3.12 isolado (via uv) e
todos os modelos; depois disso, transcribe não precisa de rede. Se o comando informar que o
ambiente virtual está ausente, execute isso.
Force um modo específico se quiser:
bash install-transcribe.sh --release # apenas o pacote do release pré-compilado
bash install-transcribe.sh --build # apenas uma construção do zero (HF + PyPI)
HF_TOKEN=hf_xxx bash install-transcribe.sh --build # também ativa --diarizer pyannote
Sem acesso à internet / sem acesso HuggingFace? Construa um pacote autocontido uma vez em uma máquina conectada, hospede-o em qualquer lugar e instale a partir dele sem acesso HF/PyPI:
# Em uma máquina onde o install-transcribe.sh já foi executado:
bash ~/.claude/skills/ffmpeg/scripts/make-bundle.sh ffmpeg-transcribe-bundle.tar.gz
O pacote empacota todo o código, modelos, caches de modelos e rodas Python. Se exceder
2GB, é automaticamente dividido em <nome>.parte-aa, <nome>.parte-ab, … (cada <2GB) para caber
nos limites de hospedagem/upload. Então, na máquina de destino (precisa apenas de uv, ffmpeg e
python3.12):
# Pacote de arquivo único:
bash install-transcribe.sh --bundle https://seu.servidor/ffmpeg-transcribe-bundle.tar.gz
# Pacote dividido — passe as partes em ordem (são concatenadas automaticamente):
bash install-transcribe.sh --bundle \
https://seu.servidor/ffmpeg-transcribe-bundle.tar.gz.parte-aa \
https://seu.servidor/ffmpeg-transcribe-bundle.tar.gz.parte-ab
(Para remontar manualmente: cat ffmpeg-transcribe-bundle.tar.gz.parte-* > ffmpeg-transcribe-bundle.tar.gz.)
Uso
# Transcrição completa + identificação de falantes (escreve meeting.json, meeting.srt, meeting.txt)
python3 $SCRIPT transcribe meeting.mp4
# Opções
python3 $SCRIPT transcribe entrevista.mp4 --speakers 2 # número conhecido de falantes → melhor precisão
python3 $SCRIPT transcribe chamada.m4a --language pt # força o idioma (pula detecção automática)
python3 $SCRIPT transcribe palestra.mp4 --format txt # escreve apenas .txt
python3 $SCRIPT transcribe longo.mp4 --model medium # mais rápido, menos preciso
python3 $SCRIPT transcribe q4.mp4 --diarizer pyannote # diarizador de maior qualidade (precisa de token HF)
python3 $SCRIPT transcribe notas.mp4 --no-diarize # apenas transcrição, sem separação de falantes
python3 $SCRIPT transcribe raw.wav -o ./out/sessao # caminho base de saída personalizado
Formatos de saída
.txt— legível por humanos, agrupado por turno de falante. Leia isso para entender o conteúdo:[00:03:12] FALANTE_01: ....srt— legendas com tags de falante, para queimar de volta (comandosubtitles).json— dados estruturados completos: cada segmento + palavra com horários de início/fim e falante, para análise programática (pesquisa, linhas do tempo, citações com carimbos de tempo)
Fluxo de trabalho de análise de reunião
# 1. Transcreva com identificação de falantes
python3 $SCRIPT transcribe meeting.mp4
# 2. Leia a transcrição para analisar o conteúdo
# (use a ferramenta Read no meeting.txt, ou analise meeting.json para carimbos de tempo)
# 3. A partir daqui, você pode resumir, extrair itens de ação, encontrar quem-disse-o-quê
# ou pular para um momento: emparelhe um carimbo de tempo JSON com `cut`/`thumbnail`.
python3 $SCRIPT cut meeting.mp4 clip.mp4 --start 00:12:30 --end 00:14:00
Notas:
- A transcrição roda na CPU (CTranslate2 não tem caminho de GPU no Apple Silicon), então
large-v3 é aproximadamente 1–2× o tempo real. Uma reunião de 1 hora ≈ 30–60 min para processar — ok
para executar em segundo plano. Use
--model mediumoudistil-large-v3para velocidade. - Passar
--speakers N(quando você sabe o número) melhora visivelmente a diarização.
Fluxo de Trabalho Padrão
Passo 1 — Analise a entrada
Sempre comece obtendo informações do arquivo:
python3 $SCRIPT info input.mp4
Isso informa duração, resolução, codecs, tamanho do arquivo. Use isso para tomar decisões inteligentes sobre as configurações de saída.
Passo 2 — Execute a operação
Use o comando apropriado. Para edições complexas, encadeie várias operações — use a saída de uma como entrada da próxima.
Passo 3 — Verifique o resultado
Após qualquer operação, inspecione a saída para confirmar que funcionou:
python3 $SCRIPT info output.mp4
Passo 4 — Mostre o resultado
Use a ferramenta Read para exibir imagens (thumbnails, quadros). Para vídeos, informe ao usuário o caminho de saída e o tamanho do arquivo.
ffmpeg bruto — Para operações avançadas
Quando o script auxiliar não cobre seu caso de uso, use ffmpeg diretamente:
# Picture-in-picture
ffmpeg -y -i main.mp4 -i overlay.mp4 \
-filter_complex "[1:v]scale=320:-1[pip];[0:v][pip]overlay=W-w-10:H-h-10" \
-c:v libx264 -c:a copy output.mp4
# Comparação lado a lado
ffmpeg -y -i left.mp4 -i right.mp4 \
-filter_complex "[0:v]pad=iw*2:ih[bg];[bg][1:v]overlay=W/2:0" \
-c:v libx264 output.mp4
# Grade/mosaico (2x2)
ffmpeg -y -i a.mp4 -i b.mp4 -i c.mp4 -i d.mp4 \
-filter_complex "[0:v]scale=640:360[v0];[1:v]scale=640:360[v1];
[2:v]scale=640:360[v2];[3:v]scale=640:360[v3];
[v0][v1]hstack[top];[v2][v3]hstack[bot];[top][bot]vstack" \
-c:v libx264 grid.mp4
# Inverter vídeo
ffmpeg -y -i input.mp4 -vf reverse -af areverse reversed.mp4
# Extrair canal de áudio específico
ffmpeg -y -i input.mp4 -af "pan=mono|c0=FL" left_channel.wav
# Redução de ruído
ffmpeg -y -i input.mp4 -af "afftdn=nf=-25" denoised.mp4
# Correção de cor (brilho, contraste, saturação)
ffmpeg -y -i input.mp4 -vf "eq=brightness=0.1:contrast=1.2:saturation=1.3" corrected.mp4
# Chroma key (remoção de tela verde)
ffmpeg -y -i greenscreen.mp4 -i background.mp4 \
-filter_complex "[0:v]chromakey=0x00FF00:0.3:0.1[fg];[1:v][fg]overlay" \
-c:v libx264 composited.mp4
# Timelapse a partir de sequência de imagens
ffmpeg -y -framerate 30 -i frame_%04d.jpg -c:v libx264 -pix_fmt yuv420p timelapse.mp4
# Vídeo a partir de imagem única + áudio
ffmpeg -y -loop 1 -i cover.jpg -i audio.mp3 -c:v libx264 -tune stillimage \
-c:a aac -shortest output.mp4
# Crossfade entre dois vídeos (1 segundo)
ffmpeg -y -i first.mp4 -i second.mp4 \
-filter_complex "xfade=transition=fade:duration=1:offset=PRIMEIRA_DURACAO_MENOS_1" \
-c:v libx264 crossfade.mp4
Guia de Qualidade CRF
| CRF | Qualidade | Caso de uso |
|---|---|---|
| 18 | Visualmente sem perdas | Arquivamento, edição profissional |
| 23 | Alta qualidade | ffmpeg padrão, bom para a maioria dos usos |
| 28 | Boa qualidade | Recomendado para compartilhamento, arquivos menores |
| 32 | Aceitável | Redes sociais, compressão agressiva |
| 38+ | Baixa qualidade | Pré-visualizações, thumbnails |
CRF mais baixo = arquivo maior, melhor qualidade. Cada +6 aproximadamente reduz o tamanho do arquivo pela metade.
Referência Rápida de Formatos
| Contêiner | Codec de vídeo | Codec de áudio | Caso de uso |
|---|---|---|---|
.mp4 | H.264 (libx264) | AAC | Compatibilidade universal |
.webm | VP9 (libvpx-vp9) | Opus | Web, arquivos menores |
.mkv | H.265 (libx265) | Opus | Compressão máxima |
.mov | ProRes | PCM | Edição profissional |
.gif | — | — | Animações, sem áudio |
Tratamento de Erros
- "No such file" — Verifique o caminho de entrada, use caminhos absolutos
- "Unknown encoder" — Codec não compilado. Verifique
ffmpeg -encoders - "Permission denied" — Caminho de saída não gravável
- "Avi header too large" — Entrada corrompida, tente
-fflags +genptsantes da entrada - Timeout — O vídeo é muito longo. Aumente o tempo limite ou use
--preset ultrafast - Out of memory — Reduza a resolução primeiro, depois processe