Lewati ke isi
ID
Dapatkan kunci API
Jelajahi dokumentasi

Panduan

API Python yt-dlp

Contoh Python yang bisa dijalankan untuk unduhan, metadata, set data AI, dan proses yang bisa dilanjutkan.

Di halaman ini

Menginstal perpustakaan Python

Dalam lingkungan Python 3.11+ Anda
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"

Tetapi juga instal Deno, FFmpeg dan ffprobe. Contoh-contoh ini berjalan secara lokal pada Linux, macOS atau Windows dan tidak memerlukan kunci API.

Download video pertama Anda

Download 1 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"])
Ini menulis media lokal sampai 1080p dan dapat menggabungkan arus terpisah. bekas output tergantung pada format sumber yang dipilih.

Seting CLI tidak diwarisi. Setkan Deno, impersonasi dan pacing dalam pilihan Python, bahkan ketika perintah terminal Anda sudah menggunakannya.

download() mengambil daftar URL dan mengembalikan kode status. extract_info(url, download=True) mengembalikan informasi ekstraksi serta melakukan download. Gunakan manajer konteks untuk menutup instansi dengan bersih, dan membuat instansi segar untuk pekerjaan independen daripada berbagi status yang berubah-ubah di seluruh rantai.

Baca Metadata Tanpa Media

Mengekspor rekaman metadata kecil
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))
download=False masih melakukan permintaan jaringan. sanitize_info membuat hasil JSON-kompatibel; ia tidak mengedit rahasia atau mengurangi hasil ke medan ini.

Lapangan yang dikeluarkan dapat tidak ada atau nol. Gunakan get() untuk metadata opsi, dan jangan menganggap setiap sumber memiliki durasi, ID saluran atau daftar format lengkap. Daftar playlist rata juga berbeda dari video yang sepenuhnya diselesaikan. Untuk jawaban publik, hanya menampilkan bidang yang ingin Anda temukan.

Hindari ekstraksi metadata dengan segera diikuti dengan ekstraksi download yang identik untuk setiap sumber kecuali aplikasi Anda membutuhkan langkah perencanaan tambahan. Ini menggandakan permintaan sumber. Jika Anda membutuhkan pekerjaan yang berkelanjutan, simpan ID sumber dan kebijakan output; URL media yang ditandatangani dari metadata tidak merupakan pengganti yang berkelanjutan untuk sumber asli.

Pilihan Python

TugasPilihan PythonDetail
Daftar dan nama filen"outtmpl": "downloads/%(id)s.%(ext)s"Simpan ID sumber dan ekstensi dinamis.
Ketebalan langit-langit 1080p"format": "bv*[height<=1080]+ba/b[height<=1080]"Memungkinkan kodek sumber dan gagal jika tidak sepadan dengan batas.
Metadata sidecar"writeinfojson": TrueMengetik total ekstraksi metadata di samping media.
Titik verifikasi lengkap"download_archive": "archive.txt"Satu file per kebijakan output; bukan inventory check-in.
Kesalahan yang ketat"ignoreerrors": FalseBiarkan panggilan merekam kegagalan bukannya memperlakukan masalah post-processing sebagai keberhasilan.
Menggunakan Runtime"js_runtimes": {"deno": {}}Instal Deno di pekerja dan membuat binarynya terlihat pada PATH.
Imperasi browser"impersonate": ImpersonateTarget()Python setara dengan --impersonate=""; impor kelas sasaran dan menginstal curl-cffi.
File cookie yang ada"cookiefile": "private/youtube-cookies.txt"Gunakan pengesahan sesi pribadi hanya ketika diperlukan untuk akses.
MP3 Pilihan Konversi
audio_options = {
    "format": "ba",
    "outtmpl": "audio/%(id)s.%(ext)s",
    "postprocessors": [{
        "key": "FFmpegExtractAudio",
        "preferredcodec": "mp3",
        "preferredquality": "192",
    }],
}
Pass audio_options to YoutubeDL. Post-processor FFmpeg berkonversi ke target bitrate 192 kbps; itu tidak meningkatkan kualitas asal sumber.

Video + audio + captions untuk set data AI

Gunakan kebijakan output ini ketika tujuan adalah set data pelatihan dan bukannya koleksi contoh pekerja 1080p. itu membutuhkan bestvideo dan bestaudio, membiarkan FFmpeg menggabungkan mereka ke MP4, dan menyimpan captions dan metadata bahasa Inggris yang tersedia di samping media.

Satu item set data dalam Python
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])
Permintaan FFmpeg/ffprobe, Deno dan instalasi malam [default,curl-cffi] Parameter format favorit remuxer dipaparkan dengan cara itu dalam API yt-dlp.

