Compétence d'agent de transcription YouTube

Transcription YouTube

Télécharge les transcriptions (sous-titres/légendes) à partir de vidéos YouTube. Fonctionne avec les transcriptions créées manuellement et celles générées automatiquement. Aucune clé API ni navigateur requis — utilise directement l'API InnerTube de YouTube et bascule automatiquement sur yt-dlp lorsque YouTube bloque le chemin API direct.

Récupère les métadonnées de la vidéo et l'image de couverture lors de la première exécution, met en cache les données brutes pour une reformatation rapide.

Répertoire des scripts

Scripts dans le sous-répertoire scripts/. {baseDir} = chemin du répertoire de ce SKILL.md. Résoudre l'exécution ${BUN_X} : si bun est installé → bun ; si npx est disponible → npx -y bun ; sinon suggérer d'installer bun. Remplacer {baseDir} et ${BUN_X} par les valeurs réelles.

Utilisation

# Par défaut : markdown avec horodatages (anglais)
${BUN_X} {baseDir}/scripts/main.ts <youtube-url-or-id>

# Spécifier les langues (ordre de priorité)
${BUN_X} {baseDir}/scripts/main.ts <url> --languages zh,en,ja

# Sans horodatages
${BUN_X} {baseDir}/scripts/main.ts <url> --no-timestamps

# Avec segmentation par chapitres
${BUN_X} {baseDir}/scripts/main.ts <url> --chapters

# Avec identification des locuteurs (nécessite un post-traitement IA)
${BUN_X} {baseDir}/scripts/main.ts <url> --speakers

# Fichier de sous-titres SRT
${BUN_X} {baseDir}/scripts/main.ts <url> --format srt

# Traduire la transcription
${BUN_X} {baseDir}/scripts/main.ts <url> --translate zh-Hans

# Lister les transcriptions disponibles
${BUN_X} {baseDir}/scripts/main.ts <url> --list

# Forcer une nouvelle récupération (ignorer le cache)
${BUN_X} {baseDir}/scripts/main.ts <url> --refresh

Options

Variables d'environnement optionnelles

Formats d'entrée

Accepte l'un des formats suivants en entrée vidéo :

• URL complète : https://www.youtube.com/watch?v=dQw4w9WgXcQ
• URL courte : https://youtu.be/dQw4w9WgXcQ
• URL d'intégration : https://www.youtube.com/embed/dQw4w9WgXcQ
• URL Shorts : https://www.youtube.com/shorts/dQw4w9WgXcQ
• ID de la vidéo : dQw4w9WgXcQ

Formats de sortie

Répertoire de sortie

youtube-transcript/
├── .index.json                            # Correspondance ID vidéo → chemin du répertoire (pour la recherche en cache)
└── {channel-slug}/{title-full-slug}/
    ├── meta.json                        # Métadonnées de la vidéo (titre, chaîne, description, durée, chapitres, etc.)
    ├── transcript-raw.json              # Fragments de transcription bruts de l'API YouTube (en cache)
    ├── transcript-sentences.json        # Transcription segmentée par phrases (découpée par ponctuation, fusionnée entre les fragments)
    ├── imgs/
    │   └── cover.jpg                    # Vignette de la vidéo
    ├── transcript.md                    # Transcription Markdown (générée à partir des phrases)
    └── transcript.srt                   # Sous-titres SRT (générés à partir des fragments bruts, si --format srt)

• {channel-slug} : Nom de la chaîne en kebab-case
• {title-full-slug} : Titre complet de la vidéo en kebab-case

Le mode --list génère une sortie uniquement sur stdout (aucun fichier enregistré).

Mise en cache

Lors de la première récupération, le script enregistre :

• meta.json — métadonnées de la vidéo, chapitres, chemin de l'image de couverture, informations de langue
• transcript-raw.json — fragments de transcription bruts de l'API YouTube ({ text, start, duration }[])
• transcript-sentences.json — transcription segmentée en phrases ({ text, start: "HH:mm:ss", end: "HH:mm:ss" }[]), découpée par la ponctuation de fin de phrase (.?!…。？！ etc.), horodatages alloués proportionnellement à la longueur des caractères, fusion de texte sensible aux caractères CJK
• imgs/cover.jpg — vignette de la vidéo

