Téléchargeur YouTube
Présentation
Activez 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) en utilisant des fournisseurs de jetons PO ou les cookies du 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
Expérience Utilisateur Non Technique (Par défaut)
Partez du principe que l'utilisateur n'est pas technique. Ne lui demandez pas d'exécuter des commandes. Exécutez tout vous-même et rapportez la progression en langage clair. Évitez de mentionner les outils, sauf si l'utilisateur le demande.
Flux par défaut :
- Demandez l'URL (si elle n'est pas fournie).
- Récupérez les métadonnées de la vidéo (titre/uploader/durée/vignette) et confirmez qu'elles correspondent à l'intention de l'utilisateur.
- Si yt-dlp est bloqué par un message "confirmez que vous n'êtes pas un robot", utilisez le repli YouTube oEmbed pour le titre/l'uploader/la vignette (la durée peut être inconnue).
- Proposez des choix simples (vidéo vs. audio uniquement, qualité, sous-titres, emplacement de sauvegarde).
- Procédez avec des valeurs par défaut raisonnables si l'utilisateur ne spécifie pas :
- Téléchargement vidéo à la meilleure qualité
- Sortie fusionnée en MP4
- Vidéo unique uniquement (pas de playlists)
- Téléchargez et indiquez le chemin du fichier final, sa taille et sa résolution (si c'est une vidéo).
Proposez des choix en termes simples :
- "Télécharger la vidéo en meilleure qualité (par défaut)"
- "Télécharger l'audio uniquement (MP3)"
- "Choisir une qualité : 1080p / 720p / 480p / 360p"
- "Inclure les sous-titres (si disponibles)"
- "Enregistrer dans le dossier Téléchargements (par défaut) ou indiquez-moi un autre dossier"
Affichez toujours la vignette lorsqu'elle est disponible :
- Si les métadonnées incluent une URL de vignette, incluez-la en utilisant la syntaxe d'image Markdown :
.
Demandez avant d'effectuer un travail supplémentaire :
- Confirmez le téléchargement de playlists (peut être volumineux).
- Confirmez l'installation/mise à jour des dépendances si elles sont manquantes.
- Demandez avant d'extraire les cookies du navigateur.
- Si vous utilisez des cookies, ne mentionnez jamais le nombre de cookies ou les détails bruts des cookies dans les réponses destinées à l'utilisateur. Dites "utilisé votre session de connexion Chrome".
- Si une vérification est requise, configurez automatiquement un assistant PO Token local (aucune action de l'utilisateur). Si Docker est manquant ou échoue, n'essayez pas d'installer Docker—passez au fournisseur de jetons PO basé sur le navigateur.
Rappel légal/sécurité (bref) :
- Procédez uniquement si l'utilisateur a les droits ou l'autorisation de télécharger le contenu.
Modèle de réponse (utilisez un langage clair, pas de commandes) :

Titre : ...
Chaîne : ...
Durée : ...
Je peux vous aider à :
1) Télécharger la vidéo (meilleure qualité, MP4)
2) Télécharger l'audio uniquement (MP3)
3) Choisir une qualité spécifique (1080p/720p/480p/360p)
4) Inclure les sous-titres (si disponibles)
Où dois-je l'enregistrer ? (Dossier par défaut : Téléchargements)
Si l'utilisateur dit « télécharge simplement » :
- Procédez avec les valeurs par défaut et confirmez lorsque le téléchargement est terminé.
- Si bloqué par une erreur 403, configurez automatiquement l'assistant de vérification et réessayez.
SOP de Téléchargement Fiable (Interne)
Suivez cette SOP pour éviter les échecs et confusions courants :
- Mettez les URLs entre guillemets dans les commandes shell (zsh traite
?comme un glob). Exemple :'https://www.youtube.com/watch?v=ID_VIDEO'. - Assurez-vous que le proxy est actif pour yt-dlp et les fournisseurs de jetons PO (HTTP_PROXY/HTTPS_PROXY/ALL_PROXY).
- Si vous voyez « Connectez-vous pour confirmer que vous n'êtes pas un robot », demandez la permission et utilisez les cookies du navigateur. Ne continuez pas sans cookies.
- Démarrez un fournisseur de jetons PO avant de télécharger (échouez rapidement s'il ne peut pas démarrer).
- Utilisez le fournisseur bgutil Docker lorsqu'il est disponible.
- Si Docker est manquant ou échoue, passez au fournisseur WPC basé sur le navigateur.
- Si des cookies sont utilisés, préférez le client
web_safari. Sinon, préférezmwebpour les jetons PO. - Gardez la fenêtre du navigateur ouverte pendant que WPC génère des jetons. Assurez-vous que Chrome peut atteindre YouTube via le même proxy.
- Si vous obtenez « Seules les images sont disponibles » ou « Le format demandé n'est pas disponible », traitez cela comme un échec du jeton PO et réessayez après avoir corrigé l'état du fournisseur/du navigateur.
- Si vous obtenez des erreurs SSL EOF ou de fragment, traitez cela comme un problème de proxy/réseau. Réessayez avec des formats progressifs et/ou un meilleur proxy.
Liste de Contrôle d'Exécution de l'Agent (Interne)
- Exécutez
scripts/download_video.py URL --info(ajoutez--cookies-from-browser chromesi autorisation donnée) pour récupérer les métadonnées et la vignette. - Si les métadonnées yt-dlp échouent, utilisez le repli oEmbed du script pour le titre/l'uploader/la vignette et notez que la durée peut être indisponible.
- Si une URL de vignette est présente, affichez-la dans la réponse avec la syntaxe d'image Markdown.
- Demandez à l'utilisateur de choisir vidéo vs. audio uniquement et (éventuellement) un préréglage de qualité.
- Utilisez un emplacement de sauvegarde par défaut convivial (dossier Téléchargements) sauf si l'utilisateur spécifie un dossier.
- Pour les sous-titres, exécutez avec
--subtitleset le--sub-langdemandé. - Après le téléchargement, indiquez le nom du fichier, sa taille et sa résolution (si c'est une vidéo) en langage clair.
- Si le téléchargement échoue avec des erreurs 403/fragment, réessayez une fois avec des formats progressifs non-m3u8.
- Si « Connectez-vous pour confirmer que vous n'êtes pas un robot » apparaît, demandez l'accès aux cookies et réessayez avec les cookies +
web_safari. - Si « Seules les images sont disponibles » apparaît, traitez cela comme un échec du jeton PO et réessayez après avoir corrigé l'état du fournisseur/du navigateur.
- Démarrez le fournisseur de jetons PO avant les téléchargements (
--auto-po-tokenpar défaut). Échouez rapidement s'il ne peut pas démarrer. - Si le fournisseur basé sur Docker échoue (courant en Chine), passez automatiquement au fournisseur WPC basé sur le navigateur (cela peut ouvrir brièvement une fenêtre de navigateur).
- Si le fournisseur WPC est utilisé, gardez la fenêtre du navigateur ouverte jusqu'à ce que le téléchargement commence. Si le navigateur ne parvient pas à se lancer, définissez explicitement le chemin de Chrome.
- Si le fournisseur de jeton PO expire, redémarrez-le une fois et réessayez.
- Si un proxy système est configuré, transmettez-le au conteneur du fournisseur. Si le proxy pointe vers 127.0.0.1/localhost, réécrivez-le en
host.docker.internalpour Docker.
Quand Utiliser Cette Compétence
Cette compétence doit être invoquée lorsque les utilisateurs :
- Demandent le téléchargement de vidéos ou playlists YouTube
- Souhaitent extraire l'audio de vidéos YouTube
- Rencontrent des échecs de téléchargement 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 basse qualité (360p) sont disponibles
- Demandent des informations sur le téléchargement de 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 compatibilité plus large
- 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 (Exécutez-le vous-même)
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 Actuel à la Qualité (Exécutez-le vous-même)
Avant de télécharger, vérifiez les formats disponibles :
yt-dlp -F "https://youtu.be/ID_VIDEO"
Si seul le format 18 (360p) apparaît : La configuration du fournisseur de jetons PO est nécessaire pour un accès haute qualité.
Workflow de Téléchargement Haute Qualité
Étape 1 : Installer le Fournisseur de Jeton PO (Configuration Unique)
Pour un accès 1080p/1440p/4K, installez un plugin fournisseur de jeton PO dans l'environnement Python de yt-dlp :
# Trouvez le chemin Python de yt-dlp (interpréteur utilisé par yt-dlp)
head -1 $(which yt-dlp)
# Installez le plugin en utilisant l'interpréteur de la ligne ci-dessus
<PYTHON_YTDLP> -m pip install bgutil-ytdlp-pot-provider
Vérification : Exécutez à nouveau yt-dlp -F "URL_VIDEO". Recherchez les formats 137 (1080p), 271 (1440p) ou 313 (4K).
Voir references/po-token-setup.md pour des instructions de configuration détaillées et le dépannage.
Étape 2 : Télécharger avec la Meilleure Qualité
Une fois le fournisseur de jeton PO installé :
# Télécharger la meilleure qualité jusqu'à 1080p
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "URL_VIDEO"
# Télécharger la meilleure qualité disponible (4K si disponible)
yt-dlp -f "bestvideo+bestaudio/best" "URL_VIDEO"
É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 du Navigateur
Si la configuration du fournisseur de jeton PO est problématique, utilisez les cookies du navigateur :
# Firefox
yt-dlp --cookies-from-browser firefox -f "bestvideo[height<=1080]+bestaudio/best" "URL_VIDEO"
# Chrome
yt-dlp --cookies-from-browser chrome -f "bestvideo[height<=1080]+bestaudio/best" "URL_VIDEO"
Avantages : Accès au contenu restreint par âge et aux membres uniquement. Prérequis :
- Vous devez être connecté à YouTube dans le navigateur spécifié.
- Le navigateur et yt-dlp doivent utiliser la même IP/proxy.
- N'utilisez pas le client Android avec des cookies (le client Android ne prend pas en charge les cookies).
Tâches Courantes
Téléchargement Audio Uniquement (Exécutez-le vous-même)
Extrayez l'audio en MP3 :
yt-dlp -x --audio-format mp3 "URL_VIDEO"
Dossier de Sortie Personnalisé (Exécutez-le vous-même)
yt-dlp -P ~/Téléchargements/YouTube "URL_VIDEO"
Téléchargement avec Sous-titres (Exécutez-le vous-même)
yt-dlp --write-subs --sub-lang fr "URL_VIDEO"
Téléchargement de Playlist (Exécutez-le vous-même)
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "URL_PLAYLIST"
Convertir WebM en MP4 (Exécutez-le vous-même)
Les téléchargements haute qualité YouTube utilisent souvent le format WebM (codec VP9). Convertissez en MP4 pour une compatibilité plus large :
# Vérifiez si ffmpeg est installé
which ffmpeg || brew install ffmpeg # macOS
# Convertir WebM en MP4 avec de bons 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: Utiliser 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: Utiliser 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 jeton PO manquant ou yt-dlp obsolète.
Solution :
- Mettez à jour yt-dlp :
brew upgrade yt-dlp - Installez le fournisseur de jeton PO (voir Étape 1 ci-dessus)
- Ou utilisez la méthode des cookies du navigateur
Connectez-vous pour Confirmer que Vous n'Êtes Pas un Robot
Cause : YouTube nécessite une authentification pour continuer.
Solution :
- Demandez l'autorisation et utilisez les cookies du navigateur (
--cookies-from-browser chrome). - Assurez-vous que le navigateur et yt-dlp utilisent la même IP/proxy.
- Réessayez avec le client
web_safarisi nécessaire.
Seules les Images Disponibles / Format Demandé Non Disponible
Cause : Jetons PO non appliqués ou échec de vérification du fournisseur/du navigateur.
Solution :
- Vérifiez que le fournisseur de jeton PO est en cours d'exécution avant le téléchargement.
- Gardez la fenêtre du navigateur ouverte si vous utilisez WPC.
- Si des cookies sont utilisés, préférez le client
web_safariet réessayez.
Échec de l'Extraction nsig
Symptômes :
ATTENTION : [youtube] l'extraction nsig a échoué : certains formats peuvent être manquants
Solution :
- Mettez à jour yt-dlp vers la dernière version
- Installez le fournisseur de jeton PO
- Si cela échoue toujours et que les jetons PO sont désactivés, utilisez le client Android :
yt-dlp --extractor-args "youtube:player_client=android" "URL_VIDEO"
Erreurs SSL EOF / Fragment
Cause : Instabilité du proxy ou du réseau.
Solution :
- Réessayez avec des formats progressifs (non-m3u8).
- Passez à un proxy/nœud plus stable.
- Évitez de fermer la fenêtre du navigateur de jeton PO pendant le téléchargement.
Téléchargements Lents ou Erreurs Réseau
Pour les utilisateurs en Chine ou derrière des proxies restrictifs :
- Les téléchargements peuvent être lents en raison des conditions réseau
- Accordez suffisamment de temps pour l'achèvement
- yt-dlp réessaie automatiquement en cas d'échecs transitoires
Avertissement de Jeton PO (Inoffensif)
ATTENTION : les formats https du client android nécessitent un jeton PO GVS
Action : Ignorez si le téléchargement réussit. Cela indique que le client Android a un accès limité aux formats sans jetons PO.
Référence du Script Inclus
scripts/download_video.py
Utilisez cet encapsuleur pratique pour démarrer automatiquement un fournisseur de jetons PO par défaut pour les téléchargements haute qualité. Utilisez-le vous-même et rapportez les résultats à l'utilisateur sans lui demander d'exécuter des commandes.
Utilisation de base :
scripts/download_video.py "URL_VIDEO"
Arguments :
url- URL de la vidéo YouTube (obligatoire)-o, --output-dir- Répertoire de sortie--output-template- Modèle de nom de fichier de sortie (syntaxe yt-dlp)-f, --format- Spécification du format-q, --quality- Préréglage de qualité (best, 1080p, 720p, 480p, 360p, worst). Par défaut : best (ignoré pour--audio-only)-a, --audio-only- Extraire l'audio en MP3--subtitles- Télécharger les sous-titres si disponibles--sub-lang- Langues des sous-titres (séparées par des virgules, par défaut : en)--cookies-from-browser- Charger les cookies depuis un navigateur (ex. : chrome, firefox)--cookies-file- Charger les cookies depuis un fichier cookies.txt--player-client- Utiliser un client YouTube spécifique (ex. : web_safari)--auto-po-token- Démarrer automatiquement le fournisseur de jetons PO (par défaut ; utilise Docker si disponible, sinon passe au fournisseur basé sur le navigateur)--no-auto-po-token- Désactiver la configuration automatique du jeton PO--proxy- URL du proxy pour yt-dlp et le fournisseur de jeton PO (ex. : http://127.0.0.1:1082)--wpc-browser-path- Chemin d'exécution du navigateur pour le fournisseur WPC-F, --list-formats- Lister les formats disponibles--merge-format- Conteneur de sortie fusionné (ex. : mp4, mkv). Par défaut : mp4--playlist- Autoriser les téléchargements de playlists (par défaut : vidéo unique uniquement)--info- Afficher le titre/l'uploader/la durée/la vignette et quitter--no-android-client- Désactiver le repli du client Android
Remarque : Utilisez le client Android uniquement lorsque les jetons PO sont désactivés. Gardez les jetons PO activés pour une haute qualité.
Attentes en Matière de Qualité
| Configuration | 360p | 720p | 1080p | 1440p | 4K |
|---|---|---|---|---|---|
| Jeton PO automatique (par défaut) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Client Android uniquement | ✓ | ✗ | ✗ | ✗ | ✗ |
| Fournisseur de jeton PO (manuel) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Cookies du navigateur | ✓ | ✓ | ✓ | ✓ | ✓ |
Remarque : L'activation des jetons PO est nécessaire pour un accès fiable à la haute résolution. Sans jetons PO, vous pouvez voir un nombre limité de formats (par exemple, uniquement format 18 360p).
Utilisation du Proxy
Passer un Proxy à yt-dlp
yt-dlp --proxy http://127.0.0.1:1082 "URL_VIDEO"
Utilisation avec le Script Inclus
Le script scripts/download_video.py dispose d'un argument --proxy qui transmet le proxy à la fois à yt-dlp et au fournisseur de jetons PO :
scripts/download_video.py --proxy http://127.0.0.1:1082 "URL_VIDEO"
Pièges Courants à Éviter
- URLs non entre guillemets : Les URLs YouTube contiennent
&,?, etc., que zsh interprète comme des globs. Mettez toujours les URLs entre guillemets. - Client Android avec cookies : Le client Android (
player_client=android) ne prend pas en charge les cookies. Utilisezweb_safariou le client par défaut (web) avec des cookies. - Ignorer les avertissements de jeton PO : Bien que certains avertissements soient inoffensifs, si le téléchargement produit 360p uniquement, vérifiez l'état de votre fournisseur de jetons PO.
- Fermeture de la fenêtre du navigateur : Si le navigateur s'ouvre pour la génération de jetons PO, ne le fermez pas pendant que le téléchargement est en cours.
- Incompatibilité de proxy : Le proxy du conteneur Docker diffère des proxies hôtes. Utilisez
host.docker.internalpour les services s'exécutant sur l'hôte.
Problèmes de Droits d'Auteur
AVERTISSEMENT : Cette compétence ne contourne pas les mesures de protection des droits d'auteur. Elle ne télécharge que du contenu que l'utilisateur a le droit ou l'autorisation de télécharger. Il est de la responsabilité de l'utilisateur de s'assurer de la conformité avec les lois locales et les conditions d'utilisation de la plateforme.