# yt-dlp の Python API

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

キャニシニカル参照: https://flashdata.dev/ja/docs/guides/yt-dlp-python-api
レビュー: FlashData による 2026-11-13

- [Python から始める](https://flashdata.dev/ja/docs/guides/yt-dlp-python-api/reference.md#first-call) — インストールして1つの通話を作成する
- [最終ファイルを検索](https://flashdata.dev/ja/docs/guides/yt-dlp-python-api/reference.md#completion) — 転送・処理後
- [ワーカーを手に入れ](https://flashdata.dev/ja/docs/guides/yt-dlp-python-api/reference.md#worker) — ダウンロード ダウンロード .py
- [コレクションを処理](https://flashdata.dev/ja/docs/guides/yt-dlp-python-api/reference.md#batch) — ソースによる結果と回復

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

## Python ライブラリの設定


**Python 3.11+ 環境**

```bash
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"
```

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

- [外部依存の設置](https://flashdata.dev/ja/docs/guides/how-to-use-yt-dlp/reference.md#install)
- [Upstream インベンテーション 参照](https://github.com/yt-dlp/yt-dlp#embedding-yt-dlp)

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

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


**1 動画をダウンロード**

```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"])
```

これは、地元メディアを 1080p まで書き込み、別々のストリームを合併することができます。

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

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

> **Python オプションは、旗の機械的な翻訳ではありません。**
> --write-info-json 地図を書き込み、 --no-playlist 地図を noplaylist に。オーディオ変換は、ポストプロセッサリストを使用します。YoutubeDL のパラメータードキュメンタリーまたはアップストリーム cli_to_api.py アシスタントを調べる代わりにオプション名を推測します。

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

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


**メタデータの小型レコードを輸出**

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

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

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

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

## 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変換の選択肢**

```python
audio_options = {
    "format": "ba",
    "outtmpl": "audio/%(id)s.%(ext)s",
    "postprocessors": [{
        "key": "FFmpegExtractAudio",
        "preferredcodec": "mp3",
        "preferredquality": "192",
    }],
}
```

audio_options を YoutubeDL に移行します. FFmpeg ポストプロセッサは 192 kbps のターゲットビットレートに変換されます; ソースのオリジナルの品質を向上させません。

- [Python パラメーター参照](https://github.com/yt-dlp/yt-dlp/blob/master/yt_dlp/YoutubeDL.py)
- [CLI オプションを Python オプションに変換する](https://github.com/yt-dlp/yt-dlp/blob/master/devscripts/cli_to_api.py)

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

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


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

**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])
```

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 トラック、タイムスタンプ、ファイルが実際に存在するかどうか。 |
| 合計キャプチャは利用できません。 | メディアを保持し、テキストが欠けていることをマークし、必要に応じて音声をトランスクリプションステージに送信します。 |
| キャプテン ヒット 429 | Retry caption retrieval after an IP cooldown with subtitle pacing; 完成したメディアを再ダウンロードしないでください。 |

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

- [CLIレシピとデータセットのリスト](https://flashdata.dev/ja/docs/guides/how-to-use-yt-dlp/reference.md#dataset)
- [PACE Python メタデータとキャプション](https://flashdata.dev/ja/docs/guides/yt-dlp-429-too-many-requests/reference.md#python)

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

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


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

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

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

> **完成したローカルダウンロードは、完成したクラウド配達ではありません。**
> 次のステップがファイルをアップロードする場合は、アップロード状態を別々に保持します. ダウンロードアーカイブは、以前のアップロードが失敗した場合でも、次のラウンドでソースを切り離すことができます. 保存された地元のファイルと仕事の記録からアップロードを取り戻します。

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

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


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

- [ダウンロード 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))
```

完全なスクリプトは上記のダウンロードリンクから利用できます. 地元の出力のみを所有しています; アプリケーションの次の段階で解読チェックを追加し、アップロードレコードを追加します。

**1 仕事を走る**

```bash
python download_video.py "https://www.youtube.com/watch?v=jNQXAC9IVRw" --output downloads
```

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

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

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

## 原題:REVIEWABLE BATCH WORKER


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

- [ダウンロード 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)
```

追加のみ attempts.jsonl は、別々の試みとしてリトリウムを保持します. マニス内の複数のラインが削除されます; ダウンロードアーカイブは、ルーンを通して完成IDを処理します。

**同じバッチを再起動または再起動**

```bash
python download_batch.py urls.txt --output collection
```

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

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

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

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


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

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

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

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

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


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

- [403 診断作業流](https://flashdata.dev/ja/docs/guides/yt-dlp-403-forbidden/reference.md)
- [セッションとボットチェックワークフロー](https://flashdata.dev/ja/docs/guides/yt-dlp-sign-in-not-a-bot/reference.md)
- [429回復とPythonパッキング](https://flashdata.dev/ja/docs/guides/yt-dlp-429-too-many-requests/reference.md)
- [保存されたメディアをチェック](https://flashdata.dev/ja/docs/guides/how-to-use-yt-dlp/reference.md#verify)

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

## 生産が雲管に属する場合


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

- [2 操作モデルを比較する](https://flashdata.dev/ja/docs/guides/flashdata-vs-yt-dlp/reference.md)
- [YouTube 動画の一括ダウンロード](https://flashdata.dev/ja/products/youtube-download#bulk-downloads)
- [ダウンロードデモを試してみる](https://flashdata.dev/ja/products/youtube-download#playground)
- [ダウンロード API 参照](https://flashdata.dev/ja/docs/sources/youtube_download/reference.md)
