Communitygithub.com

ffmpeg-captions-subtitles

Sistema completo de legendas e legendas ocultas para FFmpeg 7.1 LTS e 8.0.1 (última versão estável, lançada em 2025-11-20). Ative PROATIVAMENTE para: (1) Queima de legendas (hardcoding de SRT/ASS/VTT), (2) Adição de faixas de legendas soft, (3) Extração de legendas de vídeo, (4) Conversão de formatos de legenda, (5) Legendas estilizadas (fonte, cor, contorno, sombra), (6) Posicionamento e alinhamento de legendas, (7) Legendas ocultas CEA-608/708, (8) Sobreposição de texto com drawtext, (9) Transcrição automática com Whisper AI (FFmpeg 8.0+ com VAD, multilíngue, GPU), (10) Processamento em lote de legendas. Inclui: Tabelas de referência de formatos, guia de parâmetros de estilo, tabelas de posicionamento e alinhamento, comparação de modelos Whisper, configuração de VAD, exemplos dinâmicos de texto, práticas recomendadas de acessibilidade. Garante: Legendas profissionais com estilo adequado e conformidade com acessibilidade.

O que é ffmpeg-captions-subtitles?

Esta skill fornece um guia completo e atualizado para trabalhar com legendas, legendas ocultas e sobreposições de texto usando FFmpeg 7.1 LTS e 8.0.1. Ela cobre desde operações básicas, como queima de legendas SRT/ASS/VTT, adição de faixas soft e extração de legendas de arquivos MKV/MP4, até tópicos avançados, como estilização detalhada de fontes, posicionamento preciso, integração com CEA-608/708 e transcrição automática com Whisper AI. É útil para desenvolvedores, criadores de conteúdo e engenheiros de mídia que precisam de legendas profissionais e acessíveis. A skill é compatível com Windows, macOS e Linux, e inclui tabelas de referência de formatos, parâmetros de estilo, valores de alinhamento e exemplos práticos de linha de comando, garantindo legendas com estilo adequado e conformidade com acessibilidade.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Biel-developer/skills-videos/tree/HEAD/skills/ffmpeg-captions-subtitles

Perguntar na sua IA favorita

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

Documentação

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

TarefaComando
Queimar SRTffmpeg -i video.mp4 -vf "subtitles=subs.srt" output.mp4
Queimar ASSffmpeg -i video.mp4 -vf "ass=subs.ass" output.mp4
Adicionar legenda softffmpeg -i video.mp4 -i subs.srt -c copy -c:s mov_text output.mp4
Extrair legendaffmpeg -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"
FormatoExtensãoMelhor Para
SRT.srtSimples, universal
ASS.assEstilizado, animado, anime
VTT.vttVí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

FormatoExtensãoCaracterísticasCaso de Uso
SubRip.srtTemporização simples + textoUniversal, web
Advanced SubStation Alpha.ass/.ssaEstilo rico, posicionamento, efeitosAnime, legendas estilizadas
WebVTT.vttPadrão web, dicas, estiloVídeo HTML5
TTML/DFXP.ttml/.dfxpBroadcast, acessibilidadeServiços de streaming
MOV Text.mov (embutido)Nativo QuickTimeEcossistema Apple
DVB Subtitle(embutido)Baseado em bitmapBroadcast europeu
PGS.supLegendas bitmap Blu-rayBlu-ray
CEA-608/708(embutido)Legendas ocultasBroadcast, 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âmetroDescriçãoExemplo
FontNameFamília da fonteFontName=Arial
FontSizeTamanho em pontosFontSize=24
PrimaryColourCor do texto (AABBGGRR)PrimaryColour=&HFFFFFF
SecondaryColourCor do karaokêSecondaryColour=&H00FFFF
OutlineColourCor do contorno/ bordaOutlineColour=&H000000
BackColourCor da sombra/fundoBackColour=&H80000000
BoldTexto em negrito (0/1)Bold=1
ItalicTexto em itálico (0/1)Italic=1
UnderlineTexto sublinhado (0/1)Underline=1
OutlineLargura do contornoOutline=2
ShadowProfundidade da sombraShadow=1
AlignmentPosição (estilo teclado numérico)Alignment=2
MarginL/R/VMargens em pixelsMarginV=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

  1. Use cores de alto contraste (branco sobre escuro, amarelo sobre escuro)
  2. Tamanho mínimo de fonte de 24pt para vídeo padrão
  3. Inclua identificação do falante para múltiplos falantes
  4. Posicione as legendas para evitar obscurecer conteúdo visual importante
  5. Mantenha linhas curtas (máximo de 42 caracteres por linha)
  6. Duração de exibição: mínimo 1 segundo, máximo 7 segundos por legenda

Qualidade

  1. Use o formato ASS para legendas estilizadas (anime, videoclipes)
  2. Use SRT para diálogos simples
  3. Use WebVTT para entrega na web
  4. Preserve o estilo original sempre que possível
  5. Teste em dispositivos de destino antes da distribuição

Desempenho

  1. Queime legendas apenas quando necessário (streaming, compatibilidade)
  2. Prefira legendas soft para arquivamento e flexibilidade
  3. Use codificação por hardware ao queimar legendas em arquivos grandes
  4. 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.

Habilidades Relacionadas