Como Adicionar Legendas a Vídeo com FFmpeg

Guia prático de legendas com FFmpeg — gravar SRT/ASS, embutir faixas, customizar estilo, suporte multi-idioma e extração de legendas.

FFHub·2026-04-28

Como Adicionar Legendas a Vídeo com FFmpeg

Legendas tornam vídeos acessíveis, pesquisáveis e assistíveis em ambientes barulhentos. O FFmpeg pode gravar legendas direto nos pixels do vídeo, embutir como faixas selecionáveis, extrair legendas existentes e converter entre formatos. Este guia cobre tudo isso com comandos práticos.

Hardcode ou softcode: qual escolher?

Antes de adicionar legendas, você precisa decidir o como:

Método	Descrição	Prós	Contras
Hardcode (gravado)	Legendas renderizadas nos pixels do vídeo	Sempre visível, reprodução universal	Não dá pra desligar, exige reencodificação
Softcode (embutido)	Legendas guardadas como faixa separada	Pode ligar/desligar, vários idiomas	O player precisa suportar

Regra geral: hardcode para redes sociais e compatibilidade máxima. Softcode para conteúdo longo e suporte multi-idioma. Se você está construindo uma plataforma UGC que processa vídeos enviados por usuários, softcode geralmente é a melhor escolha.

Como gravar legendas SRT no vídeo (hardcode)?

SRT é o formato de legenda mais comum. Para gravar no vídeo:

# Hardcode SRT subtitles
ffmpeg -i input.mp4 -vf "subtitles=subs.srt" output.mp4

Só isso. O FFmpeg usa o filtro subtitles (com libass por trás) para renderizar o arquivo SRT direto em cada frame.

Como customizar a aparência do SRT?

A renderização padrão de SRT é simples. Você pode estilizar com a opção force_style:

# Custom font, size, and color
ffmpeg -i input.mp4 -vf "subtitles=subs.srt:force_style='FontName=Arial,FontSize=24,PrimaryColour=&H00FFFFFF,OutlineColour=&H00000000,Outline=2,Shadow=1'" output.mp4

Parâmetros de estilo comuns:

Parâmetro	Exemplo	Descrição
FontName	Arial	Família da fonte
FontSize	24	Tamanho em pontos
PrimaryColour	&H00FFFFFF	Cor do texto (hex ABGR)
OutlineColour	&H00000000	Cor do contorno
BackColour	&H80000000	Cor da sombra/fundo
Outline	2	Espessura do contorno
Shadow	1	Profundidade da sombra
Bold	1	Texto em negrito (0 ou 1)
Alignment	2	Posição (2=centro inferior)
MarginV	30	Margem vertical da borda

Atenção: as cores usam formato ABGR (Alpha, Blue, Green, Red), não o RGB tradicional.

# Yellow text with black outline, larger font, positioned higher
ffmpeg -i input.mp4 -vf "subtitles=subs.srt:force_style='FontSize=28,PrimaryColour=&H0000FFFF,OutlineColour=&H00000000,Outline=3,MarginV=40'" output.mp4

Como lidar com caracteres especiais no caminho?

Se o caminho do arquivo de legenda tem caracteres especiais, escape:

# Escape colons in Windows paths or special characters
ffmpeg -i input.mp4 -vf "subtitles='my\ subtitles.srt'" output.mp4

# Or use the subtitle file index approach
ffmpeg -i input.mp4 -i subs.srt -filter_complex "[0:v][1:s]overlay" output.mp4

Como gravar legendas estilizadas ASS/SSA?

Legendas ASS (Advanced SubStation Alpha) suportam estilização rica — fontes, cores, animações e posicionamento por linha. Ao gravar arquivos ASS, todo o estilo é preservado:

# Hardcode ASS subtitles (all styling preserved)
ffmpeg -i input.mp4 -vf "ass=subs.ass" output.mp4

Como criar um arquivo ASS simples?

Exemplo de estrutura de arquivo ASS:

[Script Info]
Title: My Subtitles
ScriptType: v4.00+
PlayResX: 1920
PlayResY: 1080

[V4+ Styles]
Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
Style: Default,Arial,48,&H00FFFFFF,&H000000FF,&H00000000,&H80000000,0,0,0,0,100,100,0,0,1,2,1,2,10,10,40,1

[Events]
Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
Dialogue: 0,0:00:01.00,0:00:04.00,Default,,0,0,0,,Hello, this is a subtitle.
Dialogue: 0,0:00:05.00,0:00:08.00,Default,,0,0,0,,This line has {\b1}bold{\b0} text.

