Communitygithub.com

chenwei791129/agent-skills

Transcribe un video de YouTube (o cualquier archivo de audio/video local) en una transcripción de texto, subtítulos SRT y JSON usando whisper localmente. Úsalo cada vez que el usuario comparta una URL de YouTube y quiera sus subtítulos, transcripción, o 字幕/逐字稿 — especialmente cuando el video no tenga subtítulos para descargar — o quiera transcribir / convertir a texto un archivo de audio o video. Se activa con solicitudes como '幫我抓這部 YouTube 的字幕/逐字稿', 'transcribe este video', '把這段音檔轉成文字'. Se ejecuta localmente y es multiplataforma: mlx-whisper en Apple Silicon, faster-whisper en otros.

¿Qué es agent-skills?

Esta habilidad convierte cualquier video de YouTube (o archivo de audio/video local) en una transcripción de texto, subtítulos SRT y JSON sin depender de los subtítulos proporcionados por YouTube. Muchos videos, especialmente re-subidas y algunos en chino, carecen de subtítulos o auto-captions, por lo que descargarlos con `yt-dlp --write-subs` no funciona. La habilidad soluciona esto descargando el audio y transcribiéndolo localmente con un motor whisper elegido según la plataforma: `mlx-whisper` en Apple Silicon (acelerado por GPU Metal) y `faster-whisper` en Intel Mac, Linux o Windows (CPU o NVIDIA CUDA). Es útil para desarrolladores y usuarios que necesitan transcripciones precisas de contenido multimedia, y se activa con solicitudes como '幫我抓這部 YouTube 的字幕/逐字稿' o 'transcribe este video'. El script es autocontenido, se ejecuta con `uv run`, y gestiona automáticamente las dependencias, incluida la descarga del modelo whisper (~1.6 GB) en el primer uso. Los archivos de salida incluyen texto plano, SRT con marcas de tiempo y JSON con segmentos detallados, y el script convierte automáticamente el texto a chino tradicional si es necesario.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/chenwei791129/agent-skills/tree/HEAD/skills/youtube-transcribe

Preguntar en tu IA favorita

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

Documentación

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-subs informa no tiene subtítulos / no tiene auto-captions.
  • El usuario tiene un archivo local .m4a/.mp3/.mp4/etc. para transcribir.

Requisitos previos

  • uv instalado (se usa para ejecutar yt-dlp y el script de transcripción sin contaminar el entorno global). El script selecciona automáticamente el motor whisper y uv instala 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).
  • Un runtime de JavaScript — node, bun o deno — 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 afconvert integrado 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 por mlx-community/whisper-large-v3 para 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 defecto txt,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é)

  1. 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 prefijo uvx si yt-dlp no está instalado, y agrega --js-runtimes <node|bun|deno> para el runtime que exista.
  2. Normalizar audio — convierte a WAV mono de 16 kHz y 16 bits con ffmpeg, o con afconvert de macOS si ffmpeg no está.
  3. 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 de FileNotFoundError: ffmpeg en máquinas sin él.

Solución de problemas

  • no tiene subtítulos pero 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 — afconvert es solo para macOS, así que instala ffmpeg (Linux/Windows no tienen alternativa integrada).
  • yt-dlp advierte sobre el desafío JS / "Only images are available" — asegúrate de que node/bun/deno esté en el PATH; el script necesita uno para la extracción. No recurras a --remote-components ejs:github para solucionarlo.
  • Salida distorsionada o en idioma incorrecto — pasa --language explícitamente.

Skills relacionados