yt-dlpとPython

🎬 Pythonでyt-dlpを強化する: 地理的バイパス、バッチダウンロード、プロキシローテーション

⚠️ 免責事項: 私はBright Dataやこの記事で言及されている他のサービスとは無関係です。すべてのツールは技術的なメリットに基づいて独立して評価されました。

TL;DR

yt-dlpはPythonでのプログラムによるビデオダウンロードの金標準です。その組み込みの --proxy オプションにより、住宅プロキシの統合が簡単になります。そして、スケールで地理的に制限されたコンテンツに確実にアクセスする必要がある場合、大規模な住宅プロキシネットワーク（Bright Dataのような）を使用することが最も効果的なアプローチです。この記事では、yt-dlpをPythonに埋め込む方法、フォーマットの処理、IPのローテーション、プロダクション対応のバッチダウンローダーの構築について説明します。 完全なMermaidダイアグラムを参照してください。
Pythonでのyt-dlp使用の完全なダイアグラム

yt-dlpとは何か（そしてなぜyoutube-dlに取って代わったのか）

yt-dlpは、現在停滞している youtube-dl のコミュニティメンテナンスされたフォークで、現在149k+ GitHubスターと1,500+貢献者を持っています（github.com/yt-dlp/yt-dlp）。YouTubeだけでなく、数千のサイトをサポートし、重要な改善点を追加しています：よりスマートなフォーマットソート、SponsorBlock統合、マルチスレッドのフラグメントダウンロード、クリーンなPython埋め込みAPI。2026年に youtube-dl や pytube をまだ使用しているなら、パフォーマンスと信頼性を失っています。

yt-dlpとその依存関係のインストール

yt-dlpは**Python 3.10+**を必要とし、別々のビデオ/オーディオストリームをマージするために ffmpeg を強く推奨します。

pip install "yt-dlp[default]"

[default] の追加により、 certifi , brotli , websockets , requests , pycryptodomex がインストールされます — すべて堅牢なダウンロードに必要です。ブラウザの偽装（いくつかのサイトでTLSフィンガープリンティングを回避するため）には、 curl-cffi を追加します：

pip install "yt-dlp[default,curl-cffi]"

ffmpegは別にインストールします（ ffmpeg という名前のPythonパッケージをインストールしないでください — それは別のものです）：

# macOS
brew install ffmpeg
# Ubuntu/Debian
sudo apt install ffmpeg

Pythonにyt-dlpを埋め込む: 基本

yt-dlpは YoutubeDL クラスを通じてクリーンなPython APIを公開しています。オプション辞書を渡し、 .download() を呼び出します。

import yt_dlp
# Basic download - best quality, auto-merge
ydl_opts = {
    'format': 'bestvideo+bestaudio/best',
    'merge_output_format': 'mp4',
    'outtmpl': '%(title)s [%(id)s].%(ext)s',  # default naming template
}
with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    ydl.download(['https://www.youtube.com/watch?v=BaW_jenozKc'])

with ブロックは、ダウンローダーのコンテキストが適切にクリーンアップされることを保証します。常に使用してください。

フォーマット選択: 正確に必要なものを取得する

yt-dlpのフォーマットセレクターは、その最も強力な機能の1つです。デフォルト（ bv*+ba/b ）は、最良のビデオストリームを選択し、最良のオーディオとマージしますが、正確に指定することができます。

ydl_opts = {
    # Best video up to 1080p, paired with best audio
    'format': 'bestvideo[height<=1080]+bestaudio/best[height<=1080]',
    'merge_output_format': 'mp4',
}

オーディオのみの抽出（例：ポッドキャストのアーカイブ、音楽）：

ydl_opts = {
    'format': 'm4a/bestaudio/best',
    'postprocessors': [{
        'key': 'FFmpegExtractAudio',
        'preferredcodec': 'mp3',
        'preferredquality': '192',
    }],
    'outtmpl': '%(uploader)s - %(title)s.%(ext)s',
}

ダウンロードせずにメタデータを抽出する

