Integra subtítulos en videos fácilmente con Lua

Tim Koschützki

Cofundador · Berlín, Alemania ·

Añadir subtítulos a los videos mejora la accesibilidad y refuerza la participación de los espectadores. Lua, un lenguaje de scripting ligero y versátil, ofrece un enfoque simple pero eficiente para integrar subtítulos en tus proyectos de video.

La importancia de los subtítulos en el contenido de video

Los subtítulos son fundamentales para llegar a un público más amplio. Ayudan a los espectadores con discapacidad auditiva y también atienden a los usuarios multilingües al ofrecer texto traducido. Integrar subtítulos puede mejorar notablemente la comprensión y aumentar la participación de los usuarios.

Lua: un lenguaje de scripting ligero para el procesamiento de video

Lua es reconocido por su velocidad, su simplicidad y su facilidad de integración. Su huella mínima lo hace ideal para tareas de scripting, incluido el procesamiento de video. Con la sintaxis clara de Lua, puedes implementar rápidamente la automatización para añadir subtítulos sin sobrecarga innecesaria.

Configurar tu entorno de Lua para el procesamiento de video

El script de abajo está pensado para Lua 5.3 o una versión más reciente en Linux o macOS, con un shell POSIX y /dev/fd. FFmpeg debe incluir el filtro subtitles, que requiere libass, y el codificador libx264. Las compilaciones de los paquetes varían: revisa ffmpeg -filters y ffmpeg -encoders después de la instalación.

Para Ubuntu/Debian:

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

Para macOS:

brew update
brew install lua ffmpeg

Es posible que el paquete predeterminado de FFmpeg para macOS no incluya libass. Usa una compilación con el filtro requerido; instalar solo Lua no habilita el renderizado de subtítulos. En Windows, usa un entorno de Linux compatible como WSL en lugar de ejecutar este script de shell POSIX a través de CMD o PowerShell.

Trabajar con formatos de subtítulos

Antes de integrar subtítulos, confirma que tus archivos de subtítulos estén en un formato compatible. Los formatos más comunes incluyen:

SRT (SubRip): formato estándar con información de tiempos y de texto; ampliamente compatible.
SSA/ASS (Advanced SubStation Alpha): ofrece opciones avanzadas de estilo y posicionamiento.
VTT (Web Video Text Tracks): de uso común en aplicaciones de video para la web.

Asegúrate de que tus archivos de subtítulos se guarden con codificación UTF-8 y respeten las especificaciones de tiempos correctas.

Guía paso a paso para añadir subtítulos con Lua y FFmpeg

El siguiente script de Lua incrusta subtítulos SRT en UTF-8 dentro de un MP4. Entrecomilla los argumentos del shell y pasa el archivo de subtítulos a través del descriptor 3, de modo que su nombre de archivo nunca forme parte de la sintaxis de filtros de FFmpeg. Esto también maneja nombres que contienen espacios, comillas, dos puntos y corchetes.

#!/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.")

Guarda este script como add_subtitles.lua y hazlo ejecutable:

chmod +x add_subtitles.lua

Ejecuta el script con:

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

La verificación previa informa de un archivo de salida existente como un error, y -n le indica a FFmpeg que no lo reemplace. Usa un directorio de trabajo privado sin escritores concurrentes: este pequeño script no ofrece publicación transaccional si otro proceso crea el archivo de salida después de la verificación. Una conversión fallida aún puede dejar un archivo parcial nuevo; inspecciónalo y elige una nueva ruta de salida antes de volver a intentarlo. El audio se copia, así que el códec de audio de entrada debe ser compatible con MP4. Para subidas no confiables, ejecuta FFmpeg en un worker aislado con límites de sistema de archivos, red, memoria y tiempo de ejecución. El entrecomillado del shell no es un sandbox de medios.

Solución de problemas comunes

A continuación encontrarás algunos consejos para resolver problemas que suelen surgir durante la integración de subtítulos:

Problemas de codificación de caracteres:

Si tu archivo de subtítulos no está en UTF-8, conviértelo con:
```
iconv -f ISO-8859-1 -t UTF-8 input.srt > output.srt
```
Sincronización de los tiempos de los subtítulos:

Si los subtítulos aparecen desincronizados, añade un retraso con FFmpeg. Por ejemplo, para añadir un retraso de 2,5 segundos, crea un archivo SRT desplazado aparte y luego pasa ese archivo al script de 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 renderizado de fuentes:

Instala una fuente que contenga los caracteres de tus subtítulos y luego reemplaza solo la variable filter del script. Por ejemplo, con DejaVu Sans instalada:
```
local filter = "subtitles=/dev/fd/3:force_style='FontName=DejaVu Sans,FontSize=24'"
```

Mantén esta cadena de estilo fija en el script. Las expresiones de filtro arbitrarias proporcionadas por el usuario necesitan su propia validación; el entrecomillado del shell no valida la sintaxis de filtros de FFmpeg.

Manipulación avanzada de subtítulos (opcional)

Para un estilo más elaborado, crea un archivo de subtítulos ASS con un editor de subtítulos dedicado e inspecciona el resultado antes de incrustarlo en el video. La documentación del filtro subtitles de FFmpeg describe las opciones compatibles. Mantén los ajustes de los tiempos de los subtítulos separados del renderizado, como en el ejemplo de SRT anterior, en lugar de tratar el retraso como una opción de estilo de fuente.

Buenas prácticas para la integración de subtítulos

Cuando integres subtítulos en tus videos, ten en cuenta estas buenas prácticas:

Valida todos los archivos de entrada antes de procesarlos.
Asegúrate de que los archivos de subtítulos usen codificación UTF-8 y sigan el formato correcto.
Haz pruebas con segmentos de video más cortos para verificar la sincronización y el formato.
Mantén copias de seguridad de tus archivos originales para evitar la pérdida accidental de datos.
Implementa el manejo de errores en tus scripts para simplificar la solución de problemas.

Conclusión

Superponer subtítulos con Lua y FFmpeg es una solución práctica para mejorar la accesibilidad y la participación en los videos. Al combinar la potencia de scripting de Lua con las sólidas capacidades de FFmpeg, puedes automatizar el proceso y gestionar de forma eficaz los desafíos habituales. Para proyectos escalables y necesidades de procesamiento avanzadas, considera explorar Transloadit, que ofrece API y servicios completos para el encoding de video y la integración de subtítulos.