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. Dieses Skill bietet Workflows für:
- YouTube-Downloads (bis zu 4K) mit PO-Token-Anbietern oder Browser-Cookies
- HLS-Stream-Downloads mit Authentifizierungs-Headern
- Behandlung geschützter Inhalte und Fehlerbehebung bei häufigen Download-Fehlern
Wann dieses Skill verwendet werden soll
Dieses Skill sollte aufgerufen werden, wenn Benutzer:
- Das Herunterladen von YouTube-Videos oder -Playlists anfordern
- Audiodaten aus YouTube-Videos extrahieren möchten
- yt-dlp-Download-Fehler oder eine eingeschränkte Formatverfügbarkeit erleben
- Hilfe bei der Formatauswahl oder Qualitätsoptionen benötigen
- Nur Formate mit niedriger Qualität (360p) gemeldet bekommen
- Fragen zum Herunterladen von YouTube-Inhalten in einer bestimmten Qualität (1080p, 4K usw.) stellen
- Heruntergeladene WebM-Videos in das MP4-Format für eine breitere Kompatibilität 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. yt-dlp-Installation überprüfen
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
Wichtig: Veraltete yt-dlp-Versionen verursachen nsig-Extraktionsfehler und fehlende Formate.
2. Aktuellen Qualitätszugriff prüfen
Vor dem Herunterladen verfügbare Formate prüfen:
yt-dlp -F "https://youtu.be/VIDEO_ID"
Wenn nur Format 18 (360p) angezeigt wird: PO-Token-Anbieter-Setup für den Zugriff auf hohe Qualität erforderlich.
Workflow für hochwertige Downloads
Schritt 1: PO-Token-Anbieter installieren (Einmaliges Setup)
Für den Zugriff auf 1080p/1440p/4K ein PO-Token-Anbieter-Plugin in yt-dlps Python-Umgebung installieren:
# Python-Pfad von yt-dlp finden
head -1 $(which yt-dlp)
# Plugin installieren (Pfad an die yt-dlp-Version anpassen)
/opt/homebrew/Cellar/yt-dlp/$(yt-dlp --version)/libexec/bin/python -m pip install bgutil-ytdlp-pot-provider
Überprüfung: yt-dlp -F "VIDEO_URL" erneut ausführen. Nach Formaten 137 (1080p), 271 (1440p) oder 313 (4K) suchen.
Siehe references/po-token-setup.md für detaillierte Setup-Anweisungen und Fehlerbehebung.
Schritt 2: Mit bester Qualität herunterladen
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: Download-Qualität überprüfen
# Videoauflösung prüfen
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, Browser-Cookies verwenden:
# 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 exklusive Inhalte. Anforderung: Im angegebenen Browser muss man bei YouTube angemeldet sein.
Häufige Aufgaben
Nur Audio herunterladen
Audio als MP3 extrahieren:
yt-dlp -x --audio-format mp3 "VIDEO_URL"
Benutzerdefiniertes Ausgabeverzeichnis
yt-dlp -P ~/Downloads/YouTube "VIDEO_URL"
Mit Untertiteln herunterladen
yt-dlp --write-subs --sub-lang en "VIDEO_URL"
Playlist herunterladen
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "PLAYLIST_URL"
WebM in MP4 konvertieren
YouTube-Hochqualitäts-Downloads verwenden oft das WebM-Format (VP9-Codec). Für eine breitere Kompatibilität in MP4 konvertieren:
# Prüfen, ob ffmpeg installiert ist
which ffmpeg || brew install ffmpeg # macOS
# WebM mit guten Qualitätseinstellungen in MP4 konvertieren
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: H.264-Videocodec verwenden (weit verbreitet kompatibel)-preset medium: Gleichgewicht zwischen Enkodiergeschwindigkeit und Dateigröße-crf 23: Constant Rate Factor für Qualität (Bereich 18-28, niedriger = bessere Qualität)-c:a aac: AAC-Audiocodec verwenden-b:a 128k: Audiobitrate 128 kbps
Tipp: Die Konvertierung behält die 1080p-Auflösung bei und bietet auf moderner Hardware etwa die 6-fache Enkodiergeschwindigkeit.
Kurzreferenz zur Fehlerbehebung
Nur 360p verfügbar (Format 18)
Ursache: Fehlender PO-Token-Anbieter oder veraltetes yt-dlp.
Lösung:
- yt-dlp aktualisieren:
brew upgrade yt-dlp - PO-Token-Anbieter installieren (siehe Schritt 1 oben)
- Oder Browser-Cookies-Methode verwenden
nsig-Extraktion fehlgeschlagen
Symptome:
WARNING: [youtube] nsig extraction failed: Some formats may be missing
Lösung:
- yt-dlp auf die neueste Version aktualisieren
- PO-Token-Anbieter installieren
- Falls weiterhin fehlschlägt, Android-Client verwenden:
yt-dlp --extractor-args "youtube:player_client=android" "VIDEO_URL"
Langsame Downloads oder Netzwerkfehler
Für Benutzer in China oder hinter restriktiven Proxys:
- Downloads können aufgrund der Netzwerkbedingungen langsam sein
- Ausreichend Zeit für den Abschluss einplanen
- 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 bedeutet, dass der Android-Client ohne PO-Token eingeschränkten Formatzugriff hat.
Referenz zum gebündelten Skript
scripts/download_video.py
Ein Komfort-Wrapper, der standardmäßig die Android-Client-Umgehung anwendet:
Grundlegende Verwendung:
scripts/download_video.py "VIDEO_URL"
Argumente:
url- YouTube-Video-URL (erforderlich)-o, --output-dir- Ausgabeverzeichnis-f, --format- Formatspezifikation-a, --audio-only- Audio als MP3 extrahieren-F, --list-formats- Verfügbare Formate auflisten--no-android-client- Android-Client-Umgehung deaktivieren
Hinweis: Dieses Skript verwendet den Android-Client (nur 360p ohne PO-Token). Für hohe Qualität yt-dlp direkt mit PO-Token-Anbieter verwenden.
Qualitätserwartungen
| Setup | 360p | 720p | 1080p | 1440p | 4K |
|---|---|---|---|---|---|
| Kein Setup (Standard) | ✗ | ✗ | ✗ | ✗ | ✗ |
| Nur Android-Client | ✓ | ✗ | ✗ | ✗ | ✗ |
| PO-Token-Anbieter | ✓ | ✓ | ✓ | ✓ | ✓ |
| Browser-Cookies | ✓ | ✓ | ✓ | ✓ | ✓ |
HLS-Stream-Downloads (m3u8)
Für Streaming-Plattformen wie Mux, Vimeo und andere HLS-basierte Dienste ffmpeg als primäres Werkzeug verwenden. Diese Streams erfordern oft Authentifizierungs-Header, die yt-dlp möglicherweise nicht korrekt behandelt.
HLS-Streams identifizieren
HLS-Streams verwenden .m3u8-Playlist-Dateien:
- Master-Playlist: Listet mehrere Qualitätsoptionen auf
- Wiedergabe-Playlist: Enthält tatsächliche Video-/Audio-Segment-URLs
Download-Workflow
Schritt 1: Stream-URL ermitteln
Die m3u8-URL aus der Videoquelle abrufen. Für geschützte Streams:
- Browser-DevTools öffnen → Netzwerk-Tab
- Video abspielen
- Nach "m3u8" filtern, um die Playlist-URLs zu finden
- Die Wiedergabe-URL kopieren (enthält normalerweise Qualitätsinfo wie "rendition.m3u8")
Schritt 2: Erforderliche Header identifizieren
Viele CDNs erfordern Authentifizierungs-Header:
- Referer: Ursprungswebsite (z. B.
https://maven.com/) - Origin: Gleiche wie Referer für CORS
- User-Agent: Browseridentifikation
Im Netzwerk-Tab prüfen, welche Header der Browser sendet.
Schritt 3: Mit ffmpeg herunterladen
ffmpeg mit dem -headers-Flag für geschützte Streams verwenden:
ffmpeg -headers "Referer: https://example.com/" \
-protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
-i "https://cdn.example.com/path/rendition.m3u8?params" \
-c copy -bsf:a aac_adtstoasc \
output.mp4
Wichtige Parameter:
-headers: HTTP-Header setzen (entscheidend für Authentifizierung)-protocol_whitelist: Erforderliche Protokolle für HLS aktivieren-c copy: Stream-Kopie (keine Neukodierung, schneller)-bsf:a aac_adtstoasc: AAC-Audio-Kompatibilität korrigieren
Häufige Headermuster:
# Einzelner Header
-headers "Referer: https://example.com/"
# Mehrere Header
-headers "Referer: https://example.com/" \
-headers "User-Agent: Mozilla/5.0..."
# Alternative Syntax
-headers $'Referer: https://example.com/\r\nUser-Agent: Mozilla/5.0...'
Behandlung separater Audio-/Video-Streams
Einige Plattformen (wie Mux) liefern Audio und Video getrennt:
- Audio-Stream herunterladen:
ffmpeg -headers "Referer: https://example.com/" \
-protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
-i "https://cdn.example.com/audio/rendition.m3u8" \
-c copy audio.m4a
- Video-Stream herunterladen:
ffmpeg -headers "Referer: https://example.com/" \
-protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
-i "https://cdn.example.com/video/rendition.m3u8" \
-c copy video.mp4
- Streams zusammenführen:
ffmpeg -i video.mp4 -i audio.m4a -c copy merged.mp4
Fehlerbehebung bei HLS-Downloads
403 Forbidden-Fehler
Ursache: Fehlende oder falsche Authentifizierungs-Header.
Lösung:
- Überprüfen, ob der Referer-Header der Videoquell-Website entspricht
- Prüfen, ob zusätzliche Header (Origin, User-Agent) erforderlich sind
- Sicherstellen, dass die m3u8-URL alle Abfrageparameter aus dem Browser enthält
yt-dlp hängt bei Cookie-Extraktion
Symptom: Extracting cookies from chrome hängt auf unbestimmte Zeit.
Lösung: Für HLS-Streams ffmpeg direkt anstelle von yt-dlp verwenden.
Protokoll nicht auf der Whitelist
Fehler: Protocol 'https' not on whitelist 'file,crypto,data'
Lösung: -protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy hinzufügen
Leere Segmente oder keine Streams
Ursache: Abgelaufene Signaturen in den m3u8-URLs.
Lösung:
- Neue URLs aus den Browser-DevTools abrufen
- Unmittelbar nach dem Abrufen der URLs herunterladen
- Nach Wiedergabe-URLs mit aktualisierten Signaturparametern suchen
Leistungstipps
- HLS-Downloads laufen typischerweise mit der 10-15-fachen Echtzeitgeschwindigkeit
- Keine Neukodierung mit
-c copy(am schnellsten) - Download mit Echtzeit-Fortschrittsanzeige überwachen
- Absolute Ausgabepfade verwenden, um Verzeichnisverwirrung zu vermeiden
Weiterführende Informationen
- PO-Token-Setup: Siehe
references/po-token-setup.mdfür detaillierte Installation und Fehlerbehebung - yt-dlp Dokumentation: https://github.com/yt-dlp/yt-dlp
- Formatauswahl-Leitfaden: https://github.com/yt-dlp/yt-dlp#format-selection