Communitygithub.com

chenwei791129/agent-skills

Transkribiere ein YouTube-Video (oder eine lokale Audio-/Videodatei) lokal mit Whisper in Text-Transkript, SRT-Untertitel und JSON. Nutze dies immer, wenn der Nutzer einen YouTube-URL teilt und Untertitel, Captions, 字幕 oder 逐字稿 wünscht – besonders wenn das Video keine herunterladbaren Captions hat – oder eine Audio-/Videodatei transkribieren / 轉錄 möchte.

Was ist agent-skills?

Diese Fähigkeit ermöglicht KI-Agenten, YouTube-Videos oder lokale Audio-/Videodateien vollständig lokal zu transkribieren, ohne auf von YouTube bereitgestellte Untertitel angewiesen zu sein. Sie ist besonders nützlich für Videos ohne Untertitel oder automatische Captions, was oft bei Zweitveröffentlichungen oder chinesischsprachigen Inhalten vorkommt. Der Agent lädt die Audiodatei herunter, normalisiert sie und transkribiert sie mit einem plattformoptimierten Whisper-Modell: Auf Apple Silicon (Mac) kommt das GPU-beschleunigte mlx-whisper zum Einsatz, auf anderen Plattformen (Intel Mac, Linux, Windows) das effiziente faster-whisper. Das Skript wird über `uv run` ausgeführt, sodass Abhängigkeiten automatisch in einer isolierten Umgebung installiert werden. Der Benutzer kann die Ausgabesprache, das Whisper-Modell und die Ausgabeformate (txt, srt, json) steuern. Nach der Transkription wandelt der Agent vereinbarungsgemäß vereinfachte chinesische Zeichen in traditionelle um, bereinigt Fehlinterpretationen von Eigennamen und technischen Begriffen und präsentiert eine übersichtliche Zusammenfassung.

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

YouTube / Audio-Transkription

Wandele ein YouTube-Video – oder eine lokale Audio-/Videodatei – in ein Transkript um, ohne auf YouTube-Untertitel angewiesen zu sein. Viele Videos (besonders Zweitveröffentlichungen und einige chinesischsprachige Uploads) haben keine Untertitel und keine automatischen Captions, sodass das Herunterladen der Untertitel mit yt-dlp --write-subs nichts liefert. Diese Fähigkeit umgeht das, indem sie das Audio herunterlädt und lokal mit einer je nach Plattform ausgewählten Whisper-Engine transkribiert.

Wann dies verwenden

  • Der Benutzer gibt eine YouTube-URL an und möchte 字幕 / 逐字稿 / Transkript / Untertitel.
  • yt-dlp --list-subs meldet has no subtitles / has no automatic captions.
  • Der Benutzer hat eine lokale .m4a/.mp3/.mp4/etc.-Datei zu transkribieren.

Voraussetzungen

  • uv installiert (wird verwendet, um yt-dlp und das Transkriptionsskript auszuführen, ohne die globale Umgebung zu beeinträchtigen). Das Skript wählt automatisch die Whisper-Engine aus und uv installiert nur das, was Ihre Plattform benötigt:
    • Apple Silicon Mac → mlx-whisper (MLX/Metal, GPU-beschleunigt).
    • Intel Mac / Linux / Windows → faster-whisper (CTranslate2, CPU oder NVIDIA CUDA).
  • Eine JavaScript-Laufzeitumgebung – node, bun oder deno – im PATH. Aktuelle yt-dlp-Versionen benötigen eine solche, um YouTube zu extrahieren; das Skript erkennt automatisch, welche vorhanden ist.
  • ffmpeg empfohlen, aber nicht erforderlich: Wenn nicht vorhanden, greift das Skript auf den integrierten macOS-Befehl afconvert zurück (unter Nicht-macOS-Systemen daher ffmpeg installieren).

Verwendung

Die gesamte Pipeline ist ein einziges eigenständiges Skript. Führen Sie es mit uv run aus, sodass die Abhängigkeiten automatisch bereitgestellt werden:

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

