YouTube-Transkript-Agenten-Skill

YouTube-Transkript

Lädt Transkripte (Untertitel) von YouTube-Videos herunter. Funktioniert mit manuell erstellten und automatisch generierten Transkripten. Kein API-Schlüssel oder Browser erforderlich – verwendet direkt die InnerTube-API von YouTube und greift automatisch auf yt-dlp zurück, wenn YouTube den direkten API-Pfad blockiert.

Ruft beim ersten Durchlauf Videometadaten und Coverbild ab, speichert Rohdaten für schnelle Umformatierung zwischen.

Skriptverzeichnis

Skripte im Unterverzeichnis scripts/. {baseDir} = Verzeichnispfad dieser SKILL.md. Ersetze ${BUN_X}-Laufzeitumgebung: wenn bun installiert → bun; wenn npx verfügbar → npx -y bun; andernfalls schlage die Installation von bun vor. Ersetze {baseDir} und ${BUN_X} durch tatsächliche Werte.

Verwendung

# Standard: Markdown mit Zeitstempeln (Englisch)
${BUN_X} {baseDir}/scripts/main.ts <youtube-url-oder-id>

# Sprachen angeben (Prioritätsreihenfolge)
${BUN_X} {baseDir}/scripts/main.ts <url> --languages zh,en,ja

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

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

# Mit Sprecheridentifikation (erfordert KI-Nachbearbeitung)
${BUN_X} {baseDir}/scripts/main.ts <url> --speakers

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

# Transkript übersetzen
${BUN_X} {baseDir}/scripts/main.ts <url> --translate zh-Hans

# Verfügbare Transkripte auflisten
${BUN_X} {baseDir}/scripts/main.ts <url> --list

# Erneuten Abruf erzwingen (Cache ignorieren)
${BUN_X} {baseDir}/scripts/main.ts <url> --refresh

Optionen

Optionale Umgebungsvariablen

Eingabeformate

Akzeptiert eine der folgenden als Videoeingabe:

• Vollständige URL: https://www.youtube.com/watch?v=dQw4w9WgXcQ
• Kurze URL: https://youtu.be/dQw4w9WgXcQ
• Einbettungs-URL: https://www.youtube.com/embed/dQw4w9WgXcQ
• Shorts-URL: https://www.youtube.com/shorts/dQw4w9WgXcQ
• Video-ID: dQw4w9WgXcQ

Ausgabeformate

Ausgabeverzeichnis

youtube-transcript/
├── .index.json                          # Zuordnung Video-ID → Verzeichnispfad (für Cache-Suche)
└── {channel-slug}/{title-full-slug}/
    ├── meta.json                        # Videometadaten (Titel, Kanal, Beschreibung, Dauer, Kapitel, etc.)
    ├── transcript-raw.json              # Rohtranskript-Snippets von der YouTube-API (gecached)
    ├── transcript-sentences.json        # Satzsegmentiertes Transkript (durch Interpunktion getrennt, über Snippets hinweg zusammengeführt)
    ├── imgs/
    │   └── cover.jpg                    # Videothumbnail
    ├── transcript.md                    # Markdown-Transkript (aus Sätzen generiert)
    └── transcript.srt                   # SRT-Untertitel (aus Rohsnippets generiert, wenn --format srt)

• {channel-slug}: Kanalname in kebab-case
• {title-full-slug}: Voller Videotitel in kebab-case

Der --list-Modus gibt nur auf stdout aus (keine Datei gespeichert).

Caching

Beim ersten Abruf speichert das Skript:

• meta.json – Videometadaten, Kapitel, Coverbildpfad, Sprachinfo
• transcript-raw.json – Rohtranskript-Snippets von der YouTube-API ({ text, start, duration }[])
• transcript-sentences.json – Satzsegmentiertes Transkript ({ text, start: "HH:mm:ss", end: "HH:mm:ss" }[]), aufgeteilt durch satzbeendende Interpunktion (.?!…。？！ etc.), Zeitstempel proportional zur Zeichenlänge zugewiesen, CJK-bewusste Textzusammenführung
• imgs/cover.jpg – Videothumbnail

Nachfolgende Durchläufe für dasselbe Video verwenden zwischengespeicherte Daten (keine Netzwerkaufrufe). Verwende --refresh zum erneuten Abrufen. Wird eine andere Sprache angefordert, wird der Cache automatisch aktualisiert.

