Parcourir la documentation
Guides
Un guide axé sur Linux pour télécharger au quotidien, installer la version nightly, choisir les formats, récupérer les sous-titres et reprendre une collecte.
Sur cette page
Installer les outils de téléchargement
Commencez par la version nightly, Deno et FFmpeg. Utilisez l’environnement virtuel du projet et activez l’émulation de navigateur avec --impersonate="". La procédure Linux est indiquée ci-dessous. Les onglets proposent également des instructions pour macOS et Windows.
Ubuntu / Debian exemple avec Python 3.11+. Installer les outils système, créer un environnement virtuel du projet, puis installer le nuit actuel et ses extraits.
sudo apt-get update
sudo apt-get install -y python3 python3-venv ffmpeg aria2 curl unzip
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"
curl -fsSL https://deno.land/install.sh -o /tmp/install-deno.sh
sh /tmp/install-deno.sh
export PATH="$HOME/.deno/bin:$PATH"
deno --version
python -m yt_dlp --versionAvec Homebrew installé, utilisez-le pour Python, Deno, FFmpeg et aria2. Gardez yt-dlp lui-même dans l'environnement de projet afin que le commandement d'actualisation nocturne soit le même que sur Linux.
brew install python deno ffmpeg aria2
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"
deno --version
python -m yt_dlp --versionInstallez Python 3.11+, Deno et les exécuteurs FFmpeg, puis ouvrez un nouveau terminal. Utilisez directement l'interprète de l'environnement si PowerShell bloque l'activation. aria2 est facultatif; installez-le séparément si vous utilisez la recette de téléchargement extérieur.
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -U --pre "yt-dlp[default,curl-cffi]"
deno --version
ffmpeg -version
.\.venv\Scripts\python.exe -m yt_dlp --version| Outil | Ce qu'il fait | Vérification |
|---|---|---|
| Python 3.11+ | Il y a le package Python et les exemples dans cette série. | python --version |
| Dernière yt-dlp nocturne + défaut,curl-cffi extra | Extracteur YouTube actuel, compatible avec le solvateur EJS et le support d'impersonnalisation du navigateur. | python -m yt_dlp --version |
| FFmpeg et ffprobe | Mélanger les courants, convertir l'audio, couper les clips et inspecter les médias sauvés. | ffmpeg -version / ffprobe -version |
| Deno 2.3+ (ne nécessite dans ce flux de travail) | Rendez-vous sur YouTube, installez-le sur chaque processus, pas seulement votre machine de développement. | deno --version |
Installez les exécutables aussi. [default] fournit les scripts EJS; Deno est séparé. FFmpeg et ffprobe doivent également être sur le PATH du processus.
deno --version
ffmpeg -version
ffprobe -version
python -m pip show yt-dlp yt-dlp-ejs curl-cffi
python -m yt_dlp --list-impersonate-targetspython -m yt_dlp --ignore-config --js-runtimes deno --impersonate="" --verbose \
--simulate "https://www.youtube.com/watch?v=jNQXAC9IVRw"La base d'exploitation de FlashData comprend --impersonate=": il permet à curl-cffi de choisir une empreinte d'empreinte du navigateur disponible. Cela change l’empreinte d’empreinte de la demande ; il ne fournit pas de cookies de connexion, ne résout pas les défis de JavaScript ou ne modifie pas l’IP de sortie. Si cette option ralentit une route de travail ou introduit des erreurs, répétez le même test d'un vidéo sans cela et gardez la configuration de travail.
Vérifiez le délivrance avant de le mettre sur un processus
Obtenez des exécutions de la page de sortie du projet officiel, ou installez le paquet Python de sa source de paquet publiée. Si vous téléchargez un binaire indépendant, comparez son SHA-256 avec le nom de fil correspondant dans ce SHA2-256SUMS. Enregistrez le délivrance et le checksum avec votre image de processus afin que vous puissiez identifier exactement ce qui a été effectué.
sha256sum yt-dlpshasum -a 256 yt-dlp_macosGet-FileHash -Algorithm SHA256 .\yt-dlp.exeUne comparaison de checksum n’est utile que lorsque la valeur attendue vient du débit confié, pas le même miroir inconnu que l’exécutable. Si le logiciel de sécurité flamme un fichier, enquêtez sur sa source et rapportez-le avant de faire une exception. La disponibilité à source ouverte seule n’est pas la preuve que chaque plugin binaire ou tiers téléchargé est sûr.
Traitez les fichiers de configuration partagés comme code à réviser: des options telles que --exec peuvent lancer des commandes, et les plugins ajouter du code au processus de téléchargement. Gardez les cookies de navigateur, les identifiants proxy et les URL signés hors des exemples de configuration et des rapports diagnostiques.
Téléchargez un vidéo
Utilisez un petit vidéo d'abord. Cite l'URL, ajoutez --no-playlist et nommez le fichier par ID vidéo.
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist -P downloads \
-o "%(id)s.%(ext)s" --print after_move:filepath \
"https://www.youtube.com/watch?v=jNQXAC9IVRw"Sans un surride de format, yt-dlp choisit ses flux disponibles préférés. Des sources de haute qualité ont souvent des flux vidéo et audio séparés, donc deux transferts suivis d'une fusion FFmpeg sont normaux. Les fichiers intermédiaires et un fichier .part peuvent apparaître pendant que le travail est en cours de fonctionnement.
Choisir la qualité et les codecs
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
-F "https://www.youtube.com/watch?v=jNQXAC9IVRw"Choisissez une politique, pas un identifiant de format copié. Vérifiez la résolution, les codecs et les traces séparées audio/video.
| Selection ou option | Signification | Quand l’utiliser |
|---|---|---|
| BV + BV | Choisissez un seul streaming vidéo et un seul streaming audio; FFmpeg les combine. | Vous avez besoin de deux traces et vous pouvez fusionner localement. |
| A/B | Essayez le sélectionneur A, puis B si A n'est pas disponible. | Définissez un défaut explicite au lieu d'assumer que chaque source a les mêmes formats. |
| [height<=1080] | Exclut les flux au-dessus de 1080 pixels hauts. | Un lien haut dur est un besoin. |
| -S res:1080 | Préférez la résolution jusqu'à 1080; vous pouvez sélectionner une plus grande lorsque aucune des éléments ci-dessous n'est disponible. | 1080p est une préférence plutôt qu'un plafond dur. |
| --merge-output-format mp4 | Choisissez le conteneur lors de la fusion de flux séparés. | Vous avez déjà sélectionné les flux compatibles. il ne transcode pas les codecs. |
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
-f "bv*[height<=1080]+ba/b[height<=1080]" -P downloads \
"https://www.youtube.com/watch?v=jNQXAC9IVRw"Pour un éditeur ou un stack de lecture qui nécessite spécifiquement H.264 vidéo et AAC audio, filtrez ces codecs et fusionnez-vous à MP4. MP4 est un conteneur: un flux dans un conteneur MP4 peut toujours contenir un codec votre application ne peut pas décoder.
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
-f "bv[vcodec^=avc1][height<=1080]+ba[acodec^=mp4a]/b[vcodec^=avc1][acodec^=mp4a][height<=1080]" \
--merge-output-format mp4 -P downloads "https://www.youtube.com/watch?v=jNQXAC9IVRw"Remuxing remplace les flux sans les réencoder. Transcodage change les codecs et consomme la CPU tout en changant potentiellement la qualité. Utilisez --remux-video lorsque les courants sont déjà en conformité avec le conteneur cible; utilisez une conversion délibérée FFmpeg lorsque un décoder en descente nécessite des codecs différents.
Écrivez l’audio ou MP3
Si votre pipeline de transcription accepte le codec audio source, téléchargez ce streaming directement. Cela évite une conversion inutile. MP3 est utile lorsque un consommateur le demande spécifiquement ; une haute MP3 n’est pas en mesure de restaurer les détails déjà perdues dans la source.
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist -f ba -P audio \
-o "%(id)s.%(ext)s" "https://www.youtube.com/watch?v=jNQXAC9IVRw"python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist -f ba -x \
--audio-format mp3 --audio-quality 0 -P audio -o "%(id)s.%(ext)s" \
"https://www.youtube.com/watch?v=jNQXAC9IVRw"Écrivez des captions et des métadonnées
Une collection utile a besoin de plus que des filenames. Gardez les identifiants vidéo, les URL source, les titres, les durées et les captions disponibles afin que vous puissiez rechercher la collection et suivre un actif à sa source. Commencez par la liste des traces de l'affichage; demander en ne signifie pas que chaque vidéo a une piste anglaise.
python -m yt_dlp --list-subs "https://www.youtube.com/watch?v=jNQXAC9IVRw"
python -m yt_dlp --skip-download --write-subs --write-auto-subs --sub-langs "en.*" \
--sub-format "vtt/best" -P captions -o "%(id)s.%(ext)s" \
"https://www.youtube.com/watch?v=jNQXAC9IVRw"python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist --write-info-json \
--write-thumbnail -P downloads -o "%(id)s.%(ext)s" \
"https://www.youtube.com/watch?v=jNQXAC9IVRw"Le fichier .info.json est des méta-dataes opérationnelles détaillées, pas une réponse API publique propre. Il peut inclure des URL médias expirant et des champs liés à la demande. Gardez le côté complet avec la collection, et exporter seulement les champs dont votre système de descente a besoin. Si vous avez besoin de SRT au lieu de VTT, ajoutez --convert-subs srt et assurez-vous que FFmpeg est disponible.
Créer un élément de données AI
Pour une collection de formation, décidez les médias et les outils de texte ensemble. Un besoin commun est le meilleur vidéo et audio disponibles, combiné dans MP4, avec des captions timestampées et des métadonnées d'extraction conservées sous le même ID vidéo. Un plafond de résolution utile pour les prévisions est généralement le mauvais défaut pour un ensemble de données de qualité source.
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
-f "bestvideo+bestaudio/best" \
--merge-output-format mp4 --remux-video mp4 \
--write-info-json --write-subs --write-auto-subs \
--sub-langs "en" --sub-format "vtt/best" \
--sleep-subtitles 5 --concurrent-fragments 1 \
-P dataset -o "%(id)s/%(id)s.%(ext)s" \
--print after_move:filepath "https://www.youtube.com/watch?v=jNQXAC9IVRw"Commencez par un langage précis. Dans notre check-in en direct, en.* a sélectionné en, en-en et en-de; la troisième piste est retournée 429 avant que le téléchargement médiatique ne commence. Un erreur de note peut arrêter l'élément à ce stade. Après un refroidissement, retirez seulement la piste requise, ou divisez les médias et les postes de travail si votre collection doit maintenir l'ingestion des médias en mouvement.
Le /best fallback permet un flux combiné video/audio lorsque des traces séparées ne sont pas disponibles. Rémunissez ce retard si votre contrat de collecte nécessite des sources bestvideo et bestaudio séparées. MP4 ne signifie pas H.264 : cette recette maintient les codecs source sélectionnés. Utilisez le sélecteur H.264/AAC strict ci-dessus si votre décoder de formation nécessite ces codecs, ou transcode comme un pas séparé, enregistré.
dataset/VIDEO_ID/
VIDEO_ID.mp4
VIDEO_ID.info.json
VIDEO_ID.en.vtt| Conditions | Décision collective |
|---|---|
| La plus haute qualité disponible | Utilisez bestvideo+bestaudio, conservez les codecs source et vérifiez les flux mélangés avec ffprobe. |
| Texte timé | Gardez les segments VTT/SRT et la langue à côté de l'ID vidéo. Le texte en flatte disque les horaires nécessaires pour l'alignement des clips. |
| Légendes manquantes | Récupérer le texte manquant explicitement.Router l'audio sauvé à votre étape de transcription si le texte est obligatoire. |
| Captions pour de nombreuses langues | Chaque piste supplémentaire ajoute des demandes et peut rencontrer 429 indépendamment des médias. |
| Médias récapitulaires + livraison de texte | Utilisez un archive de données séparé et un enregistrement avec des médias, des métadonnées et des statuts d'indications. Une entrée d'archive ne prouve pas que toutes les pages requises existent. |
Ne réutilisez pas un archive créé par un précédent média-seulement fonctionnant pour cette nouvelle politique: les vidéos archivées peuvent être éteintes avant que leurs captures manquantes soient collectées. Ou bien exécutez la politique de données avec son propre archive ou planifiez un passage de réparation séparé pour les IDs manquants du texte. Enregistrez les captions originales; si votre modèle a besoin de texte transcrit propre, dérivez-le dans une étape de traitement versionnée.
Améliorer la puissance de transfert sans surchauffer un IP
aria2c peut aider lorsque une seule connexion sous-tend un lien non fiable ou à haute latitude. Il ne peut pas réparer une demande de joueur refusée ou un IP de sortie flaglé. Tout d'abord, faites le téléchargateur natif travailler sur une seule source; puis comparez les temps de transfert et les erreurs avec un petit nombre de connexions aria2.
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
--downloader aria2c --downloader "dash,m3u8:native" \
--downloader-args "aria2c:-x 2 -s 2 -j 1" \
--concurrent-fragments 1 \
-P downloads -o "%(id)s.%(ext)s" "https://www.youtube.com/watch?v=jNQXAC9IVRw"| Contrôle | Ce qui limite |
|---|---|
| aria2c -x 2 | Connexions à un serveur pour un téléchargement. |
| aria2c -s 2 | Les divisions demandées pour un fichier; la division dépend également de la taille du fichier et du support du serveur. |
| aria2c -j 1 | Les éléments concurrents à l'intérieur de cette aria2 invocation, pas d'autres yt-dlp ouvriers. |
| --concurrent-fragments 1 | Le débit est téléchargé dans le téléchargement natif DASH/HLS. |
| Votre travail queue | Le total des vidéos actives partage le même hôte ou IP de sortie proxy. |
curl-cffi l'impression appartient aux demandes de yt-dlp ; elle ne configure pas la empreinte-d'empreinte TLS de aria2. Si les téléchargements natifs fonctionnent mais aria2 reçoit 403, retournez à l'original avant de changer les paramètres d'extracteur non liés. Gardez l'extraction et le transfert extérieur sur la même session de proxy.
Dans l’opération de FlashData, augmenter la concurrence trop agressivement peut faire que la route de travail commence à retourner 403 immédiatement. Si cela arrive, arrêtez les autres emplois, retournez à un processus et à une connexion, puis réessayez. Ne vous compensez pas en ajoutant plus de aria2 divisions ou en retraitant le même flux refusé en parallèle. Si cette IP reste rejetée à faible charge, utilisez le flux de travail de remplacement de l'IP 403.
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
--downloader native --concurrent-fragments 1 --limit-rate 2M \
--sleep-requests 2 --sleep-interval 5 --max-sleep-interval 10 \
-P diagnostics "https://www.youtube.com/watch?v=jNQXAC9IVRw"Préparer une collection
Pour un petit ensemble connu, créez un UTF-8 urls.txt avec un URL d'horloge par ligne. Pour une liste de lecture YouTube, enregistrez d’abord ses ID dans un manifeste. L'extraction plate inspecte la liste de lecture sans faire une extraction complète pour chaque vidéo; elle est utile pour la révision d'échelle, mais ses entrées peuvent manquer de durée, de formats et de détails de disponibilité.
python -m yt_dlp --flat-playlist --print "https://www.youtube.com/watch?v=%(id)s" \
"https://www.youtube.com/playlist?list=YOUR_PLAYLIST_ID" > urls.txtPour tester une collection, sélectionnez quelques entrées de la liste de lecture avec --playlist-items 1:5. La barre /videos d'un canal est un point de départ plus clair pour les vidéos téléchargées qu'une page d'accueil ambiguë du canal. Ne traitez pas l'ordre de la liste de lecture comme une identité: les articles peuvent être insérés, reordonnés ou supprimés.
| Filtre | Utilisation | conséquences |
|---|---|---|
| --playlist-items 1:5 | Les cinq premiers articles de la liste actuelle. | Utile pour un petit essai, pas un point de contrôle durable. |
| --dateafter 20260101 | Restez les entrées datées ou après janvier 1, 2026. | Le filtre de date peut encore nécessiter l'extraction par vidéo. |
| --match-filters "!is_live & duration <= 1800" | Require un élément non en direct avec une durée connue au plus 30 minutes. | Les entrées à durée inconnue ne correspondent pas à ce filtre strict. |
| --download-archive archive.txt | Skip les identifiants source déjà enregistrés par des téléchargements antérieurs. | Il travaille sur des titres changés et des positions de playlist. |
Récupérer une collection en toute sécurité
Ensuite, vous pouvez enregistrer yt-dlp-work.conf dans votre dossier de collecte, à côté urls.txt. Il définit la politique de sortie une fois, donne à la collection son propre archive et limite les retraites. Gardez les fichiers de sortie et cet archive ensemble : un archive enregistre le succès par l’extracteur et l’ID, pas par le numéro de vérification ou la localisation du fichier actuel.
# YouTube worker baseline
--js-runtimes deno
--impersonate=""
--concurrent-fragments 1
# Output policy
--no-playlist
-f "bv*[height<=1080]+ba/b[height<=1080]"
-P downloads
-o "%(channel_id)s/%(id)s.%(ext)s"
--write-info-json
# Resume and remember completed media
--continue
--download-archive archive.txt
--no-abort-on-error
# Bound each attempt and spread out work
--retries 5
--fragment-retries 5
--socket-timeout 30
--sleep-requests 1
--sleep-interval 5
--max-sleep-interval 10
# Append paths only after the final move
--print-to-file after_move:filepath completed-paths.txtpython -m yt_dlp --ignore-config --config-locations yt-dlp-work.conf --batch-file urls.txtRécupérer le même ordre après une interruption. Les ID complets sont éteints, et les transferts partiels récurrents continuent là où ils sont soutenus. Les défauts d’extraction peuvent être révisés dans la prochaine ligne. Les fichiers .part par défaut sont d'une manière utile; ne les supprimez pas comme une étape de retrait de routine.
--no-abort-on-error continue à passer des entrées inaccessibles, mais un cours peut toujours sortir nonzero et les erreurs post-traitement nécessitent l'attention. Évitez d'ajouter --ignore-errors uniquement pour obtenir un travail vert: il peut traiter les échecs post-processing comme des téléchargements réussis. Vérifiez le journal et les sorties complètes avant de déclarer la collection complète.
Vérifier les fichiers terminés
Le fichier completed-paths.txt est un inventaire de début utile. Testez la sortie finale réelle plutôt qu'un seul streaming vidéo temporaire. ffprobe lit les métadonnées conteneur et flux; un passage de décodage séparé prend des problèmes que seuls un titre lisible manquera.
ffprobe -v error -show_entries format=duration,size:stream=codec_type,codec_name,width,height -of json "downloads/CHANNEL_ID/VIDEO_ID.mp4"ffmpeg -v error -i "downloads/CHANNEL_ID/VIDEO_ID.mp4" -f null -| Rechercher | Solution |
|---|---|
| Seul un fichier .part ou séparé de flux reste | Vérifiez l'erreur transfer/merge et réinitialisez le travail d'origine; ne marquez pas le fichier intermédiaire complet. |
| Vidéo sans son | Inspectez le format sélectionné et les flux ffprobe. Un format vidéo-unique nécessite une sélection audio et une fusion. |
| MP4 ne s'ouvre pas dans votre éditeur | Inspectez les codecs, pas seulement l’extension; sélectionnez des courants compatibles ou transcodes explicitement. |
| ID archivé mais pas de fichier local | Vérifiez si le fichier était moved/deleted. Reconnaître l'inventaire avant de changer les entrées d'archive. |
9 Mettre un commandement prouvé dans un travail prévu
Exécuter le commandement complet avec succès à la main avant de le planifier. Un calendrier commence généralement avec un PATH différent et un directory de travail. Donnez-lui la voie Python complète de l'environnement virtuel, la voie de configuration complète et un directeur de travail explicite ; faites également FFmpeg et le temps de fonctionnement JavaScript disponible pour ce processus.
- Utilisez un seul ouvrier pour un collection/archive. Ne laissez pas la course d'hier surlapper la course d'aujourd'hui contre les mêmes sorties.
- Sur Linux, utilisez une entrée timer/service ou cron avec un directory de travail et un lock comme le floc. Gardez les journaux en dehors de la dossier médiatique et les tournez.
- Sur macOS, utilisez le lancement avec des voies exécutoires absolues et directives de travail.
- Sur Windows Task Scheduler, définissez le programme dans l'environnement python.exe, Arguments dans -m yt_dlp plus les options de configuration et de mise en jeu, et démarrez dans la dossier de collecte.
- Enregistrement start/end temps, version exécutable, manifest source, état de sortie et completed/failed compte. Un sortie de lot non zéro ne signifie pas chaque élément échoué.
- Gardez les fichiers cookies et les identifiants de destination hors du repository de configuration partagée. Donnez un travail uniquement les identifiants dont il a besoin.
Les options de sommeil dans le config agissent dans un seul processus. Deux processus utilisant les mêmes paramètres produisent encore dix flux de demandes. Augmentation --concurrent-fragments change la concurrence de fragments dans un téléchargement, pas le nombre de vidéos dans votre coque de travail.
Choisir le bon guide d'erreur
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"
python -m yt_dlp --versionLorsqu'une source précédemment fonctionnelle s'efface, mise à jour au dernier soir, y compris les extra correspondants. Pour l'utilisation binaire indépendante yt-dlp --update-to de nuit; -U seul reste sur le canal actuel. Exécutez un petit canary après chaque mise à jour, puis reconstruisez les processus et enregistrez la révision afin que la flotte ne mélange pas silencieusement les sorties.
| Symptôme | Commencez ici |
|---|---|
Requested format is not available | Liste des formats et vérifiez vos filtres stricts avant de changer les retraites. |
ffmpeg not found / ffprobe and ffmpeg not found | Vérifiez le PATH depuis le compte du processus ou du calendrier réel. |
| JavaScript challenge / Avertissement de runtime manquant | Vérifiez la détection du temps de fonctionnement et le paquet EJS correspondant. |
| HTTP 403 pendant le transfert | Identifier l'hébergement refusé et le stade; extraire séparé de la transmission des médias. |
| HTTP 429 | Pause l'IP affecté, permet un coulement et une fréquence de demande inférieure extraction/caption. |
Sign in to confirm you’re not a bot | Arrêtez le groupe et diagnostiquez une source, une session et un réseau. |
Lorsque la production appartient à un pipeline cloud
Si vous voulez posséder le téléchargateur, les flux de travail ci-dessus vous donnent le contrôle sur les fichiers, les formats et le traitement. Si votre application a besoin de médias complets livrés à l'enregistrement, FlashData fournit des emplois de téléchargement YouTube traqués, le traitement des bot, la route proxy et les retours. Votre application soumet les paramètres source et sortie, puis maintient l'ID de travail et le registre de livraison.
Matériel de référence
Le référence option upstream est la source de vérité pour votre version installée. Utilisez ces sections lors de la modification d'une politique de collecte ou de l'actualisation d'une image du processus.