YouTube Transcript Agent-vaardigheid

YouTube Transcriptie

Downloadt transcripties (ondertitels/bijschriften) van YouTube-video's. Werkt met zowel handmatig gemaakte als automatisch gegenereerde transcripties. Geen API-sleutel of browser nodig — gebruikt direct de InnerTube API van YouTube en schakelt automatisch over naar yt-dlp wanneer YouTube het directe API-pad blokkeert.

Haalt video-metadata en omslagafbeelding op bij de eerste uitvoering, slaat ruwe gegevens op in cache voor snelle herformattering.

Scriptmap

Scripts in de scripts/ submap. {baseDir} = het mappad van deze SKILL.md. Bepaal ${BUN_X} runtime: als bun is geïnstalleerd → bun; als npx beschikbaar is → npx -y bun; anders stel voor om bun te installeren. Vervang {baseDir} en ${BUN_X} door werkelijke waarden.

Gebruik

# Standaard: markdown met tijdstempels (Engels)
${BUN_X} {baseDir}/scripts/main.ts <youtube-url-or-id>

# Specificeer talen (prioriteitsvolgorde)
${BUN_X} {baseDir}/scripts/main.ts <url> --languages zh,en,ja

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

# Met hoofdstuksegmentatie
${BUN_X} {baseDir}/scripts/main.ts <url> --chapters

# Met sprekeridentificatie (vereist AI-nabewerking)
${BUN_X} {baseDir}/scripts/main.ts <url> --speakers

# SRT-ondertitelbestand
${BUN_X} {baseDir}/scripts/main.ts <url> --format srt

# Transcriptie vertalen
${BUN_X} {baseDir}/scripts/main.ts <url> --translate zh-Hans

# Toon beschikbare transcripties
${BUN_X} {baseDir}/scripts/main.ts <url> --list

# Forceer opnieuw ophalen (negeer cache)
${BUN_X} {baseDir}/scripts/main.ts <url> --refresh

Opties

Optionele Omgevingsvariabelen

Invoerformaten

Accepteert een van de volgende als video-invoer:

• Volledige URL: https://www.youtube.com/watch?v=dQw4w9WgXcQ
• Verkorte URL: https://youtu.be/dQw4w9WgXcQ
• Insluit-URL: https://www.youtube.com/embed/dQw4w9WgXcQ
• Shorts-URL: https://www.youtube.com/shorts/dQw4w9WgXcQ
• Video-ID: dQw4w9WgXcQ

Uitvoerformaten

Uitvoermap

youtube-transcript/
├── .index.json                          # Video-ID → mappadtoewijzing (voor cache-opzoekingen)
└── {channel-slug}/{title-full-slug}/
    ├── meta.json                        # Videometadata (titel, kanaal, beschrijving, duur, hoofdstukken, enz.)
    ├── transcript-raw.json              # Ruwe transcriptiefragmenten van YouTube API (gecached)
    ├── transcript-sentences.json        # In zinnen gesegmenteerd transcript (gesplitst door interpunctie, samengevoegd over fragmenten)
    ├── imgs/
    │   └── cover.jpg                    # Videominiatuur
    ├── transcript.md                    # Markdown-transcript (gegenereerd uit zinnen)
    └── transcript.srt                   # SRT-ondertiteling (gegenereerd uit ruwe fragmenten, indien --format srt)

• {channel-slug}: Kanaalnaam in kebab-case
• {title-full-slug}: Volledige videotitel in kebab-case

De modus --list voert alleen uit naar stdout (geen bestand opgeslagen).

Caching

Bij de eerste ophaalactie slaat het script op:

• meta.json — videometadata, hoofdstukken, pad naar omslagafbeelding, taalinformatie
• transcript-raw.json — ruwe transcriptiefragmenten van YouTube API ({ text, start, duration }[])
• transcript-sentences.json — in zinnen gesegmenteerd transcript ({ text, start: "HH:mm:ss", end: "HH:mm:ss" }[]), gesplitst door zinseindigende interpunctie (.?!…。？！ enz.), tijdstempels proportioneel toegewezen op basis van karakterlengte, CJK-bewuste tekstsamenvoeging
• imgs/cover.jpg — videominiatuur

Latere uitvoeringen voor dezelfde video gebruiken gegevens uit de cache (geen netwerkaanroepen). Gebruik --refresh om opnieuw ophalen te forceren. Als een andere taal wordt aangevraagd, wordt de cache automatisch vernieuwd.

