Communitygithub.com

ffmpeg-captions-subtitles

Sistema completo de subtítulos y leyendas para FFmpeg 7.1 LTS y 8.0.1 (última versión estable, publicada el 2025-11-20). Actívalo de forma proactiva para: (1) Quemado de subtítulos (incrustar SRT/ASS/VTT), (2) Añadir pistas de subtítulos blandos, (3) Extraer subtítulos de video, (4) Conversión de formatos de subtítulos, (5) Leyendas con estilo (fuente, color, contorno, sombra), (6) Posicionamiento y alineación de subtítulos, (7) Subtítulos cerrados CEA-608/708, (8) Superposiciones de texto con drawtext, (9) Transcripción automática con Whisper AI (FFmpeg 8.0+ con VAD, multilingüe, GPU), (10) Procesamiento por lotes de subtítulos. Incluye: Tablas de referencia de formatos, guía de parámetros de estilo, gráficos de alineación y posicionamiento, comparativa de modelos Whisper, configuración de VAD, ejemplos de texto dinámico, mejores prácticas de accesibilidad. Garantiza: Leyendas profesionales con estilo adecuado y cumplimiento de accesibilidad.

¿Qué es ffmpeg-captions-subtitles?

Este skill proporciona una guía completa y práctica para trabajar con subtítulos, leyendas cerradas y superposiciones de texto utilizando FFmpeg (versiones 7.1 LTS y 8.0.1+). Es útil para cualquier desarrollador o creador de contenido que necesite manipular subtítulos en archivos de video, ya sea para incrustarlos (quemado), agregarlos como pistas blandas (soft subs), extraerlos, convertirlos entre formatos o personalizar su estilo visual. El skill incluye tablas de referencia de formatos compatibles (SRT, ASS, VTT, entre otros), parámetros de estilo ASS (como color, fuente, contorno y sombra), valores de alineación, y ejemplos detallados de comandos para cada operación. También aborda la integración con Whisper AI para transcripción automática (disponible en FFmpeg 8.0+), la configuración de VAD, y las mejores prácticas de accesibilidad. El skill está diseñado para trabajar en Windows (usando barras invertidas en rutas) y sistemas Unix/Linux, y se activa de forma proactiva cuando se detectan tareas relacionadas con subtítulos o leyendas.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Biel-developer/skills-videos/tree/HEAD/skills/ffmpeg-captions-subtitles

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

PAUTAS CRÍTICAS

Requisitos de Rutas de Archivo en Windows

OBLIGATORIO: Usar siempre barras invertidas en Windows para las rutas de archivo

Cuando uses herramientas de Editar o Escribir en Windows, DEBES usar barras invertidas (\) en las rutas de archivo, NO barras normales (/).

Pautas de Documentación

NUNCA crear nuevos archivos de documentación a menos que el usuario lo solicite explícitamente.


Referencia Rápida

TareaComando
Quemar SRTffmpeg -i video.mp4 -vf "subtitles=subs.srt" output.mp4
Quemar ASSffmpeg -i video.mp4 -vf "ass=subs.ass" output.mp4
Añadir sub blandoffmpeg -i video.mp4 -i subs.srt -c copy -c:s mov_text output.mp4
Extraer subffmpeg -i video.mkv -map 0:s:0 output.srt
Estilo subs-vf "subtitles=s.srt:force_style='FontSize=24,PrimaryColour=&HFFFFFF'"
Superponer texto-vf "drawtext=text='Hola':x=10:y=10:fontsize=24:fontcolor=white"
FormatoExtensiónMejor para
SRT.srtSimple, universal
ASS.assCon estilo, animado, anime
VTT.vttWeb/Video HTML5

Cuándo Usar Este Skill

Úsalo para operaciones con subtítulos y leyendas:

  • Incrustar (quemar) subtítulos en el video
  • Añadir pistas de subtítulos blandos a contenedores
  • Extraer subtítulos de MKV/MP4
  • Dar estilo a las leyendas (fuente, color, posición)
  • Superposiciones de texto dinámico

Subtítulos y Leyendas en FFmpeg (2025)

Guía completa para trabajar con subtítulos, leyendas cerradas y superposiciones de texto usando FFmpeg.

Referencia de Formatos de Subtítulo

Formatos Soportados

