YouTube Downloader
Übersicht
Ermöglicht zuverlässige Video- und Audio-Downloads von YouTube und HLS-Streaming-Plattformen (Mux, Vimeo usw.) mit yt-dlp und ffmpeg. Dieser Skill bietet Workflows für:
- YouTube-Downloads (bis zu 4K) mit PO-Token-Anbietern oder Browser-Cookies
- HLS-Stream-Downloads mit Authentifizierungs-Headern
- Umgang mit geschützten Inhalten und Fehlerbehebung bei häufigen Download-Fehlern
Benutzererfahrung für nicht-technische Benutzer (Standard)
Gehe davon aus, dass der Benutzer nicht technisch versiert ist. Bitte ihn nicht, Befehle auszuführen. Führe alles selbst aus und berichte über den Fortschritt in einfacher Sprache. Erwähne keine Tools, es sei denn, der Benutzer fragt danach.
Standardablauf:
- Frage nach der URL (falls nicht angegeben).
- Rufe Video-Metadaten (Titel/Uploader/Dauer/Thumbnail) ab und bestätige, dass sie mit der Absicht des Benutzers übereinstimmen.
- Wenn yt-dlp durch „Bestätigen Sie, dass Sie kein Roboter sind“ blockiert wird, verwende als Fallback YouTube oEmbed für Titel/Uploader/Thumbnail (Dauer kann unbekannt sein).
- Biete einfache Auswahlmöglichkeiten (Video vs. Nur Audio, Qualität, Untertitel, Speicherort).
- Verwende sinnvolle Standardeinstellungen, wenn der Benutzer keine Angaben macht:
- Video-Download in bester Qualität
- MP4-zusammengeführte Ausgabe
- Einzelnes Video (keine Playlists)
- Lade herunter und melde den endgültigen Dateipfad, die Dateigröße und die Auflösung (bei Video).
Biete Auswahlmöglichkeiten in benutzerfreundlichen Begriffen an:
- „Video in bester Qualität herunterladen (Standard)“
- „Nur Audio herunterladen (MP3)“
- „Eine Qualität auswählen: 1080p / 720p / 480p / 360p“
- „Untertitel einschließen (falls verfügbar)“
- „Im Ordner Downloads speichern (Standard) oder gib mir einen anderen Ordner an“
Zeige das Thumbnail immer an, wenn verfügbar:
- Wenn die Metadaten eine Thumbnail-URL enthalten, binde sie mit der Markdown-Bildsyntax ein:
.
Frage, bevor du zusätzliche Arbeit erledigst:
- Bestätige Playlist-Downloads (können groß sein).
- Bestätige die Installation/Aktualisierung von Abhängigkeiten, falls diese fehlen.
- Frage, bevor du Browser-Cookies extrahierst.
- Wenn Cookies verwendet werden, erwähne niemals Cookie-Anzahlen oder rohe Cookie-Details in Antworten an den Benutzer. Sage stattdessen „habe Ihre Chrome-Anmeldesitzung verwendet.“
- Wenn eine Überprüfung erforderlich ist, richte automatisch einen lokalen PO-Token-Helfer ein (keine Benutzeraktionen). Wenn Docker fehlt oder fehlschlägt, versuche nicht, Docker zu installieren – wechsle stattdessen zum browserbasierten PO-Token-Anbieter.
Rechtlicher/Sicherheitshinweis (kurz):
- Fahre nur fort, wenn der Benutzer die Rechte oder die Erlaubnis zum Herunterladen des Inhalts hat.
Antwortvorlage (verwende einfache Sprache, keine Befehle):