時には、ビデオ情報 — タイトル、長さ、利用可能なフォーマット、アップロード日が必要です。 extract_info を使用し、 download=False を指定します。

import json
import yt_dlp

URL = 'https://www.youtube.com/watch?v=BaW_jenozKc'

with yt_dlp.YoutubeDL({}) as ydl:
    info = ydl.extract_info(URL, download=False)
    # sanitize_info makes the dict JSON-serializable
    clean = ydl.sanitize_info(info)
print(f"Title: {clean['title']}")
print(f"Duration: {clean['duration']}s")
print(f"Uploader: {clean['uploader']}")
print(f"Views: {clean['view_count']:,}")

これは、メタデータパイプラインを構築したり、大量ダウンロードの前にコンテンツを事前チェックするのに役立ちます。

本当の問題: レート制限と地理的制限

ここがほとんどのチュートリアルが止まるところであり、実際の使用が難しくなるところです。
問題1 — レート制限。 YouTubeのようなプラットフォームは、同じIPからの繰り返しリクエストを検出し、スロットリングまたはブロックします。スケールで、単一のIPはすぐに制限に達します。
問題2 — 地理的制限。 多くのビデオコンテンツは地域によってロックされています。yt-dlpの組み込みの --xff ヘッダー偽装は、いくつかのケースで役立ちますが、信頼性が低く、簡単に検出されます。

# yt-dlp's built-in geo-bypass (unreliable for most modern sites)
ydl_opts = {
    'geo_bypass': True,
    'geo_bypass_country': 'US',
}

正直な答え: ヘッダー偽装は、ターゲット地域の実際のIPを経由することの代わりにはなりません。 プラットフォームはミスマッチを検出するのが得意です。

プロキシソリューション: yt-dlpがプロキシを処理する方法

yt-dlpは一級のプロキシサポートを提供しています。 proxy オプションはHTTP、HTTPS、またはSOCKS5のURLを受け入れます（ここに文書化されています）：

ydl_opts = {
    'proxy': 'http://user:password@proxy-host:port',
    # For geo-verification only (some sites require this):
    'geo_verification_proxy': 'http://user:password@proxy-host:port',
}

専用の geo_verification_proxy オプションもあります — このプロキシは、地理的に制限されたサイトのIP位置を確認するために特に使用され、実際のダウンロードトラフィックは別のルートを通過できます。

なぜ住宅プロキシなのか？（そしてなぜ無料プロキシではないのか）

プロキシは、その背後にあるIPの良さに依存します。ここが核心のトレードオフです：

プロキシタイプ	検出リスク	スピード	地理的精度
無料/公共	非常に高い	悪い	なし
データセンター	中〜高	高速	限定的
住宅	低	良好	精密
ISP（静的住宅）	低	非常に高速	精密
無料プロキシはこのユースケースには行き止まりです。彼らは過剰に使用され、すべての主要なプラットフォームによってフラグされ、信頼性がありません。データセンタープロキシはより良いですが、洗練されたボット検出を持つサイトではブロックされます。住宅プロキシは、実際の消費者デバイス — 実際の家庭、実際のISPを通じてトラフィックをルーティングします。YouTubeの観点から見ると、リクエストはその場所からブラウジングしている通常のユーザーと同じに見えます。これが、データセンタープロキシが機能しない場所で機能する理由です。

Bright Data住宅プロキシの設定

いくつかの住宅プロキシプロバイダーを評価した結果、Bright Dataは、このユースケースに関連するいくつかの具体的な理由で際立っています：

150M+の住宅IPが195か国にわたって存在 — 回転に重要な最大のプール
HTTP/SおよびSOCKS5サポート — yt-dlpは両方をネイティブにサポート
国、都市、ZIP、ASNレベルのターゲティング — 特定の地域からコンテンツが必要な場合に便利
99.95%の成功率と約0.7秒の応答時間
倫理的に調達された — ピアは明示的にオプトインし、報酬が支払われます（コンプライアンスに重要）
クレジットカード不要の無料トライアルでテスト可能
Bright Data住宅プロキシのプロキシURL形式は次のとおりです：

