DIRETRIZES CRÍTICAS
Requisitos de Caminho de Arquivo no Windows
OBRIGATÓRIO: Sempre Use Barras Invertidas no Windows para Caminhos de Arquivo
Ao usar ferramentas Edit ou Write no Windows, você DEVE usar barras invertidas (\) nos caminhos de arquivo, NÃO barras normais (/).
Diretrizes de Documentação
NUNCA crie novos arquivos de documentação, a menos que seja explicitamente solicitado pelo usuário.
Referência Rápida
| Tarefa | Comando |
|---|---|
| Queimar SRT | ffmpeg -i video.mp4 -vf "subtitles=subs.srt" output.mp4 |
| Queimar ASS | ffmpeg -i video.mp4 -vf "ass=subs.ass" output.mp4 |
| Adicionar legenda soft | ffmpeg -i video.mp4 -i subs.srt -c copy -c:s mov_text output.mp4 |
| Extrair legenda | ffmpeg -i video.mkv -map 0:s:0 output.srt |
| Estilizar legendas | -vf "subtitles=s.srt:force_style='FontSize=24,PrimaryColour=&HFFFFFF'" |
| Sobreposição de texto | -vf "drawtext=text='Olá':x=10:y=10:fontsize=24:fontcolor=white" |
| Formato | Extensão | Melhor Para |
|---|---|---|
| SRT | .srt | Simples, universal |
| ASS | .ass | Estilizado, animado, anime |
| VTT | .vtt | Vídeo web/HTML5 |
Quando Usar Esta Skill
Use para operações de legenda e descrição:
- Codificação (queima) de legendas no vídeo
- Adição de faixas de legendas soft em contêineres
- Extração de legendas de MKV/MP4
- Estilização de legendas (fonte, cor, posição)
- Sobreposições dinâmicas de texto
Legendas e Descrições com FFmpeg (2025)
Guia completo para trabalhar com legendas, legendas ocultas e sobreposições de texto usando FFmpeg.
Referência de Formatos de Legenda
Formatos Suportados
| Formato | Extensão | Características | Caso de Uso |
|---|---|---|---|
| SubRip | .srt | Temporização simples + texto | Universal, web |
| Advanced SubStation Alpha | .ass/.ssa | Estilo rico, posicionamento, efeitos | Anime, legendas estilizadas |
| WebVTT | .vtt | Padrão web, dicas, estilo | Vídeo HTML5 |
| TTML/DFXP | .ttml/.dfxp | Broadcast, acessibilidade | Serviços de streaming |
| MOV Text | .mov (embutido) | Nativo QuickTime | Ecossistema Apple |
| DVB Subtitle | (embutido) | Baseado em bitmap | Broadcast europeu |
| PGS | .sup | Legendas bitmap Blu-ray | Blu-ray |
| CEA-608/708 | (embutido) | Legendas ocultas | Broadcast, streaming (EUA) |
Características dos Formatos
SRT (SubRip):
- Formato simples baseado em texto
- Suporta tags HTML básicas (<b>, <i>, <u>)
- Amplamente compatível
- Sem posicionamento ou estilo avançado
ASS/SSA:
- Estilo avançado (fontes, cores, contornos)
- Posicionamento preciso em qualquer lugar da tela
- Suporte a animação e efeitos
- Temporização para karaokê
WebVTT:
- Formato padrão HTML5
- Estilo similar a CSS
- Configurações de dica para posicionamento
- Identificação de falantes
Queima de Legendas (Hardcoding)
Queima Básica de Legendas
# Queimar legendas SRT
ffmpeg -i video.mp4 -vf "subtitles=subs.srt" output.mp4
# Queimar legendas ASS/SSA (preserva o estilo)
ffmpeg -i video.mp4 -vf "ass=subs.ass" output.mp4
# Queimar legendas de contêiner MKV
ffmpeg -i video.mkv -vf "subtitles=video.mkv" output.mp4
# Queimar faixa de legenda específica (índice 0)
ffmpeg -i video.mkv -vf "subtitles=video.mkv:si=0" output.mp4
# Queimar legendas com índice de fluxo
ffmpeg -i video.mkv -vf "subtitles=video.mkv:stream_index=1" output.mp4
Queima de Legendas Estilizadas
# Forçar estilo (substitui o estilo da legenda)
ffmpeg -i video.mp4 \
-vf "subtitles=subs.srt:force_style='FontName=Arial,FontSize=24,PrimaryColour=&HFFFFFF,OutlineColour=&H000000,Outline=2,Shadow=1'" \
output.mp4
# Legendas amarelas com contorno preto
ffmpeg -i video.mp4 \
-vf "subtitles=subs.srt:force_style='FontSize=28,PrimaryColour=&H00FFFF,OutlineColour=&H000000,Outline=3'" \
output.mp4
# Fonte maior para acessibilidade
ffmpeg -i video.mp4 \
-vf "subtitles=subs.srt:force_style='FontSize=36,Bold=1'" \
output.mp4
Parâmetros de Estilo ASS
| Parâmetro | Descrição | Exemplo |
|---|---|---|
| FontName | Família da fonte | FontName=Arial |
| FontSize | Tamanho em pontos | FontSize=24 |
| PrimaryColour | Cor do texto (AABBGGRR) | PrimaryColour=&HFFFFFF |
| SecondaryColour | Cor do karaokê | SecondaryColour=&H00FFFF |
| OutlineColour | Cor do contorno/ borda | OutlineColour=&H000000 |
| BackColour | Cor da sombra/fundo | BackColour=&H80000000 |
| Bold | Texto em negrito (0/1) | Bold=1 |
| Italic | Texto em itálico (0/1) | Italic=1 |
| Underline | Texto sublinhado (0/1) | Underline=1 |
| Outline | Largura do contorno | Outline=2 |
| Shadow | Profundidade da sombra | Shadow=1 |
| Alignment | Posição (estilo teclado numérico) | Alignment=2 |
| MarginL/R/V | Margens em pixels | MarginV=50 |
Formato de Cor (ASS)
ASS usa o formato &HAABBGGRR (Alfa, Azul, Verde, Vermelho):
- Branco: &HFFFFFF ou &H00FFFFFF
- Preto: &H000000 ou &H00000000
- Amarelo: &H00FFFF (00-Azul, FF-Verde, FF-Vermelho)
- Vermelho: &H0000FF
- Azul: &HFF0000
- Preto 50% transparente: &H80000000
Adicionando Faixas de Legenda (Legendas Soft)
Embutir SRT como Faixa
# Adicionar SRT ao MP4 (MOV text)
ffmpeg -i video.mp4 -i subs.srt \
-c copy -c:s mov_text \
output.mp4
# Adicionar SRT ao MKV
ffmpeg -i video.mp4 -i subs.srt \
-c copy -c:s srt \
output.mkv
# Adicionar SRT ao WebM (WebVTT)
ffmpeg -i video.webm -i subs.srt \
-c copy -c:s webvtt \
output.webm
Múltiplas Faixas de Legenda
# Adicionar vários idiomas
ffmpeg -i video.mp4 -i subs_en.srt -i subs_es.srt -i subs_fr.srt \
-map 0:v -map 0:a -map 1 -map 2 -map 3 \
-c copy -c:s mov_text \
-metadata:s:s:0 language=eng -metadata:s:s:0 title="Inglês" \
-metadata:s:s:1 language=spa -metadata:s:s:1 title="Espanhol" \
-metadata:s:s:2 language=fra -metadata:s:s:2 title="Francês" \
output.mp4
# Adicionar legendas ASS ao MKV (preserva o estilo)
ffmpeg -i video.mp4 -i styled.ass \
-map 0 -map 1 \
-c copy -c:s ass \
output.mkv
Definir Faixa de Legenda Padrão
# Definir legenda como padrão
ffmpeg -i video.mp4 -i subs.srt \
-c copy -c:s mov_text \
-disposition:s:0 default \
output.mp4
# Definir legendas forçadas (sempre exibir)
ffmpeg -i video.mp4 -i forced.srt \
-c copy -c:s mov_text \
-disposition:s:0 forced \
output.mp4
Extraindo Legendas
Extrair para Arquivo Externo
# Extrair primeira faixa de legenda para SRT
ffmpeg -i video.mkv -map 0:s:0 output.srt
# Extrair fluxo de legenda específico
ffmpeg -i video.mkv -map 0:s:1 output.srt
# Extrair para formato ASS
ffmpeg -i video.mkv -map 0:s:0 output.ass
# Extrair para WebVTT
ffmpeg -i video.mkv -map 0:s:0 output.vtt
# Extrair todas as faixas de legenda
ffmpeg -i video.mkv -map 0:s subs_%d.srt
Listar Faixas de Legenda Disponíveis
# Mostrar todos os fluxos, incluindo legendas
ffprobe -v error -show_entries stream=index,codec_name,codec_type:stream_tags=language,title \
-of csv=p=0 video.mkv
# Mostrar apenas fluxos de legenda
ffprobe -v error -select_streams s \
-show_entries stream=index,codec_name:stream_tags=language,title \
-of csv=p=0 video.mkv
Converter Formatos de Legenda
# SRT para ASS
ffmpeg -i subs.srt subs.ass
# ASS para SRT (perde o estilo)
ffmpeg -i subs.ass subs.srt
# SRT para WebVTT
ffmpeg -i subs.srt subs.vtt
# WebVTT para SRT
ffmpeg -i subs.vtt subs.srt
Sobreposições com drawtext e Integração com Whisper AI
Exemplos detalhados para sobreposições drawtext (fontes, posicionamento, escape, expressões de tempo, caixas, contornos, texto animado) e fluxos de trabalho de transcrição/ geração de legendas com Whisper AI estão em references/drawtext-and-whisper.md. Carregue essa referência ao criar gráficos de texto queimados ou gerar legendas a partir da fala.
Legendas Ocultas CEA-608/708
Extrair Legendas Ocultas
# Extrair legendas CEA-608 de fluxo ATSC
ffmpeg -f lavfi -i "movie=broadcast.ts[out0+subcc]" -map 0:1 captions.srt
# Extrair de vídeo com CC embutido
ffmpeg -i video_with_cc.mp4 \
-filter_complex "[0:v]format=yuv420p[v];[0:v]crop=1:1:0:0[c]" \
-map "[c]" -c:v libx264 -f null - 2>&1 | grep -A 1 "Closed caption"
Adicionar Legendas CEA-608
# Embutir legendas CEA-608 (requer linha eia608)
ffmpeg -i video.mp4 -i captions.scc \
-c:v libx264 -c:a copy \
-vf "movie=captions.scc[captions];[0:v][captions]overlay" \
output.mp4
Posicionamento de Legendas
Valores de Alinhamento ASS
7 (superior-esquerdo) 8 (superior-centro) 9 (superior-direito)
4 (meio-esquerdo) 5 (meio-centro) 6 (meio-direito)
1 (inferior-esquerdo) 2 (inferior-centro) 3 (inferior-direito)
Exemplos de Posicionamento
# Legendas no centro superior
ffmpeg -i video.mp4 \
-vf "subtitles=subs.srt:force_style='Alignment=8,MarginV=20'" \
output.mp4
# Legendas alinhadas à esquerda
ffmpeg -i video.mp4 \
-vf "subtitles=subs.srt:force_style='Alignment=1,MarginL=50,MarginV=30'" \
output.mp4
# Lado direito para identificação do falante
ffmpeg -i video.mp4 \
-vf "subtitles=subs.srt:force_style='Alignment=3,MarginR=50'" \
output.mp4
Múltiplas Posições de Legenda
# Duas faixas de legenda em posições diferentes
ffmpeg -i video.mp4 \
-vf "[in]subtitles=speaker1.srt:force_style='Alignment=1,MarginL=50'[tmp];\
[tmp]subtitles=speaker2.srt:force_style='Alignment=3,MarginR=50'" \
output.mp4
Processamento em Lote
Queimar Legendas em Vários Vídeos
#!/bin/bash
# burn_subs_batch.sh
for video in *.mp4; do
base="${video%.mp4}"
if [ -f "${base}.srt" ]; then
ffmpeg -i "$video" \
-vf "subtitles=${base}.srt:force_style='FontSize=24,Outline=2'" \
-c:a copy \
"output/${base}_subbed.mp4"
fi
done
Converter Formato de Legenda em Lote
#!/bin/bash
# convert_subs.sh
for srt in *.srt; do
base="${srt%.srt}"
ffmpeg -i "$srt" "${base}.vtt"
done
Solução de Problemas
Problemas Comuns
"Unable to find a suitable output format"
# Especificar formato de saída explicitamente
ffmpeg -i video.mkv -map 0:s:0 -f srt output.srt
Caracteres ilegíveis nas legendas
# Forçar codificação UTF-8
ffmpeg -i video.mp4 \
-vf "subtitles=subs.srt:charenc=UTF-8" \
output.mp4
Fonte não encontrada
# Especificar diretório de fontes
ffmpeg -i video.mp4 \
-vf "subtitles=subs.srt:fontsdir=/caminho/para/fontes" \
output.mp4
# Listar fontes disponíveis
fc-list : family | sort | uniq
Atraso na temporização da legenda
# Atrasar legendas em 2 segundos
ffmpeg -i video.mp4 \
-vf "subtitles=subs.srt:itsoffset=2" \
output.mp4
# Ou usar setpts para ajustar
ffmpeg -i subs.srt -itsoffset 2 delayed.srt
Legenda não aparece em vídeo de alta resolução
# Escalar a renderização da legenda para a resolução do vídeo
ffmpeg -i video_4k.mp4 \
-vf "subtitles=subs.srt:force_style='FontSize=48,Outline=3'" \
output.mp4
Comandos de Verificação
# Verificar se há legendas presentes
ffprobe -v error -select_streams s -show_entries stream=codec_name -of default=nw=1 video.mp4
# Contar linhas de legenda
grep -c "^[0-9]" subs.srt
# Validar formato SRT
ffmpeg -i subs.srt -f null -
Práticas Recomendadas
Acessibilidade
- Use cores de alto contraste (branco sobre escuro, amarelo sobre escuro)
- Tamanho mínimo de fonte de 24pt para vídeo padrão
- Inclua identificação do falante para múltiplos falantes
- Posicione as legendas para evitar obscurecer conteúdo visual importante
- Mantenha linhas curtas (máximo de 42 caracteres por linha)
- Duração de exibição: mínimo 1 segundo, máximo 7 segundos por legenda
Qualidade
- Use o formato ASS para legendas estilizadas (anime, videoclipes)
- Use SRT para diálogos simples
- Use WebVTT para entrega na web
- Preserve o estilo original sempre que possível
- Teste em dispositivos de destino antes da distribuição
Desempenho
- Queime legendas apenas quando necessário (streaming, compatibilidade)
- Prefira legendas soft para arquivamento e flexibilidade
- Use codificação por hardware ao queimar legendas em arquivos grandes
- Processe em paralelo para operações em lote
Este guia cobre operações de legenda e descrição com FFmpeg. Para sobreposições de texto com formas e gráficos, consulte a skill shapes-graphics.