Téléchargeur YouTube
Vue d'ensemble
Permet le téléchargement fiable de vidéos et d'audio depuis YouTube et les plateformes de streaming HLS (Mux, Vimeo, etc.) en utilisant yt-dlp et ffmpeg. Cette compétence fournit des workflows pour :
- Téléchargements YouTube (jusqu'en 4K) avec fournisseurs de tokens PO ou cookies de navigateur
- Téléchargements de flux HLS avec en-têtes d'authentification
- Gestion du contenu protégé et dépannage des échecs de téléchargement courants
Quand utiliser cette compétence
Cette compétence doit être invoquée lorsque les utilisateurs :
- Demandent le téléchargement de vidéos ou de playlists YouTube
- Veulent extraire l'audio de vidéos YouTube
- Rencontrent des échecs de téléchargement avec yt-dlp ou une disponibilité limitée des formats
- Ont besoin d'aide pour la sélection de format ou les options de qualité
- Signalent que seuls des formats de faible qualité (360p) sont disponibles
- Demandent comment télécharger du contenu YouTube dans une qualité spécifique (1080p, 4K, etc.)
- Ont besoin de convertir des vidéos WebM téléchargées au format MP4 pour une meilleure compatibilité
- Demandent le téléchargement de flux HLS (m3u8) depuis des plateformes comme Mux, Vimeo ou d'autres services de streaming
- Ont besoin de télécharger des flux protégés qui nécessitent des en-têtes d'authentification
Prérequis
1. Vérifier l'installation de yt-dlp
which yt-dlp
yt-dlp --version
S'il n'est pas installé ou obsolète (< 2025.10.22) :
brew upgrade yt-dlp # macOS
# ou
pip install --upgrade yt-dlp # Multi-plateforme
Critique : Les versions obsolètes de yt-dlp provoquent des échecs d'extraction nsig et des formats manquants.
2. Vérifier l'accès à la qualité actuelle
Avant de télécharger, vérifiez les formats disponibles :
yt-dlp -F "https://youtu.be/VIDEO_ID"
Si seul le format 18 (360p) apparaît : La configuration du fournisseur de tokens PO est nécessaire pour un accès haute qualité.
Workflow de téléchargement haute qualité
Étape 1 : Installer le fournisseur de tokens PO (Configuration unique)
Pour l'accès 1080p/1440p/4K, installez un plugin fournisseur de tokens PO dans l'environnement Python de yt-dlp :
# Trouver le chemin Python de yt-dlp
head -1 $(which yt-dlp)
# Installer le plugin (ajuster le chemin pour correspondre à la version de yt-dlp)
/opt/homebrew/Cellar/yt-dlp/$(yt-dlp --version)/libexec/bin/python -m pip install bgutil-ytdlp-pot-provider
Vérification : Exécutez yt-dlp -F "VIDEO_URL" à nouveau. Recherchez les formats 137 (1080p), 271 (1440p) ou 313 (4K).
Voir references/po-token-setup.md pour des instructions détaillées d'installation et de dépannage.
Étape 2 : Télécharger avec la meilleure qualité
Une fois le fournisseur de tokens PO installé :
# Télécharger la meilleure qualité jusqu'à 1080p
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"
# Télécharger la meilleure qualité disponible (4K si disponible)
yt-dlp -f "bestvideo+bestaudio/best" "VIDEO_URL"
Étape 3 : Vérifier la qualité du téléchargement
# Vérifier la résolution vidéo
ffprobe -v error -select_streams v:0 -show_entries stream=width,height,codec_name -of default=noprint_wrappers=1 video.mp4
Sortie attendue pour 1080p :
codec_name=vp9
width=1920
height=1080
Alternative : Méthode des cookies de navigateur
Si la configuration du fournisseur de tokens PO pose problème, utilisez les cookies de navigateur :
# 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"
Avantages : Accès au contenu restreint par âge et réservé aux membres. Condition : Vous devez être connecté à YouTube dans le navigateur spécifié.
Tâches courantes
Téléchargement audio uniquement
Extraire l'audio au format MP3 :
yt-dlp -x --audio-format mp3 "VIDEO_URL"
Répertoire de sortie personnalisé
yt-dlp -P ~/Downloads/YouTube "VIDEO_URL"
Téléchargement avec sous-titres
yt-dlp --write-subs --sub-lang en "VIDEO_URL"
Téléchargement de playlist
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "PLAYLIST_URL"
Convertir WebM en MP4
Les téléchargements haute qualité YouTube utilisent souvent le format WebM (codec VP9). Convertissez en MP4 pour une meilleure compatibilité :
# Vérifier si ffmpeg est installé
which ffmpeg || brew install ffmpeg # macOS
# Convertir WebM en MP4 avec des paramètres de qualité
ffmpeg -i "video.webm" -c:v libx264 -preset medium -crf 23 -c:a aac -b:a 128k "video.mp4"
Paramètres expliqués :
-c:v libx264: Utilise le codec vidéo H.264 (largement compatible)-preset medium: Équilibre entre vitesse d'encodage et taille de fichier-crf 23: Facteur de taux constant pour la qualité (plage 18-28, plus bas = meilleure qualité)-c:a aac: Utilise le codec audio AAC-b:a 128k: Débit audio 128 kbps
Astuce : La conversion maintient la résolution 1080p et offre une vitesse d'encodage ~6x sur du matériel moderne.
Référence rapide de dépannage
Seulement 360p disponible (Format 18)
Cause : Fournisseur de tokens PO manquant ou yt-dlp obsolète.
Solution :
- Mettez à jour yt-dlp :
brew upgrade yt-dlp - Installez le fournisseur de tokens PO (voir Étape 1 ci-dessus)
- Ou utilisez la méthode des cookies de navigateur
Échec d'extraction nsig
Symptômes :
WARNING: [youtube] nsig extraction failed: Some formats may be missing
Solution :
- Mettez à jour yt-dlp vers la dernière version
- Installez le fournisseur de tokens PO
- Si cela échoue encore, utilisez le client Android :
yt-dlp --extractor-args "youtube:player_client=android" "VIDEO_URL"
Téléchargements lents ou erreurs réseau
Pour les utilisateurs en Chine ou derrière des proxy restrictifs :
- Les téléchargements peuvent être lents en raison des conditions réseau
- Laissez suffisamment de temps pour l'achèvement
- yt-dlp réessaie automatiquement en cas d'échecs transitoires
Avertissement de token PO (Inoffensif)
WARNING: android client https formats require a GVS PO Token
Action : Ignorez si le téléchargement réussit. Cela indique que le client Android a un accès limité aux formats sans tokens PO.
Référence du script fourni
scripts/download_video.py
Un wrapper pratique qui applique la solution de contournement du client Android par défaut :
Utilisation de base :
scripts/download_video.py "VIDEO_URL"
Arguments :
url- URL de la vidéo YouTube (obligatoire)-o, --output-dir- Répertoire de sortie-f, --format- Spécification du format-a, --audio-only- Extraire l'audio au format MP3-F, --list-formats- Lister les formats disponibles--no-android-client- Désactiver la solution de contournement du client Android
Remarque : Ce script utilise le client Android (360p uniquement sans tokens PO). Pour une haute qualité, utilisez yt-dlp directement avec le fournisseur de tokens PO.
Attentes de qualité
| Configuration | 360p | 720p | 1080p | 1440p | 4K |
|---|---|---|---|---|---|
| Aucune configuration (par défaut) | ✗ | ✗ | ✗ | ✗ | ✗ |
| Client Android uniquement | ✓ | ✗ | ✗ | ✗ | ✗ |
| Fournisseur de tokens PO | ✓ | ✓ | ✓ | ✓ | ✓ |
| Cookies de navigateur | ✓ | ✓ | ✓ | ✓ | ✓ |
Téléchargements de flux HLS (m3u8)
Pour les plateformes de streaming comme Mux, Vimeo et autres services basés sur HLS, utilisez ffmpeg comme outil principal. Ces flux nécessitent souvent des en-têtes d'authentification que yt-dlp peut ne pas gérer correctement.
Identification des flux HLS
Les flux HLS utilisent des fichiers de playlist .m3u8 :
- Playlist maître : Liste plusieurs options de qualité
- Playlist de rendu : Contient les URLs réelles des segments vidéo/audio
Workflow de téléchargement
Étape 1 : Obtenir l'URL du flux
Obtenez l'URL m3u8 à partir de la source vidéo. Pour les flux protégés :
- Ouvrez les outils de développement du navigateur → onglet Réseau
- Jouez la vidéo
- Filtrez pour "m3u8" afin de trouver les URLs des playlists
- Copiez l'URL du rendu (contient généralement des informations de qualité comme "rendition.m3u8")
Étape 2 : Identifier les en-têtes requis
De nombreux CDN nécessitent des en-têtes d'authentification :
- Referer : Site web d'origine (ex.
https://maven.com/) - Origin : Identique à Referer pour CORS
- User-Agent : Identification du navigateur
Vérifiez l'onglet Réseau pour voir les en-têtes que le navigateur envoie.
Étape 3 : Télécharger avec ffmpeg
Utilisez ffmpeg avec l'option -headers pour les flux protégés :
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
Paramètres clés :
-headers: Définit les en-têtes HTTP (critique pour l'authentification)-protocol_whitelist: Active les protocoles requis pour HLS-c copy: Copie de flux (pas de réencodage, plus rapide)-bsf:a aac_adtstoasc: Corrige la compatibilité audio AAC
Modèles d'en-têtes courants :
# En-tête unique
-headers "Referer: https://example.com/"
# Plusieurs en-têtes
-headers "Referer: https://example.com/" \
-headers "User-Agent: Mozilla/5.0..."
# Syntaxe alternative
-headers $'Referer: https://example.com/\r\nUser-Agent: Mozilla/5.0...'
Gestion des flux audio/vidéo séparés
Certaines plateformes (comme Mux) fournissent l'audio et la vidéo séparément :
- Télécharger le flux audio :
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
- Télécharger le flux vidéo :
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
- Fusionner les flux :
ffmpeg -i video.mp4 -i audio.m4a -c copy merged.mp4
Dépannage des téléchargements HLS
Erreurs 403 Interdit
Cause : En-têtes d'authentification manquants ou incorrects.
Solution :
- Vérifiez que l'en-tête Referer correspond au site web source de la vidéo
- Vérifiez si des en-têtes supplémentaires (Origin, User-Agent) sont nécessaires
- Assurez-vous que l'URL m3u8 inclut tous les paramètres de requête du navigateur
yt-dlp bloqué sur l'extraction de cookies
Symptôme : Extracting cookies from chrome reste bloqué indéfiniment.
Solution : Utilisez ffmpeg directement au lieu de yt-dlp pour les flux HLS.
Protocole non autorisé
Erreur : Protocol 'https' not on whitelist 'file,crypto,data'
Solution : Ajoutez -protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy
Segments vides ou aucun flux
Cause : Signatures expirées dans les URLs m3u8.
Solution :
- Obtenez des URLs fraîches depuis les outils de développement du navigateur
- Téléchargez immédiatement après avoir obtenu les URLs
- Recherchez des URLs de rendu avec des paramètres de signature mis à jour
Conseils de performance
- Les téléchargements HLS s'exécutent généralement à une vitesse de 10 à 15 fois la vitesse réelle
- Pas de réencodage avec
-c copy(le plus rapide) - Surveillez le téléchargement avec l'affichage de progression en temps réel
- Utilisez des chemins de sortie absolus pour éviter toute confusion de répertoire
Pour en savoir plus
- Configuration des tokens PO : Voir
references/po-token-setup.mdpour une installation et un dépannage détaillés - Documentation yt-dlp : https://github.com/yt-dlp/yt-dlp
- Guide de sélection de format : https://github.com/yt-dlp/yt-dlp#format-selection