FormatoExtensiónCaracterísticasCaso de Uso
SubRip.srtTemporización simple + textoUniversal, web
Advanced SubStation Alpha.ass/.ssaEstilo rico, posicionamiento, efectosAnime, subs con estilo
WebVTT.vttEstándar web, señales, estiloVideo HTML5
TTML/DFXP.ttml/.dfxpTransmisión, accesibilidadServicios de streaming
MOV Text.mov (incrustado)Nativo de QuickTimeEcosistema Apple
DVB Subtitle(incrustado)Basado en mapas de bitsTransmisión europea
PGS.supSubtítulos de mapa de bits Blu-rayBlu-ray
CEA-608/708(incrustado)Subtítulos cerradosTransmisión en EE. UU., streaming

Características de los Formatos

SRT (SubRip):
- Formato simple basado en texto
- Soporta etiquetas HTML básicas (<b>, <i>, <u>)
- Ampliamente compatible
- Sin posicionamiento ni estilo avanzado

ASS/SSA:
- Estilo avanzado (fuentes, colores, contornos)
- Posicionamiento preciso en cualquier parte de la pantalla
- Soporte de animación y efectos
- Temporización de karaoke

WebVTT:
- Formato estándar de HTML5
- Estilo similar a CSS
- Configuraciones de señal para posicionamiento
- Identificación del hablante

Quemado de Subtítulos (Incrustación)

Incrustación Básica de Subtítulos

# Quemar subtítulos SRT
ffmpeg -i video.mp4 -vf "subtitles=subs.srt" output.mp4

# Quemar subtítulos ASS/SSA (conserva el estilo)
ffmpeg -i video.mp4 -vf "ass=subs.ass" output.mp4

# Quemar subtítulos desde un contenedor MKV
ffmpeg -i video.mkv -vf "subtitles=video.mkv" output.mp4

# Quemar pista de subtítulos específica (índice 0)
ffmpeg -i video.mkv -vf "subtitles=video.mkv:si=0" output.mp4

# Quemar subtítulos con índice de flujo
ffmpeg -i video.mkv -vf "subtitles=video.mkv:stream_index=1" output.mp4

Incrustación con Estilo

# Forzar estilo (anula el estilo del subtítulo)
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:force_style='FontName=Arial,FontSize=24,PrimaryColour=&HFFFFFF,OutlineColour=&H000000,Outline=2,Shadow=1'" \
  output.mp4

# Subtítulos amarillos con contorno negro
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:force_style='FontSize=28,PrimaryColour=&H00FFFF,OutlineColour=&H000000,Outline=3'" \
  output.mp4

# Fuente más grande para accesibilidad
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:force_style='FontSize=36,Bold=1'" \
  output.mp4

Parámetros de Estilo ASS

ParámetroDescripciónEjemplo
FontNameFamilia de fuenteFontName=Arial
FontSizeTamaño en puntosFontSize=24
PrimaryColourColor del texto (AABBGGRR)PrimaryColour=&HFFFFFF
SecondaryColourColor de karaokeSecondaryColour=&H00FFFF
OutlineColourColor de contorno/bordeOutlineColour=&H000000
BackColourColor de sombra/fondoBackColour=&H80000000
BoldTexto en negrita (0/1)Bold=1
ItalicTexto en cursiva (0/1)Italic=1
UnderlineTexto subrayado (0/1)Underline=1
OutlineAncho del contornoOutline=2
ShadowProfundidad de la sombraShadow=1
AlignmentPosición (estilo teclado numérico)Alignment=2
MarginL/R/VMárgenes en píxelesMarginV=50

Formato de Color (ASS)

ASS usa el formato &HAABBGGRR (Alfa, Azul, Verde, Rojo):
- Blanco: &HFFFFFF o &H00FFFFFF
- Negro: &H000000 o &H00000000
- Amarillo: &H00FFFF (00-Azul, FF-Verde, FF-Rojo)
- Rojo: &H0000FF
- Azul: &HFF0000
- Negro 50% transparente: &H80000000

Añadir Pistas de Subtítulos (Subtítulos Blandos)

Incrustar SRT como Pista

# Añadir SRT a MP4 (texto MOV)
ffmpeg -i video.mp4 -i subs.srt \
  -c copy -c:s mov_text \
  output.mp4