ImpersonateTarget() memilih target browser yang tersedia, sesuai dengan --impersonate="". Lakukan objek, bukan string kosong yang disalin dari sintax CLI. curl-cffi harus dipasang di lingkungan Python ini. Deno masih menjalankan penyelesaian JavaScript; impersonasi tidak menggantikannya.

MP4 adalah konten output; video yang dipilih masih bisa menjadi AV1 atau VP9. Jika dekoder pelatihan Anda membutuhkan H.264/AAC, gunakan kebijakan kode ekspres sebelum menggabungkan atau merekam transcode FFmpeg yang terpisah. Subtitle yang tersedia diambil, tidak dihasilkan dari ucapan.

Setelah media selesaiApa yang diperlukan oleh rekaman data
Lihatlah yang terakhir MP4 dengan ffprobeVideo/audio codec, durasi, dimensi, jalur file dan byte count.
Periksa sidecars secara terpisahBahasa, supplied/automatic track, timestamp dan apakah file itu sebenarnya ada.
Tidak ada captions yang tersediaTetap media dan tanda teks hilang; mengirim audio ke tahap transcription Anda jika diperlukan.
Keterangan yang ditunjukkan 429Retry caption retrieval setelah IP sejuk dengan subtitle pacing; jangan download ulang media yang selesai.

Untuk satu set, gunakan arkib terpisah untuk kebijakan set data ini dan simpan inventori untuk halaman yang diperlukan. Jangan menggunakan ulang 1080p sebelumnya atau media-hanya arkib: itu mungkin melepaskan video sebelum capsi yang baru dikehendaki mereka dikumpulkan. Gunakan after_move untuk persiapan media, kemudian validasi teks dan metadata sebelum menerbitkan item set data lengkap.

Ketahui kapan file akhir siap

Status = selesai berarti transfer selesai. FFmpeg mungkin masih perlu untuk menggabungkan video dan audio, menukar file audio, atau memindahkan output. Sebuah video-hanya streaming mencapai 100% bukan peristiwa penyelesaian aplikasi Anda harus menerbitkan.

TahapApa yang Anda KetahuiNegara Aplikasi
DownloadBeberapa media byte sudah tiba.Berlari
Transfer Hook: selesaiTransfer ini selesai; pemrosesan masih dapat diikuti.Pemrosesan
after_move Pengaturan prosesorFile telah melewati post-processing yang dikonfigurasi dan langkah akhir.File lokal siap
Upload dan Integrity CheckDestinasi Anda memiliki objek dan verifikasi yang tercatat.disampaikan

Contoh lengkap di bawah ini mencatat PostProcessor tersuai di after_move dan membaca info["filepath"] di sana. Ia memeriksa bahwa file itu ada dan tidak terisi. Ini menghindari meneka perpanjangan akhir dengan prepare_filename(), yang dapat merujuk pada nama pre-konversi.

Script lengkap: seorang pekerja video tunggal

Dan jadikanlah itu sebagai download_video.py. Ini menerima ID video atau watch/Shorts/live/embed URL dan menolak input playlist/channel. Setiap invoicing menggunakan satu contoh YoutubeDL, retries download terbatas dan sebuah koleksi-lokal arkib. Kembali kembali sumber yang berulang-ulang selesai terlepas dari berpura-pura file baru dibuat.

download_video.py
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))
Skrip penuh juga tersedia dari link download di atas. ia hanya memiliki output lokal; tambahkan cek dekoding dan upload rekaman di tahap berikutnya aplikasi Anda.
Lakukan satu pekerjaan
python download_video.py "https://www.youtube.com/watch?v=jNQXAC9IVRw" --output downloads

Rekor yang selesai mengandung URL sumber kanonik, ID video, jalur akhir dan ukuran byte. Rekod yang terhapus berarti tidak ada panggilan kembali file akhir baru; menyelaraskannya terhadap arkib dan inventori yang ada jika Anda membutuhkan bukti bahwa file masih ada. Arsip itu sendiri tidak memeriksa apakah pengguna kemudian menghapus atau memindahkan media.

Catch DownloadError for extractor/download/post-processing failure, ValueError for rejected input dan OSError for local file system failure. Perlakukan ini sebagai kelas yang berbeda dalam log aplikasi Anda. Pesan kesalahan adalah diagnosis yang berguna, tetapi teks mereka tidak menjadi taksonomi terstruktur yang stabil dari setiap kegagalan YouTube.

Script lengkap: pengembara batch yang dapat dipulihkan

Masukkan download_batch.py di samping download_video.py. Buat UTF-8 urls.txt dengan satu URL video atau ID per baris. Ini sengaja berjalan secara seperinci, sehingga satu proses dimiliki oleh direktori arkib dan output. Ini menulis hasil yang selesai, terlepas atau gagal untuk setiap percobaan input dan outs nonzero ketika item gagal.

