Flujo CLI de subtítulos: generar, convertir e incrustar

Tim Koschützki

Cofundador · Berlín, Alemania · Mostrar bio

Gestionar subtítulos de forma rápida y reproducible es clave para lograr videos accesibles y multilingües. Las herramientas de interfaz de línea de comandos (CLI, por sus siglas en inglés) destacan aquí porque se prestan al scripting, se integran bien con CI/CD y evitan las interfaces gráficas lentas y llenas de clics. Esta guía recorre un flujo de trabajo completo (generar, convertir, insertar o incrustar subtítulos) con utilidades de código abierto que puedes instalar con un solo comando.

¿Por qué usar herramientas CLI para gestionar subtítulos?

Los programas de CLI te permiten:

• procesar por lotes cientos de videos sin tocar el ratón,
• automatizar tareas en GitHub Actions, Jenkins o trabajos cron,
• combinar herramientas de primer nivel en lugar de depender de una sola aplicación monolítica, y
• reproducir los resultados con exactitud al registrar tus comandos en el control de versiones.

Si tu equipo ya publica código desde la terminal, añadir subtítulos de la misma manera mantiene el pipeline coherente.

Generar subtítulos con Whisper o subsai

Los modelos modernos de voz a texto por fin hacen que la generación automática de subtítulos sea lo bastante precisa para producción. Whisper, de OpenAI, es el caballo de batalla, y subsai añade una envoltura amigable junto con algunos trucos de edición adicionales.

Whisper

# Create a virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate

# Install whisper
pip install git+https://github.com/openai/whisper.git

# Generate english subtitles in SRT format
whisper video.mp4 --model base --output_format srt --language en

Subsai

pip install git+https://github.com/absadiki/subsai.git

# Same result as above, with some post-processing niceties
subsai video.mp4 --model base --output subtitles.srt

Ambas herramientas generan subtítulos con marcas de tiempo que suelen tener una precisión del 95 %–98 % sin ajustes adicionales. Una revisión manual rápida con un editor de subtítulos como Aegisub remata el trabajo.

Convertir entre formatos con Subtitle Edit CLI

¿Necesitas WebVTT para la web o ASS para estilos avanzados? Subtitle Edit, famoso por su interfaz gráfica, también ofrece una CLI multiplataforma.

# For Ubuntu/Debian, use the .Net version
sudo apt-get install -y dotnet-sdk-8.0

# Install the global tool
dotnet tool install --global SubtitleEdit.CLI

# Convert SRT ➜ VTT
SubtitleEdit.CLI convert input.srt output.vtt

# Convert SRT ➜ ASS
SubtitleEdit.CLI convert input.srt output.ass

Subtitle Edit admite más de 200 formatos, así que es muy probable que hable el que necesitas.

Insertar subtítulos seleccionables con mkvtoolnix

Los subtítulos seleccionables viven en el contenedor como una pista independiente. Se pueden activar o desactivar, aplicarles estilos o reemplazarlos sin tocar el flujo de video.

# Install mkvtoolnix (Ubuntu/Debian)
sudo apt-get install mkvtoolnix

# Embed subtitles
mkvmerge -o output.mkv video.mp4 subtitles.srt

¿Quieres varios idiomas?

mkvmerge -o output.mkv \
  video.mp4 \
  --language 0:eng subs_en.srt \
  --language 0:spa subs_es.srt

Reproductores como VLC, mpv y la mayoría de las apps de smart TV mostrarán automáticamente un selector de idioma.

Incrustar subtítulos (hard-code) con FFmpeg

Los subtítulos incrustados se pintan sobre los píxeles del video, lo que garantiza una compatibilidad del 100 % a costa de la flexibilidad.

# Plain SRT burn-in
ffmpeg -i video.mp4 -vf "subtitles=subtitles.srt" -c:v libx264 -crf 20 -preset veryfast output.mp4

