Subtítulos con fqmpeg: Quemar, Extraer y Embeber

El cluster C3 de fqmpeg cubre todo lo relacionado con subtítulos en cuatro verbos: subtitle y subtitle-burn queman las subtítulos en los píxeles del vídeo, extract-subtitle saca una pista de subtítulos del contenedor como .srt, y sidecar embebe un archivo externo (.srt/.ass/.vtt) dentro de un MKV como pista seleccionable. Entre los cuatro cubren el ciclo completo: leer lo que ya viene en el archivo, escribir algo nuevo dentro o al lado.

Esta guía recorre cada comando con su invocación FFmpeg generada, valores por defecto y nombre de salida, todo verificado contra el código en src/commands/ de fqmpeg 3.0.1. Al final, tres recetas que encadenan los verbos en flujos reales — incluyendo el pipeline Whisper → fqmpeg.

Lo que sacarás de esta guía

• Cuál de los 4 verbos elegir (matriz: hard vs soft, leer vs escribir)
• Comando FFmpeg exacto que cada verbo genera (salida --dry-run verificada)
• Defaults, valores permitidos y nombres de salida de cada comando
• Tres recetas end-to-end, incluyendo el pipeline de subtítulos automáticos con Whisper

El modelo mental: hard vs soft, leer vs escribir

Antes del recorrido verbo por verbo, fija dos ejes que separan toda decisión sobre subtítulos.

Eje 1 — subtítulos hard vs soft. Los hard (también llamados "quemados" u "open captions") quedan grabados en los píxeles del vídeo. No se pueden apagar, restilizar ni retraducir; viajan con la imagen para siempre. Los soft viven como una pista aparte dentro del contenedor; el reproductor permite encenderlos y apagarlos, y los menús multilingüe estilo Netflix/YouTube funcionan justamente gracias a esto.

Eje 2 — leer vs escribir. Tres verbos añaden subtítulos a un archivo (subtitle, subtitle-burn, sidecar); uno los extrae de un archivo existente (extract-subtitle).

Tres cosas a tener claras antes de seguir:

1. subtitle y subtitle-burn ambos son hard subs. A pesar del nombre, subtitle no produce una pista soft — la única diferencia entre los dos es el control de estilo. Para una pista soft conmutable, usa siempre sidecar.
2. Los soft subs piden MKV. MP4 admite mov_text técnicamente, pero la compatibilidad entre reproductores es irregular (especialmente Safari móvil y caracteres no latinos). El default de sidecar es .mkv por la misma razón que la mayoría de pipelines de archivado: Matroska es el contenedor más permisivo para múltiples pistas de subtítulos.
3. extract-subtitle solo maneja texto por defecto. La salida es .srt, así que los subtítulos basados en imagen (PGS de Blu-ray, VobSub de DVD) no se pueden extraer directamente — eso es un problema de OCR, no de remux. Para pistas de texto (la inmensa mayoría de archivos modernos), es una sola línea.

Si todavía no tienes el archivo de subtítulos, la guía de subtítulos automáticos con FFmpeg + Whisper muestra cómo generarlo desde el audio. La Receta 1 más abajo encadena ese pipeline directamente con subtitle.

Quemado: subtitle y subtitle-burn

Ambos verbos usan el filtro subtitles de FFmpeg, que decodifica el archivo de subtítulos con libass y los pinta sobre el vídeo antes de codificar. La salida es un vídeo normal con los subtítulos pintados de manera permanente en la imagen — sin pista aparte, sin botón de apagado.

subtitle — Quemado con control de estilo

El verbo principal del cluster. Permite elegir tamaño de fuente, color (5 presets) y posición en pantalla (top / center / bottom). El audio se copia stream a stream, así que solo el vídeo se vuelve a codificar.