Como converter SRT em ASS para customizar?

# Convert SRT to ASS (then you can edit the ASS styles)
ffmpeg -i subs.srt subs.ass

Depois de converter, edite a seção [V4+ Styles] do arquivo ASS para customizar a aparência. Você também pode querer converter seu vídeo para outro formato antes de adicionar legendas, dependendo da plataforma alvo.

Como adicionar legendas softcode (faixas embutidas)?

Legendas softcode ficam guardadas como uma faixa separada (faixa de legenda) dentro do container. O espectador pode ligar e desligar.

Adicionar SRT como faixa de legenda

# Add SRT subtitle track to MP4
ffmpeg -i input.mp4 -i subs.srt -c copy -c:s mov_text output.mp4

# Add SRT subtitle track to MKV (MKV supports SRT natively)
ffmpeg -i input.mp4 -i subs.srt -c copy -c:s srt output.mkv

Importante: containers MP4 exigem o codec mov_text para legendas. MKV suporta SRT, ASS e muitos outros formatos nativamente.

Adicionar legendas em vários idiomas

# Add English and Spanish subtitle tracks to MKV
ffmpeg -i input.mp4 -i english.srt -i spanish.srt \
  -map 0:v -map 0:a -map 1 -map 2 \
  -c copy -c:s srt \
  -metadata:s:s:0 language=eng -metadata:s:s:0 title="English" \
  -metadata:s:s:1 language=spa -metadata:s:s:1 title="Spanish" \
  output.mkv

Para MP4:

# Add multiple subtitle tracks to MP4
ffmpeg -i input.mp4 -i english.srt -i chinese.srt \
  -map 0:v -map 0:a -map 1 -map 2 \
  -c copy -c:s mov_text \
  -metadata:s:s:0 language=eng -metadata:s:s:0 title="English" \
  -metadata:s:s:1 language=chi -metadata:s:s:1 title="Chinese" \
  output.mp4

Definir faixa de legenda padrão

# Mark the first subtitle track as default
ffmpeg -i input.mp4 -i subs.srt \
  -map 0 -map 1 \
  -c copy -c:s mov_text \
  -disposition:s:0 default \
  output.mp4

Adicionar legendas ASS como faixa softcode

# Add ASS to MKV (preserves all styling for compatible players)
ffmpeg -i input.mp4 -i subs.ass -map 0 -map 1 -c copy -c:s ass output.mkv

Como extrair legendas de um vídeo?

Extrair para SRT

# Extract the first subtitle track to SRT
ffmpeg -i input.mkv -map 0:s:0 output.srt

# Extract the second subtitle track
ffmpeg -i input.mkv -map 0:s:1 output.srt

Extrair para ASS

# Extract subtitle track as ASS (preserves styling)
ffmpeg -i input.mkv -map 0:s:0 output.ass

Listar faixas de legenda disponíveis

# Show all streams including subtitles
ffprobe -v error -show_entries stream=index,codec_name,codec_type -of csv input.mkv

# More detailed subtitle info
ffprobe -v error -select_streams s -show_entries stream=index,codec_name:stream_tags=language,title -of json input.mkv

Extrair todas as faixas de legenda

#!/bin/bash
# Extract all subtitle tracks from a video
INPUT="input.mkv"

# Count subtitle streams
COUNT=$(ffprobe -v error -select_streams s -show_entries stream=index -of csv=p=0 "$INPUT" | wc -l)

for i in $(seq 0 $((COUNT - 1))); do
  # Get language tag
  LANG=$(ffprobe -v error -select_streams s:$i -show_entries stream_tags=language -of csv=p=0 "$INPUT")
  LANG=${LANG:-"track$i"}
  ffmpeg -i "$INPUT" -map 0:s:$i "${INPUT%.*}_${LANG}.srt"
done

Como converter entre formatos de legenda?

O FFmpeg consegue converter entre formatos de legenda:

# SRT to ASS
ffmpeg -i subs.srt subs.ass

# ASS to SRT (loses styling)
ffmpeg -i subs.ass subs.srt

# SRT to WebVTT
ffmpeg -i subs.srt subs.vtt

# SUB/IDX (DVD) to SRT (requires OCR — FFmpeg can't do this directly)
# Use a tool like SubtitleEdit or Tesseract for bitmap-to-text conversion

De	Para	Preserva Estilo?
SRT → ASS	Sim	Adiciona estilo padrão
ASS → SRT	Não	Perde todo o estilo
SRT → VTT	Parcial	Mantém formatação básica
VTT → SRT	Parcial	Perde recursos específicos do VTT

