İçeriğe geç
TR
API anahtarı al
Belgeleri incele

Kılavuzlar

yt-dlp Python API'si

İndirmeler, meta veriler, yapay zekâ veri kümeleri ve sürdürülebilir işler için çalıştırılabilir Python örnekleri.

Bu sayfada

Python Kütüphanesi'ni kurun

Python 3.11+ çevresinde
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"

Ayrıca Deno, FFmpeg ve ffprobe yükleme. Bu örnekler Linux, macOS veya Windows'ta yerel olarak çalışır ve API anahtarına gerek yoktur.

İlk videoyu indirin

1 video indirmek
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"])
Bu, yerel medyayı 1080p'ye kadar yazar ve ayrı akımları birleştirebilir. çıkış konteynerinin seçilen kaynak biçimlerine bağlıdır.

CLI ayarları miras alınmaz. Python seçeneklerinde Deno, kişiselleştirme ve paketleme ayarları ayarlayın, hatta terminal komutunuz zaten bunları kullanırsa bile.

download() URL'lerin bir listesini alır ve bir durum kodu iade eder. extract_info(url, download=True) çıkarma bilgileri yanı sıra indirmeyi gerçekleştirir. Bir bağlam yöneticisi kullanarak örnekleri temiz bir şekilde kapatın ve bağımsız bir iş için taze bir örnek oluşturun, değiştirilebilir durumun çizgiler üzerinden paylaşılmasını değil.

Metadata Media olmadan okuyun

Küçük Metadata Kayıtları
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 hala ağ istekleri gerçekleştirir. sanitize_info sonucu JSON uyumlu hale getirir; sırları yazmaz veya sonuçları bu alanlara düşürmez.

Çekilen alanlar eksik veya sıfır olabilir. Seçmeli metadata için get() kullanın ve her kaynağın bir süresi, kanal kimliği veya tam bir format listesi olduğunu varsaymayın. Bir düz bir oynatma listesi ayrıca tamamen çözülmüş bir video ile farklıdır. Bir kamu yanıt için, yalnızca ortaya çıkmayı planladığınız alanları projesi yapın.

Her kaynağa eşdeğer bir indirme ekstraksiyonu ile hemen takip edilen bir metadata çıkarılmasını önleyin, eğer uygulamanızın ek planlama adımına ihtiyaç duymadığı sürece. Kaynak taleplerini çoğaltır. Sürdürülebilir bir işe ihtiyacınız varsa, kaynak kimliğini ve çıkış politikalarını kaydedin; metadata'dan bir imzalanan medya URL'si orijinal kaynağın kalıcı bir yedek değildir.

Python Opsiyon Referansları

Görev Görev GöreviPython seçeneğiDetaylı
Çıkış dizin ve filename"outtmpl": "downloads/%(id)s.%(ext)s"Kaynak kimliğini ve dinamik uzantıyı tutun.
Sert 1080p Çatı"format": "bv*[height<=1080]+ba/b[height<=1080]"Kaynak kodekleri ve bozukluklar eşleşmezse başarısız olur.
Metadata Sıfır"writeinfojson": TrueMetadata ek olarak tam metadata çıkarır.
Tamamlanmış ID kontrol noktası"download_archive": "archive.txt"Bir arşiv, bir çıkış politikası; bir kontrol ücreti değil.
Sıkı hatalar"ignoreerrors": FalseÇağrıcı başarısızlıkları başarı olarak işleme sonrası sorunları ele almak yerine kaydeder.
Deno Runtime İlanları"js_runtimes": {"deno": {}}Deno'yu işçi içinde kurun ve ikili PATH'da görülebilir hale getirin.
Browser İsposyon"impersonate": ImpersonateTarget()Python eşdeğer --impersonate="; hedef sınıfı ithal ve yükleme curl-cffi.
Mevcut Cookie Dosyası"cookiefile": "private/youtube-cookies.txt"Özel oturum kimliklerini yalnızca erişim için gerekli olduğunda kullanın.
MP3 Dönüşüm seçenekleri
audio_options = {
    "format": "ba",
    "outtmpl": "audio/%(id)s.%(ext)s",
    "postprocessors": [{
        "key": "FFmpegExtractAudio",
        "preferredcodec": "mp3",
        "preferredquality": "192",
    }],
}
audio_options YoutubeDL'ye geçin. FFmpeg post-processor bir hedef bitrate dönüştürür 192 kbps; kaynağın orijinal kalitesini iyileştirmez.

