コンテンツへスキップ
JA
APIキーを取得する
ドキュメントを探す

ガイド

yt-dlp の Python API

ダウンロード、メタデータ、AI データセット、中断後に再開できるワーカーの実行例を紹介します。

このページの内容

Python ライブラリの設定

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

Deno、FFmpeg、 ffprobe をインストールすることもできます。 これらの例は Linux、macOS、Windows でローカルで実行され、API キーは必要ありません。

最初の動画をダウンロード

1 動画をダウンロード
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"])
これは、地元メディアを 1080p まで書き込み、別々のストリームを合併することができます。

CLI 設定は相続されていません. Deno、パイソン オプションのインパクション、パッキングを設定する場合でも、ターミナルコマンドがすでにそれらを使用している場合でも。

download() は URL のリストを取得し、状態コードを返します. extract_info(URL、ダウンロード=True) は、抽出情報とダウンロードを実行することも返します。コンテキストマネージャーを使用して、例を清潔に閉じ、独立した仕事のための新鮮な例を作成する代わりに、線を通じて変動状態を共有します。

メディアなしでメタデータを読む

メタデータの小型レコードを輸出
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 はまだネットワークリクエストを実行しています. sanitize_info は結果を JSON に互換性をもたらします. 秘密を編集したり、結果をこれらのフィールドに削減したりしません。

抽出されたフィールドは、欠席またはゼロである可能性があります。選択肢のメタデータのために get() を使用し、すべてのソースが長さ、チャンネル ID 、または完全なフォーマットリストを持っていると仮定しないでください。フラットプレーリストリストは、完全に解析されたビデオとは異なります。公開の回答には、展示する予定のフィールドのみをプロジェクトします。

メタデータ抽出を避け、それぞれのソースに同じダウンロード抽出を伴うメタデータ抽出を直ちに避ける、アプリケーションが追加の計画ステップを必要としない限り。源要請を複製する。持続可能な仕事が必要な場合は、ソースIDと出力ポリシーを保存し、メタデータからサインされたメディアURLは、オリジナルのソースの持続可能な代わりではありません。

Python オプション参照

タスクPython オプション詳細
出力ディレクトリとフィレンマ"outtmpl": "downloads/%(id)s.%(ext)s"ソースIDとダイナミック拡張子を保持します。
ハード 1080p 屋根"format": "bv*[height<=1080]+ba/b[height<=1080]"ソースコデックが許可され、制限に合わない場合に失敗します。
メタデータサイド"writeinfojson": Trueメディアに加えて完全な抽出メタデータをキップします。
チェックポイント 完了"download_archive": "archive.txt"1 出力ポリシーごとにアーカイブ、チェックインインベンチャーではない。
厳格なミス"ignoreerrors": Falseプロセッサ後の問題を成功として扱う代わりに、通話者に失敗を記録させます。
Deno・ランティム"js_runtimes": {"deno": {}}Denoをワーカーにインストールし、そのバイナリーをPATHで目に見えるようにします。
ブラウザのインパルソン"impersonate": ImpersonateTarget()ピートン等式は --impersonate=""; ターゲットクラスをインポートし、 curl-cffi をインストールします。
既存のCookieファイル"cookiefile": "private/youtube-cookies.txt"アクセスに必要な場合にのみプライベートセッション認証を使用します。
MP3変換の選択肢
audio_options = {
    "format": "ba",
    "outtmpl": "audio/%(id)s.%(ext)s",
    "postprocessors": [{
        "key": "FFmpegExtractAudio",
        "preferredcodec": "mp3",
        "preferredquality": "192",
    }],
}
audio_options を YoutubeDL に移行します. FFmpeg ポストプロセッサは 192 kbps のターゲットビットレートに変換されます; ソースのオリジナルの品質を向上させません。

ビデオ + オーディオ + キャプション AI データセット

この出力ポリシーを使用すると、目標はワーカーの例の1080pコレクションの代わりにトレーニングデータセットです。それはベストビデオと bestaudioを要求し、FFmpegがそれらをMP4に融合させ、メディアに加えて利用可能な英語キャプションとメタデータを保存します。

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])
FFmpeg/ffprobe、Deno と夜間の [デフォルト、curl-cffi] インストールが必要です. リムクサーの好みのフォーマットパラメーターは yt-dlp の API でそのように表示されます。

