Subtítulos automáticos con faster-whisper en CPU: SRT por lotes, chino simplificado y ffmpeg

Los subtítulos permiten ver videos cortos sin sonido, ayudan a las plataformas a entender su contenido y convierten llamadas, reuniones y transmisiones en directo grabadas en texto en el que se puede buscar. Whisper es un modelo de reconocimiento de voz de código abierto que maneja bien el chino, el inglés y decenas de otros idiomas, y faster-whisper lo ejecuta de forma eficiente en un servidor normal con CPU. Esta guía instala faster-whisper, elige el tamaño del modelo, convierte audio y video en archivos de subtítulos SRT por lotes, obtiene una salida limpia en chino simplificado e incrusta los subtítulos en los videos con ffmpeg.

Paso 1: Instalar faster-whisper

# Debian / Ubuntu
apt install -y python3-venv ffmpeg
python3 -m venv /opt/whisper
/opt/whisper/bin/pip install --upgrade pip
/opt/whisper/bin/pip install faster-whisper "av<19"    # PyAV 19 is not yet compatible with faster-whisper 1.2

Un entorno virtual independiente mantiene las bibliotecas separadas del Python del sistema. ffmpeg se usa para extraer el audio e incrustar los subtítulos.

Paso 2: Elegir el tamaño del modelo

Empiece con small, transcriba una muestra de 5 minutos y mida el tiempo; después decida si la precisión de medium o large-v3 compensa el tiempo adicional para su contenido.

Paso 3: Crear el script de transcripción

cat > /opt/whisper/transcribe.py <<'EOF2'
import os, sys
from faster_whisper import WhisperModel

def ts(t):
    ms = int(round(t * 1000))
    h, ms = divmod(ms, 3600000)
    m, ms = divmod(ms, 60000)
    s, ms = divmod(ms, 1000)
    return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"

size = os.environ.get("WHISPER_MODEL", "small")
lang = os.environ.get("WHISPER_LANG") or None          # e.g. zh, en; empty = auto-detect
prompt = os.environ.get("WHISPER_PROMPT") or None
model = WhisperModel(size, device="cpu", compute_type="int8", cpu_threads=os.cpu_count())

for path in sys.argv[1:]:
    segments, info = model.transcribe(path, language=lang, initial_prompt=prompt,
                                      beam_size=5, vad_filter=True)
    out = os.path.splitext(path)[0] + ".srt"
    with open(out, "w", encoding="utf-8") as f:
        for i, seg in enumerate(segments, 1):
            f.write(f"{i}\n{ts(seg.start)} --> {ts(seg.end)}\n{seg.text.strip()}\n\n")
    print(f"{path}: language={info.language} -> {out}")
EOF2

vad_filter omite los silencios y la música sin voz, lo que acelera el proceso y evita texto inventado en las partes silenciosas.

Paso 4: Transcribir archivos y carpetas

# One file, automatic language detection
/opt/whisper/bin/python /opt/whisper/transcribe.py /data/videos/demo.mp4

# A whole folder with the medium model, in the background, with a log
cd /data/videos
WHISPER_MODEL=medium nohup /opt/whisper/bin/python /opt/whisper/transcribe.py *.mp4 > transcribe.log 2>&1 &
tail -f transcribe.log

Cada archivo de entrada genera a su lado un archivo .srt con el mismo nombre. faster-whisper lee directamente la mayoría de los formatos de audio y video; para archivos muy grandes puede extraer antes el audio con ffmpeg -i in.mp4 -vn -ac 1 -ar 16000 in.wav.

Paso 5: Obtener chino simplificado limpio

En mandarín, Whisper a veces escribe caracteres tradicionales u omite la puntuación. Fije el idioma y proporcione como prompt inicial una frase breve de ejemplo en chino simplificado; el modelo imitará su estilo:

WHISPER_LANG=zh WHISPER_PROMPT="以下是普通话的句子，请使用简体中文和标点符号。" \
  /opt/whisper/bin/python /opt/whisper/transcribe.py livestream-0612.mp4

El mismo truco sirve para nombres de productos y jerga técnica: ponga las grafías correctas en el prompt para que el modelo las use.

Paso 6: Incrustar subtítulos en un video

# Hard subtitles (always visible), keeping the original audio
ffmpeg -i demo.mp4 -vf "subtitles=demo.srt:force_style='FontSize=20,Outline=1'" -c:a copy demo-sub.mp4

# Or add them as a selectable subtitle track (MP4)
ffmpeg -i demo.mp4 -i demo.srt -c copy -c:s mov_text demo-softsub.mp4

Para subtítulos en chino, asegúrese de que haya una fuente china instalada en el servidor (por ejemplo, apt install fonts-noto-cjk); de lo contrario, los caracteres aparecerán como cuadros. La mayoría de las plataformas, incluida YouTube, también aceptan que suba el archivo .srt junto al video.

Preguntas frecuentes

¿Cuánto tarda?

Depende del modelo y de la CPU. En un servidor multinúcleo moderno, el modelo small suele procesar el audio más rápido que en tiempo real; medium y large-v3 son varias veces más lentos. Mida con una muestra corta antes de procesar grandes volúmenes de grabaciones.

¿El texto se repite o contiene frases que nunca se dijeron?

Suele ocurrir en partes largas de silencio o solo con música. Mantenga activado vad_filter, pruebe un modelo más grande y compruebe que el audio no esté demasiado bajo o distorsionado.

¿Puedo traducir los subtítulos?

Whisper puede traducir la voz directamente al inglés (task="translate" en model.transcribe). Para otros idiomas de destino, traduzca el texto del SRT con un modelo de lenguaje, por ejemplo el modelo local de cómo ejecutar un LLM local con Ollama.

¿Sigue sin resolverlo después de seguir estos pasos? Abra un ticket de soporte y el equipo técnico de IMIDC, disponible 24/7, le ayudará. Incluya la IP del servidor, la versión del sistema operativo, la CPU y la RAM, el comando que ejecutó y la salida completa del error para que podamos localizar el problema más rápido.