# API Python yt-dlp

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

Referensi kanonikal: https://flashdata.dev/id/docs/guides/yt-dlp-python-api
Diulang: 2026-11-13 oleh FlashData

- [Mulai dengan Python](https://flashdata.dev/id/docs/guides/yt-dlp-python-api/reference.md#first-call) — Berhubung dan membuat satu panggilan
- [Temukan file terakhir](https://flashdata.dev/id/docs/guides/yt-dlp-python-api/reference.md#completion) — Setelah pemindahan dan pemrosesan
- [Dapatkan Pekerja](https://flashdata.dev/id/docs/guides/yt-dlp-python-api/reference.md#worker) — Download .Py yang dapat diunduh
- [Mengatur sebuah koleksi](https://flashdata.dev/id/docs/guides/yt-dlp-python-api/reference.md#batch) — Hasil Per Sumber dan Pemulihan

<a id="setup"></a>

## Menginstal perpustakaan Python


**Dalam lingkungan Python 3.11+ Anda**

```bash
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.

- [Mengatur ketergantungan eksternal](https://flashdata.dev/id/docs/guides/how-to-use-yt-dlp/reference.md#install)
- [Upstream referensi](https://github.com/yt-dlp/yt-dlp#embedding-yt-dlp)

<a id="first-call"></a>

## Download video pertama Anda


**Download 1 video**

```python
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.

> **Pilihan Python bukan terjemahan mekanis bendera**
> --write-info-json peta untuk menulisinfojson; --no-playlist peta untuk noplaylist. Audio Conversion menggunakan postprocessor list. Periksa dokumen parameter YoutubeDL atau pembantu upstream cli_to_api.py bukannya meneka nama opsi.

<a id="metadata"></a>

## Baca Metadata Tanpa Media


**Mengekspor rekaman metadata kecil**

```python
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.

<a id="options"></a>

## Pilihan Python


| Tugas | Pilihan Python | Detail |
| --- | --- | --- |
| 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": True | Mengetik 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": False | Biarkan 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**

```python
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.

- [Perbedaan Parameter Python](https://github.com/yt-dlp/yt-dlp/blob/master/yt_dlp/YoutubeDL.py)
- [Konversi opsi CLI ke opsi Python](https://github.com/yt-dlp/yt-dlp/blob/master/devscripts/cli_to_api.py)

<a id="dataset"></a>

## 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**

```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 selesai | Apa yang diperlukan oleh rekaman data |
| --- | --- |
| Lihatlah yang terakhir MP4 dengan ffprobe | Video/audio codec, durasi, dimensi, jalur file dan byte count. |
| Periksa sidecars secara terpisah | Bahasa, supplied/automatic track, timestamp dan apakah file itu sebenarnya ada. |
| Tidak ada captions yang tersedia | Tetap media dan tanda teks hilang; mengirim audio ke tahap transcription Anda jika diperlukan. |
| Keterangan yang ditunjukkan 429 | Retry 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.

- [CLI resep dan inventori data](https://flashdata.dev/id/docs/guides/how-to-use-yt-dlp/reference.md#dataset)
- [Pace Python Metadata dan Captions](https://flashdata.dev/id/docs/guides/yt-dlp-429-too-many-requests/reference.md#python)

<a id="completion"></a>

## 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.

| Tahap | Apa yang Anda Ketahui | Negara Aplikasi |
| --- | --- | --- |
| Download | Beberapa media byte sudah tiba. | Berlari |
| Transfer Hook: selesai | Transfer ini selesai; pemrosesan masih dapat diikuti. | Pemrosesan |
| after_move Pengaturan prosesor | File telah melewati post-processing yang dikonfigurasi dan langkah akhir. | File lokal siap |
| Upload dan Integrity Check | Destinasi 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.

> **Sebuah download lokal yang selesai bukanlah penyampaian awan yang selesai**
> Jika langkah berikutnya memuat file, tetaplah status upload secara terpisah.Arsip download dapat melepas sumber pada rute berikutnya bahkan ketika upload sebelumnya gagal.

<a id="worker"></a>

## 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 dari download_video.py](https://flashdata.dev/examples/yt-dlp/download_video.py)

**download_video.py**

```python
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**

```bash
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.

<a id="batch"></a>

## 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 dari download_batch.py](https://flashdata.dev/examples/yt-dlp/download_batch.py)

**download_batch.py**

```python
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**

```bash
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.

<a id="service"></a>

## 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.

<a id="diagnostics"></a>

## Menyelesaikan masalah dengan pekerja Python


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

- [403 Diagnosis aliran kerja](https://flashdata.dev/id/docs/guides/yt-dlp-403-forbidden/reference.md)
- [Sesi dan proses kerja bot-check](https://flashdata.dev/id/docs/guides/yt-dlp-sign-in-not-a-bot/reference.md)
- [429 pemulihan dan Python pacing](https://flashdata.dev/id/docs/guides/yt-dlp-429-too-many-requests/reference.md)
- [Periksa Media yang Diselamatkan](https://flashdata.dev/id/docs/guides/how-to-use-yt-dlp/reference.md#verify)

<a id="managed-downloads"></a>

## 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.

- [Perbandingan dua model operasi](https://flashdata.dev/id/docs/guides/flashdata-vs-yt-dlp/reference.md)
- [Unduhan massal video YouTube](https://flashdata.dev/id/products/youtube-download#bulk-downloads)
- [Coba download demo](https://flashdata.dev/id/products/youtube-download#playground)
- [Download referensi API](https://flashdata.dev/id/docs/sources/youtube_download/reference.md)
