1仕組みと動作原理

中核は yt-dlp/ffmpeg CLI のラッパー：SKILL.md がエージェントに対し、yt-dlp によるダウンロードや ffmpeg による HLS 処理/トランスコードを指示し、付属の Python ラッパースクリプト download_video.py でダウンロード手順をプログラム化しています。

SKILL.md

Enable reliable video and audio downloads from YouTube and HLS streaming platforms (Mux, Vimeo, etc.) using yt-dlp and ffmpeg.

実現原理＝外部 CLI のオーケストレーションであり、組み込みデコーダーではありません。スクリプト内部では cmd = ["yt-dlp"] から argv を組み立てて subprocess.run を実行し、全編で shell=True は使用していません。

PO Token プロバイダーの自動オーケストレーション（高画質の要）：yt-dlp の Python 環境へプラグインを pip で自動インストールし、優先して brainicism/bgutil-ytdlp-pot-provider コンテナ（-p 4416:4416）を Docker 実行、127.0.0.1:4416 への ping で死活監視を行います。Docker が存在しない/失敗した場合は pip install yt-dlp-getpot-wpc にフォールバックしてブラウザ WPC 方式を採用します。

scripts/download_video.py

run_cmd = ["docker", "run", "-d", "--name", name] ... "-p", "4416:4416", *env_args, "--init", "brainicism/bgutil-ytdlp-pot-provider"

ここでの処理：サードパーティの PO token プロバイダーをコンテナとして立ち上げ、プロキシ環境変数を注入しています。SKILL.md の「YouTube downloads (up to 4K) using PO token providers」という宣言に対応します。コンテナ内のコードは本リポジトリで監査できません（サプライチェーンリスク面）。

Cookie 認証パイプライン：ユーザーの認可を得た後、ブラウザの Cookie セッションを yt-dlp（--cookies-from-browser chrome/firefox または --cookies ファイル）に渡し、Cookie がある場合は強制的に youtube player client を web_safari に設定します。

scripts/download_video.py

cmd.extend(["--cookies-from-browser", cookies_from_browser]) ... elif cookies_file: cmd.extend(["--cookies", cookies_file])

ここでの処理：Cookie の復号/読み取りは実際には yt-dlp 側で行われ、スクリプトはパラメータを透過するのみです。SKILL.md の規定「Ask before extracting browser cookies.」に従い、事前に権限確認を行います。

非技術者向け UX 設計：エージェントが全自動で代行——まず --info でメタデータを取得（失敗時は YouTube oEmbed にフォールバック）して動画を特定・確認し、デフォルトまたは指定の設定でダウンロードし、最終的にファイルパス、サイズ、解像度を報告するため、ユーザーはコマンドを一切入力する必要がありません。

SKILL.md

Assume the user is non-technical. Do not ask them to run commands. Execute everything yourself and report progress in plain language.

oEmbed のフォールバックはスクリプトの fetch_oembed_info にあります：urlopen https://www.youtube.com/oembed?... により、Bot 対策でブロックされた場合でもタイトル/投稿者を確認でき、動画の誤ダウンロードリスクを低減します。

エラー駆動型リトライチェーン：yt-dlp の一般的な障害（403 / nsig / 'Only images are available' / SSL EOF）を戦略に対応付け——403 時は非 m3u8 のプログレッシブ形式にフォールバック、PO token 障害時はコンテナ再起動または WPC に切り替えてリトライ、Cookie+403 時は web_safari クライアントに変更します。

scripts/download_video.py

return "http error 403" in text or "403: forbidden" in text or "fragment 1 not found" in text

has_403_error/has_pot_error/has_wpc_error と download_video 内の多重リトライ分岐が、当スキルが謳う「高い信頼性」の技術的根拠となっています。

プロキシ検知設計（中国本土ネットワーク向け）：環境変数 ALL_PROXY/HTTPS_PROXY/HTTP_PROXY を読み取って yt-dlp、pip、Docker コンテナに透過し、localhost プロキシは host.docker.internal に書き換えます。pip は清華大学のミラー pypi.tuna.tsinghua.edu.cn がハードコードされています。

scripts/download_video.py

PYPI_MIRROR = "https://pypi.tuna.tsinghua.edu.cn/simple"