Wanneer YouTube anti-bot / geblokkeerde antwoorden retourneert op het directe InnerTube-pad, probeert het script opnieuw met alternatieve clientidentiteiten en schakelt vervolgens over naar yt-dlp indien beschikbaar. Als fallback nodig is maar yt-dlp niet beschikbaar is, moet de agent beslissen hoe hij yt-dlp beschikbaar maakt en doorgaan in plaats van de installatiebeslissing aan de gebruiker over te laten.

SRT-uitvoer (--format srt) wordt gegenereerd uit transcript-raw.json. Tekst/markdown-uitvoer gebruikt transcript-sentences.json voor natuurlijke zinsgrenzen.

Workflow

Wanneer de gebruiker een YouTube-URL opgeeft en de transcriptie wil:

1. Voer eerst --list uit als de gebruiker geen taal heeft opgegeven, om beschikbare opties te tonen
2. Gebruik altijd enkele aanhalingstekens voor de URL bij het uitvoeren van het script — zsh behandelt ? als een glob-wildcard, dus een niet-geciteerde YouTube-URL veroorzaakt "no matches found": gebruik 'https://www.youtube.com/watch?v=ID'
3. Standaard: voer uit met --chapters --speakers voor de rijkste uitvoer (hoofdstukken + sprekeridentificatie)
4. Het script slaat automatisch gegevens in cache + uitvoerbestand op en toont het bestandspad
5. Voor de modus --speakers: nadat het script het ruwe bestand heeft opgeslagen, volg de onderstaande workflow voor sprekeridentificatie om na te bewerken met sprekerlabels

Wanneer de gebruiker alleen een omslagafbeelding of metadata wil, zal het uitvoeren van het script met elke optie ook meta.json en imgs/cover.jpg in de cache opslaan.

Bij het opnieuw formatteren van dezelfde video (bijv. eerst tekst, dan SRT), worden de gegevens in de cache hergebruikt — geen nieuwe ophaalactie nodig.

Hoofdstuk- en sprekerworkflow

Hoofdstukken (--chapters)

Het script ontleedt hoofdstuktijdstempels uit de videobeschrijving (bijv. 0:00 Introductie), segmenteert de transcriptie op hoofdstukgrenzen, groepeert fragmenten in leesbare alinea's en slaat op als .md met een inhoudsopgave. Geen verdere verwerking nodig.

Als er geen hoofdstuktijdstempels in de beschrijving bestaan, wordt de transcriptie uitgevoerd als gegroepeerde alinea's zonder hoofdstukkoppen.

Sprekeridentificatie (--speakers)

Sprekeridentificatie vereist AI-verwerking. Het script voert een ruw .md-bestand uit met:

• YAML-frontmatter met videometadata (titel, kanaal, datum, omslag, beschrijving, taal)
• Videobeschrijving (voor het extraheren van sprekersnamen)
• Hoofdstuklijst uit beschrijving (indien beschikbaar)
• Ruwe transcriptie in SRT-formaat (vooraf berekende start-/eindtijdstempels, token-efficiënt)

Nadat het script het ruwe bestand heeft opgeslagen, start een sub-agent (gebruik een goedkoper model zoals Sonnet voor kostenefficiëntie) om sprekeridentificatie te verwerken:

1. Lees het opgeslagen .md-bestand
2. Lees de promptsjabloon op {baseDir}/prompts/speaker-transcript.md
3. Verwerk de ruwe transcriptie volgens de prompt:
   • Identificeer sprekers met behulp van videometadata (titel → gast, kanaal → host, beschrijving → namen)
   • Detecteer sprekerwisselingen op basis van gespreksstroom, vraag-antwoordpatronen en contextuele aanwijzingen
   • Segmenteer in hoofdstukken (gebruik beschrijvingshoofdstukken indien beschikbaar, anders maak aan op basis van onderwerpverschuivingen)
   • Opmaak met **Spreker Naam:** labels, alineagroepering (2-4 zinnen) en [HH:MM:SS → HH:MM:SS] tijdstempels
4. Overschrijf het .md-bestand met de verwerkte transcriptie (behoud de YAML-frontmatter)

Wanneer --speakers wordt gebruikt, is --chapters impliciet — de verwerkte uitvoer bevat altijd hoofdstuksegmentatie.

Foutgevallen