http://brd-customer-[CUSTOMER_ID]-zone-residential:[PASSWORD]@brd.superproxy.io:33335

CUSTOMER_ID 、ゾーン名、 PASSWORD は、住宅プロキシゾーンを作成した後にBright Dataダッシュボードから取得します。

Bright Dataとの基本的なyt-dlp統合

import yt_dlp
# Bright Data residential proxy credentials
BD_CUSTOMER_ID = "your_customer_id"
BD_PASSWORD = "your_password"
BD_ZONE = "residential"  # your zone name

PROXY_URL = (
    f"http://brd-customer-{BD_CUSTOMER_ID}-zone-{BD_ZONE}:"
    f"{BD_PASSWORD}@brd.superproxy.io:33335"
)

ydl_opts = {
    'format': 'bestvideo[height<=1080]+bestaudio/best',
    'merge_output_format': 'mp4',
    'proxy': PROXY_URL,
    'outtmpl': 'downloads/%(title)s [%(id)s].%(ext)s',
}
with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    ydl.download(['https://www.youtube.com/watch?v=BaW_jenozKc'])

すべてのリクエストは現在、実際の住宅IPを通じてルーティングされます。Bright Dataは各新しい接続でIPを自動的にローテーションします — 基本的なローテーションのための追加の設定は必要ありません。

地理ターゲットダウンロード: 地域制限されたコンテンツへのアクセス

特定の国に制限されたコンテンツをダウンロードするには、その国のIPをターゲットにしてBright Dataの国コードパラメータを使用します：

import yt_dlp
BD_CUSTOMER_ID = "your_customer_id"
BD_PASSWORD = "your_password"
# Route through a US residential IP
PROXY_URL = (
    f"http://brd-customer-{BD_CUSTOMER_ID}-zone-residential-country-us:"
    f"{BD_PASSWORD}@brd.superproxy.io:33335"
)
ydl_opts = {
    'format': 'best',
    'proxy': PROXY_URL,
    # Also use as geo-verification proxy
    'geo_verification_proxy': PROXY_URL,
    'outtmpl': 'downloads/%(title)s.%(ext)s',
}
with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    ydl.download(['https://www.example-geo-restricted-site.com/video'])

ゾーンユーザー名の`-country-us`サフィックスは、Bright Dataにリクエストを米国ベースの住宅IPを通じてルーティングするよう指示します。`us`を任意のISO 3166-1 alpha-2国コード — `gb`, `de`, `jp`, `br`などに置き換えることができます。

プロダクション対応のバッチダウンローダーとプロキシローテーション

以下は、実際にプロダクションで使用するようなより完全なスクリプトです。複数のURLを処理し、失敗時には再試行し、ロギングを追加し、ダウンロードごとに国ターゲットプロキシをローテーションします：

import yt_dlp
import logging
import time
from pathlib import Path
# --- Configuration ---
BD_CUSTOMER_ID = "your_customer_id"
BD_PASSWORD = "your_password"
OUTPUT_DIR = Path("downloads")
OUTPUT_DIR.mkdir(exist_ok=True)
# Rotate through different country IPs for each download
TARGET_COUNTRIES = ["us", "gb", "de", "fr", "au"]
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(message)s"
)
logger = logging.getLogger(__name__)
def get_proxy_url(country: str) -> str:
    """Build a country-targeted Bright Data residential proxy URL."""
    return (
        f"http://brd-customer-{BD_CUSTOMER_ID}"
        f"-zone-residential-country-{country}:"
        f"{BD_PASSWORD}@brd.superproxy.io:33335"
    )

def build_ydl_opts(proxy_url: str) -> dict:
    """Return yt-dlp options with the given proxy."""
    return {
        "format": "bestvideo[height<=1080]+bestaudio/best",
        "merge_output_format": "mp4",
        "proxy": proxy_url,
        "geo_verification_proxy": proxy_url,
        "outtmpl": str(OUTPUT_DIR / "%(uploader)s - %(title)s [%(id)s].%(ext)s"),
        "retries": 5,
        "fragment_retries": 5,
        "ignoreerrors": False,
        "quiet": False,
        "no_warnings": False,
        "sleep_interval": 2,  # seconds between requests
        "max_sleep_interval": 5,
    }