ImpersonateTarget() は、利用可能なブラウザのターゲットを選択し、 --impersonate="" に合致します。オブジェクトを通過し、CLI合成からコピーされた空っぽのストレッチではありません。 curl-cffi はこの Python 環境にインストールする必要があります。DenoはまだJavaScriptを解決する機能を実行していますが、インパルソングはそれを置き換えることはありません。

MP4は出力コンテナであり、選択したビデオはまだAV1または VP9であることがあります。トレーニングデコードが H.264/AAC を必要とする場合は、合併する前に明確なコデックポリシーを適用または別々の FFmpeg トランスコードを記録します。利用可能なサブタイトルは、スピーチから生成されず、取り戻されます。

メディアが終わった後データセット記録が必要なもの
最後のMP4を ffprobe でチェックするVideo/audioコデック、長さ、次元、ファイルパスとバイット数。
チェックイン サイドカラー 別々に言語、 supplied/automatic トラック、タイムスタンプ、ファイルが実際に存在するかどうか。
合計キャプチャは利用できません。メディアを保持し、テキストが欠けていることをマークし、必要に応じて音声をトランスクリプションステージに送信します。
キャプテン ヒット 429Retry caption retrieval after an IP cooldown with subtitle pacing; 完成したメディアを再ダウンロードしないでください。

バッチの場合は、このデータセットポリシーのための別々のアーカイブを使用し、必要なサイドカバーのためのリストを保存します。以前の 1080p またはメディアのみのアーカイブを再利用しないでください: 彼らの新しく要求されたキャプションが収集される前にビデオをスキャンする可能性があります。メディアの準備のために after_move を使用して、完全なデータセット項目を公開する前に、テキストとメタデータを確認します。

最終ファイルがいつ準備が整ったか知る

進歩ホーク報告状態=完成は、転送が完了することを意味します。FFmpeg まだビデオとオーディオを融合し、オーディオファイルを変換したり、出力を移動する必要があるかもしれません。ビデオだけのストリームが 100% に到達することは、あなたのアプリケーションが公開するべき完成イベントではありません。

ステージあなたが知っていること応用国
ダウンロードメディアバイトがいくつか来ています。走る
トランスフォーマット:終了この転送は終了しました;処理はまだ続くことができます。処理
after_move プロセッサファイルは、構成されたプロセッサ後と最終動きを通過しました。地元ファイル準備
アップロード・整合チェック目的地には、オブジェクトと記録された確認があります。配達

以下の完全な例では、カスタマイズされた PostProcessor を after_move に登録し、そこで info["filepath"] を読み取ります。ファイルが存在するか、無効であるかを確認します。これは、最終的な拡張子を prepare_filename() で推測することを避け、これは事前変換名を参照することができます。

シングル・ビデオ・ワーカー(Single Video Worker)

これを download_video.py として保存します。ビデオIDまたは watch/Shorts/live/embed URL を受け入れ、 playlist/channel 入力を拒否します。各招待状には、YouTubeDLの例、制限ダウンロードリトリ、収集・ローカル・アーカイブが1つ使用されます。新しいファイルが作成されたと仮定する代わりに、繰り返し完成したソースの返信が切り落とされます。

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))
完全なスクリプトは上記のダウンロードリンクから利用できます. 地元の出力のみを所有しています; アプリケーションの次の段階で解読チェックを追加し、アップロードレコードを追加します。
1 仕事を走る
python download_video.py "https://www.youtube.com/watch?v=jNQXAC9IVRw" --output downloads

完成した記録には、カノニックソースURL、ビデオID、最終パス、バイトサイズが含まれています。スカップされたレコードは、新しい最終ファイルの呼び出しが行われていないことを意味します; ファイルがまだ存在していることを証明する必要がある場合は、アーカイブと既存のレコードに対してそれを調和します。ファイルだけでは、ユーザーがそのメディアを削除または移動したかどうかを確認しません。

キャッチ ダウンロードエラー extractor/download/post-processing エラー、 拒否された入力のための ValueError と 地元のファイルシステムのエラーのための OSError を取得します。これらをアプリケーションのログで別々のクラスとして扱います。エラーメッセージは有用な診断ですが、そのテキストは、YouTubeのすべての失敗の安定した構造化されたタクソノミーではありません。

原題:REVIEWABLE BATCH WORKER