• Source: src/commands/subtitle.js
• Filtro: subtitles=<path>:force_style='FontSize=N,PrimaryColour=…,Alignment=…'
• Audio: -c:a copy (sin recodificación)
• Escape de paths: la ruta del subtítulo se resuelve a absoluta y se escapa (: se vuelve \:, las barras invertidas se voltean a barras normales) — necesario para que libavfilter no se rompa con letras de unidad de Windows o paths con dos puntos

$ npx fqmpeg subtitle input.mp4 captions.srt --dry-run

  ffmpeg -i input.mp4 -vf subtitles=/abs/path/to/captions.srt:force_style='FontSize=24,PrimaryColour=&H00FFFFFF,Alignment=2' -c:a copy input-subtitled.mp4

$ npx fqmpeg subtitle input.mp4 captions.srt --font-size 32 --color yellow --pos top --dry-run

  ffmpeg -i input.mp4 -vf subtitles=/abs/path/to/captions.srt:force_style='FontSize=32,PrimaryColour=&H0000FFFF,Alignment=8' -c:a copy input-subtitled.mp4

Los nombres de color se mapean al formato hex BGR de ASS/SSA: white = &H00FFFFFF, yellow = &H0000FFFF, red = &H000000FF. (Ojo: el orden es BGR, no RGB, por eso "red" es 0000FF y "cyan" es FFFF00.) Si necesitas un color personalizado, copia la salida --dry-run, cambia el hex y ejecuta el FFmpeg directamente.

Los números de posición son los valores Alignment de libass: 1–3 abajo izquierda/centro/derecha, 4–6 centro vertical, 7–9 arriba. fqmpeg expone los tres más usados (bottom = 2, top = 8, center = 5); para alineación a izquierda o derecha, baja a FFmpeg directo.

subtitle-burn — Mismo quemado, API más simple

Efecto idéntico a subtitle pero sin más estilo que el tamaño de fuente. Útil cuando confías en el estilo propio del archivo de subtítulos (típico de los .ass traducidos por fans, que ya traen colores y posición) o cuando solo quieres quemar y olvidarte.

• Source: src/commands/subtitle-burn.js
• Filtro: subtitles=<path>:force_style='FontSize=N'
• Escape de paths: ninguno — el path se pasa tal cual. Usa rutas relativas simples (captions.srt) ejecutando desde el mismo directorio, o un .ass con sus propios estilos

$ npx fqmpeg subtitle-burn input.mp4 captions.srt --dry-run

  ffmpeg -i input.mp4 -vf subtitles=captions.srt:force_style='FontSize=24' -c:a copy input-burned.mp4

$ npx fqmpeg subtitle-burn input.mp4 captions.srt --font-size 28 --dry-run

  ffmpeg -i input.mp4 -vf subtitles=captions.srt:force_style='FontSize=28' -c:a copy input-burned.mp4

Cuál elegir: subtitle es el default seguro (escape de path + control de estilo, defaults razonables). Recurre a subtitle-burn cuando quieras la forma más mínima y prefieras que el estilo del archivo gane — típico con .ass traducidos por fans, donde restilear pisaría la intención del traductor.

Leer pistas existentes: extract-subtitle

extract-subtitle — Sacar una pista como .srt

Selecciona un único stream de subtítulos de un archivo multipista (típicamente un MKV de un rip de Blu-ray, o un vídeo de YouTube descargado con varios idiomas) y lo escribe como .srt independiente. El modo stream-copy lo hace casi instantáneo, sin importar el tamaño del input.

• Source: src/commands/extract-subtitle.js
• Mapping: -map 0:s:<n> -c:s srt
• Output: SubRip texto (.srt). Los subtítulos basados en imagen (PGS, DVDSub) no se transcodifican a SRT — eso es OCR, no remux

$ npx fqmpeg extract-subtitle movie.mkv --dry-run

  ffmpeg -i movie.mkv -map 0:s:0 -c:s srt movie-sub.srt

$ npx fqmpeg extract-subtitle movie.mkv --stream 1 -o english.srt --dry-run

  ffmpeg -i movie.mkv -map 0:s:1 -c:s srt english.srt