def download_with_retry(url: str, max_retries: int = 3) -> bool:
    """Attempt to download a URL, rotating proxy country on each retry."""
    for attempt, country in enumerate(TARGET_COUNTRIES[:max_retries]):
        proxy_url = get_proxy_url(country)
        logger.info(f"Attempt {attempt + 1}/{max_retries} - proxy country: {country.upper()}")
        try:
            with yt_dlp.YoutubeDL(build_ydl_opts(proxy_url)) as ydl:
                error_code = ydl.download([url])
                if error_code == 0:
                    logger.info(f"✓ Successfully downloaded: {url}")
                    return True
                else:
                    logger.warning(f"Download returned error code {error_code}")
        except yt_dlp.utils.DownloadError as e:
            logger.error(f"DownloadError on attempt {attempt + 1}: {e}")
            time.sleep(2 ** attempt)  # exponential backoff

logger.error(f"✗ All retries exhausted for: {url}")
return False

def batch_download(urls: list[str]) -> dict[str, bool]:
"""Download a list of URLs, returning a success/failure map."""
results = {}
for i, url in enumerate(urls, 1):
logger.info(f"[{i}/{len(urls)}] Processing: {url}")
results[url] = download_with_retry(url)
time.sleep(1) # brief pause between items
return results

--- Main ---

if name == "main":
VIDEO_URLS = [
"https://www.youtube.com/watch?v=BaW_jenozKc",
# Add more URLs here
]
results = batch_download(VIDEO_URLS)
print("\n--- Download Summary ---")
for url, success in results.items():
status = "✓ OK" if success else "✗ FAILED"
print(f"{status}: {url}")

このスクリプトは以下を行います:
- 各リトライでターゲット国を変更します（つまり、ジオロックされたビデオが米国からアクセスできない場合、GB、DEなどを順に試します）
- リトライ間で指数バックオフを使用します
- すべてをクリーンにログ化します
- 関心の分離を行います — プロキシ設定、yt-dlp設定、およびダウンロードロジックはすべて独立した関数です