download_batch.py を download_video.py と同じディレクトリに置きます。UTF-8 の urls.txt を作成し、動画 URL または ID を 1 行ずつ記入します。アーカイブと出力先は 1 つのプロセスで管理するため、処理は順次実行されます。試行したすべての入力について完了、スキップ、失敗のいずれかを記録し、失敗した項目があればゼロ以外の終了コードを返します。

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)
追加のみ attempts.jsonl は、別々の試みとしてリトリウムを保持します. マニス内の複数のラインが削除されます; ダウンロードアーカイブは、ルーンを通して完成IDを処理します。
同じバッチを再起動または再起動
python download_batch.py urls.txt --output collection

各記録の後にフラッシュして、中断はすべての結果を終わりまでバッファーするわけではありません。図書館がそのアーカイブを記録し、アプリが試み記録を書く間に小さな窓があります。事故が発生した場合、次のラウンドはスカイプされたことを報告することができます。サービスの場合、このテキストファイルの例を主張する代わりに、持続可能な作業データベースと filesystem/archive を調和することは、取引性です。

プライベートを保つ attempts.jsonl:エラーはソースとリクエストの詳細を含むことができます. 状態によって総数を報告し、失敗した項目を検証し、共有環境問題を解決した後に同じマニュアルを再生します. 成功アーカイブに失敗したIDを追加しないでください。

生産: クイーン、期限及び保管

YoutubeDLは同期性です。オペレーターのイベントループをブロックするアシンクウェブトレーダーの内部に直接実行する; ストレッチオフロードさえも、ブラウザのリクエストは大きなダウンロードのために適切な寿命を作ることはありません。仕事を受け入れ、その源/選択肢を継続し、ワーカーが最終的な結果を生み出すことを許す。

  • 実行前に持続可能な仕事IDを作成します. 動画ID、出力ポリシー、試用番号、目的地を保存します。
  • 仕事ごとに作業ディレクトリと限定ワーカープールを使用します. 競合する職場でYouTubeDLの例を共有しないでください。
  • ハードウォール時計の期限またはキャンセルが必要な場合、別々のプロセスを使用する; socket_timeout 個々のネットワーク操作を制限し、仕事全体を制限します。
  • ユーザーの入力を HTTP 以上に表示する場合、任意の URL、出力パス、抽出論文、またはシェルスニッペットの代わりにサポートされた YouTube ビデオ ID を受け入れる。
  • 地元のファイル準備とクラウドアップロードの完了を別々に記録し、再ダウンロードなしにアップロードをリリースするのに十分な状態を保ちます。
  • あなたのデポレーションで FFmpeg、実行時間、 yt-dlp およびプラグインのバージョンを保持します. ワーカーのイメージを置き換える前に、知られている小さな作業負荷を実行します。

シンプルなワーカープールは、無制限の asyncio.gather が多くのダウンロードを呼び出すよりも、より良い出発点です。プロセス全体の作業を調整する; 各ダウンロードの睡眠設定は、サービス全体を規制しない。仕事の試みのために別々の退職予算を保持するので、応募退職はダウンロード者の自らの退職数を倍増しない。

パイソンワーカーを解決する

問題の問題インフォメーション
仕事はCLIで、Pythonで失敗YoutubeDL は自動的に CLI 設定ファイルをロードしません。
ファイルがなくなり、ファイルが終わる。使用する after_move 限界と処理後のエラーを検証します。
繰り返し返品 回転収集アーカイブを読み、出力ポリシーを変更する際に別のアーカイブを使用します。
socket_timeout より長く吊るされるワーカー仕事は多くのことを実行することができます operations/retries. 必要に応じてプロセスレベルの期限を追加します。
403またはボットがサーバーでチェック夜間更新、Denoをチェックし、競争力を減らし、ルートが拒否されるときに代替出力IPをテストします。
429 in メタデータ / トランスクリプト 仕事影響を受けたIP、ペースextraction/subtitleのリクエストを停止し、メタデータだけの仕事の間で遅延を追加します。

生産が雲管に属する場合

ダウンロードを所有したい場合は、上記のワークフローは、ファイル、フォーマット、および処理をコントロールします。アプリケーションが完全にメディアをストレージに提供する必要がある場合は、FlashDataは、YouTubeのダウンロード作業、ボット処理、プロキシルーティング、リトリを追跡します。アプリケーションはソースと出力設定を提出し、その後、仕事IDと配達記録を保持します。