Video + ses + bir AI veri kümesi için çekimler

Bu çıkış politikası kullanın, hedef bir eğitim veri kümesi değil, örneğin işçi koleksiyonu 1080p. en iyi video ve bestaudio gerektirir, FFmpeg bunları MP4 birleştirmesine izin verir ve mevcut İngilizce çekimleri ve metadata medyanın yanında kaydedilir.

Python'da bir veri kümesi öğesi
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])
İhtiyacınız olan FFmpeg/ffprobe, Deno ve gece [default,curl-cffi kurulumudur. Remüxer'ın tercih edilen format parametresi yt-dlp API'sinde bu şekilde oynanır.

ImpersonateTarget() herhangi bir mevcut tarayıcı hedefi seçer, eşleşen --impersonate="". CLI sintaxinden kopyalanmış boş bir çubuk değil, nesneyi geçin. curl-cffi bu Python ortamında yüklen olmalıdır. Deno hala JavaScript çözme işlemini yapar; impersonation bunu değiştirmez.

MP4 çıkış konteyneridir; seçilen video hala AV1 veya VP9 olabilir. Eğitim dekoderinizin H.264/AAC gerektirmesi durumunda, birleşmeden veya ayrı bir FFmpeg transkod kaydetmeden önce açık bir kodlama politikası uygulayın. Mevcut alt başlıklar alınır, konuşma tarafından üretilmez.

Medya bittikten sonraBilgi kayıtlarının neye ihtiyacı var
Sonuçları inceleyin MP4 ile ffprobeVideo/audio kodekler, süresi, boyutları, dosya yolu ve byte sayımı.
Soru: Soruşturma sayfaları ayrıDil, supplied/automatic iz, zaman çubuğu ve dosyanın gerçekten var olup olmadığı.
Hiçbir eşleşen kapak mevcutMedyayı tutun ve eksik metin işaretleyin; gerekirse transcription aşamasına ses gönderin.
Kapsüller vurdu 429Retry caption, bir IP soğutma ile alt başlık paketleme sonrası geri çekilme; tamamlanmış medyayı yeniden indirmeyin.

Bir paket için, bu veri kümesi politikası için ayrı bir arşiv kullanın ve gerekli yan çubuklar için bir arşiv tutun. Daha önceki 1080p veya sadece medya arşivi tekrar kullanmayın: yeni istenen çekimleri toplanacak önce videoları kaydırabilir. Medya hazırlığı için after_move kullanın, sonra metin ve metadata bir tam veri kümesi öğesi yayınlamadan önce doğrulayın.

Son dosya ne zaman hazır olduğunu bilmek

Bir ilerleme kaynağı raporlama durumu = bitmiş bir transfer bitmiş anlamına gelir. FFmpeg hala video ve ses birleştirmek, bir ses dosyasını dönüştürmek veya çıkış hareket etmek gerekebilir. Sadece bir video akışı ulaşmak 100% tamamlanma etkinliği değil, başvuru yayınlamak gerekir.

Aşama Aşama AşamaNe biliyorsunUygulama Devleti
İndirmekBazı medya baytları geliyor.koşmak
Transfer Hook: TamamlandıBu transfer sona erdi; işlem hala devam edebilir.İşleme
after_move İşlemci SonrasıDosya, yapılandırılmış post-processing ve nihai hareketini geçti.Yerel dosya hazır
Yükleme ve bütünlük kontrolüAmaçınızın nesnesi ve kaydedilen doğrulama var.teslimat

Aşağıdaki tam örnek, after_move'de özelleştirilmiş bir PostProcessor kaydeder ve orada info["filepath"] okuyar. Dosyanın var olup olmadığını kontrol eder ve boşaltılmamıştır. Bu, prepare_filename(), bir önceki dönüşüm adı ile son uzantıyı tahmin etmeyi önler.

Tam Script: Tek Video Çalışanı

Bu durumun kaybı download_video.py olarak yapılır. Video ID veya watch/Shorts/live/embed URL'yi kabul eder ve playlist/channel girişini reddeder. Her çağrı tek bir YoutubeDL örneği, sınırlı indirme retries ve bir koleksiyon-yerel arşivi kullanır. Yeni bir dosya oluşturulduğunu iddia etmek yerine tekrarlanan tamamlanmış kaynak geri dönüşleri kayboldu.

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))
Tam senaryo yukarıdaki indirme bağlantısından da mevcuttur. sadece yerel çıkışa sahiptir; uygulamanızın bir sonraki aşamasında dekodasyon kontrolleri ve yükleme kayıtları ekleyin.
1 iş yapın
python download_video.py "https://www.youtube.com/watch?v=jNQXAC9IVRw" --output downloads

