Communitygithub.com

chenwei791129/agent-skills

Transcrire une vidéo YouTube (ou tout fichier audio/vidéo local) en transcription texte, sous-titres SRT et JSON en utilisant Whisper localement. À utiliser chaque fois que l'utilisateur partage une URL YouTube et souhaite ses sous-titres, légendes, transcription, 字幕, ou 逐字稿 — en particulier lorsque la vidéo n'a pas de sous-titres à télécharger — ou veut transcrire / 轉錄 un fichier audio ou vidéo. Déclenché par des demandes comme "幫我抓這部 YouTube 的字幕/逐字稿", "transcribe this video", "把這段音檔轉成文字". S'exécute localement et est multiplateforme : mlx-whisper sur Apple Silicon, faster-whisper ailleurs.

Qu'est-ce que agent-skills ?

Cette compétence permet de transcrire localement des vidéos YouTube ou des fichiers audio/vidéo locaux en texte, sous-titres SRT et JSON, sans dépendre des sous-titres fournis par YouTube. Elle est particulièrement utile lorsque les vidéos (notamment les re-téléchargements et certaines vidéos en chinois) n'ont **aucun** sous-titre ni **aucune** légende automatique, rendant les téléchargements avec `yt-dlp --write-subs` inefficaces. La compétence télécharge la piste audio et la transcrit à l'aide d'un moteur Whisper sélectionné automatiquement selon la plateforme : `mlx-whisper` sur les Mac Apple Silicon (accéléré GPU via MLX/Metal) et `faster-whisper` ailleurs (sur CPU ou NVIDIA CUDA). Elle s'exécute entièrement en local via `uv run`, ce qui garantit la confidentialité des données et ne nécessite aucun service cloud. Les utilisateurs n'ont qu'à fournir une URL YouTube ou un chemin de fichier local, et la compétence gère le téléchargement, la normalisation audio (conversion en WAV 16 kHz mono) et la transcription. Les sorties incluent une transcription texte, des sous-titres horodatés (SRT) et un fichier JSON complet avec les horodatages et la langue détectée. Cette compétence fonctionne sur macOS, Linux et Windows et nécessite `uv`, un runtime JavaScript (node, bun ou deno) et ffmpeg (recommandé mais pas obligatoire sur macOS).

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Transcription YouTube / Audio

Transformez une vidéo YouTube — ou tout fichier audio/vidéo local — en transcription sans vous fier aux sous-titres fournis par YouTube. De nombreuses vidéos (en particulier les re-téléchargements et certaines vidéos en chinois) n'ont aucun sous-titre ni aucune légende automatique, donc télécharger les sous-titres avec yt-dlp --write-subs ne renvoie rien. Cette compétence contourne ce problème en téléchargeant l'audio et en le transcrivant localement avec un moteur Whisper choisi selon la plateforme.

Quand utiliser cette compétence

  • L'utilisateur fournit une URL YouTube et souhaite obtenir les 字幕 / 逐字稿 / transcript / captions.
  • yt-dlp --list-subs signale has no subtitles / has no automatic captions.
  • L'utilisateur a un fichier local .m4a/.mp3/.mp4/etc. à transcrire.

