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-subssignalehas no subtitles/has no automatic captions.- L'utilisateur a un fichier local
.m4a/.mp3/.mp4/etc. à transcrire.
Prérequis
uvinstallé (utilisé pour exécuteryt-dlpet le script de transcription sans polluer l'environnement global). Le script sélectionne automatiquement le moteur Whisper etuvn'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).
- Mac Apple Silicon →
- Un runtime JavaScript —
node,bun, oudeno— 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
afconvertinté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 parmlx-community/whisper-large-v3pour 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éfauttxt,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)
- 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éfixeuvxsiyt-dlpn'est pas installé, et ajoute--js-runtimes <node|bun|deno>pour le runtime existant. - Normalisation audio — conversion en WAV 16 kHz mono 16 bits avec ffmpeg, ou
afconvertsur macOS si ffmpeg est manquant. - 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'erreurFileNotFoundError: ffmpegsur les machines qui n'en disposent pas.
Dépannage
has no subtitlesmais 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 —
afconvertest exclusif à macOS, installez doncffmpeg(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/denoest dans le PATH ; le script en a besoin pour l'extraction. N'utilisez pas--remote-components ejs:githubpour le résoudre. - Sortie brouillée / dans la mauvaise langue — utilisez explicitement l'option
--language.