Back to Details

video-download

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Video Download Skill

视频下载Skill

Overview

概述

This skill enables automated video downloads from Chinese video platforms using headless browser automation. It handles platform detection, login management, and video extraction with proper quality settings.
该Skill借助无头浏览器自动化实现国内视频平台的视频自动下载。它支持平台检测、登录管理，并可按合适的画质设置提取视频。

Quick Start

快速开始

When a user requests video download, follow this decision tree:
  1. Identify platform from URL
    • Douyin: 
      v.douyin.com/xxx
      , 
      douyin.com/video/xxx
    • Xiaohongshu: 
      xiaohongshu.com/discovery/item/xxx
      , 
      xhslink.com/xxx
    • Bilibili: 
      bilibili.com/video/BVxxx
      , 
      b23.tv/xxx
  2. Check dependencies
    • First time use → Run 
      scripts/install_deps.sh
      to install playwright and ffmpeg
    • Dependencies verified → Proceed to platform-specific workflow
  3. Execute platform workflow
    • Douyin/Xiaohongshu → Direct download using 
      scripts/download.py
    • Bilibili → Check login status first, then download
当用户请求下载视频时，遵循以下决策树：
  1. 通过URL识别平台
    • 抖音：
      v.douyin.com/xxx
      , 
      douyin.com/video/xxx
    • 小红书：
      xiaohongshu.com/discovery/item/xxx
      , 
      xhslink.com/xxx
    • B站：
      bilibili.com/video/BVxxx
      , 
      b23.tv/xxx
  2. 检查依赖项
    • 首次使用 → 运行
      scripts/install_deps.sh
      安装playwright和ffmpeg
    • 依赖项已验证 → 进入对应平台的工作流
  3. 执行平台工作流
    • 抖音/小红书 → 使用
      scripts/download.py
      直接下载
    • B站 → 先检查登录状态，再进行下载

Core Capabilities

核心功能

1. Platform Support

1. 平台支持

  • Douyin (抖音): No login required, captures video URL from network requests
  • Xiaohongshu (小红书): No login required, captures video URL from network requests
  • Bilibili (B站): Login recommended for HD quality, requires ffmpeg for video merging
  • 抖音：无需登录，从网络请求中捕获视频URL
  • 小红书：无需登录，从网络请求中捕获视频URL
  • B站：推荐登录以获取高清画质，需要ffmpeg进行视频合并

2. Dependency Management

2. 依赖管理

  • Auto-installation: 
    scripts/install_deps.sh
    handles all dependencies with China mirror optimization
  • Dependencies: playwright (browser automation), ffmpeg (video processing for Bilibili)
  • Detection: Script automatically checks for missing dependencies
  • 自动安装：
    scripts/install_deps.sh
    通过国内镜像优化处理所有依赖项
  • 依赖项：playwright（浏览器自动化）、ffmpeg（B站视频处理）
  • 检测：脚本自动检查缺失的依赖项

3. Login Management

3. 登录管理

  • Cookie persistence: Saves login state in 
    ~/.config/video-download/<platform>_cookies.json
  • Interactive login: Opens visible browser for user authentication
  • Status checking: Verifies login state before download
  • Supported platforms: bilibili, douyin, xiaohongshu
  • Cookie持久化：将登录状态保存至
    ~/.config/video-download/<platform>_cookies.json
  • 交互式登录：打开可视化浏览器供用户完成认证
  • 状态检查：下载前验证登录状态
  • 支持平台：bilibili、douyin、xiaohongshu

4. Video Download

4. 视频下载

  • Automatic quality: Best available quality (Bilibili HD requires login)
  • Title extraction: Auto-generates filename from video title
  • Output location: 
    ~/Downloads/
    directory
  • Format: MP4 with proper codec settings
  • 自动画质选择：获取可用的最佳画质（B站高清需登录）
  • 标题提取：从视频标题自动生成文件名
  • 输出位置：
    ~/Downloads/
    目录
  • 格式：采用合适编码设置的MP4格式

Workflow Examples

工作流示例

Example 1: Douyin/Xiaohongshu Direct Download

示例1：抖音/小红书直接下载

User request: "下载这个抖音视频 [v.douyin.com/xxx]"
Workflow:
  1. Check dependencies installed using Shell command exit code
  2. If missing → Execute 
    scripts/install_deps.sh
    (block_until_ms: 120000)
  3. Run 
    scripts/download.py
    with video URL
  4. Wait for download completion and report saved file path
