video-download

動画ダウンロードスキル

YouTube のボット対策チャレンジに自動で対処しながら、yt-dlp をラップします。

ツール

scripts/download.py — 初回実行時に yt-dlp をインストールし、動画と音声を MP4 に結合します。ボット検出時は戦略を自動で切り替え、安全に再開できるようダウンロードアーカイブを使用します。

ワークフロー

1. ユーザーのリクエストからすべての URL を集めます。
2. 出力先ディレクトリを決定します（指定がない場合は現在の作業ディレクトリ）。
3. 単一動画モードとプレイリストモードのどちらを使うか決めます。
   • ユーザーが「この動画」や「単一の URL」と指定した場合 → デフォルトのまま（単一動画）。
   • ユーザーが「プレイリスト」や「すべての動画」と指定した場合、または playlist?list= URL を渡した場合 → --playlist を追加します。
4. スクリプトを実行します。YouTube のボット検出に遭遇した場合、スクリプトが戦略を自動で切り替えます。
5. 保存されたファイルと、成功した戦略を報告します。

使い方

# Single video, current directory
python scripts/download.py "https://www.youtube.com/watch?v=..."

# Multiple URLs to a folder
python scripts/download.py "URL1" "URL2" -o "/path/to/output"

# Full playlist as 720p MP4
python scripts/download.py "https://www.youtube.com/playlist?list=..." --playlist -o "./out"

# Force a specific browser for cookies (skips auto-rotation)
python scripts/download.py "URL" --cookies-from-browser chrome

# Force a manual cookies.txt file
python scripts/download.py "URL" --cookies "~/Downloads/www.youtube.com_cookies.txt"

# Higher quality
python scripts/download.py "URL" --max-height 1080

フラグ

フラグ	デフォルト	説明
-o、--output	cwd	出力先ディレクトリ
--max-height	720	動画の最大高さ（例：1080、480）
--playlist	off	プレイリスト全体をダウンロードします。デフォルトは単一動画です
--cookies-from-browser	auto	使用するブラウザーを指定します。自動切り替えはスキップされます
--cookies	auto	使用する cookies.txt ファイルを指定します。自動切り替えはスキップされます
--no-archive	off	.download-archive.txt による再開状況の追跡を無効にします

自動復旧の戦略チェーン

リクエストがボット検出を示すマーカー（Sign in to confirm、 LOGIN_REQUIRED）によって失敗すると、スクリプトは以下の戦略を順番に自動で試し、最初に成功した時点で停止します。

1. 認証なし＋スロットリング — デフォルトです。リクエストの間に待機時間を設けます。
2. プレーヤークライアントの切り替え — default,tv,mweb,web_safari。比較的軽いブロックを回避します。
3. ブラウザー Cookie の切り替え — システムにインストールされているブラウザーのみを対象に、chrome → edge → firefox → brave → vivaldi → opera の順に試します。
4. Cookie ファイルの検出 — ~/Downloads/www.youtube.com_cookies.txt、youtube*cookies*.txt、cookies.txt から、最も新しい有効な Cookie ファイルを選びます（新しいファイルと見なすのは 7 日未満のものです）。

4 つすべての戦略が失敗した場合、スクリプトは状況に応じた復旧手順を表示します（以下の「ユーザー向け復旧手順」を参照）。

ユーザーが --cookies-from-browser または --cookies を明示的に指定した場合、戦略チェーンはスキップされ、その Cookie ソースだけが使用されます（ユーザーがすでに有効な方法を把握している場合に便利です）。

ユーザー向け復旧手順

すべての戦略が失敗すると、スクリプトは手順を追ったガイドを自動で表示します。最も関連性の高い部分をそのままユーザーに提示してください。具体的ですぐに実行できます。

スクリプトが確認した内容に応じて、ガイドの内容が変わります。

• Cookie ファイルが見つかったが拒否された場合（ファイルが古い場合）：ボットブロックが発生すると YouTube は Cookie をすぐに無効化するため、ユーザーに今すぐ Cookie を再エクスポートするよう伝えます。
• Cookie ファイルが見つからない場合：初回エクスポートの手順をユーザーに案内します。
• それ以外の場合：代替策（ブラウザーを閉じる、ネットワークを変更する、待つ）のみを提示します。

Cookie のエクスポート手順（ユーザーに必要となる可能性が高い部分）

1. Cookie エクスポート用のブラウザー拡張機能をインストールします。

   • Chrome / Edge / Brave / Vivaldi / Opera：「Get cookies.txt LOCALLY」 — https://chromewebstore.google.com/detail/get-cookiestxt-locally/cclelndahbckbenkjhflpdbgdldlbecc
   • Firefox：「cookies.txt」 — https://addons.mozilla.org/en-US/firefox/addon/cookies-txt/

2. そのブラウザーで https://www.youtube.com を開き、Google アカウントにログインします。

3. 拡張機能のツールバーアイコンをクリックします。

   • 「Get cookies.txt LOCALLY」→「Export As」→ Netscape 形式の順に選択し、「Current Site」オプションを使って youtube.com の Cookie のみを含めます。
   • Firefox の「cookies.txt」では、「Current Site」→「Save」の順に選択します。

4. ファイルを OS のデフォルトのダウンロードフォルダーに保存します。以下のどのファイル名でも使えます（自動検出され、最も新しいファイルが優先されます）。

   • www.youtube.com_cookies.txt（拡張機能のデフォルト名。最も簡単です）
   • youtube.com_cookies.txt
   • cookies.txt

5. 同じダウンロードコマンドを再実行します。戦略 4 がファイルを自動的に検出します。

各代替手段を推奨するタイミング

• ブラウザーを閉じる（Chrome／Edge）：App-Bound Encryption によってブラウザーの実行中は Cookie データベースがロックされる Windows では、最も手早い解決策です。「前回の続きから再開」が有効になっていない場合、開いているタブが失われます。
• 別のネットワークを使う（モバイルホットスポット、VPN）：IP レベルのブロックを回避できます。ユーザーがすでに VPN を使っている場合は、最も手早い方法です。
• しばらく待つ：YouTube の IP ブロックは通常、24 時間以内に自動的に解除されます。他の選択肢が適さない場合にのみ推奨してください。

再開／再実行時の安全性

--download-archive .download-archive.txt はデフォルトで有効です。ダウンロード済みの動画は再実行時にスキップされるため、一部失敗した後や、同じフォルダーに URL を追加するときに再実行しても安全です。無効にするには --no-archive を渡してください。

出力ファイル名のパターン

• 単一の動画：{title} [{id}].mp4
• プレイリスト：{NNN} - {title} [{id}].mp4（ゼロ埋めされたインデックスにより、ファイルマネージャーで順序が保たれます）

--windows-filenames は常に有効なので、どの OS でも安全に使えるファイル名になります。

認証に関する注意事項

• 自動ローテーションにより、ほとんどの場合、ユーザーの入力は不要です。
• --cookies-from-browser chrome を使う場合、Windows では Chrome を終了する必要があります（Chrome の実行中は App-Bound Encryption によって Cookie DB がロックされます）。
• Chrome を開いたままにする必要がある場合は、「Get cookies.txt LOCALLY」Chrome 拡張機能を使って Cookie をエクスポートし、そのファイルを ~/Downloads/ に置くようユーザーに案内してください。スクリプトは次回の実行時に自動でファイルを検出します。

対応プラットフォーム

YouTube（単一動画＋プレイリスト）、Instagram、TikTok、Twitter/X、Facebook、Vimeo、 Reddit、および yt-dlp 経由で対応するその他 1000 以上のサービス。