Titel: …
Kanal: …
Dauer: …
Ich kann Ihnen helfen:
1) Das Video herunterladen (beste Qualität, MP4)
2) Nur Audio herunterladen (MP3)
3) Eine bestimmte Qualität auswählen (1080p/720p/480p/360p)
4) Untertitel einschließen (falls verfügbar)
Wo soll ich es speichern? (Standard: Ordner Downloads)
Wenn der Benutzer sagt „einfach herunterladen“:
- Fahre mit den Standardeinstellungen fort und bestätige, wenn der Download abgeschlossen ist.
- Wenn ein 403-Fehler blockiert, richte automatisch den Überprüfungshelfer ein und wiederhole den Vorgang.
Zuverlässiger Download-SOP (Intern)
Befolge diese SOP, um häufige Fehler und Verwirrung zu vermeiden:
- Setze URLs in Shell-Befehle in Anführungszeichen (zsh behandelt
?als glob). Beispiel:'https://www.youtube.com/watch?v=VIDEO_ID'. - Stelle sicher, dass der Proxy sowohl für yt-dlp als auch für PO-Token-Anbieter aktiv ist (HTTP_PROXY/HTTPS_PROXY/ALL_PROXY).
- Wenn du „Melden Sie sich an, um zu bestätigen, dass Sie kein Roboter sind“ siehst, bitte um Erlaubnis und verwende Browser-Cookies. Fahre nicht ohne Cookies fort.
- Starte einen PO-Token-Anbieter vor dem Herunterladen (schnell fehlschlagen, wenn er nicht starten kann).
- Verwende den Docker-basierten bgutil-Anbieter, wenn verfügbar.
- Wenn Docker fehlt oder fehlschlägt, wechsle zum browserbasierten WPC-Anbieter.
- Wenn Cookies verwendet werden, bevorzuge den Player-Client
web_safari. Ansonsten bevorzugemwebfür PO-Token. - Lasse das Browser-Fenster geöffnet, während WPC Token generiert. Stelle sicher, dass Chrome YouTube über denselben Proxy erreichen kann.
- Wenn du „Nur Bilder verfügbar“ oder „Angeforderte Format nicht verfügbar“ erhältst, behandele dies als PO-Token-Fehler und wiederhole den Vorgang, nachdem der Token-Anbieter-/Browser-Status behoben wurde.
- Wenn du SSL-EOF- oder Fragment-Fehler erhältst, behandele dies als Proxy-/Netzwerkproblem. Wiederhole mit progressiven Formaten und/oder einem besseren Proxy.
Agenten-Ausführungs-Checkliste (Intern)
- Führe
scripts/download_video.py URL --infoaus (füge--cookies-from-browser chromehinzu, wenn die Erlaubnis erteilt wurde), um Metadaten und Thumbnail abzurufen. - Wenn yt-dlp-Metadaten fehlschlagen, verwende den oEmbed-Fallback des Skripts für Titel/Uploader/Thumbnail und beachte, dass die Dauer möglicherweise nicht verfügbar ist.
- Wenn eine Thumbnail-URL vorhanden ist, rendere sie in der Antwort mit der Markdown-Bildsyntax.
- Frage den Benutzer, ob er Video oder nur Audio und (optional) eine Qualitätsvoreinstellung auswählen möchte.
- Verwende einen benutzerfreundlichen Standardspeicherort (Ordner Downloads), es sei denn, der Benutzer gibt einen Ordner an.
- Führe für Untertitel den Vorgang mit
--subtitlesund der angeforderten--sub-langaus. - Melde nach dem Download Dateiname, Größe und Auflösung (bei Video) in einfacher Sprache.
- Wenn der Download mit 403-/Fragment-Fehlern fehlschlägt, wiederhole einmal mit progressiven Formaten ohne m3u8.
- Wenn „Melden Sie sich an, um zu bestätigen, dass Sie kein Roboter sind“ erscheint, bitte um Cookie-Zugriff und wiederhole mit Cookies +
web_safari. - Wenn „Nur Bilder verfügbar“ erscheint, behandele dies als PO-Token-Fehler und wiederhole, nachdem der Token-Anbieter-/Browser-Status behoben wurde.
- Starte den PO-Token-Anbieter vor den Downloads (
--auto-po-tokenStandard). Schnell fehlschlagen, wenn er nicht starten kann. - Wenn der Docker-basierte Anbieter fehlschlägt (häufig in China), wechsle automatisch zum browserbasierten WPC-Anbieter (es kann kurz ein Browser-Fenster geöffnet werden).
- Wenn der WPC-Anbieter verwendet wird, lasse das Browser-Fenster geöffnet, bis der Download beginnt. Wenn der Browser nicht startet, setze den Chrome-Pfad explizit.
- Wenn der PO-Token-Anbieter eine Zeitüberschreitung hat, starte ihn einmal neu und wiederhole den Vorgang.
- Wenn ein System-Proxy konfiguriert ist, übergib ihn an den Anbieter-Container. Wenn der Proxy auf 127.0.0.1/localhost verweist, schreibe ihn für Docker auf
host.docker.internalum.
Wann dieser Skill verwendet werden soll
Dieser Skill sollte aufgerufen werden, wenn Benutzer:
- Das Herunterladen von YouTube-Videos oder -Playlists anfordern
- Audio aus YouTube-Videos extrahieren möchten
- yt-dlp-Download-Fehler oder eingeschränkte Formatverfügbarkeit erleben
- Hilfe bei der Formatauswahl oder Qualitätsoptionen benötigen
- Nur Formate mit niedriger Qualität (360p) verfügbar melden
- Fragen zum Herunterladen von YouTube-Inhalten in bestimmter Qualität (1080p, 4K usw.) stellen
- Heruntergeladene WebM-Videos für eine breitere Kompatibilität in das MP4-Format konvertieren müssen
- Das Herunterladen von HLS-Streams (m3u8) von Plattformen wie Mux, Vimeo oder anderen Streaming-Diensten anfordern
- Geschützte Streams herunterladen müssen, die Authentifizierungs-Header erfordern
Voraussetzungen
1. Überprüfe die yt-dlp-Installation (führe dies selbst aus)
which yt-dlp
yt-dlp --version
Wenn nicht installiert oder veraltet (< 2025.10.22):
brew upgrade yt-dlp # macOS
# oder
pip install --upgrade yt-dlp # Plattformübergreifend
Kritisch: Veraltete yt-dlp-Versionen verursachen nsig-Extraktionsfehler und fehlende Formate.
2. Überprüfe den aktuellen Qualitätszugriff (führe dies selbst aus)
Überprüfe vor dem Download die verfügbaren Formate:
yt-dlp -F "https://youtu.be/VIDEO_ID"
Wenn nur Format 18 (360p) erscheint: PO-Token-Anbieter-Setup für hochwertigen Zugriff erforderlich.
Hochwertiger Download-Workflow
Schritt 1: Installiere den PO-Token-Anbieter (Einmaliges Setup)
Für den Zugriff auf 1080p/1440p/4K installiere ein PO-Token-Anbieter-Plugin in die Python-Umgebung von yt-dlp:
# Finde den Python-Pfad von yt-dlp (Interpreter, der von yt-dlp verwendet wird)
head -1 $(which yt-dlp)
# Installiere das Plugin mit dem Interpreter aus der obigen Zeile
<YTDLP_PYTHON> -m pip install bgutil-ytdlp-pot-provider
Überprüfung: Führe yt-dlp -F "VIDEO_URL" erneut aus. Suche nach den Formaten 137 (1080p), 271 (1440p) oder 313 (4K).
Siehe references/po-token-setup.md für detaillierte Setup-Anleitungen und Fehlerbehebung.
Schritt 2: Download mit bester Qualität
Sobald der PO-Token-Anbieter installiert ist:
# Beste Qualität bis zu 1080p herunterladen
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"
# Beste verfügbare Qualität herunterladen (4K, falls verfügbar)
yt-dlp -f "bestvideo+bestaudio/best" "VIDEO_URL"
Schritt 3: Überprüfe die Download-Qualität
# Überprüfe die Video-Auflösung
ffprobe -v error -select_streams v:0 -show_entries stream=width,height,codec_name -of default=noprint_wrappers=1 video.mp4
Erwartete Ausgabe für 1080p:
codec_name=vp9
width=1920
height=1080
Alternative: Browser-Cookies-Methode
Wenn das PO-Token-Anbieter-Setup problematisch ist, verwende Browser-Cookies:
# Firefox
yt-dlp --cookies-from-browser firefox -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"
# Chrome
yt-dlp --cookies-from-browser chrome -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"
Vorteile: Zugriff auf altersbeschränkte und nur für Mitglieder bestimmte Inhalte. Anforderungen:
- Du musst im angegebenen Browser bei YouTube angemeldet sein.
- Browser und yt-dlp müssen dieselbe IP / denselben Proxy verwenden.
- Verwende den Android-Client nicht mit Cookies (Android-Client unterstützt keine Cookies).
Häufige Aufgaben
Nur Audio herunterladen (führe dies selbst aus)
Audio als MP3 extrahieren:
yt-dlp -x --audio-format mp3 "VIDEO_URL"
Benutzerdefiniertes Ausgabeverzeichnis (führe dies selbst aus)
yt-dlp -P ~/Downloads/YouTube "VIDEO_URL"
Mit Untertiteln herunterladen (führe dies selbst aus)
yt-dlp --write-subs --sub-lang en "VIDEO_URL"
Playlist-Download (führe dies selbst aus)
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "PLAYLIST_URL"
WebM in MP4 konvertieren (führe dies selbst aus)
YouTube-High-Quality-Downloads verwenden oft das WebM-Format (VP9-Codec). Konvertiere für eine breitere Kompatibilität in MP4:
# Überprüfe, ob ffmpeg installiert ist
which ffmpeg || brew install ffmpeg # macOS
# Konvertiere WebM in MP4 mit guten Qualitätseinstellungen
ffmpeg -i "video.webm" -c:v libx264 -preset medium -crf 23 -c:a aac -b:a 128k "video.mp4"
Parameter erklärt:
-c:v libx264: Verwende den H.264-Video-Codec (weit verbreitet kompatibel)-preset medium: Ausgewogen zwischen Kodierungsgeschwindigkeit und Dateigröße-crf 23: Constant Rate Factor für Qualität (Bereich 18-28, niedriger = bessere Qualität)-c:a aac: Verwende den AAC-Audio-Codec-b:a 128k: Audio-Bitrate 128 kbps
Tipp: Die Konvertierung behält die 1080p-Auflösung bei und bietet auf moderner Hardware eine etwa 6-fache Kodierungsgeschwindigkeit.
Kurzreferenz zur Fehlerbehebung
Nur 360p verfügbar (Format 18)
Ursache: Fehlender PO-Token-Anbieter oder veraltetes yt-dlp.
Lösung:
- Aktualisiere yt-dlp:
brew upgrade yt-dlp - Installiere den PO-Token-Anbieter (siehe Schritt 1 oben)
- Oder verwende die Browser-Cookies-Methode
Melde dich an, um zu bestätigen, dass du kein Roboter bist
Ursache: YouTube erfordert eine Authentifizierung, um fortzufahren.
Lösung:
- Bitte um Erlaubnis und verwende Browser-Cookies (
--cookies-from-browser chrome). - Stelle sicher, dass der Browser und yt-dlp dieselbe IP / denselben Proxy verwenden.
- Wiederhole bei Bedarf mit dem
web_safari-Client.
Nur Bilder verfügbar / Angefordertes Format nicht verfügbar
Ursache: PO-Token nicht angewendet oder Überprüfung des Anbieters/Browsers fehlgeschlagen.
Lösung:
- Überprüfe, ob der PO-Token-Anbieter vor dem Download läuft.
- Lasse das Browser-Fenster geöffnet, wenn du WPC verwendest.
- Wenn Cookies verwendet werden, bevorzuge den
web_safari-Client und wiederhole den Vorgang.
nsig-Extraktion fehlgeschlagen
Symptome:
WARNING: [youtube] nsig extraction failed: Some formats may be missing
Lösung:
- Aktualisiere yt-dlp auf die neueste Version
- Installiere den PO-Token-Anbieter
- Wenn es immer noch fehlschlägt und PO-Token deaktiviert sind, verwende den Android-Client:
yt-dlp --extractor-args "youtube:player_client=android" "VIDEO_URL"
SSL-EOF- / Fragment-Fehler
Ursache: Proxy- oder Netzwerkinstabilität.
Lösung:
- Wiederhole mit progressiven Formaten (nicht-m3u8).
- Wechsle zu einem stabileren Proxy/Knoten.
- Vermeide es, das PO-Token-Browser-Fenster während des Downloads zu schließen.
Langsame Downloads oder Netzwerkfehler
Für Benutzer in China oder hinter restriktiven Proxys:
- Downloads können aufgrund von Netzwerkbedingungen langsam sein
- Gib ausreichend Zeit für den Abschluss
- yt-dlp wiederholt bei vorübergehenden Fehlern automatisch
PO-Token-Warnung (harmlos)
WARNING: android client https formats require a GVS PO Token
Aktion: Ignorieren, wenn der Download erfolgreich ist. Dies zeigt an, dass der Android-Client ohne PO-Token nur eingeschränkten Format-Zugriff hat.
Referenz für gebündelte Skripte
scripts/download_video.py
Verwende diesen Komfort-Wrapper, um automatisch einen PO-Token-Anbieter für hochwertige Downloads zu starten. Verwende es selbst und berichte dem Benutzer die Ergebnisse, ohne ihn zu bitten, Befehle auszuführen.
Grundlegende Verwendung:
scripts/download_video.py "VIDEO_URL"
Argumente:
url- YouTube-Video-URL (erforderlich)-o, --output-dir- Ausgabeverzeichnis--output-template- Ausgabedateinamen-Vorlage (yt-dlp-Syntax)-f, --format- Formatangabe-q, --quality- Qualitätsvoreinstellung (best, 1080p, 720p, 480p, 360p, worst). Standard: best (für--audio-onlyübersprungen)-a, --audio-only- Audio als MP3 extrahieren--subtitles- Untertitel herunterladen, falls verfügbar--sub-lang- Untertitel-Sprachen (kommagetrennt, Standard: en)--cookies-from-browser- Cookies aus einem Browser laden (z.B. chrome, firefox)--cookies-file- Cookies aus einer cookies.txt-Datei laden--player-client- Einen bestimmten YouTube-Player-Client verwenden (z.B. web_safari)--auto-po-token- PO-Token-Anbieter automatisch starten (Standard; verwendet Docker, falls verfügbar, andernfalls wird auf den browserbasierten Anbieter umgeschaltet)--no-auto-po-token- Automatisches PO-Token-Setup deaktivieren--proxy- Proxy-URL für yt-dlp und den PO-Token-Anbieter (z.B. http://127.0.0.1:1082)--wpc-browser-path- Browser-Ausführungspfad für den WPC-Anbieter-F, --list-formats- Verfügbare Formate auflisten--merge-format- Ausgabe-Container zusammenführen (z.B. mp4, mkv). Standard: mp4--playlist- Playlist-Downloads zulassen (Standard: nur einzelnes Video)--info- Titel/Uploader/Dauer/Thumbnail ausgeben und beenden--no-android-client- Android-Client-Fallback deaktivieren
Hinweis: Verwende den Android-Client nur, wenn PO-Token deaktiviert sind. Lasse PO-Token für hohe Qualität aktiviert.
Qualitätserwartungen
| Einrichtung | 360p | 720p | 1080p | 1440p | 4K |
|---|---|---|---|---|---|
| Auto PO-Token (Standard) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Nur Android-Client | ✓ | ✗ | ✗ | ✗ | ✗ |
| PO-Token-Anbieter (manuell) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Browser-Cookies | ✓ | ✓ | ✓ | ✓ | ✓ |