Transcripción de YouTube / Audio
Convierte un video de YouTube — o cualquier archivo de audio/video local — en una transcripción sin depender de los subtítulos proporcionados por YouTube. Muchos videos (especialmente re-subidas y algunas subidas en chino) no tienen subtítulos ni auto-captions, por lo que descargarlos con yt-dlp --write-subs no devuelve nada. Esta habilidad evita ese problema descargando el audio y transcribiéndolo localmente con un motor whisper elegido según la plataforma.
Cuándo usar esto
- El usuario proporciona una URL de YouTube y quiere los 字幕 / 逐字稿 / transcript / subtítulos.
yt-dlp --list-subsinformano tiene subtítulos/no tiene auto-captions.- El usuario tiene un archivo local
.m4a/.mp3/.mp4/etc. para transcribir.
Requisitos previos
uvinstalado (se usa para ejecutaryt-dlpy el script de transcripción sin contaminar el entorno global). El script selecciona automáticamente el motor whisper yuvinstala solo el que tu plataforma necesita:- Mac Apple Silicon →
mlx-whisper(MLX/Metal, acelerado por GPU). - Intel Mac / Linux / Windows →
faster-whisper(CTranslate2, CPU o NVIDIA CUDA).
- Mac Apple Silicon →
- Un runtime de JavaScript —
node,bunodeno— en el PATH. Un yt-dlp reciente necesita uno para extraer YouTube; el script detecta automáticamente el que esté presente. - Se recomienda ffmpeg pero no es obligatorio: si no está, el script recurre al
afconvertintegrado de macOS (en sistemas que no sean macOS, instala ffmpeg).
Uso
Todo el pipeline es un solo script autocontenido. Ejecútalo con uv run para que las dependencias se aprovisionen automáticamente:
uv run ~/.claude/skills/youtube-transcribe/scripts/yt_transcribe.py \
"https://www.youtube.com/watch?v=VIDEO_ID" \
--output-dir /tmp/whisper_out
Opciones comunes:
--language zh— fuerza un idioma en lugar de detectarlo automáticamente (más rápido, evita detección incorrecta en intros bilingües).--model mlx-community/whisper-large-v3-turbo— el predeterminado; buena velocidad/calidad en Apple Silicon. Cambia pormlx-community/whisper-large-v3para máxima calidad o un modelo más pequeño para velocidad.--output-name my-video— nombre base para los archivos de salida (por defecto es el ID del video).--formats txt,srt— elige qué formatos de salida generar (por defectotxt,srt,json).
Un archivo local funciona de la misma manera — solo pasa una ruta en lugar de una URL:
uv run ~/.claude/skills/youtube-transcribe/scripts/yt_transcribe.py /path/to/talk.m4a --language en
La primera ejecución descarga el modelo whisper (~1.6 GB para turbo) en la caché de Hugging Face; las ejecuciones posteriores lo reutilizan.
Archivos de salida
Se escriben en --output-dir (por defecto: el directorio actual), nombrados según el ID del video (o --output-name):
<name>.txt— transcripción en texto plano (un solo bloque).<name>.srt— subtítulos con marcas de tiempo.<name>.json— resultado completo, incluyendo marcas de tiempo por segmento e idioma detectado.
Después de la transcripción
La salida sin procesar de whisper refleja el idioma hablado textualmente. Si el audio es mandarín, whisper genera Chino simplificado. Siguiendo la regla global del usuario, al presentar la transcripción en el chat, conviértela a 正體中文 (Tradicional) y corrige las malas interpretaciones evidentes de nombres propios/términos técnicos (nombres de modelos, IDs CVE, nombres de herramientas). Ofrece un resumen ordenado y seccionado en lugar de volcar todo el muro de texto, e indica al usuario dónde están los archivos completos.
Cómo funciona (y por qué)
- Descargar audio —
yt-dlp -f "bestaudio[ext=m4a]/bestaudio". El formato 140 (m4a de 128 kbps) se descarga sin resolver el desafío JS "n" del reproductor de YouTube, por lo que evitamos--remote-components ejs:github(ya que obtiene y ejecuta código remoto y normalmente está bloqueado por el sandbox). El script añade el prefijouvxsiyt-dlpno está instalado, y agrega--js-runtimes <node|bun|deno>para el runtime que exista. - Normalizar audio — convierte a WAV mono de 16 kHz y 16 bits con ffmpeg, o con
afconvertde macOS si ffmpeg no está. - Transcribir — lee el WAV en un array numpy float32 y lo pasa directamente al motor (
mlx_whisper.transcribe(...)en Apple Silicon,faster_whisper.WhisperModel.transcribe(...)en otros casos). Ambos producen el mismo resultado normalizado (text/language/segments). Pasarle a whisper un array decodificado significa que nunca invoca ffmpeg internamente — que es la causa habitual deFileNotFoundError: ffmpegen máquinas sin él.
Solución de problemas
no tiene subtítulospero aún quieres texto — ese es exactamente el trabajo de esta habilidad; procede a transcribir el audio.FileNotFoundError: ffmpeg— no debería ocurrir con este script (primero convierte), pero si llamas al motor whisper directamente sobre un m4a, conviértelo a WAV primero.- En sistemas que no sean Apple Silicon y falla la conversión —
afconvertes solo para macOS, así que instalaffmpeg(Linux/Windows no tienen alternativa integrada). - yt-dlp advierte sobre el desafío JS / "Only images are available" — asegúrate de que
node/bun/denoesté en el PATH; el script necesita uno para la extracción. No recurras a--remote-components ejs:githubpara solucionarlo. - Salida distorsionada o en idioma incorrecto — pasa
--languageexplícitamente.