normalize_proxy_for_docker はプロキシ URL 内の user:password を保持したままコンテナの環境変数に注入するため、プロキシ認証情報がサードパーティ製コンテナのプロセス環境に入り込みます。

2コア機能

01YouTube 動画/プレイリストのダウンロード（画質プリセット: best/1080p/720p/480p/360p/worst、MP4 結合出力）

02MP3 への音声抽出および字幕ダウンロード（-x --audio-format mp3 / --write-subs --write-auto-subs --sub-lang）

03メタデータの事前取得と確認（--dump-json で title/uploader/duration/thumbnail をパース、失敗時は YouTube oEmbed へフォールバック）

04PO Token による高画質自動アンロック（Docker bgutil 優先 → ブラウザ WPC フォールバック → 障害時の再起動リトライ）

05ブラウザ Cookie 認証によるダウンロード（--cookies-from-browser chrome/firefox、web_safari クライアント、ログのマスキング）

06HLS (m3u8) 保護ストリームのダウンロード案内とフォールバックリトライ（ffmpeg -headers + -protocol_whitelist ガイドライン、スクリプト内での非 m3u8 プログレッシブ形式フォールバック）

07プロキシおよびミラーへの適応（中国本土ネットワーク向け：清華大学 PyPI ミラーによるプラグイン導入、プロキシ透過/コンテナ向け書き換え）

3外部依存関係

Kind	Dependency / Endpoint
cli	yt-dlp
cli	ffmpeg / ffprobe
cli	docker
cli	python / pip（yt-dlp 解释器）
network	youtube.com（下载取流 + oEmbed 元数据）
network	清华 PyPI 镜像（硬编码装插件源）
network	Docker Hub 镜像 brainicism/bgutil-ytdlp-pot-provider（第三方 PO token 服务，拉取即执行）
network	本机 PO provider 探活端点
network	用户提供任意视频/HLS URL（m3u8 可指向任意第三方 CDN，如 Mux/Vimeo）
package	bgutil-ytdlp-pot-provider（pip 插件）
package	yt-dlp-getpot-wpc（pip 浏览器版 token 提供者，会启动真实浏览器）

4推奨統制措置と判定根拠

安全運用のための推奨統制措置

Agent 向け

隔離環境で実行、都度明示的な認可

管理者向け

厳格な認可、全量監査、コンプライアンス確認

判定根拠（ファイルパスと抜粋）

本地凭据 / 浏览器配置: ユーザーログイン Cookie/セッション/キーチェーンの読み取り: ブラウザ Cookie: --cookies-from-browser chrome/firefox → yt-dlp がブラウザの Cookie ストアを読み取り（スクリプト
scripts/: ローカルスクリプトまたはコマンドの実行: 外部 CLI: yt-dlp（ダウンロード/メタデータ/フォーマット一覧取得）、ffprobe/ffmpeg、docker run/start/rm/info、pip inst
scripts/ 或 SKILL.md: 外部言語パッケージ依存関係の動的インストールを宣言
网络端点: 外部ネットワークアクセスの宣言: youtube.com: yt-dlp によるメタデータ/ストリーム取得、urlopen https://www.youtube.com/oembed による oEmbed フォールバック（
本地工作目录: ファイル読み書きおよび成果物出力: ダウンロード出力: output_dir を再帰的に mkdir ＋ -o テンプレートに従って動画/音声/字幕ファイルを書き込み（テンプレートは絶対パスおよび yt-dlp の %()s 構文に対応し、ユーザーが指定可能

監査ノート： 調査所見であり、公式の認定ではありません。イエロー判定の主因は認証情報とサプライチェーンリスクです：(a) Cookie の読み取りパイプラインが実在し、それが中核機能となっている点（Cookie の復号は yt-dlp 側で行われ、スクリプトは透過とログマスキングを実施、SKILL でも事前確認を要求していますが、実行時の強制力はありません）；(b) 2つのサードパーティプラグインの自動 pip インストール、および常駐するサードパーティ製 brainicism コンテナの Docker プルを実行する点（コンテナ内コードは本リポジトリの監査対象外であり、.security-scan-passed は本ディレクトリの静的テキストに対する gitleaks スキャンのみをカバー）；(c) WPC パスがユーザーのログイン状態で YouTube にアクセスするために実際の Chrome を起動する点；(d) 任意のユーザー URL をダウンロードし、headers やテンプレートをそのまま信頼することが SSRF や任意ファイル書き込みのリスク面を形成している点。スクリプト自体には shell=True や難読化、不正な隠密送信は見られないためレッド判定には至りませんが、グリーン判定の基準を満たさないためイエローと判断しました。