download_batch.py
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)
Tambahan-hanya attempts.jsonl menjaga retries sebagai percobaan terpisah. garis duplikat dalam manifest dihapus; file download mengendalikan ID lengkap di sepanjang lintasan.
Lakukan atau mengembalikan batch yang sama
python download_batch.py urls.txt --output collection

Flush setelah setiap rekaman sehingga perhentian tidak meninggalkan setiap hasil buffer sampai akhir. Masih ada jendela kecil antara perpustakaan yang merekam arsipnya dan aplikasi Anda menulis rekaman percobaan. Jika kecelakaan melanda di sana, ronde berikutnya dapat melaporkan terlepas. Untuk layanan, konsolidasi filesystem/archive dengan database pekerjaan yang berkelanjutan bukannya menuntut contoh file teks ini adalah transaksional.

Tetap attempts.jsonl pribadi: kesalahan dapat mencakup sumber dan permintaan detail. melaporkan total berdasarkan status, memeriksa item yang gagal, dan memainkan manifest yang sama setelah menyelesaikan masalah lingkungan yang dikongsi. Jangan menambahkan setiap ID yang gagal ke arsip keberhasilan.

Produksi: kue, deadlines dan penyimpanan

YoutubeD adalah sinyal. Menggunakannya langsung di dalam blok web trader async yang menghubungkan acara trader; bahkan thread offload tidak membuat permintaan browser hidup yang sesuai untuk download besar. Mengadopsi pekerjaan, bertahan source/options, dan biarkan pekerja menghasilkan hasil akhir.

  • Mencipta ID pekerjaan yang berkelanjutan sebelum pelaksanaan. menyimpan ID video kanonik, kebijakan output, nomor percobaan dan tujuan.
  • Gunakan direktori kerja per pekerjaan dan kolam pekerja terbatas.Jangan berbagi contoh YoutubeDL di seluruh pekerjaan yang bersaing.
  • Gunakan proses yang terpisah ketika Anda membutuhkan waktu waktu atau pembatalan jam dinding keras; socket_timeout membatasi operasi jaringan individu, bukan seluruh pekerjaan.
  • Jika mengeksposkan input pengguna di atas HTTP, menerima pengenal video YouTube yang disokong daripada URL arbitrary, jalur output, argumen ekstraktor atau snippets shell.
  • Rekam kesiapannya file lokal dan penyelesaian upload awan secara terpisah; tetap cukup status untuk menarik kembali upload tanpa muat turun lagi.
  • Tetap FFmpeg, runtime, yt-dlp dan plugin versi dengan pengembangan Anda. Latih beban kerja kecil yang diketahui sebelum menggantikan gambar pekerja.

Kolam kerja sederhana adalah titik awal yang lebih baik daripada asyncio.gather panggilan tanpa batas di sekitar banyak download. Koordinasi total kerja di seluruh proses; pengaturan tidur setiap download tidak mengatur seluruh layanan. Tetaplah anggaran penarikan yang terpisah untuk upaya kerja sehingga penarikan aplikasi tidak berbilang jumlah penarikan sendiri dari downloader.

Menyelesaikan masalah dengan pekerja Python

MasalahPeriksa
Kegiatan di CLI, gagal di PythonYoutubeDL tidak secara otomatis memuat file konfigurasi CLI Anda.
Keterlambatan kata selesai, file hilangGunakan batas after_move dan periksa kesalahan post-proses.
Kembali Kembali Kembali Kembali Kembali KembaliBaca arsip koleksi; gunakan arsip yang berbeda saat mengubah kebijakan output.
Pekerja menggantung lebih lama dari socket_timeoutSebuah pekerjaan dapat melakukan banyak operations/retries. Tambah waktu waktu tingkat proses jika perlu.
403 atau bot memeriksa pada serverUpdate malam, periksa Deno, mengurangi konversi dan menguji IP output pengganti ketika rute tetap ditolak.
429 dalam Metadata / Transcript pekerjaanBerhenti IP yang terjejas, permintaan tempo extraction/subtitle dan tambahkan keterlambatan antara metadata-hanya pekerjaan.

Ketika output tergolong dalam saluran awan

Jika Anda ingin memiliki download, aliran kerja di atas memberi Anda kontrol atas file, format dan pemrosesan. Jika aplikasi Anda membutuhkan media lengkap yang disimpan, FlashData menyediakan pekerjaan download YouTube yang diikuti, pengendalian bot, routing proxy dan retries. Aplikasi Anda mengajukan pengaturan sumber dan output, kemudian menyimpan ID pekerjaan dan catatan pengiriman.