### Bright Data Python SDKに関する注意
Bright Dataは、彼らのスクレイピングおよび検索APIをラップする[公式Python SDK](https://github.com/brightdata/sdk-python) (`` `pip install brightdata-sdk` ``)も公開しています。Amazon製品のスクレイピング、Google検索の実行、LinkedInデータの抽出などのユースケースにぴったりで、クリーンで型指定されたPythonインターフェースを提供しています。

**yt-dlpのユースケースに特化して言えば、このSDKは必要ありません。** yt-dlpは内部で独自にHTTPリクエストを管理し、単にプロキシURLストリングを必要とするだけです。この場合、SDKのスクレイピング層ではなく、直接使用するべきBright Data製品は**Residential Proxy**（またはISPプロキシ）ネットワークです。SDKは構造化されたWebデータを扱うデータパイプラインの構築時に輝きます。それは異なる用途のための異なるツールです。

### 長セッションのためのISPプロキシ
非常に長いビデオをダウンロードしたり、プレイリスト全体を通して安定したセッションを維持する必要がある場合（セッション中にIPが回転することが問題となる場合）、Bright Dataの**ISPプロキシ**を検討してください。

ISPプロキシは**静的な住宅IP**です — 実際のISP（Comcast、BT、Deutsche Telekomなど）に関連付けられており、明示的に新しいものをリクエストしない限り回転しません。これにより、住宅用IPの正当性とデータセンタープロキシの安定性を兼ね備えることができます。

# ISP proxy — static, no mid-session rotation
ISP_PROXY_URL = (
    f"http://brd-customer-{BD_CUSTOMER_ID}-zone-isp:"
    f"{BD_PASSWORD}@brd.superproxy.io:33335"
)

ydl_opts = {
    'format': 'best',
    'proxy': ISP_PROXY_URL,
    'outtmpl': 'downloads/%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s',
}

# Download an entire playlist without IP rotation interruptions
with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    ydl.download(['https://www.youtube.com/playlist?list=PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re'])

プログレスフックとカスタムロガーの追加

長時間のダウンロードでは、進捗状況を確認したくなるでしょう。yt-dlpはカスタムロガーとプログレスフックをサポートしています:

```python
import yt_dlp

class MinimalLogger:
    def debug(self, msg):
        if not msg.startswith('[debug]'):
            print(msg)

    def info(self, msg): print(msg)
    def warning(self, msg): print(f"[WARN] {msg}")
    def error(self, msg): print(f"[ERROR] {msg}")

def progress_hook(d: dict):
    if d['status'] == 'downloading':
        pct = d.get('_percent_str', 'N/A')
        speed = d.get('_speed_str', 'N/A')
        print(f"\r  Downloading: {pct} at {speed}", end='', flush=True)
    elif d['status'] == 'finished':
        print(f"\n  Done: {d['filename']}")

PROXY_URL = "http://brd-customer-YOUR_ID-zone-residential:PASSWORD@brd.superproxy.io:33335"

ydl_opts = {
    'format': 'bestvideo+bestaudio/best',
    'merge_output_format': 'mp4',
    'proxy': PROXY_URL,
    'logger': MinimalLogger(),
    'progress_hooks': [progress_hook],
}

with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    ydl.download(['https://www.youtube.com/watch?v=BaW_jenozKc'])

年齢制限されたコンテンツのためのクッキーの取り扱い

一部のコンテンツでは認証が必要です。yt-dlpは、ブラウザからクッキーを直接読み込むことができます:

```python
ydl_opts = {
    'format': 'best',
    'proxy': PROXY_URL,
    # Load cookies from Chrome (also supports firefox, edge, safari, brave, etc.)
    'cookiesfrombrowser': ('chrome', None, None, None),
    # OR use a Netscape-format cookies file:
    # 'cookiefile': 'cookies.txt',
}

`cookiesfrombrowser`オプションは、`(browser, keyring, profile, container)`のタプルを受け取ります — デフォルトには`None`を指定します。これにより、クッキーを手動で管理することなく、yt-dlpがログイン済みのブラウザセッションとして認証できます。

主なポイント

yt-dlpは2026年におけるPythonでのプログラムによるビデオダウンロードの正しいツールです — サイトサポートと信頼性において他に匹敵するものはありません。
yt-dlpの`proxy` オプションを使えば、特別なライブラリなしで任意のプロキシにトラフィックをルートできます。
無料のプロキシは失敗するでしょう。 住宅プロキシ — 実際のISPデバイスからのIP — は、地理的制限やレート制限されたコンテンツをスケールで扱うための唯一の信頼できる解決策です。
Bright DataのResidential Proxiesは、150M+ IP、国/都市/ZIPレベルのターゲティング、HTTP/SとSOCKS5のサポートを提供し、無料トライアルもあるので、この特定のユースケースに最も実用的なオプションです。
ISPプロキシは、安定していて回転しないIPが必要なとき（例: 長いプレイリストのダウンロード時）に使用します。
Bright Data Python SDKは素晴らしいツールですが、異なるユースケースのためのものであり、yt-dlpをプロキシに接続するものではありません。
常に指数バックオフを使ったリトライロジックとリクエスト間のスリープ間隔を本番環境で追加してください。

リソース

yt-dlp GitHubリポジトリ — 完全なドキュメント、すべてのオプション
yt-dlpネットワークオプション — `--proxy`, `--geo-verification-proxy`, など
Bright Data Residential Proxies — 無料トライアル、価格情報、ドキュメント
Bright Dataプロキシドキュメント — 接続形式、設定
Bright Data Python SDK — スクレイピング/検索APIのユースケース向け
yt-dlp埋め込み例 — 公式Python埋め込みガイド

この記事のすべてのコードは、yt-dlpの公式ドキュメントとBright Dataのプロキシドキュメントに基づいて作成および検証されています。Bright Dataやその他のサービスと提携していません。