用户请求："下载这个抖音视频 [v.douyin.com/xxx]"
工作流:
  1. 通过Shell命令退出码检查依赖项是否已安装
  2. 若缺失 → 执行
    scripts/install_deps.sh
    （block_until_ms: 120000）
  3. 运行
    scripts/download.py
    并传入视频URL
  4. 等待下载完成并报告保存文件路径

Example 2: Bilibili with Login Flow

示例2：B站登录流程

User request: "下载这个B站视频 [bilibili.com/video/BVxxx]"
Workflow:
  1. Check dependencies (playwright, ffmpeg)
  2. Check login status using 
    scripts/download.py check-login bilibili
  3. If exit code 2 (LOGIN_REQUIRED):
    • Launch 
      scripts/download.py login bilibili --signal-file /tmp/video_dl_login_done
      (block_until_ms: 0, run in background)
    • Immediately show AskQuestion to user:
      • Prompt: "已打开 B站 登录页面，请在浏览器中完成登录，完成后点击下方确认按钮。"
      • Option A: "已完成登录"
      • Option B: "跳过登录（使用低画质）"
    • If option A: Create signal file 
      touch /tmp/video_dl_login_done
      , wait for login script exit
    • If option B: Kill login script process, proceed with low quality
  4. Run 
    scripts/download.py
    with video URL
  5. Report completion and file location
用户请求："下载这个B站视频 [bilibili.com/video/BVxxx]"
工作流:
  1. 检查依赖项（playwright、ffmpeg）
  2. 使用
    scripts/download.py check-login bilibili
    检查登录状态
  3. 若退出码为2（需要登录）：
    • 启动
      scripts/download.py login bilibili --signal-file /tmp/video_dl_login_done
      （block_until_ms: 0，后台运行）
    • 立即向用户发起提问：
      • 提示："已打开 B站 登录页面，请在浏览器中完成登录，完成后点击下方确认按钮。"
      • 选项A："已完成登录"
      • 选项B："跳过登录（使用低画质）"
    • 若选择A：创建信号文件
      touch /tmp/video_dl_login_done
      ，等待登录脚本退出
    • 若选择B：终止登录脚本进程，以低画质继续
  4. 运行
    scripts/download.py
    并传入视频URL
  5. 报告完成状态及文件位置

Example 3: First-Time User Setup

示例3：首次用户设置

User request: "帮我下载小红书视频 [xhslink.com/xxx]"
Workflow:
  1. Detect first use (no playwright/ffmpeg installed)
  2. Inform user: "首次使用需要安装依赖（playwright 和 ffmpeg），约需 1-2 分钟"
  3. Execute 
    scripts/install_deps.sh
    (block_until_ms: 120000)
  4. Monitor installation progress by reading terminal output
  5. After success, proceed with download workflow
用户请求："帮我下载小红书视频 [xhslink.com/xxx]"
工作流:
  1. 检测到首次使用（未安装playwright/ffmpeg）
  2. 告知用户："首次使用需要安装依赖（playwright 和 ffmpeg），约需 1-2 分钟"
  3. 执行
    scripts/install_deps.sh
    （block_until_ms: 120000）
  4. 通过读取终端输出来监控安装进度
  5. 安装成功后，进入下载工作流

Resource Guide

资源指南

scripts/

scripts/

Core script:
  • download.py
    - Main entry point for all download operations
Available commands:
  • Download: Pass video URL as first argument, optional output filename as second
  • Login: 
    login <platform>
    - Opens browser for authentication
  • Login with signal: 
    login <platform> --signal-file <path>
    - For agent interaction mode
  • Check status: 
    check-login <platform>
    - Returns exit code 0 (logged in) or 2 (login required)
Dependency installer:
  • install_deps.sh
    - One-click setup with China mirror optimization
    • Configures pip to use Tsinghua mirror
    • Sets Playwright download host to npmmirror
    • Installs playwright package
    • Installs Chromium browser
    • Installs ffmpeg via Homebrew
核心脚本:
  • download.py
    - 所有下载操作的主入口
可用命令:
  • 下载：将视频URL作为第一个参数传入，可选输出文件名作为第二个参数
  • 登录：
    login <platform>
    - 打开浏览器完成认证
  • 带信号的登录：
    login <platform> --signal-file <path>
    - 用于Agent交互模式
  • 检查状态：
    check-login <platform>
    - 返回退出码0（已登录）或2（需要登录）
