download-web-video

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.