Integre legendas em vídeos com facilidade usando Lua

Tim Koschützki

Cofundador · Berlim, Alemanha ·

Adicionar legendas a vídeos melhora a acessibilidade e aumenta o engajamento do público. Lua, uma linguagem de script leve e versátil, oferece uma abordagem simples e eficiente para integrar legendas aos seus projetos de vídeo.

A importância das legendas em conteúdo de vídeo

As legendas são essenciais para alcançar um público mais amplo. Elas ajudam espectadores com deficiência auditiva e também atendem usuários multilíngues ao oferecer o texto traduzido. Integrar legendas pode melhorar bastante a compreensão e aumentar o engajamento dos usuários.

Lua: uma linguagem de script leve para processamento de vídeo

Lua é conhecida pela velocidade, pela simplicidade e pela facilidade de incorporação. Seu consumo mínimo de recursos a torna ideal para tarefas de script, incluindo o processamento de vídeo. Com a sintaxe clara de Lua, você implementa rapidamente a automação para adicionar legendas sem sobrecarga desnecessária.

Como configurar seu ambiente Lua para processamento de vídeo

O script abaixo é voltado para Lua 5.3 ou mais recente no Linux ou no macOS, com um shell POSIX e /dev/fd. O FFmpeg precisa incluir o filtro subtitles, que exige a libass, e o encoder libx264. As builds dos pacotes variam: confira ffmpeg -filters e ffmpeg -encoders após a instalação.

Para Ubuntu/Debian:

sudo apt-get update
sudo apt-get install lua5.3 ffmpeg

Para macOS:

brew update
brew install lua ffmpeg

O pacote padrão do FFmpeg para macOS pode não incluir a libass. Use uma build com o filtro necessário; instalar apenas o Lua não habilita a renderização de legendas. No Windows, use um ambiente Linux compatível, como o WSL, em vez de executar este script de shell POSIX pelo CMD ou pelo PowerShell.

Como trabalhar com formatos de legenda

Antes de integrar as legendas, confirme que seus arquivos de legenda estão em um formato compatível. Os formatos mais comuns incluem:

SRT (SubRip): formato padrão com informações de tempo e texto; amplamente compatível.
SSA/ASS (Advanced SubStation Alpha): oferece opções avançadas de estilo e posicionamento.
VTT (Web Video Text Tracks): muito usado em aplicações de vídeo para a web.

Garanta que seus arquivos de legenda estejam salvos com a codificação UTF-8 e sigam as especificações de tempo corretas.

Guia passo a passo para adicionar legendas com Lua e FFmpeg

O script Lua a seguir grava legendas SRT em UTF-8 diretamente na imagem de um MP4 (legendas embutidas). Ele coloca os argumentos do shell entre aspas e passa o arquivo de legenda pelo descritor 3, de modo que o nome do arquivo nunca passa a fazer parte da sintaxe de filtros do FFmpeg. Isso também resolve nomes que contêm espaços, aspas, dois-pontos e colchetes.

#!/usr/bin/env lua

if #arg ~= 0 and #arg ~= 3 then
  io.stderr:write("Usage: lua add_subtitles.lua <video.mp4> <subtitles.srt> <new-output.mp4>\n")
  os.exit(1)
end

local video_file = arg[1] or "input.mp4"
local subtitles_file = arg[2] or "subtitles.srt"
local output_file = arg[3] or "output.mp4"

local existing = io.open(output_file, "rb")
if existing then
  existing:close()
  io.stderr:write("Output already exists; choose a new filename.\n")
  os.exit(1)
end

local function shell_quote(value)
  return "'" .. value:gsub("'", "'\\''") .. "'"
end

local function local_path(value)
  if value:sub(1, 1) == "/" then return value end
  return "./" .. value
end

local filter = "subtitles=/dev/fd/3"
local command = string.format(
  "ffmpeg -nostdin -n -i %s -vf %s -c:v libx264 -crf 23 -c:a copy %s 3<%s",
  shell_quote(local_path(video_file)),
  shell_quote(filter),
  shell_quote(local_path(output_file)),
  shell_quote(local_path(subtitles_file))
)