依赖项安装器:
  • install_deps.sh
    - 一键式安装，适配国内镜像
    • 配置pip使用清华镜像
    • 将Playwright下载源设置为npmmirror
    • 安装playwright包
    • 安装Chromium浏览器
    • 通过Homebrew安装ffmpeg

Platform-Specific Notes

平台特定说明

Douyin (抖音):
  • Accepts short links (v.douyin.com) or full URLs
  • Extracts video from network HAR requests
  • No login required
  • Auto-detects modal_id from share text
Xiaohongshu (小红书):
  • Supports xiaohongshu.com and xhslink.com domains
  • Captures video URL from page network requests
  • No login required
  • Works for both discovery and explore paths
Bilibili (B站):
  • Requires login for HD quality (1080p+), otherwise limited to 480p
  • Uses 
    __playinfo__
    page variable for video URL extraction
  • Downloads separate audio/video streams and merges with ffmpeg
  • Cookie expiration auto-detected
抖音:
  • 支持短链接（v.douyin.com）或完整URL
  • 从网络HAR请求中提取视频
  • 无需登录
  • 自动从分享文本中识别modal_id
小红书:
  • 支持xiaohongshu.com和xhslink.com域名
  • 从页面网络请求中捕获视频URL
  • 无需登录
  • 适用于发现页和探索页路径
B站:
  • 高清画质（1080p+）需登录，否则限制为480p
  • 使用
    __playinfo__
    页面变量提取视频URL
  • 分别下载音频和视频流，再通过ffmpeg合并
  • 自动检测Cookie过期

Error Handling

错误处理

Exit CodeMeaningAgent Action
0SuccessProceed to next step
1General errorReport error message to user
2Login requiredInitiate login workflow
Common IssuesAuto-Resolution
Missing dependenciesRun 
scripts/install_deps.sh
SSL certificate errorScript uses unverified SSL context
Video not capturedContent may require login or is image post
Low quality (Bilibili)Prompt user to login for HD
Cookie expiredRe-run login command automatically
CDN URL expiredRetry download (URLs valid for few hours)
退出码含义Agent操作
0成功执行下一步
1通用错误向用户报告错误信息
2需要登录启动登录工作流
常见问题自动解决方案
缺失依赖项运行
scripts/install_deps.sh
SSL证书错误脚本使用未验证的SSL上下文
未捕获到视频内容可能需要登录或为图片帖
画质低（B站）提示用户登录以获取高清画质
Cookie过期自动重新运行登录命令
CDN URL过期重试下载（URL有效期为数小时）

Technical Details

技术细节

Browser automation:
  • Uses Playwright with Chromium
  • Headless mode (user-invisible)
  • Network HAR capture for video URL extraction
  • Cookie persistence across sessions
Video processing:
  • Bilibili: Merges DASH audio/video streams using ffmpeg
  • Douyin/Xiaohongshu: Direct MP4 download
  • Proper HTTP headers (User-Agent, Referer) for CDN access
File management:
  • Default output: 
    ~/Downloads/<sanitized_title>.mp4
  • Title sanitization: Removes special chars, limits length
  • Config directory: 
    ~/.config/video-download/
Usage notes:
  • Script handles all platform detection automatically from URL
  • Agent should monitor Shell command exit codes to handle errors
  • Use AskQuestion tool for interactive login confirmation
  • Set block_until_ms: 0 for login command to avoid blocking
  • Dependency installation takes 1-2 minutes on first run
浏览器自动化:
  • 使用Playwright搭配Chromium
  • 无头模式（对用户不可见）
  • 捕获网络HAR请求以提取视频URL
  • 会话间Cookie持久化
视频处理:
  • B站：使用ffmpeg合并DASH音频/视频流
  • 抖音/小红书：直接下载MP4
  • 适配CDN访问的HTTP请求头（User-Agent、Referer）
文件管理:
  • 默认输出路径：
    ~/Downloads/<sanitized_title>.mp4
  • 标题清理：移除特殊字符，限制长度
  • 配置目录：
    ~/.config/video-download/
使用注意事项:
  • 脚本会自动通过URL识别平台
  • Agent应监控Shell命令退出码以处理错误
  • 使用AskQuestion工具进行交互式登录确认
  • 登录命令设置block_until_ms: 0以避免阻塞
  • 首次运行依赖项安装需1-2分钟