Sfoglia la documentazione
Guide
Esempi Python eseguibili per download, metadati, dataset per l’IA e processi che possono essere ripresi.
In questa pagina
Installare la biblioteca Python
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"Installa anche Deno, FFmpeg e ffprobe. Questi esempi funzionano localmente su Linux, macOS o Windows e non hanno bisogno di una chiave API.
Scarica il tuo primo video
from yt_dlp import YoutubeDL
from yt_dlp.networking.impersonate import ImpersonateTarget
options = {
"js_runtimes": {"deno": {}},
"impersonate": ImpersonateTarget(),
"concurrent_fragment_downloads": 1,
"noplaylist": True,
"outtmpl": "downloads/%(id)s.%(ext)s",
"format": "bv*[height<=1080]+ba/b[height<=1080]",
}
with YoutubeDL(options) as downloader:
downloader.download(["https://www.youtube.com/watch?v=jNQXAC9IVRw"])Le impostazioni CLI non sono ereditate. Imposta il Deno, la personificazione e il pacing nelle opzioni Python, anche quando il tuo comando terminale li utilizza già.
download() prende una lista di URL e restituisce un codice di stato. extract_info(url, download=True) restituisce le informazioni di estrazione nonché l'esecuzione del download. Utilizzare un contesto manager per chiudere l'esempio pulito, e creare un nuovo esempio per un lavoro indipendente piuttosto che condividere uno stato mutabile in tutta la linea.
Leggi i metadati senza media
import json
from yt_dlp import YoutubeDL
from yt_dlp.networking.impersonate import ImpersonateTarget
url = "https://www.youtube.com/watch?v=jNQXAC9IVRw"
options = {
"js_runtimes": {"deno": {}},
"impersonate": ImpersonateTarget(),
"noplaylist": True,
"sleep_interval_requests": 3,
}
with YoutubeDL(options) as downloader:
info = downloader.sanitize_info(downloader.extract_info(url, download=False))
record = {key: info.get(key) for key in (
"id", "webpage_url", "title", "channel_id", "duration", "upload_date"
)}
print(json.dumps(record, ensure_ascii=False, indent=2))
I campi extravi possono essere assenti o nulli. Utilizzare get() per metadati opzionali, e non presumere che ogni fonte abbia una durata, ID canale o una lista completa di formati. Un elenco di playlist piatto è anche diverso da un video completamente risoluto. Per una risposta pubblica, progettare solo i campi che intendi esponere.
Evitare un'estrazione dei metadati immediatamente seguita da un'estrazione di download identica per ogni fonte a meno che la tua applicazione non abbia bisogno del passo di pianificazione aggiuntivo. duplicata delle richieste di sorgente. Se hai bisogno di un lavoro duraturo, memorizza l'ID fonte e la politica di uscita; un URL di media firmato dai metadati non è un sostituto duraturo per la fonte originale.
Python Opzione di riferimento
| Compiti | Opzione Python | Dettagli |
|---|---|---|
| Il nome e la directory di uscita | "outtmpl": "downloads/%(id)s.%(ext)s" | Mantenere l'ID di fonte e l'estensione dinamica. |
| Il tetto di Hard 1080p | "format": "bv*[height<=1080]+ba/b[height<=1080]" | Permette codec di sorgente e fallisce se nessuno corrisponde al limite. |
| Metadati di Sido | "writeinfojson": True | Il metadato di estrazione completa è inserito accanto ai media. |
| Il checkpoint di ID | "download_archive": "archive.txt" | Un archivio per politica di produzione; non un inventario di controllo. |
| errori rigorosi | "ignoreerrors": False | Lascia che il chiamante registri i fallimenti invece di trattare i problemi post-processing come successo. |
| Il tempo di runtime | "js_runtimes": {"deno": {}} | Installare Deno nel lavoratore e rendere visibile il suo binario su PATH. |
| Impersonazione del browser | "impersonate": ImpersonateTarget() | Python equivalente di --impersonate=""; importare la classe target e installare curl-cffi. |
| Cookie esistenti | "cookiefile": "private/youtube-cookies.txt" | Utilizzare le credenziali sessioni private solo quando necessario per l'accesso. |
audio_options = {
"format": "ba",
"outtmpl": "audio/%(id)s.%(ext)s",
"postprocessors": [{
"key": "FFmpegExtractAudio",
"preferredcodec": "mp3",
"preferredquality": "192",
}],
}Video + audio + capzioni per un database AI
Utilizzare questa politica di uscita quando l'obiettivo è un set di dati di formazione piuttosto che la raccolta dell'esempio del lavoratore 1080p. richiede bestvideo e bestaudio, permette FFmpeg di fusione in MP4, e salva le capture e i metadati disponibili in inglese accanto ai media.
from yt_dlp import YoutubeDL
from yt_dlp.networking.impersonate import ImpersonateTarget
url = "https://www.youtube.com/watch?v=jNQXAC9IVRw"
options = {
"js_runtimes": {"deno": {}},
"impersonate": ImpersonateTarget(),
"noplaylist": True,
"format": "bestvideo+bestaudio/best",
"merge_output_format": "mp4",
"postprocessors": [{
"key": "FFmpegVideoRemuxer",
"preferedformat": "mp4",
}],
"outtmpl": "dataset/%(id)s/%(id)s.%(ext)s",
"writeinfojson": True,
"writesubtitles": True,
"writeautomaticsub": True,
"subtitleslangs": ["en"],
"subtitlesformat": "vtt/best",
"sleep_interval_requests": 2,
"sleep_interval_subtitles": 5,
"sleep_interval": 5,
"max_sleep_interval": 10,
"concurrent_fragment_downloads": 1,
"retries": 3,
"fragment_retries": 3,
}
with YoutubeDL(options) as downloader:
downloader.download([url])
ImpersonateTarget() seleziona qualsiasi target del browser disponibile, corrispondendo --impersonate="". Passare l'oggetto, non una riga vuota copiata dalla sintasi CLI. curl-cffi deve essere installato in questo ambiente Python. Deno continua a svolgere la risoluzione JavaScript; impersonazione non lo sostituisce.
MP4 è il contenitore di uscita; il video selezionato può ancora essere AV1 o VP9. Se il tuo decoder di formazione richiede H.264/AAC, applicare una politica esplicita di codec prima di unire o registrare un transcodio separato FFmpeg. I sottotitoli disponibili sono recuperati, non generati dal discorso.
| Dopo che i media finiscono | Cosa ha bisogno il registro dei dati |
|---|---|
| Scopri il finale MP4 con ffprobe | Video/audio codec, durata, dimensioni, percorso di file e conte byte. |
| Controlla le carattere laterali separatamente | Lingua, traccia supplied/automatic, timestamp e se il file esiste effettivamente. |
| Nessuna capienza di matching disponibile | Mantenere i media e segnalare il testo mancante; inviare l'audio alla fase di transcrizione se necessario. |
| Il cappello è stato colpito 429 | Retry caption retrieval dopo un IP cooldown con subtitle pacing; non ricaricare i media completati. |
Per un pacchetto, utilizzare un archivio separato per questa politica del set di dati e conservare un inventario per le pagine richieste. Non riutilizzare un precedente 1080p o solo archivio media: può scappare i video prima che le loro capture di nuova richiesta siano raccolte. Utilizzare after_move per la disponibilità dei media, quindi valutare testo e metadati prima di pubblicare un elemento completo del set di dati.
Scopri quando il file finale è pronto
Un progresso hook reporting status=finished significa un trasferimento terminato. FFmpeg può ancora essere necessario mescolare video e audio, convertire un file audio, o spostare la produzione. Un video solo in streaming raggiungendo 100% non è l'evento di completamento che la tua domanda dovrebbe pubblicare.
| Fase | Cosa sai | Stato di applicazione |
|---|---|---|
| Scarica | Arrivano alcuni byte di media. | Correndo |
| Trasferimento di HOK: finito | Questo trasferimento è finito; il trattamento può ancora essere seguito. | Il trattamento |
| after_move Il post-processore | Il file ha superato il post-processing configurato e il passo finale. | Il file locale pronto |
| Caricamento e controllo dell'integrità | Il tuo destinazione ha l'oggetto e la verifica registrata. | consegnato |
L'esempio completo qui sotto registra un PostProcessor personalizzato a after_move e legge info["filepath"] lì. Verifica che il file esiste e non è esente. Questo evita la ipotesi della estensione finale con prepare_filename(), che può riferirsi a un nome pre-conversione.
Sceneggiatura completa: singolo video lavoratore
Questo è il modo in cui download_video.py Accetta un ID video o watch/Shorts/live/embed URL e rifiuta l'ingresso playlist/channel. Ogni invocazione utilizza un’esempio YoutubeDL, ritorni di download limitati e un archivio locale. Un ripetuto ritorno di fonte completato è scappato invece di pretendere che un nuovo file sia stato creato.
import argparse
import json
import re
from pathlib import Path
from urllib.parse import parse_qs, urlparse
from yt_dlp import YoutubeDL
from yt_dlp.networking.impersonate import ImpersonateTarget
from yt_dlp.postprocessor.common import PostProcessor
from yt_dlp.utils import DownloadError, PostProcessingError
def watch_url(value):
"""Accept a video ID or a single YouTube video URL, never a playlist."""
video_id = value
if not re.fullmatch(r"[A-Za-z0-9_-]{11}", value):
parsed = urlparse(value)
parts = parsed.path.strip("/").split("/")
host = (parsed.hostname or "").lower()
if parsed.scheme not in {"http", "https"}:
raise ValueError("Use a YouTube watch URL or 11-character video ID")
if host in {"youtu.be", "www.youtu.be"}:
video_id = parts[0]
elif host in {"youtube.com", "www.youtube.com", "m.youtube.com"}:
if parsed.path == "/watch":
video_id = parse_qs(parsed.query).get("v", [""])[0]
elif len(parts) == 2 and parts[0] in {"shorts", "live", "embed"}:
video_id = parts[1]
else:
video_id = ""
else:
video_id = ""
if not re.fullmatch(r"[A-Za-z0-9_-]{11}", video_id):
raise ValueError("Expected one YouTube video, not a channel or playlist")
return "https://www.youtube.com/watch?v=" + video_id
class FinalFile(PostProcessor):
def __init__(self):
super().__init__()
self.result = None
def run(self, info):
path = Path(info["filepath"]).resolve()
if not path.is_file() or path.stat().st_size == 0:
raise PostProcessingError("Final media file is missing or empty")
self.result = {
"status": "completed", "video_id": info["id"],
"title": info.get("title"), "duration": info.get("duration"),
"path": str(path), "bytes": path.stat().st_size,
}
return [], info
def download_video(source, output="downloads"):
url = watch_url(source)
folder = Path(output).resolve()
folder.mkdir(parents=True, exist_ok=True)
final_file = FinalFile()
options = {
"js_runtimes": {"deno": {}},
"impersonate": ImpersonateTarget(),
"concurrent_fragment_downloads": 1,
"noplaylist": True,
"format": "bv*[height<=1080]+ba/b[height<=1080]",
"outtmpl": str(folder / "%(id)s.%(ext)s"),
"download_archive": str(folder / "archive.txt"),
"writeinfojson": True,
"ignoreerrors": False,
"retries": 3, "fragment_retries": 3, "socket_timeout": 30,
"sleep_interval_requests": 1,
"sleep_interval": 5, "max_sleep_interval": 10,
}
with YoutubeDL(options) as downloader:
downloader.add_post_processor(final_file, when="after_move")
downloader.extract_info(url, download=True)
if final_file.result is None:
return {"status": "skipped", "source": url,
"reason": "No new file recorded; check the archive"}
return {**final_file.result, "source": url}
if __name__ == "__main__":
parser = argparse.ArgumentParser()
parser.add_argument("source", help="YouTube video URL or ID")
parser.add_argument("--output", default="downloads")
args = parser.parse_args()
try:
result = download_video(args.source, args.output)
except (DownloadError, ValueError, OSError) as error:
raise SystemExit(f"Job failed: {error}") from error
print(json.dumps(result, ensure_ascii=False, indent=2))
python download_video.py "https://www.youtube.com/watch?v=jNQXAC9IVRw" --output downloadsIl record completato contiene l'URL canonico della fonte, l'ID video, la strada finale e la dimensione del byte. Un record scappato significa che non c'è alcun nuovo file finale di ritorno; conciliarlo contro l'archivio e l'inventario esistente se si richiede la prova che il file è ancora presente. L’archivio non verifica se un utente ha cancellato o spostato i media in seguito.
Catch DownloadError per errori extractor/download/post-processing, ValueError per input rifiutati e OSError per errori del sistema di file locale. Tratta queste classi come classi distinte nei tuoi log di applicazione. I messaggi di errore sono diagnostiche utili, ma il loro testo non è una tassonomia stabile e strutturata di ogni fallimento di YouTube.
Sceneggiatura completa: ripetibile batch worker
Inserisci download_batch.py accanto a download_video.py. Crea un UTF-8 urls.txt con un URL video o ID per linea. Questo funziona intenzionalmente in modo sequenziale, quindi un processo è di proprietà dell'archivio e del directory di uscita. Esso scrive un risultato completato, scappato o fallito per ogni tentativo di input e outs non zero quando qualsiasi elemento fallisce.
import argparse
import json
from datetime import datetime, timezone
from pathlib import Path
from yt_dlp.utils import DownloadError
from download_video import download_video
def run_batch(manifest, output):
folder = Path(output).resolve()
folder.mkdir(parents=True, exist_ok=True)
sources = list(dict.fromkeys(
line.strip()
for line in Path(manifest).read_text(encoding="utf-8-sig").splitlines()
if line.strip() and not line.lstrip().startswith("#")
))
counts = {"completed": 0, "skipped": 0, "failed": 0}
with (folder / "attempts.jsonl").open("a", encoding="utf-8") as log:
for source in sources:
try:
result = download_video(source, folder)
except (DownloadError, ValueError, OSError) as error:
result = {"source": source, "status": "failed",
"error_type": type(error).__name__, "error": str(error)}
result["recorded_at"] = datetime.now(timezone.utc).isoformat()
log.write(json.dumps(result, ensure_ascii=False) + "\n")
log.flush()
counts[result["status"]] += 1
return counts
if __name__ == "__main__":
parser = argparse.ArgumentParser()
parser.add_argument("manifest", help="UTF-8 file, one video URL or ID per line")
parser.add_argument("--output", default="collection")
args = parser.parse_args()
counts = run_batch(args.manifest, args.output)
print(json.dumps(counts, indent=2))
raise SystemExit(1 if counts["failed"] else 0)
python download_batch.py urls.txt --output collectionFlush dopo ogni record in modo che una interruzione non lascia ogni risultato bufferato fino alla fine. C'è ancora una piccola finestra tra la biblioteca che registra il suo archivio e la tua applicazione che scrive un record di tentativo. Se un incidente si colloca lì, il prossimo giro può segnalare scappato. Per un servizio, conciliare il filesystem/archive con una base di lavoro duratura invece di affermare che questo esempio di file di testo è transazionale.
Mantenere attempts.jsonl privato: gli errori possono includere i dettagli di fonte e richiesta. Rapporti i totali per stato, verifica gli elementi falliti e riproduce lo stesso manifesto dopo aver risolto un problema ambientale condiviso. Non aggiungere ogni ID fallito all'archivio di successo.
Produzione: coda, scadenza e storage
Youtube è sincronizzato. Eseguire direttamente all'interno di un blocco di web trader async che il loop degli eventi del trader; anche un thread offload non rende una richiesta del browser una vita adeguata per un grande download. Accettate il lavoro, persistete source/options e lasciate che un lavoratore produca un risultato finale.
- Crea un ID di lavoro duraturo prima di eseguire. memorizzare il canonico ID video, la politica di uscita, il numero di tentativo e la destinazione.
- Utilizzare directories di lavoro per lavoro e una piscina lavoratrice limitata. Non condividere un esempio YoutubeDL su posti di lavoro concorrenti.
- Utilizzare un processo separato quando si ha bisogno di un termine o cancellazione di un duro muro; socket_timeout limita le operazioni di rete individuali, non l'intero lavoro.
- Se esponendo input utente sopra HTTP, accettare i video supportati YouTube identificatori piuttosto che URL arbitrari, percorsi di uscita, argomenti di estrattore o scatti di scatto.
- Ricordare la disponibilità del file locale e la completione del cloud-upload separatamente; mantenere lo stato sufficiente per ritirare un upload senza scaricare di nuovo.
- Mantenere FFmpeg, tempo di esecuzione, yt-dlp e versioni di plugin con il vostro implementazione. Esercitare una piccola carica di lavoro conosciuta prima di sostituire un'immagine del lavoratore.
Una semplice piscina di lavoratori è un punto di partenza migliore rispetto a un'asyncio.gather non limitata chiama intorno a molti download. Coordinare il lavoro totale in tutto il processo; le impostazioni del sonno di ciascun download non regolano l'intero servizio. Mantenere un budget di ritiro separato per tentativi di lavoro in modo che le retrazioni di applicazione non moltiplicino il numero di ritiro del download.
Risolvere il problema del lavoratore Python
| Problematiche | Controlla |
|---|---|
| Lavori in CLI, falliscono in Python | Confronta le opzioni efficaci. YoutubeDL non carica automaticamente il file di configurazione CLI. |
| Il progresso dice finito, file mancanti | Utilizzare il limite after_move e controllare gli errori post-processing. |
| Ripetuto ritorno di fonte scappato | Leggi l'archivio della raccolta; utilizzare un archivio diverso quando si modifica la politica di uscita. |
| Il lavoratore si è impiccato più a lungo socket_timeout | Un lavoro può eseguire molti operations/retries. Aggiungi un termine di livello del processo se necessario. |
| 403 o il bot verifica sul server | Aggiornare di notte, controllare Deno, ridurre la concorrenza e testare un IP di uscita sostitutiva quando la rotta rimane rifiutata. |
| 429 in metadati / lavori di trascrizione | Parare l'IP colpito, le richieste di ritmo extraction/subtitle e aggiungere ritardamenti tra i metadati-solo lavori. |
Quando la produzione appartiene a un tubo cloud
Se si desidera possedere il download, i flussi di lavoro sopra ti danno il controllo sui file, i formati e il trattamento. Se la tua applicazione ha bisogno di media completati forniti al storage, FlashData fornisce posti di lavoro di download YouTube tracciati, bot di gestione, routing proxy e ritrazioni. La tua domanda presenta le impostazioni di fonte e di uscita, quindi mantiene l'ID di lavoro e il registro di consegna.