Para listar qué streams de subtítulos contiene un archivo, ejecuta ffprobe -v error -show_streams input.mkv | grep -E "index=|codec_type=subtitle|TAG:language" o usa el verbo info de fqmpeg (cubierto en la guía hub). La salida te da el mapeo: s:0 = jpn, s:1 = eng, etc., para saber qué --stream <n> pasar.

Si extract-subtitle falla con Subtitle encoding currently only possible from text to text or bitmap to bitmap, el origen es un subtítulo bitmap (PGS de Blu-ray, VobSub de DVD). Tienes dos caminos: (1) copiar bit a bit (cambia -c:s srt por -c:s copy y guarda como .sup o .idx/.sub), o (2) procesarlo con una herramienta de OCR aparte como pgs2srt o Subtitle Edit.

Embebido soft: sidecar

sidecar — Añadir un .srt externo como pista seleccionable

Toma un vídeo y un archivo de subtítulos, y los copia ambos dentro de un único MKV con el subtítulo como pista conmutable (apagada por defecto en la mayoría de reproductores, pero seleccionable desde el menú). Sin recodificación: vídeo y audio se copian, los subtítulos se mezclan.

• Source: src/commands/sidecar.js
• Códec: -c copy -c:s srt (passthrough de vídeo/audio, subtítulos guardados como SRT)
• Maps: todos los streams de vídeo del input 0, todo el audio del input 0, los subtítulos del input 1
• Contenedor de salida: MKV por defecto. MP4 técnicamente puede llevar una pista mov_text, pero añadir varios subs soft o scripts no latinos es inconsistente entre reproductores

$ npx fqmpeg sidecar input.mp4 captions.srt --dry-run

  ffmpeg -i input.mp4 -i captions.srt -c copy -c:s srt -map 0:v -map 0:a -map 1:0 -metadata:s:s:0 language=und input-subtitled.mkv

$ npx fqmpeg sidecar input.mp4 captions.srt --language en --title "English" --dry-run

  ffmpeg -i input.mp4 -i captions.srt -c copy -c:s srt -map 0:v -map 0:a -map 1:0 -metadata:s:s:0 language=en -metadata:s:s:0 title=English input-subtitled.mkv

El valor de --language se escribe en los metadatos de la pista para que VLC, MPV, Plex, Jellyfin y similares muestren el idioma correcto en su menú de audio/subs. La mayoría de reproductores usan códigos ISO 639-2 de tres letras (eng, jpn, spa); los de dos letras ISO 639-1 (en, ja, es) suelen funcionar también porque libavformat los normaliza, pero quédate con la forma de tres letras para máxima compatibilidad. Usa und (el default) cuando el idioma genuinamente no se conozca.

Para embeber varios subs soft (por ejemplo, español + inglés en el mismo MKV), corre sidecar una vez y luego ejecútalo de nuevo sobre la salida con el segundo .srt:

npx fqmpeg sidecar input.mp4 es.srt --language spa --title "Español" -o paso1.mkv
npx fqmpeg sidecar paso1.mkv en.srt --language eng --title "English" -o final.mkv

El MKV producido en el paso 1 es input válido para el paso 2; el segundo pase preserva la pista en español y añade la inglesa.

Recetas reales

Cada receta encadena varios verbos en un flujo real.

Receta 1: Pipeline Whisper → fqmpeg para subtitulado automático

Tienes un screencast de tutorial y quieres subtítulos en español quemados sin escribir ni una línea de subtítulos a mano. Whisper transcribe el audio; subtitle quema el resultado.

# Paso 1: extraer audio para Whisper (16 kHz mono basta)
ffmpeg -i screencast.mp4 -ac 1 -ar 16000 audio.wav

# Paso 2: ejecutar Whisper para producir SRT
whisper audio.wav --model small --language es --output_format srt
# → audio.srt

# Paso 3: quemar en el vídeo original con un estilo legible
npx fqmpeg subtitle screencast.mp4 audio.srt --font-size 28 --color white --pos bottom
# → screencast-subtitled.mp4