Häufige Optionen:

  • --language zh – eine Sprache erzwingen anstatt automatisch zu erkennen (schneller, vermeidet Fehlerkennung bei zweisprachigen Intros).
  • --model mlx-community/whisper-large-v3-turbo – die Standardeinstellung; gute Geschwindigkeit/Qualität auf Apple Silicon. Ersetzen Sie es durch mlx-community/whisper-large-v3 für maximale Qualität oder ein kleineres Modell für Geschwindigkeit.
  • --output-name my-video – Basis-Dateiname für Ausgaben (Standard ist die Video-ID).
  • --formats txt,srt – auswählen, welche Ausgaben geschrieben werden sollen (Standard txt,srt,json).

Eine lokale Datei funktioniert genauso – übergeben Sie einfach einen Pfad anstelle einer URL:

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

Beim ersten Lauf wird das Whisper-Modell (~1,6 GB für Turbo) in den Hugging-Face-Cache heruntergeladen; spätere Läufe verwenden es erneut.

Ausgaben

Geschrieben in --output-dir (Standard: aktuelles Verzeichnis), benannt nach der Video-ID (oder --output-name):

  • <name>.txt – reiner Text (ein Block).
  • <name>.srt – Untertitel mit Zeitstempeln.
  • <name>.json – vollständiges Ergebnis inkl. Zeitstempel pro Segment und erkannter Sprache.

Nach der Transkription

Die rohe Whisper-Ausgabe gibt die gesprochene Sprache wörtlich wieder. Wenn das Audio Mandarin ist, gibt Whisper vereinfachtes Chinesisch aus. Gemäß der globalen Regel des Benutzers konvertieren Sie das Transkript bei der Darstellung im Chat in Traditionelles Chinesisch (正體中文) und bereinigen offensichtliche Fehlhörer von Eigennamen / Fachbegriffen (Modellnamen, CVE-IDs, Toolnamen). Bieten Sie eine bereinigte, abschnittsweise Zusammenfassung an, anstatt den gesamten Textblock auszuschütten, und teilen Sie dem Benutzer mit, wo die vollständigen Dateien liegen.

Funktionsweise (und warum)

  1. Audio herunterladen – yt-dlp -f "bestaudio[ext=m4a]/bestaudio". Das Format 140 (128 kbps m4a) wird heruntergeladen, ohne die Herausforderung des YouTube-Player-JS "n" zu lösen, daher vermeiden wir bewusst --remote-components ejs:github (es holt entfernten Code und wird normalerweise von der Sandbox blockiert). Das Skript stellt uvx voran, wenn yt-dlp nicht installiert ist, und fügt --js-runtimes <node|bun|deno> für die vorhandene Laufzeit hinzu.
  2. Audio normalisieren – Konvertierung in 16 kHz Mono 16-Bit WAV mit ffmpeg oder macOS afconvert, falls ffmpeg fehlt.
  3. Transkribieren – Das WAV in ein numpy-float32-Array einlesen und direkt an die Engine übergeben (mlx_whisper.transcribe(...) auf Apple Silicon, faster_whisper.WhisperModel.transcribe(...) anderswo). Beide liefern dasselbe normalisierte Ergebnisformat (text / language / segments). Die Übergabe eines decodierten Arrays an Whisper verhindert, dass Whisper intern ffmpeg aufruft – was die übliche Ursache für FileNotFoundError: ffmpeg auf Systemen ohne ffmpeg ist.

Fehlerbehebung

  • has no subtitles aber Text wird dennoch benötigt – genau das ist die Aufgabe dieser Fähigkeit; fahren Sie mit der Transkription des Audios fort.
  • FileNotFoundError: ffmpeg – sollte in diesem Skript nicht auftreten (es konvertiert zuerst), aber wenn Sie die Whisper-Engine direkt auf einer m4a-Datei aufrufen, konvertieren Sie diese zuerst in WAV.
  • Auf Nicht-Apple-Silicon und Konvertierung schlägt fehl – afconvert ist nur unter macOS verfügbar, also installieren Sie ffmpeg (Linux/Windows haben keinen integrierten Fallback).
  • yt-dlp warnt vor JS-Herausforderung / "Only images are available" – stellen Sie sicher, dass node/bun/deno im PATH ist; das Skript benötigt eine Laufzeit zur Extraktion. Verwenden Sie nicht --remote-components ejs:github zur Behebung.
  • Verstümmelte / falsche Sprachausgabe – übergeben Sie --language explizit.

Verwandte Skills