Habilidad: transcripción-y-subtitulado-de-video
Propósito
Convertir el habla de un video en texto sin ningún servicio en la nube: descargar con yt-dlp, transcribir localmente con faster-whisper, generar un archivo SRT y, opcionalmente, quemar los subtítulos con ffmpeg para que se muestren en cualquier reproductor.
Pasos
1. Verificar herramientas
which yt-dlp ffmpeg uv; nvidia-smi --query-gpu=name --format=csv,noheader 2>/dev/null
uvx yt-dlp y uv run --with faster-whisper evitan instalar nada.
Solo el filtro subtitles de ffmpeg necesita una compilación real de ffmpeg con libass
(ffmpeg -filters | grep subtitles); el binario incluido de
imageio-ffmpeg puede carecer de él.
2. Descargar
uvx yt-dlp -f "bv*[ext=mp4]+ba[ext=m4a]/b[ext=mp4]/b" --merge-output-format mp4 -o "video.%(ext)s" --no-playlist "<url>"
uvx yt-dlp --skip-download -j "<url>" | jq '{title, uploader, upload_date, description}'
3. Transcribir a SRT
# srt.py — ejecutar con: uv run --with faster-whisper python srt.py
from faster_whisper import WhisperModel
def ts(t):
h, r = divmod(t, 3600); m, s = divmod(r, 60)
return f"{int(h):02d}:{int(m):02d}:{int(s):02d},{int(s % 1 * 1000):03d}"
model = WhisperModel("large-v3", device="cpu", compute_type="int8") # device="cuda" si existe GPU
segments, info = model.transcribe("video.mp4", vad_filter=True, beam_size=5)
with open("video.srt", "w") as f:
for i, s in enumerate(segments, 1):
f.write(f"{i}\n{ts(s.start)} --> {ts(s.end)}\n{s.text.strip()}\n\n")
Elección del modelo:
smalles rápido pero distorsiona audio con múltiples voces, bromas y jerga. Adecuado para un primer vistazo, no para subtítulos.large-v3es el indicado para distribuir. Su descarga inicial es de ~3 GB en~/.cache/huggingface/hub/; en una conexión lenta eso solo puede llevar 30+ minutos. Dilo y pregunta antes de iniciarlo;mediumtiene la mitad del tamaño.- Ejecuta transcripciones largas en segundo plano e informa el progreso honestamente:
verifica si el blob
.incompleteen la caché de HF sigue creciendo (descargando) o el proceso tiene alta CPU (transcribiendo).
4. Corregir líneas malinterpretadas
Whisper aún malinterpreta nombres y palabras del dominio. Vuelve a transcribir solo el segmento defectuoso con sugerencias de vocabulario en lugar de reprocesar todo el archivo:
ffmpeg -loglevel error -y -ss 53 -to 64 -i video.mp4 -vn -ac 1 -ar 16000 clip.wav
segments, _ = model.transcribe("clip.wav", beam_size=5,
initial_prompt="Lista corta de palabras esperadas: nombres de productos, jerga, nombres de emoji.")
Luego edita manualmente esas entradas del SRT (mantén las marcas de tiempo). Extraer un fotograma
(ffmpeg -ss 58 -i video.mp4 -frames:v 1 f.jpg) ayuda cuando el texto en pantalla
desambigua el audio. Indica al usuario qué líneas aún tienen baja confianza
en lugar de presentar una suposición como un hecho.
5. Quemar subtítulos
ffmpeg -hide_banner -loglevel error -y -i video.mp4 \
-vf "subtitles=video.srt:force_style='FontSize=20,Outline=1,MarginV=30'" \
-c:v libx264 -preset fast -crf 20 -c:a copy video_cc.mp4
Conserva el SRT junto al resultado para que una sola línea se pueda corregir y renderizar de nuevo
en menos de un minuto. Para subtítulos suaves (conmutables), multiplexa con
ffmpeg -i video.mp4 -i video.srt -c copy -c:s mov_text video_cc.mp4.
Entregables
Video original, video subtitulado, archivo .srt y la transcripción en texto plano. Menciona
el tamaño del modelo en caché para que el usuario pueda eliminarlo.
Errores comunes
- Entregar resultados del modelo
smallcomo subtítulos. - Iniciar la descarga de un modelo de varios GB sin preguntar.
- Reprocesar la transcripción completa para corregir tres líneas.
- Usar un ffmpeg sin libass y obtener "No such filter: subtitles".