Tamamlanan kayıt, kanonik kaynak URL, video ID, son yol ve byte boyutu içerir. Bir kayıp kayıt, yeni bir son dosya arama geri dönüşü çalışmaması anlamına gelir; dosyanın hala mevcut olduğuna dair kanıt gerektirirse, dosyayı ve mevcut kayıtlara karşı uyum sağlar. Arşiv yalnızca bir kullanıcı daha sonra medyayı silip veya taşınmış olup olmadığını kontrol etmez.

extractor/download/post-processing hataları için DownloadError, reddedilen giriş için ValueError ve yerel dosya sisteminin hataları için OSError yakalanır. Bu türleri uygulama logunuzda ayrı sınıflar olarak ele alın. Hata mesajları yararlı bir teşhistir, ancak metinleri her YouTube başarısızlığının istikrarlı ve yapılandırılmış bir taksonomi değildir.

Tam Script: Yeniden Yapılabilir Batch İşçi

download_batch.py ile birlikte download_video.py ile birlikte indirin. Bir satır başına bir video URL veya ID ile bir UTF-8 urls.txt oluşturun. Bu kasıtlı olarak sırasıyla çalışır, bu nedenle bir süreç arşiv ve çıkış dizinine sahiptir. Her giriş ve çıkış için tamamlanmış, kaybolan veya başarısız bir sonuç yazar, herhangi bir öğe başarısız olduğunda sıfır değildir.

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)
Ek-sadece attempts.jsonl ayrı denemeler olarak geri çekilmeyi tutar. manifesto içinde çifte çizgiler kaldırılır; indirme arşivi, koşu boyunca tamamlanmış kimlikleri işler.
Aynı batch'ı tekrar veya tekrar çalıştırın
python download_batch.py urls.txt --output collection

Her kayıttan sonra kaydırın, böylece bir kesinti her sonuç sonuna kadar boğaz bırakmaz. Kütüphane arşivini kaydeder ve uygulamanız bir deneme kaydı yazar arasında küçük bir pencere var. Eğer bir kaza orada yer alırsa, bir sonraki tur kaybolmuş rapor olabilir. Bir hizmet için, bu metin dosyası örneğinin ticaret olduğunu iddia etmek yerine kalıcı bir iş veritabanı ile filesystem/archive uyum sağlar.

attempts.jsonl özel tutun: hatalar kaynak ve isteği ayrıntıları içerebilir. durumuna göre toplamları rapor, başarısız öğeleri kontrol ve ortak bir çevre sorunu çözüldükten sonra aynı manifesto yeniden oynatın. başarısız kimliği başarı arşivine eklemeyin.

