YouTube Downloader
Aperçu
Permet des téléchargements fiables de vidéos et d'audio depuis YouTube et les plateformes de streaming HLS (Mux, Vimeo, etc.) avec yt-dlp et ffmpeg. Cette compétence fournit des workflows pour :
- Téléchargements YouTube (jusqu'en 4K) avec fournisseurs de jetons PO ou cookies navigateur
- Téléchargements de flux HLS avec en-têtes d'authentification
- Gestion de contenu protégé et dépannage des échecs de téléchargement courants
Expérience Utilisateur Non Technique (Par Défaut)
Supposez que l'utilisateur est non technique. Ne lui demandez pas d'exécuter des commandes. Exécutez tout vous-même et rapportez la progression en langage simple. É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/auteur/durée/vignette) et confirmez qu'elles correspondent à l'intention de l'utilisateur.
- Si yt-dlp est bloqué par « confirmez que vous n'êtes pas un robot », utilisez le mode de repli YouTube oEmbed pour le titre/auteur/vignette (la durée peut être inconnue).
- Proposez des choix simples (vidéo ou audio uniquement, qualité, sous-titres, emplacement de sauvegarde).
- Procédez avec des valeurs par défaut si l'utilisateur ne spécifie rien :
- Téléchargement vidéo en meilleure qualité
- Sortie fusionnée en MP4
- Vidéo unique uniquement (pas de listes de lecture)
- Téléchargez et rapportez le chemin du fichier final, la taille du fichier et la résolution (si 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 un autre dossier »
Affichez toujours la vignette lorsqu'elle est disponible :
- Si les métadonnées incluent une URL de vignette, incluez-la avec la syntaxe Markdown image :
.
Demandez avant d'effectuer un travail supplémentaire :
- Confirmez les téléchargements de listes de lecture (peuvent être volumineux).
- Confirmez l'installation/mise à jour des dépendances si elles sont absentes.
- 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 utilisateur). Si Docker est manquant ou échoue, ne tentez pas d'installer Docker—passez au fournisseur PO Token basé sur 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 (langage simple, 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 ? (Par défaut : dossier Téléchargements)
Si l'utilisateur dit « télécharge simplement » :
- Procédez avec les valeurs par défaut et confirmez à la fin du téléchargement.
- 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 URL entre guillemets dans les commandes shell (zsh traite
?comme un glob). Exemple :'https://www.youtube.com/watch?v=VIDEO_ID'. - Assurez-vous que le proxy est actif pour yt-dlp et les fournisseurs PO Token (HTTP_PROXY/HTTPS_PROXY/ALL_PROXY).
- Si vous voyez « Connectez-vous pour confirmer que vous n'êtes pas un robot », demandez l'autorisation et utilisez les cookies du navigateur. Ne continuez pas sans cookies.
- Démarrez un fournisseur PO Token avant de télécharger (échec rapide s'il ne peut pas démarrer).
- Utilisez le fournisseur Docker bgutil lorsqu'il est disponible.
- Si Docker est manquant ou échoue, passez au fournisseur WPC basé sur 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-le comme un échec de 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-les comme un problème de proxy/réseau. Réessayez avec des formats progressifs et/ou un meilleur proxy.
Liste de Vérification d'Exécution pour l'Agent (Interne)
- Exécutez
scripts/download_video.py URL --info(ajoutez--cookies-from-browser chromesi autorisation accordée) pour récupérer les métadonnées et la vignette. - Si les métadonnées yt-dlp échouent, utilisez le mode de repli oEmbed du script pour le titre/auteur/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 Markdown image.
- Demandez à l'utilisateur de choisir vidéo ou 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 la--sub-langdemandée. - Après le téléchargement, rapportez le nom du fichier, la taille et la résolution (si vidéo) en langage simple.
- Si le téléchargement échoue avec des erreurs 403/de 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 des cookies +
web_safari. - Si « Seules les images sont disponibles » apparaît, traitez-le comme un échec de jeton PO et réessayez après avoir corrigé l'état du fournisseur/du navigateur.
- Démarrez le fournisseur PO Token avant les téléchargements (
--auto-po-tokenpar défaut). Échouez rapidement s'il ne peut pas démarrer. - Si le fournisseur Docker échoue (courant en Chine), passez automatiquement au fournisseur WPC basé sur navigateur (il peut ouvrir brièvement une fenêtre de navigateur).
- Si le fournisseur WPC est utilisé, gardez la fenêtre du navigateur ouverte jusqu'au début du téléchargement. Si le navigateur ne parvient pas à se lancer, définissez explicitement le chemin de Chrome.
- Si le fournisseur PO Token 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 listes de lecture 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 des formats ou les options de qualité
- Signalent que seuls des formats basse qualité (360p) sont disponibles
- Demandent 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 meilleure compatibilité
- Demandent le téléchargement de flux HLS (m3u8) depuis des plateformes comme Mux, Vimeo, ou autres services de streaming
- Ont besoin de télécharger des flux protégés nécessitant 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
Si non 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/VIDEO_ID"
Si seul le format 18 (360p) apparaît : Une 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 Jetons PO (Configuration Unique)
Pour un accès 1080p/1440p/4K, installez un plugin fournisseur de jetons PO dans l'environnement Python de yt-dlp :
# Trouver le chemin Python de yt-dlp (interpréteur utilisé par yt-dlp)
head -1 $(which yt-dlp)
# Installer le plugin avec l'interpréteur de la ligne ci-dessus
<YTDLP_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 jetons 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 du Navigateur
Si la configuration du fournisseur de jetons PO est problématique, utilisez les cookies du 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. Prérequis :
- Vous devez être connecté à YouTube dans le navigateur spécifié.
- Le navigateur et yt-dlp doivent utiliser la même IP/le même 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)
Extraire l'audio en MP3 :
yt-dlp -x --audio-format mp3 "VIDEO_URL"
Dossier de Sortie Personnalisé (Exécutez-le vous-même)
yt-dlp -P ~/Downloads/YouTube "VIDEO_URL"
Téléchargement avec Sous-titres (Exécutez-le vous-même)
yt-dlp --write-subs --sub-lang en "VIDEO_URL"
Téléchargement de Liste de Lecture (Exécutez-le vous-même)
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "PLAYLIST_URL"
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 meilleure compatibilité :
# Vérifier 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: Utilise le codec vidéo H.264 (largement compatible)-preset medium: Équilibre entre vitesse d'encodage et taille de fichier-crf 23: 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 conserve 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 jetons PO manquant ou yt-dlp obsolète.
Solution :
- Mettez à jour yt-dlp :
brew upgrade yt-dlp - Installez le fournisseur de jetons 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/le même 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 PO Token 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 d'Extraction nsig
Symptômes :
AVERTISSEMENT : [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 jetons 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" "VIDEO_URL"
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 PO Token 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'échec transitoire
Avertissement PO Token (Inoffensif)
AVERTISSEMENT : 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 Intégré
scripts/download_video.py
Utilisez ce wrapper 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 "VIDEO_URL"
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 (par ex., chrome, firefox)--cookies-file- Charger les cookies depuis un fichier cookies.txt--player-client- Utiliser un client YouTube spécifique (par ex., web_safari)--auto-po-token- Démarrer automatiquement le fournisseur PO Token (par défaut ; utilise Docker si disponible, sinon passe au fournisseur basé sur navigateur)--no-auto-po-token- Désactiver la configuration automatique PO Token--proxy- URL du proxy pour yt-dlp et le fournisseur PO Token (par 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é (par ex., mp4, mkv). Par défaut : mp4--playlist- Autoriser les téléchargements de listes de lecture (par défaut : vidéo unique uniquement)--info- Afficher le titre/l'auteur/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 auto (par défaut) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Client Android uniquement | ✓ | ✗ | ✗ | ✗ | ✗ |
| Fournisseur PO Token (manuel) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Cookies du navigateur | ✓ | ✓ | ✓ |
…
[section tronquée pour la traduction]