Prérequis

  • uv installé (utilisé pour exécuter yt-dlp et le script de transcription sans polluer l'environnement global). Le script sélectionne automatiquement le moteur Whisper et uv n'installe que celui dont votre plateforme a besoin :
    • Mac Apple Silicon → mlx-whisper (MLX/Metal, accéléré GPU).
    • Mac Intel / Linux / Windows → faster-whisper (CTranslate2, CPU ou NVIDIA CUDA).
  • Un runtime JavaScript — node, bun, ou deno — dans le PATH. Un runtime récent est nécessaire à yt-dlp pour extraire YouTube ; le script détecte automatiquement celui qui est présent.
  • ffmpeg recommandé mais pas obligatoire : s'il est absent, le script utilise afconvert intégré à macOS (donc sur les systèmes non-macOS, installez ffmpeg).

Utilisation

L'ensemble du pipeline est contenu dans un seul script. Exécutez-le avec uv run pour que les dépendances soient installées automatiquement :

uv run ~/.claude/skills/youtube-transcribe/scripts/yt_transcribe.py \
  "https://www.youtube.com/watch?v=VIDEO_ID" \
  --output-dir /tmp/whisper_out

Options courantes :

  • --language zh — forcer une langue au lieu de la détection automatique (plus rapide, évite les erreurs de détection sur les introductions bilingues).
  • --model mlx-community/whisper-large-v3-turbo — le modèle par défaut ; bon rapport vitesse/qualité sur Apple Silicon. Remplacez par mlx-community/whisper-large-v3 pour une qualité maximale ou un modèle plus petit pour la vitesse.
  • --output-name my-video — nom de base des fichiers de sortie (par défaut, l'identifiant de la vidéo).
  • --formats txt,srt — choisir les formats de sortie à écrire (par défaut txt,srt,json).

Un fichier local fonctionne de la même manière — passez simplement un chemin au lieu d'une URL :

uv run ~/.claude/skills/youtube-transcribe/scripts/yt_transcribe.py /path/to/talk.m4a --language en

La première exécution télécharge le modèle Whisper (~1,6 Go pour turbo) dans le cache Hugging Face ; les exécutions suivantes le réutilisent.

Sorties

Écrites dans le répertoire --output-dir (par défaut : le répertoire courant), nommées d'après l'identifiant de la vidéo (ou l'option --output-name) :

  • <name>.txt — transcription en texte brut (un seul bloc).
  • <name>.srt — sous-titres avec horodatages.
  • <name>.json — résultat complet incluant les horodatages par segment et la langue détectée.

Après la transcription

La sortie brute de Whisper reflète la langue parlée textuellement. Si l'audio est en mandarin, Whisper produit du chinois simplifié. Conformément à la règle globale de l'utilisateur, lors de la présentation de la transcription dans le chat, convertissez-la en chinois traditionnel (正體中文) et corrigez les erreurs évidentes sur les noms propres / termes techniques (noms de modèles, identifiants CVE, noms d'outils). Proposez un résumé structuré et ordonné plutôt que de déverser tout le mur de texte, et indiquez à l'utilisateur où se trouvent les fichiers complets.

Comment ça marche (et pourquoi)

  1. Téléchargement audio — yt-dlp -f "bestaudio[ext=m4a]/bestaudio". Le format 140 (128 kbps m4a) se télécharge sans résoudre le défi JavaScript "n" du player YouTube, donc on évite --remote-components ejs:github (il récupère et exécute du code distant et est généralement bloqué par le bac à sable). Le script préfixe uvx si yt-dlp n'est pas installé, et ajoute --js-runtimes <node|bun|deno> pour le runtime existant.
  2. Normalisation audio — conversion en WAV 16 kHz mono 16 bits avec ffmpeg, ou afconvert sur macOS si ffmpeg est manquant.
  3. Transcription — lecture du fichier WAV dans un tableau numpy float32 puis transmission directe au moteur (mlx_whisper.transcribe(...) sur Apple Silicon, faster_whisper.WhisperModel.transcribe(...) ailleurs). Les deux produisent le même format de résultat normalisé (text / language / segments). En donnant à whisper un tableau décodé, il n'appelle jamais ffmpeg en interne — ce qui est la cause habituelle de l'erreur FileNotFoundError: ffmpeg sur les machines qui n'en disposent pas.

Dépannage

  • has no subtitles mais vous voulez quand même du texte — c'est exactement le rôle de cette compétence ; procédez à la transcription audio.
  • FileNotFoundError: ffmpeg — ne devrait pas se produire via ce script (il convertit d'abord), mais si vous appelez le moteur Whisper directement sur un fichier m4a, convertissez-le d'abord en WAV.
  • Sur les machines non-Apple-Silicon et en cas d'échec de conversion — afconvert est exclusif à macOS, installez donc ffmpeg (Linux/Windows n'ont pas de solution de repli intégrée).
  • yt-dlp avertit d'un défi JavaScript / "Only images are available" — assurez-vous que node/bun/deno est dans le PATH ; le script en a besoin pour l'extraction. N'utilisez pas --remote-components ejs:github pour le résoudre.
  • Sortie brouillée / dans la mauvaise langue — utilisez explicitement l'option --language.

Skills associés