Communitygithub.com

gengwg/skills

Transcribe un video que no tenga subtítulos (X/Twitter, YouTube, cualquier URL de yt-dlp o archivo local) con Whisper local, escribir un SRT y quemar los subtítulos en un nuevo MP4. Úsalo cuando te pidan 'obtener la transcripción', 'extraer lo que dicen', 'agregar subtítulos', 'subtitular este video' o 'este video no tiene subtítulos'.

¿Qué es skills?

Esta habilidad permite transcribir y subtitular videos sin depender de servicios en la nube, usando herramientas locales como yt-dlp para descargar, faster-whisper para la transcripción y ffmpeg para quemar los subtítulos. Es útil cuando un usuario solicita la transcripción de un video de plataformas como X/Twitter o YouTube, o incluso archivos locales, especialmente si el video no tiene subtítulos incorporados. Soporta cualquier URL compatible con yt-dlp y archivos locales, y puede generar tanto un archivo SRT como un nuevo video MP4 con subtítulos visibles (hard-coded) o conmutables (soft). El proceso incluye la selección automática del modelo de Whisper (recomendando large-v3 para precisión), la fijación de líneas mal transcritas mediante recorte de audio y vocabulario guiado, y la quema final de subtítulos con ffmpeg. La habilidad maneja errores comunes como usar modelos pequeños, descargar modelos grandes sin preguntar, o transcribir el video completo para corregir pocas líneas.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/gengwg/skills/tree/HEAD/video-transcribe-and-caption

Preguntar en tu IA favorita

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

Documentación

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:

  • small es rápido pero distorsiona audio con múltiples voces, bromas y jerga. Adecuado para un primer vistazo, no para subtítulos.
  • large-v3 es 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; medium tiene la mitad del tamaño.
  • Ejecuta transcripciones largas en segundo plano e informa el progreso honestamente: verifica si el blob .incomplete en 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 small como 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".

Skills relacionados