local success = os.execute(command)
if not success then
  io.stderr:write("Subtitle conversion failed. Inspect any partial output before retrying.\n")
  os.exit(1)
end
print("Subtitles added successfully.")

Salve este script como add_subtitles.lua e torne-o executável:

chmod +x add_subtitles.lua

Execute o script com:

./add_subtitles.lua input.mp4 subtitles.srt output.mp4

A verificação prévia informa como erro um arquivo de saída já existente, e -n instrui o FFmpeg a não substituí-lo. Use um diretório de trabalho privado, sem outros processos gravando nele ao mesmo tempo: este pequeno script não oferece publicação transacional caso outro processo crie o arquivo de saída depois da verificação. Uma conversão com falha ainda pode deixar um novo arquivo parcial; inspecione-o e escolha um novo caminho de saída antes de tentar outra vez. O áudio é copiado, então o codec de áudio da entrada precisa ser compatível com MP4. Para uploads não confiáveis, execute o FFmpeg em um worker isolado, com limites de sistema de arquivos, rede, memória e tempo de execução. Colocar argumentos entre aspas no shell não funciona como sandbox de mídia.

Solução de problemas comuns

Veja abaixo algumas dicas para resolver problemas que costumam surgir ao integrar legendas:

Problemas de codificação de caracteres:

Se o seu arquivo de legenda não estiver em UTF-8, converta-o com:
```
iconv -f ISO-8859-1 -t UTF-8 input.srt > output.srt
```
Sincronização do tempo das legendas:

Se as legendas aparecerem fora de sincronia, adicione um atraso com o FFmpeg. Por exemplo, para adicionar um atraso de 2,5 segundos, crie um arquivo SRT deslocado separado e depois passe esse arquivo para o script Lua:
```
ffmpeg -nostdin -n -itsoffset 2.5 -i subtitles.srt -c:s srt shifted.srt
lua add_subtitles.lua input.mp4 shifted.srt delayed.mp4
```
Problemas de renderização de fontes:

Instale uma fonte que contenha os caracteres das suas legendas e substitua apenas a variável filter no script. Por exemplo, com a DejaVu Sans instalada:
```
local filter = "subtitles=/dev/fd/3:force_style='FontName=DejaVu Sans,FontSize=24'"
```

Mantenha essa string de estilo fixa no script. Expressões de filtro arbitrárias fornecidas por usuários precisam de validação própria; colocar argumentos entre aspas no shell não valida a sintaxe de filtros do FFmpeg.

Manipulação avançada de legendas (opcional)

Para um estilo mais elaborado, crie um arquivo de legenda ASS em um editor de legendas dedicado e confira o resultado antes de gravá-lo no vídeo. A documentação do filtro subtitles do FFmpeg descreve as opções compatíveis. Mantenha os ajustes de tempo das legendas separados da renderização, como no exemplo com SRT acima, em vez de tratar o atraso como uma opção de estilo da fonte.

Boas práticas para integrar legendas

Ao integrar legendas aos seus vídeos, tenha em mente estas boas práticas:

Valide todos os arquivos de entrada antes do processamento.
Garanta que os arquivos de legenda usem a codificação UTF-8 e sigam o formato correto.
Faça testes com trechos de vídeo mais curtos para verificar a sincronização e a formatação.
Mantenha backups dos arquivos originais para evitar perdas acidentais de dados.
Implemente tratamento de erros nos seus scripts para facilitar a solução de problemas.

Conclusão

Sobrepor legendas com Lua e FFmpeg é uma solução prática para melhorar a acessibilidade e o engajamento dos vídeos. Ao combinar o poder de script do Lua com os recursos robustos do FFmpeg, você automatiza o processo e lida de forma eficaz com os desafios mais comuns. Para projetos escaláveis e necessidades avançadas de processamento, vale conhecer a Transloadit, que oferece APIs e serviços completos de codificação de vídeo e integração de legendas.