Les exécutions suivantes pour la même vidéo utilisent les données en cache (aucun appel réseau). Utilisez --refresh pour forcer une nouvelle récupération. Si une langue différente est demandée, le cache est automatiquement actualisé.

Lorsque YouTube renvoie des réponses anti-bot / bloquées sur le chemin InnerTube direct, le script réessaie avec des identités de client alternatives, puis bascule sur yt-dlp si disponible. Si le repli est nécessaire mais que yt-dlp n'est pas disponible, l'agent doit décider comment rendre yt-dlp disponible et continuer plutôt que de repousser la décision d'installation à l'utilisateur.

La sortie SRT (--format srt) est générée à partir de transcript-raw.json. La sortie texte/markdown utilise transcript-sentences.json pour des limites de phrases naturelles.

Flux de travail

Lorsque l'utilisateur fournit une URL YouTube et souhaite la transcription :

1. Exécutez d'abord avec --list si l'utilisateur n'a pas spécifié de langue, pour afficher les options disponibles
2. Toujours mettre l'URL entre guillemets simples lors de l'exécution du script — zsh traite ? comme un caractère générique, donc une URL YouTube non entre guillemets provoque une erreur "aucune correspondance trouvée" : utilisez 'https://www.youtube.com/watch?v=ID'
3. Par défaut : exécutez avec --chapters --speakers pour la sortie la plus riche (chapitres + identification des locuteurs)
4. Le script enregistre automatiquement les données en cache + le fichier de sortie et affiche le chemin du fichier
5. Pour le mode --speakers : après que le script a enregistré le fichier brut, suivez le flux de travail d'identification des locuteurs ci-dessous pour post-traiter avec des étiquettes de locuteurs

Lorsque l'utilisateur ne souhaite qu'une image de couverture ou des métadonnées, l'exécution du script avec n'importe quelle option mettra également en cache meta.json et imgs/cover.jpg.

Lors du reformatage de la même vidéo (par exemple, d'abord en texte puis en SRT), les données en cache sont réutilisées — aucune nouvelle récupération nécessaire.

Flux de travail des chapitres et des locuteurs

Chapitres (--chapters)

Le script analyse les horodatages des chapitres à partir de la description de la vidéo (par ex., 0:00 Introduction), segmente la transcription selon les limites des chapitres, regroupe les fragments en paragraphes lisibles et enregistre en .md avec une table des matières. Aucun traitement supplémentaire nécessaire.

S'il n'y a pas d'horodatages de chapitres dans la description, la transcription est sortie sous forme de paragraphes groupés sans titres de chapitres.

Identification des locuteurs (--speakers)

L'identification des locuteurs nécessite un traitement par IA. Le script génère un fichier .md brut contenant :

• Frontmatter YAML avec les métadonnées de la vidéo (titre, chaîne, date, couverture, description, langue)
• Description de la vidéo (pour l'extraction des noms des locuteurs)
• Liste des chapitres de la description (si disponible)
• Transcription brute au format SRT (horodatages de début/fin pré-calculés, efficace en tokens)

Après que le script a enregistré le fichier brut, lancez un sous-agent (utilisez un modèle moins cher comme Sonnet pour l'efficacité des coûts) pour traiter l'identification des locuteurs :

1. Lire le fichier .md enregistré
2. Lire le modèle de consigne dans {baseDir}/prompts/speaker-transcript.md
3. Traiter la transcription brute en suivant la consigne :
   • Identifier les locuteurs en utilisant les métadonnées de la vidéo (titre → invité, chaîne → hôte, description → noms)
   • Détecter les tours de parole à partir du flux de conversation, des schémas question-réponse et des indices contextuels
   • Segmenter en chapitres (utiliser les chapitres de la description si disponibles, sinon créer à partir des changements de sujet)
   • Formater avec les étiquettes **Nom du locuteur :**, le regroupement en paragraphes (2-4 phrases) et les horodatages [HH:MM:SS → HH:MM:SS]
4. Écraser le fichier .md avec la transcription traitée (conserver le frontmatter YAML)

Lorsque --speakers est utilisé, --chapters est implicite — la sortie traitée inclut toujours la segmentation en chapitres.

Cas d'erreur