Como ajustar a sincronia das legendas?

Atrasar ou adiantar legendas

# Delay subtitles by 2.5 seconds
ffmpeg -i input.mp4 -itsoffset 2.5 -i subs.srt -map 0 -map 1 -c copy -c:s mov_text output.mp4

Para legendas hardcode, use o filtro setpts ou ajuste o arquivo SRT direto (se você precisa recortar ou juntar trechos de vídeo, os ajustes de timing ficam ainda mais importantes):

# Shift hardcoded subtitles (using subtitle filter with offset)
ffmpeg -i input.mp4 -vf "subtitles=subs.srt" -ss 00:00:02.500 output.mp4

Como gravar legendas com controle de resolução?

No hardcode, a qualidade de renderização da legenda depende da resolução do vídeo. Para o melhor resultado, mantenha a resolução original:

# Hardcode subtitles while keeping original resolution
ffmpeg -i input.mp4 -vf "subtitles=subs.srt" -c:v libx264 -crf 23 -c:a copy output.mp4

# Hardcode and scale to 1080p
ffmpeg -i input.mp4 -vf "subtitles=subs.srt,scale=-2:1080" -c:v libx264 -crf 23 -c:a copy output.mp4

Renderização da fonte para resoluções diferentes

# For 720p video — smaller font
ffmpeg -i input.mp4 -vf "subtitles=subs.srt:force_style='FontSize=20'" -c:v libx264 -crf 23 output.mp4

# For 4K video — larger font
ffmpeg -i input.mp4 -vf "subtitles=subs.srt:force_style='FontSize=48,Outline=3'" -c:v libx264 -crf 23 output.mp4

Como processar legendas em lote?

Gravar legendas em todos os vídeos

# Assumes each video has a matching .srt file
for f in *.mp4; do
  srt="${f%.mp4}.srt"
  if [ -f "$srt" ]; then
    ffmpeg -i "$f" -vf "subtitles=$srt" -c:v libx264 -crf 23 -c:a copy "subtitled_${f}"
  fi
done

Embutir legendas softcode em todos os vídeos

# Add matching SRT files as subtitle tracks
for f in *.mp4; do
  srt="${f%.mp4}.srt"
  if [ -f "$srt" ]; then
    ffmpeg -i "$f" -i "$srt" -c copy -c:s mov_text "soft_${f}"
  fi
done

Como resolver problemas comuns?

"No such filter: subtitles" — O FFmpeg foi compilado sem suporte a libass. Instale uma build completa:

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg libass-dev

As legendas não aparecem — Verifique a codificação do arquivo de legenda. O FFmpeg espera UTF-8:

# Convert subtitle encoding to UTF-8
iconv -f ISO-8859-1 -t UTF-8 subs_latin.srt > subs_utf8.srt

Posição ou tamanho da legenda errados — A resolução do vídeo não bate com a resolução assumida pela legenda. Use force_style para sobrescrever:

ffmpeg -i input.mp4 -vf "subtitles=subs.srt:force_style='FontSize=24,MarginV=30'" output.mp4

Caracteres especiais aparecem como caixinhas — A fonte não suporta os caracteres. Especifique uma fonte que suporte seu idioma:

ffmpeg -i input.mp4 -vf "subtitles=subs.srt:force_style='FontName=Noto Sans CJK SC'" output.mp4

Saída MP4 falha com "unknown codec" para legendas — MP4 só suporta mov_text. Use MKV para outros formatos de legenda, ou faça hardcode.

Alternativa em nuvem com FFHub

Gravar legendas exige reencodificação, e isso consome muita CPU — um vídeo de 1 hora pode levar mais de 20 minutos em uma máquina comum. O FFHub roda FFmpeg na nuvem via API, então você pode delegar a gravação de legendas para servidores rápidos enquanto sua máquina fica livre.

Isso é especialmente útil quando você precisa gerar várias versões de legendas (idiomas diferentes, estilos diferentes) a partir do mesmo vídeo de origem.

Resumo

Hardcode (-vf "subtitles=subs.srt") para visibilidade garantida em todas as plataformas
Softcode (-c:s mov_text para MP4, -c:s srt para MKV) para faixas que ligam/desligam
Use force_style para customizar a aparência de legendas SRT
Use formato ASS quando precisar de estilo rico e animações
Use -map para adicionar várias línguas
Use ffprobe para inspecionar faixas de legenda existentes antes de extrair
Garanta sempre que os arquivos de legenda estejam em UTF-8