5二重目の独立検証

[ok] yt-dlp 调用真实存在（下载/-F/-o/-f/--dump-json） — 脚本 cmd = ["yt-dlp"] 起步（738 行），全部参数列表化
[ok] ffmpeg/ffprobe 调用 — SKILL.md 多处 ffmpeg 命令 + 脚本 get_video_resolution 中 which ffprobe 实测存在
[ok] cookie 读取路径（--cookies-from-browser / --cookies） — 773-776 行真实拼接；注意解密主体是 yt-dlp 而非脚本，脚本无 cookie 解析代码
[ok] cookie 日志脱敏 filter_cookie_lines — 仅过滤含 'extracting cookies' 或 'extracted'+'cookies' 的行，非完整脱敏（其他含 cookie 内容行仍会输出）——实现与声称基本一致，范围略窄
[ok] oEmbed 兜底网络端点 — 660-663 行 urlopen youtube.com/oembed，URL 经 quote 编码，无注入面
[ok] PO token：docker bgutil 容器 + 4416 ping 探活 — 437-446/553-563 行 docker run brainicism 镜像，255-257 行 ping；容器内实现本 repo 无法审计 → 供应链项如实标注
[ok] WPC 浏览器回退自动拉起 Chrome — 脚本只传 --extractor-args youtubepot-wpc:browser_path=…（249-252 行）+ find_chrome_path；真实浏览器启动由第三方插件 yt-dlp-getpot-wpc 完成，脚本侧证据到传参为止
[ok] pip 自动安装插件（清华镜像） — 350、377 行安装命令真实存在，PYPI_MIRROR 38 行硬编码

6結論

スクレイピング対策への対抗知見を高度にエンジニアリング化：nsig/PO token/403/'Only images'/SSL EOF などの落とし穴をエラー分類と自動リトライチェーンに落とし込み、スクリプトの強力な自己修復能力を実現

2層構造の UX 設計：非技術者向けの分かりやすいフロー＋エージェント向けの内部 SOP で、両者の責務が明確かつ規律が統一（references/internal-sop.md と SKILL チェックリストが1対1で対応）

2つのレイヤーで徹底された Cookie プライバシー規律：SKILL テキストでの詳細な Cookie 情報露出禁止＋スクリプト層でのログ行フィルタリング

中国国内ネットワークへの万全な特化適応（清華大学ミラー、プロキシ透過、Docker 内 localhost プロキシ書き換え、WPC フォールバック）により本土ユーザーでも実利用可能

メタデータ oEmbed フォールバック＋ダウンロード前確認により、Bot 検知環境下でも動画の誤ダウンロードを防止

最適な用途： エージェントを通じて YouTube や公開 HLS 動画をワンクリックで高品質にダウンロードしたい個人ユーザー、1回限りの Cookie 認可や Docker/PO プラグインの導入を許容できるユーザー（中国本土でプロキシを利用する環境を含む）。または、自身が管理する制御された環境下で権限のあるコンテンツを一括取得する必要がある運用担当者・コンテンツ制作者。

不向きな用途： ゼロトラストまたはサプライチェーンに厳しい本番環境のエージェントサンドボックス（サードパーティ製プラグインのインストール、外部コンテナのプル、ブラウザの自動起動を伴うため）。GUI および Docker のないヘッドレス環境（WPC にはブラウザウィンドウが必要であり、欠けると 360p の Android クライアントしか残らない）。ブラウザ Cookie の読み取りを禁止する企業ポリシー環境。プロキシのない中国国内の直接接続（SKILL 自身が記載するエラーハンドリングがプロキシに依存）。

Install Agent-Ready

① Verified Mirror 2026-09-06

Option A · Direct DownloadDownload youtube-downloader.tar.gz

sha256: 6c6c403e7e905b4e…

Option B · Copy Guide for Agent

install.json

Agent はこの JSON ガイドから自動的にダウンロードして検証します。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit 63a65c1fcc.