SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsz-video-downloader

z-video-downloader

Design & creation

View repository

Updated 10-16 08:01

About this skill

Video Downloader

Download the user-provided video links as local video files. Web material collection only records video links; the actual downloading is uniformly handled by this skill. Direct-link videos support .part files and HTTP Range resumption, while platform videos and m3u8 use yt-dlp 's resumption, fragment concurrency, and retry capabilities; when encountering platform risk control, prioritize using the exported cookies.txt files to retry. WeChat Channels (weixin.qq.com/sph/ share links) directly obtain the video address through an online parsing service for download, with no need to install additional local tools.

Dependencies

  • Python: preferably use /Users/zz/miniconda3/bin/python3
  • Platform download:/Users/zz/miniconda3/bin/yt-dlp
  • Merge audio and video:ffmpeg, currently usually at /opt/homebrew/bin/ffmpeg

Default output

All files are saved by default to the current workspace's Video/Downloads. When installed in .agent/skills the workspace is automatically detected; you can also use --out-root or ZHANGAI_ROOT to specify it explicitly.

Video/Downloads/YYYY-MM-DD-主题/
├── 下载的视频文件.mp4
├── 下载的视频文件.info.json
├── download-report.md
└── download-report.json

Common commands

Single link:

/Users/zz/miniconda3/bin/python3 .agent/skills/z-video-downloader/scripts/download_video.py \
  --title "主题名" \
  "https://www.bilibili.com/video/BV..."

Multiple links:

/Users/zz/miniconda3/bin/python3 .agent/skills/z-video-downloader/scripts/download_video.py \
  --title "主题名" \
  "https://www.youtube.com/watch?v=..." \
  "https://www.bilibili.com/video/BV..."

Directly read z-web-pack 's media inventory:

/Users/zz/miniconda3/bin/python3 .agent/skills/z-video-downloader/scripts/download_video.py \
  --title "主题名" \
  --inventory "Clippings/Reading/本次资料包/04-media-inventory.md"

Batch download from text, one link per line; blank lines and # comments are automatically skipped:

/Users/zz/miniconda3/bin/python3 .agent/skills/z-video-downloader/scripts/download_video.py \
  --title "主题名" \
  --url-file "video-urls.txt"

When encountering YouTube bot verification, Bilibili 412, or login-required content:

/Users/zz/miniconda3/bin/python3 .agent/skills/z-video-downloader/scripts/download_video.py \
  --cookies-file "cookies/cookies.txt" \
  --title "主题名" \
  "视频链接"

WeChat Channels share link:

/Users/zz/miniconda3/bin/python3 .agent/skills/z-video-downloader/scripts/download_video.py \
  --title "视频号主题" \
  "https://weixin.qq.com/sph/Axv548mzBF"

Channels links are automatically recognized and downloaded through an online parsing service, saving both H.264 and H.265 versions by default.

Temporary command-line debugging still supports --browser-cookies chrome, but web services should use --cookies-file, to avoid the service process repeatedly launching Chrome/Safari.

For YouTube without cookies, if yt-dlp is blocked by login verification, the script will by default try the Invidious local=true proxy fallback, prioritizing saving 360p progressive MP4. If only the official yt-dlp route is explicitly allowed, you can add:

--no-invidious-fallback

When cookies are already provided, the link will not be handed over to a third-party proxy.

When downloading playlists, collections, or channel lists, the user must explicitly want the entire group downloaded, then add:

--playlist

To download higher quality:

--quality best

The default limit is 1080p, to avoid unintentionally downloading extremely large files. Use this only when the user explicitly wants the highest quality --quality best。

Download Chinese and English subtitles and embed the cover:

--subtitles --sub-langs "zh.*,en.*" --embed-thumbnail

After a direct link is interrupted, reuse the original directory to continue downloading:

--run-dir "Video/Downloads/原任务目录"

For long-term batch tasks, use download history to avoid duplication:

--download-archive "Video/Downloads/download-archive.txt"

Execution flow

  1. First confirm that what the user provided is a video link or direct video link; if it is web material collection and the body text and images also need to be saved, switch to z-web-pack。
  2. If the link comes from z-web-pack 's 04-media-inventory.md, directly pass --inventory, with no need to manually copy the Source URL.
  3. Run scripts/download_video.py. When there are no special requirements, use the default 1080p, single-video mode.
  4. If the YouTube failure reason includes login, bot verification, cookies, or captcha, the script will automatically try the Invidious proxy fallback; if the user needs higher quality or the official logged-in state, then use --cookies-file cookies/cookies.txt to retry.
  5. If the Bilibili or other platform failure reason includes HTTP 412, 403, login, or cookies, use --cookies-file cookies/cookies.txt to retry once.
  6. If the user provides a collection, playlist, UP主 space, or channel page, first confirm that the user really wants to batch download, then use --playlist。
  7. After completion, read download-report.md, and finally reply to the user:
    • skill path
    • output directory
    • success/failure count
    • number skipped due to download history
    • successful file names and sizes
    • reasons for failed links and cookie retry hints
    • If .partexists, it means the same output directory can be used to continue downloading

Platform strategy

  • mp4/webm/mov/m4v/mkv/flv/ogv direct links: the script downloads them directly via streaming, preserving Referer and User-Agent.
  • m3u8, YouTube, Bilibili, Vimeo, X/Twitter, TikTok, Douyin, etc.: hand over to yt-dlp。
  • WeChat Channels（https://weixin.qq.com/sph/xxx): obtain H.264/H.265 video direct links through the sph.litao.workers.dev online parsing service and then download, saving both encoding versions by default. No WeChat login state is required, and no certificate needs to be installed. Thanks to ltaoo/wx_channels_download for providing the parsing service.
  • When YouTube direct connections are blocked by login verification: try the Invidious local=true proxy endpoint, using Range small-chunk resumable transfer to save 360p MP4.
  • Default --no-playlist, to avoid accidentally downloading an entire list from one link.
  • Default --max-video-mb 2000, and if exceeded, fail and record it in the report.
  • Default --write-info-json, preserving video metadata for easier later tracing of the source.
  • Platform downloads explicitly enable resumable transfer, temporary files, 10 download retries, 10 fragment retries, and 4-way fragment concurrency.
  • When a direct link is interrupted, keep .part; using --run-dir to reuse the original task directory will continue from the saved position, and only after completion will it be changed to the formal video file.
  • The input must be a valid HTTP/HTTPS address; empty manifests, whitespace characters, embedded username/password, invalid addresses, and missing cookie files will stop before the output directory is created.
  • --download-archive is responsible for historical deduplication of platform videos; items already in the history will be recorded as "skipped", and the task will still count as normally completed.

Final checks

After downloading, at least run:

find "Video/Downloads/本次目录" -maxdepth 1 -type f | sort
sed -n '1,160p' "Video/Downloads/本次目录/download-report.md"
find "Video/Downloads/本次目录" -maxdepth 1 -name '*.part' -print

If this task only downloads videos, the report Markdown does not contain external image links, so there is no need to call the image hosting skill. If it is later changed to produce .md files containing external image links, call according to project rules 1-upload-images-to-picgo。