Üretim: çubuk, zamanlama ve depolama

YoutubeDL senkronize edilmiştir. Doğrudan bir async web tüccar blokları içinde çalıştırmak, tüccarın etkinlik yuvarlaklığı; hatta bir çubuk offload bir tarayıcı isteği büyük bir indirme için uygun bir ömür yapmaz. İşin kabul edilmesi, kaynağı / seçenekleri devam eder ve bir işçinin nihai sonucu üretmesine izin verir.

  • Uygulamadan önce kalıcı bir iş kimliği oluşturun. kanonik video kimliği, çıkış politikası, deneme numarası ve varış noktası kaydedilir.
  • İşe bağlı çalışma dizinleri ve sınırlı bir işçi havuzu kullanın. YoutubeDL örneğini eşdeğer işler arasında paylaşmayın.
  • Sert duvar saatleri veya iptal için bir zaman dilimi veya iptal gerektiğinde ayrı bir süreç kullanın; socket_timeout bireysel ağ operasyonlarını sınırlar, tüm iş değil.
  • Kullanıcı girişlerini HTTP üzerinden sergilerseniz, istenmeyen URL'ler, çıkış yolları, ekstraktör argümanları veya shell snippets yerine destekli YouTube video tanımlayıcılarını kabul edin.
  • Yerel dosya hazırlığını ve bulut yükleme tamamlanmasını ayrı ayrı kaydedin; yeniden indirme olmadan bir yüklemeyi geri çekmek için yeterli durum tutun.
  • FFmpeg, çalışma süresi, yt-dlp ve eklenti sürümlerini yerleştirmenizle birlikte tutun. işçi görüntüsünü değiştirmeden önce bilinen küçük bir çalışma yükü uygulayın.

Basit bir işçi havuzu, sınırsız asyncio.gather'ın birçok indirme çağrısından daha iyi bir başlangıç noktasıdır. Süreçler boyunca toplam çalışmayı koordine edin; her indirme cihazının uyku ayarları tüm hizmetleri düzenlemez. İş girişimleri için ayrı bir geri dönüş bütçesini tutun, böylece başvuru geri dönüşleri indirmeci kendi geri dönüş sayısını çoğaltmaz.

Python İşçilerinin Sorunları Çözmek

Problem Sorun Problem Problem ProblemKontrol
CLI'de Çalışma, Python'da BaşarısızlıkYoutubeDL otomatik olarak CLI yapılandırma dosyanızı yüklemez.
Gelişmeler bitti, dosya eksikafter_move sınırını kullanın ve işleme sonrası hataları kontrol edin.
tekrarlanan kaynak geri dönüşü kaybolduToplama arşivi okuyun; çıkış politikalarını değiştirirken farklı bir arşiv kullanın.
İşçi daha uzun asılıdır socket_timeoutBir iş birçok iş yapabilir operations/retries. Gerekirse bir süreç düzeyinde bir tarih ekleyin.
403 veya robot sunucu üzerinde kontrolGece güncelleştirme, Deno kontrol, rekabet azaltmak ve yoldan reddedildiğinde bir yedek çıkış IP test.
429 metadata / transcript işlerindeEtkili IP'leri durdurun, hız extraction/subtitle talepleri ve metadata-sadece işler arasında gecikmeler ekleyin.

Bir bulut tüpüne ait olduğunda

İndiricinin sahibi olmak istiyorsanız, yukarıdaki çalışma akışları dosya, biçim ve işleme kontrolü sağlar. Uygulamanızın depolama için teslim edilen tamamlanmış medya ihtiyacı varsa, FlashData izlenmiş YouTube indirme işleri, bot işleme, proxy yönlendirme ve geri çekilme sağlar. Başvuru kaynağı ve çıkış ayarlarını sunar, sonra iş kimliği ve teslimat kayıtlarını tutar.