# Custom styling, white text, 24 pt font
affinity='FontSize=24,PrimaryColour=&HFFFFFF&'
ffmpeg -i video.mp4 -vf "subtitles=subtitles.srt:force_style='${affinity}'" \
       -c:v libx264 -crf 20 -preset veryfast output-styled.mp4

# Ass/ssa subtitles retain their own styling
affinity_file=subtitles.ass
ffmpeg -i video.mp4 -vf "ass=${affinity_file}" -c:v libx264 -crf 20 -preset veryfast output-ass.mp4

Usa -c:v h264_nvenc o -c:v hevc_nvenc para aprovechar una GPU NVIDIA y reducir el tiempo de codificación.

Automatizar todo con un script de shell

A continuación tienes un script de Bash que enlaza algunos de los comandos anteriores. Guárdalo en subtitles.sh, hazlo ejecutable y apúntalo a un directorio con archivos .mp4.

#!/usr/bin/env bash
set -euo pipefail

# Create a function for processing
process_video() {
  local video="$1"
  echo "Processing ${video}..."

  # Generate subtitles
  # Whisper output is e.g. video.srt for video.mp4.
  whisper "$video" --model base --output_format srt --language en

  # Convert to VTT if needed
  # This assumes whisper created ${video%.mp4}.srt
  SubtitleEdit.CLI convert "${video%.mp4}.srt" "${video%.mp4}.vtt"

  # Create soft-subbed version
  # This also assumes ${video%.mp4}.srt exists
  mkvmerge -o "${video%.mp4}_subbed.mkv" "$video" "${video%.mp4}.srt"
}

# Process all MP4 files
for video in *.mp4; do
  process_video "$video"
done

Puedes guardarlo en un job de CI para que cada nuevo video que llegue al repositorio reciba subtítulos automáticamente.

Consejos de rendimiento y escalado

• Elige el modelo de Whisper adecuado. El modelo tiny procesa aproximadamente en tiempo real en una CPU; large puede ser 10× más lento, pero capta palabras difíciles.
• Usa GPU siempre que sea posible. Tanto Whisper (--device cuda) como FFmpeg (-hwaccel cuda) obtienen mejoras de 5×–10× en hardware moderno.
• Paraleliza con cautela. Whisper está limitado por CPU/GPU, así que una instancia por GPU suele ser lo óptimo. Lanzar demasiados procesos puede ralentizarlo todo.
• Guarda los resultados en caché. Almacena los archivos .srt generados para que las nuevas ejecuciones solo transcodifiquen.

Subtítulos seleccionables vs. incrustados

Elige subtítulos seleccionables para plataformas de streaming y flexibilidad de edición. Usa subtítulos incrustados cuando no puedas controlar el entorno de reproducción o necesites una marca fija sobre la imagen.

Conclusión

Con Whisper, subsai, Subtitle Edit CLI, MKVToolNix y FFmpeg puedes montar un pipeline sin un solo clic que añade subtítulos de alta calidad a cada video que publica tu equipo. Si prefieres evitar el mantenimiento de servidores para incrustar subtítulos, nuestro Robot 🤖 /video/subtitle añade subtítulos SRT o WebVTT existentes a un video. No genera la transcripción. Sube el video en el campo de formulario input_video y el archivo de subtítulos en input_srt; una Assembly mínima se ve así:

{
  "steps": {
    "subtitle_video": {
      "robot": "/video/subtitle",
      "use": {
        "steps": [
          { "name": ":original", "fields": "input_video", "as": "video" },
          { "name": ":original", "fields": "input_srt", "as": "subtitles" }
        ]
      },
      "subtitles_type": "burned",
      "font_size": 24,
      "position": "bottom",
      "font_color": "FFFFFF",
      "border_style": "outline"
    }
  }
}

Pruébalo: tus espectadores, sobre todo quienes miran con reproducción automática y sin sonido, te lo agradecerán.