| name | download-web-video |
| description | Download Bilibili and YouTube videos with yt-dlp, optional browser-profile or Netscape-file authentication, human/automatic captions, metadata, thumbnails, resumable transfers, and Bilibili CDN probing plus aria2 acceleration. Use when Codex must save an online video or captions locally, access formats/subtitles that require an existing browser login, prepare source media for transcription or visual analysis, or produce a reproducible download bundle without exposing cookies or signed media URLs. |
Download Web Video
Produce a local evidence bundle with the media, captions, metadata, hashes, and
a credential-safe manifest. Support single Bilibili and YouTube URLs by default;
enable playlists only when the user asks.
Prerequisites
Require yt-dlp and ffmpeg; use aria2c when available. On macOS:
brew install yt-dlp ffmpeg aria2
Treat browser cookies and signed media URLs as credentials. Pass cookies
directly to yt-dlp, never export or print their values, and never commit them.
The yt-dlp *.info.json artifact can contain short-lived signed format URLs;
keep it local even though manifest.json intentionally excludes those URLs.
Download
Run the bundled wrapper:
python3 <skill-dir>/scripts/download_video.py \
"https://www.bilibili.com/video/BV..." \
--output-dir "./video-source" \
--cookies-from-browser "chrome:Default"
For YouTube, use the same command and URL shape. Authentication is optional:
python3 <skill-dir>/scripts/download_video.py \
"https://www.youtube.com/watch?v=..." \
--output-dir "./video-source"
Use a Netscape cookie file only when the user supplies one:
python3 <skill-dir>/scripts/download_video.py URL \
--output-dir "./video-source" \
--cookies "/path/to/cookies.txt"
Do not assume that --cookies-from-browser chrome means the target site is
logged in. yt-dlp chooses the most recently accessed Chrome profile. If
captions or member formats are unexpectedly absent, identify the intended local
profile and pass it explicitly, such as chrome:Default.
Choose the lightest mode
- Need only captions/metadata: add
--metadata-only.
- Need no private browser state: omit both cookie options.
- Need a single entry from an anthology or playlist: keep the default
--no-playlist behavior.
- Need the full playlist: add
--playlist only with user intent.
- Need predictable native transfer behavior: add
--accelerator off.
- Need to test the plan without network access: add
--dry-run; cookie-file
paths are redacted.
For Bilibili VOD, auto probes a bounded UPOS candidate set and rewrites only
signed media hosts when the original is unhealthy or a candidate is materially
faster. It deliberately keeps yt-dlp's native single-stream downloader: some
UPOS mirrors mishandle resumed multi-range transfers. --accelerator force
opts into aria2 splitting, but the wrapper still rejects incomplete tracks.
Read references/acceleration.md before changing
the host policy, validation boundary, or local yt-dlp plugin.
Verify the bundle
Require all applicable conditions:
manifest.json exists and identifies the original page URL, site, selected
downloader, CDN probe results, output files, sizes, and SHA-256 hashes.- At least one media file exists unless
--metadata-only was requested.
- A
.info.json sidecar exists.
- Requested captions exist when the site advertises them; otherwise report that
captions were unavailable rather than inventing a transcript.
manifest.json contains neither cookie values nor signed media URLs.- Every required audio/video track opens with
ffprobe and reaches the
metadata duration within tolerance. Container duration alone is insufficient:
a Bilibili MP4 can report the full duration while one track ends early.
- A failed validation exits non-zero and does not write a success manifest.
Retry in a clean output directory with
--accelerator off; do not reuse a
suspect .part file.
Output
Write all results beneath --output-dir:
<output-dir>/
├── <video-id>.mp4 # unless metadata-only
├── <video-id>.<lang>.srt # when available
├── <video-id>.info.json
├── <video-id>.<thumbnail-ext>
└── manifest.json
Keep the bundle project-local or in a user-approved destination. Do not place
downloaded media, cookies, or short-lived URLs inside this public skill source.