# Añadir SRT a MKV
ffmpeg -i video.mp4 -i subs.srt \
  -c copy -c:s srt \
  output.mkv

# Añadir SRT a WebM (WebVTT)
ffmpeg -i video.webm -i subs.srt \
  -c copy -c:s webvtt \
  output.webm

Múltiples Pistas de Subtítulos

# Añadir varios idiomas
ffmpeg -i video.mp4 -i subs_en.srt -i subs_es.srt -i subs_fr.srt \
  -map 0:v -map 0:a -map 1 -map 2 -map 3 \
  -c copy -c:s mov_text \
  -metadata:s:s:0 language=eng -metadata:s:s:0 title="Inglés" \
  -metadata:s:s:1 language=spa -metadata:s:s:1 title="Español" \
  -metadata:s:s:2 language=fra -metadata:s:s:2 title="Francés" \
  output.mp4

# Añadir subtítulos ASS a MKV (conserva el estilo)
ffmpeg -i video.mp4 -i styled.ass \
  -map 0 -map 1 \
  -c copy -c:s ass \
  output.mkv

Establecer Pista de Subtítulos por Defecto

# Establecer subtítulo como predeterminado
ffmpeg -i video.mp4 -i subs.srt \
  -c copy -c:s mov_text \
  -disposition:s:0 default \
  output.mp4

# Establecer subtítulos forzados (siempre visibles)
ffmpeg -i video.mp4 -i forced.srt \
  -c copy -c:s mov_text \
  -disposition:s:0 forced \
  output.mp4

Extraer Subtítulos

Extraer a Archivo Externo

# Extraer la primera pista de subtítulos a SRT
ffmpeg -i video.mkv -map 0:s:0 output.srt

# Extraer flujo de subtítulos específico
ffmpeg -i video.mkv -map 0:s:1 output.srt

# Extraer a formato ASS
ffmpeg -i video.mkv -map 0:s:0 output.ass

# Extraer a WebVTT
ffmpeg -i video.mkv -map 0:s:0 output.vtt

# Extraer todas las pistas de subtítulos
ffmpeg -i video.mkv -map 0:s subs_%d.srt

Listar Pistas de Subtítulos Disponibles

# Mostrar todos los flujos, incluidos los subtítulos
ffprobe -v error -show_entries stream=index,codec_name,codec_type:stream_tags=language,title \
  -of csv=p=0 video.mkv

# Mostrar solo flujos de subtítulos
ffprobe -v error -select_streams s \
  -show_entries stream=index,codec_name:stream_tags=language,title \
  -of csv=p=0 video.mkv

Convertir Formatos de Subtítulos

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

# ASS a SRT (pierde el estilo)
ffmpeg -i subs.ass subs.srt

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

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

Superposiciones drawtext e Integración con Whisper AI

Los ejemplos detallados para superposiciones drawtext (fuentes, posicionamiento, escape, expresiones de tiempo, recuadros, contornos, texto animado) y los flujos de trabajo de transcripción / generación de subtítulos con Whisper AI se encuentran en references/drawtext-and-whisper.md. Carga esa referencia al crear gráficos de texto incrustados o generar subtítulos a partir del habla.

Subtítulos Cerrados CEA-608/708

Extraer Subtítulos Cerrados

# Extraer leyendas CEA-608 de un flujo ATSC
ffmpeg -f lavfi -i "movie=broadcast.ts[out0+subcc]" -map 0:1 captions.srt

# Extraer de video con CC incrustado
ffmpeg -i video_with_cc.mp4 \
  -filter_complex "[0:v]format=yuv420p[v];[0:v]crop=1:1:0:0[c]" \
  -map "[c]" -c:v libx264 -f null - 2>&1 | grep -A 1 "Leyenda cerrada"

Añadir Leyendas CEA-608

# Incrustar leyendas CEA-608 (requiere línea eia608)
ffmpeg -i video.mp4 -i captions.scc \
  -c:v libx264 -c:a copy \
  -vf "movie=captions.scc[captions];[0:v][captions]overlay" \
  output.mp4

Posicionamiento de Subtítulos

Valores de Alineación ASS