El pipeline completo tarda 2–3 veces la duración del vídeo en un portátil sin GPU con --model small (más rápido con GPU, más lento con --model large). Para procesamiento por lotes o precisión de producción, la guía de subtítulos automáticos con Whisper envuelve los tres pasos en un script Python y cubre la elección de modelo, detección de idioma y ajuste de calidad.

Receta 2: MKV multilingüe a partir de una descarga de YouTube

Usaste yt-dlp para bajar un vídeo con audio en inglés y subtítulos auto-generados (.vtt) en inglés, japonés y español (yt-dlp --write-subs --sub-langs "en,ja,es" --convert-subs srt URL). Quieres un único MKV que lleve el vídeo original más los tres idiomas como subs soft.

# Paso 1: embeber español primero
npx fqmpeg sidecar video.mp4 video.es.srt --language spa --title "Español" -o paso1.mkv

# Paso 2: añadir inglés
npx fqmpeg sidecar paso1.mkv video.en.srt --language eng --title "English" -o paso2.mkv

# Paso 3: añadir japonés
npx fqmpeg sidecar paso2.mkv video.ja.srt --language jpn --title "日本語" -o final.mkv

Abre final.mkv en VLC o MPV y el menú de subtítulos lista los tres idiomas. El tiempo total se mide en segundos porque cada paso es stream-copy. Para librerías Plex / Jellyfin, las etiquetas de idioma también guían la selección automática de subtítulos — fija tu idioma preferido en el servidor, y la pista correcta se enciende sola en cada dispositivo.

Receta 3: Restilear subs quemados de un rip de Blu-ray

Tienes un rip .mkv con subtítulos en español basados en texto que quieres quemar en el vídeo, pero más grandes y en amarillo (el estilo por defecto del rip se ve pequeño desde el sofá).

# Paso 1: sacar los subs en español como SRT
npx fqmpeg extract-subtitle source.mkv --stream 0 -o español.srt

# Paso 2: quemarlos otra vez con tipografía más grande y amarilla
npx fqmpeg subtitle source.mkv español.srt --font-size 32 --color yellow --pos bottom
# → source-subtitled.mkv

El paso 1 es instantáneo (stream-copy); el paso 2 recodifica el vídeo. Si tu TV es 4K y la fuente es 1080p, este es buen momento también para meter compress con un bitrate algo mayor, porque ya estás recodificando de todas formas. Si los subs del rip son bitmap (PGS), el paso 1 falla — pasa primero por OCR con pgs2srt y continúa desde el paso 2.

Preguntas Frecuentes

¿Por qué subtitle no produce una pista soft (conmutable) si se llama así?

Porque internamente usa el filtro subtitles de FFmpeg, que renderiza los subtítulos sobre el vídeo como parte del codificado. El nombre del verbo refleja la intención del usuario ("ponle subtítulos a este vídeo") más que el mecanismo técnico. Para una pista soft conmutable, usa sidecar — ese es el que mezcla el archivo de subtítulos como un stream en lugar de quemarlo.

¿Cuál es la diferencia real entre subtitle y subtitle-burn?

Ambos producen subtítulos quemados con el mismo filtro FFmpeg. subtitle añade tres controles de estilo (--font-size, --color, --pos) y escapa automáticamente la ruta del archivo, así que funciona con paths absolutos, paths con espacios o letras de unidad de Windows. subtitle-burn solo expone --font-size y pasa la ruta sin tocar. Usa subtitle salvo que quieras explícitamente la forma simple para preservar el self-styling de un .ass.

¿Por qué importa el escape de la ruta?

El parser de libavfilter interpreta : como separador de opciones dentro de los grafos de filtros. Una ruta tipo C:\Users\me\sub.srt se lee como filtro "C" con opción "Users", y eso falla al instante. subtitle resuelve la ruta a absoluta, reemplaza barras invertidas por barras normales y escapa los dos puntos como \: — todo en un paso. Si alguna vez pegaste un comando FFmpeg con subtitles= desde Stack Overflow y te explotó con Unable to open en Windows, la causa suele ser exactamente esta.