Wenn YouTube Anti-Bot-/Blockierungsantworten auf dem direkten InnerTube-Pfad zurückgibt, wiederholt das Skript mit alternativen Client-Identitäten und greift dann auf yt-dlp zurück, falls verfügbar. Falls ein Fallback erforderlich ist, aber yt-dlp nicht verfügbar ist, sollte der Agent selbst entscheiden, wie er yt-dlp verfügbar macht und fortfährt, anstatt die Installationsentscheidung dem Benutzer zu überlassen.

Die SRT-Ausgabe (--format srt) wird aus transcript-raw.json generiert. Die Text-/Markdown-Ausgabe verwendet transcript-sentences.json für natürliche Satzgrenzen.

Workflow

Wenn der Benutzer eine YouTube-URL bereitstellt und das Transkript möchte:

1. Starte zuerst mit --list, wenn der Benutzer keine Sprache angegeben hat, um die verfügbaren Optionen anzuzeigen.
2. Setze die URL immer in einfache Anführungszeichen, wenn das Skript ausgeführt wird – zsh behandelt ? als Glob-Platzhalter, daher verursacht eine nicht in Anführungszeichen gesetzte YouTube-URL den Fehler "keine Treffer gefunden": verwende 'https://www.youtube.com/watch?v=ID'
3. Standard: Führe mit --chapters --speakers aus, um die reichhaltigste Ausgabe zu erhalten (Kapitel + Sprecheridentifikation)
4. Das Skript speichert automatisch die zwischengespeicherten Daten + Ausgabedatei und gibt den Dateipfad aus.
5. Für den --speakers-Modus: Nachdem das Skript die Rohdatei gespeichert hat, folge dem untenstehenden Workflow zur Sprecheridentifikation, um mit Sprecherbezeichnungen nachzubearbeiten.

Wenn der Benutzer nur ein Coverbild oder Metadaten möchte, wird das Ausführen des Skripts mit einer beliebigen Option auch meta.json und imgs/cover.jpg cachen.

Beim Umformatieren desselben Videos (z.B. zuerst Text, dann SRT) werden die zwischengespeicherten Daten wiederverwendet – kein erneuter Abruf erforderlich.

Kapitel- & Sprecher-Workflow

Kapitel (--chapters)

Das Skript parst Kapitelzeitstempel aus der Videobeschreibung (z.B. 0:00 Einleitung), segmentiert das Transkript an Kapitelgrenzen, gruppiert Snippets in lesbare Absätze und speichert es als .md mit einem Inhaltsverzeichnis. Keine weitere Verarbeitung erforderlich.

Wenn in der Beschreibung keine Kapitelzeitstempel vorhanden sind, wird das Transkript als gruppierte Absätze ohne Kapitelüberschriften ausgegeben.

Sprecheridentifikation (--speakers)

Die Sprecheridentifikation erfordert KI-Verarbeitung. Das Skript gibt eine rohe .md-Datei aus, die Folgendes enthält:

• YAML-Frontmatter mit Videometadaten (Titel, Kanal, Datum, Cover, Beschreibung, Sprache)
• Videobeschreibung (zur Extraktion von Sprechernamen)
• Kapitelliste aus der Beschreibung (falls verfügbar)
• Rohtranskript im SRT-Format (vorberechnete Start-/Endzeitstempel, token-effizient)

Nachdem das Skript die Rohdatei gespeichert hat, starte einen Sub-Agenten (verwende ein kostengünstigeres Modell wie Sonnet für Kosteneffizienz), um die Sprecheridentifikation zu verarbeiten:

1. Lies die gespeicherte .md-Datei
2. Lies die Prompt-Vorlage unter {baseDir}/prompts/speaker-transcript.md
3. Verarbeite das Rohtranskript gemäß dem Prompt:
   • Identifiziere Sprecher anhand von Videometadaten (Titel → Gast, Kanal → Gastgeber, Beschreibung → Namen)
   • Erkenne Sprecherwechsel aus Gesprächsfluss, Frage-Antwort-Mustern und kontextuellen Hinweisen
   • Unterteile in Kapitel (verwende Beschreibungskapitel, falls vorhanden, andernfalls erstelle aus Themenwechseln)
   • Formatiere mit **Sprechername:**-Bezeichnungen, Absatzgruppierung (2-4 Sätze) und [HH:MM:SS → HH:MM:SS]-Zeitstempeln
4. Überschreibe die .md-Datei mit dem verarbeiteten Transkript (behalte das YAML-Frontmatter bei)

Wenn --speakers verwendet wird, ist --chapters impliziert – die verarbeitete Ausgabe enthält immer eine Kapitelsegmentierung.

Fehlerfälle