7 (superior-izquierda)     8 (superior-centro)     9 (superior-derecha)
4 (medio-izquierda)       5 (medio-centro)        6 (medio-derecha)
1 (inferior-izquierda)    2 (inferior-centro)     3 (inferior-derecha)

Ejemplos de Posición

# Subtítulos centrados en la parte superior
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:force_style='Alignment=8,MarginV=20'" \
  output.mp4

# Subtítulos alineados a la izquierda
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:force_style='Alignment=1,MarginL=50,MarginV=30'" \
  output.mp4

# Lado derecho para identificación del hablante
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:force_style='Alignment=3,MarginR=50'" \
  output.mp4

Múltiples Posiciones de Subtítulos

# Dos pistas de subtítulos en diferentes posiciones
ffmpeg -i video.mp4 \
  -vf "[in]subtitles=speaker1.srt:force_style='Alignment=1,MarginL=50'[tmp];\
       [tmp]subtitles=speaker2.srt:force_style='Alignment=3,MarginR=50'" \
  output.mp4

Procesamiento por Lotes

Quemar Subtítulos en Múltiples Videos

#!/bin/bash
# burn_subs_batch.sh

for video in *.mp4; do
    base="${video%.mp4}"
    if [ -f "${base}.srt" ]; then
        ffmpeg -i "$video" \
          -vf "subtitles=${base}.srt:force_style='FontSize=24,Outline=2'" \
          -c:a copy \
          "output/${base}_subbed.mp4"
    fi
done

Convertir Formato de Subtítulos en Lote

#!/bin/bash
# convert_subs.sh

for srt in *.srt; do
    base="${srt%.srt}"
    ffmpeg -i "$srt" "${base}.vtt"
done

Solución de Problemas

Problemas Comunes

"No se puede encontrar un formato de salida adecuado"

# Especificar el formato de salida explícitamente
ffmpeg -i video.mkv -map 0:s:0 -f srt output.srt

Caracteres distorsionados en los subtítulos

# Forzar codificación UTF-8
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:charenc=UTF-8" \
  output.mp4

Fuente no encontrada

# Especificar directorio de fuentes
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:fontsdir=/ruta/a/fuentes" \
  output.mp4

# Listar fuentes disponibles
fc-list : family | sort | uniq

Desfase de temporización de subtítulos

# Retrasar subtítulos 2 segundos
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:itsoffset=2" \
  output.mp4

# O usar setpts para ajustar
ffmpeg -i subs.srt -itsoffset 2 delayed.srt

Subtítulos no se muestran en video de alta resolución

# Escalar la representación de subtítulos a la resolución del video
ffmpeg -i video_4k.mp4 \
  -vf "subtitles=subs.srt:force_style='FontSize=48,Outline=3'" \
  output.mp4

Comandos de Verificación

# Verificar si hay subtítulos presentes
ffprobe -v error -select_streams s -show_entries stream=codec_name -of default=nw=1 video.mp4

# Contar líneas de subtítulos
grep -c "^[0-9]" subs.srt

# Validar formato SRT
ffmpeg -i subs.srt -f null -

Mejores Prácticas

Accesibilidad

  1. Usa colores de alto contraste (blanco sobre oscuro, amarillo sobre oscuro)
  2. Tamaño mínimo de fuente de 24pt para video estándar
  3. Incluye identificación del hablante para múltiples interlocutores
  4. Posiciona los subtítulos para no ocultar contenido visual importante
  5. Mantén las líneas cortas (máximo 42 caracteres por línea)
  6. Duración de visualización: mínimo 1 segundo, máximo 7 segundos por leyenda

Calidad

  1. Usa formato ASS para subtítulos con estilo (anime, videos musicales)
  2. Usa SRT para diálogos simples
  3. Usa WebVTT para entrega web
  4. Conserva el estilo original cuando sea posible
  5. Prueba en los dispositivos de destino antes de la distribución

Rendimiento

  1. Quema subtítulos solo cuando sea necesario (streaming, compatibilidad)
  2. Prefiere subtítulos blandos para archivo y flexibilidad
  3. Usa codificación por hardware al quemar subtítulos en archivos grandes
  4. Procesa en paralelo para operaciones por lotes

Esta guía cubre las operaciones de subtítulos y leyendas en FFmpeg. Para superposiciones de texto con formas y gráficos, consulta el skill de formas-gráficos.

Skills relacionados