¿Puedo quemar subtítulos .ass con su propio estilo?

Sí — los archivos .ass (Advanced SubStation Alpha) llevan su propia fuente, color y datos de posición, y libass los renderiza fielmente. subtitle-burn es la opción más limpia aquí porque pasarle --color a subtitle sobreescribiría el estilo línea por línea del archivo. Eso sí: asegúrate de que las fuentes referenciadas dentro del .ass están instaladas en el sistema donde corre FFmpeg, o libass cae a una fuente por defecto.

Mi SRT extraído solo tiene timecodes, sin texto. ¿Qué pasó?

Casi siempre una de dos cosas. (1) El subtítulo de origen era bitmap (PGS / VobSub) y FFmpeg cayó a escribir entradas SRT vacías — comprueba el formato de entrada con ffprobe -show_streams y busca codec_name=hdmv_pgs_subtitle o dvd_subtitle. (2) El SRT de origen tenía problemas de codificación; intenta forzar UTF-8 con iconv -f WINDOWS-1252 -t UTF-8 input.srt > output.srt antes de extraer. SRT en sí es texto plano, así que con un input limpio el ida y vuelta es sin pérdida.

¿sidecar funciona con MP4 en vez de MKV?

En teoría sí — MP4 admite una pista mov_text. En la práctica, fqmpeg usa MKV por defecto porque mov_text pierde estilo, falla con scripts no latinos y no lo reconocen todos los reproductores (Safari móvil es particularmente inconsistente). Si necesitas entregar MP4, pasa -o output.mp4 y asume las limitaciones. Para todo lo demás, MKV se reproduce en VLC, MPV, Plex, Jellyfin, smart TVs modernas y la mayoría de reproductores en navegador vía fragmentación con hls.js.

¿Por qué --language jpn es un código de tres letras y no ja?

La especificación Matroska recomienda códigos ISO 639-2 (tres letras) para el elemento Language, y la mayoría de implementaciones de reproductor los esperan así. El default und de fqmpeg también es ISO 639-2 — el placeholder oficial para "idioma no declarado". libavformat es flexible y normalmente acepta también ISO 639-1 (ja, en, es), pero la forma larga es la que aparece en herramientas como mediainfo, MakeMKV y la lógica de auto-selección de Plex, así que quédate ahí.

¿Cómo quemo subtítulos por lotes sobre una carpeta de vídeos?

Loop de shell estándar. Asumiendo que cada vídeo tiene su .srt correspondiente (por ejemplo, clase-01.mp4 + clase-01.srt):

for v in clases/*.mp4; do
  srt="${v%.mp4}.srt"
  [ -f "$srt" ] || { echo "saltar: $v (sin srt)"; continue; }
  npx fqmpeg subtitle "$v" "$srt" --font-size 28
done

Cada salida queda al lado de su input como clase-01-subtitled.mp4. La línea de salto evita que el loop falle si un vídeo se quedó sin SRT.

Conclusión

Los cuatro verbos de C3 cubren todo el ciclo de subtítulos:

• subtitle para quemar con control de estilo (la elección por defecto)
• subtitle-burn para quemar tal cual cuando el estilo del archivo debe mandar
• extract-subtitle para sacar pistas existentes de MKV/MP4 como SRT
• sidecar para embeber un SRT externo en MKV como pista soft conmutable

Cada verbo imprime su invocación FFmpeg subyacente bajo --dry-run, así que puedes copiarla, adaptarla (color hex personalizado, código ISO 639-3, salida MP4) o aprender la sintaxis detrás del verbo. Para generación automática de subtítulos desde audio, mira la guía de subtítulos automáticos con Whisper. Para el mapa más amplio de fqmpeg, vuelve a la guía completa de fqmpeg.