多平台短视频下载工具

功能概述

支持从 Excel 文件、TXT 文件或直接输入 URL 三种方式获取短视频链接（抖音/快手/小红书/B站等），自动检测平台来源，通过浏览器自动化获取原始视频地址并下载到本地。支持单条下载和批量下载，文件按 001_视频标题.mp4 格式顺序命名，支持跨会话续传、失败自动重试、未知平台自动适配。

核心特性

1. 多种输入方式：支持 Excel(.xlsx)、TXT(.txt) 文件读取，也支持直接传入单条或多条 URL
2. 单条及批量下载：传入1条URL即为单条下载，传入多条URL即为批量下载，逻辑统一
3. 多平台自动检测：平台注册器架构，根据 URL 域名自动路由到对应提取器
4. 四重校验：HTTP状态码 + Content-Type + 文件大小 + 文件头特征，确保下载的是真实视频文件
5. 3次递增重试：超时时间递增（30s→45s→60s），间隔递增（5s→8s）
6. 未知平台自适配：通用提取器拦截网络流量尝试提取视频 URL，并记录网络特征到日志
7. 跨会话续传：映射文件记录已下载视频，重复运行自动跳过
8. 多平台混合支持：同一文件中可混合不同平台 URL

支持平台

> 注意：快手、小红书、B站、微视的提取器基于各平台已知 API 结构实现，未经大规模实测验证。首次使用时如果提取失败，通用提取器会作为后备方案尝试，并记录网络特征日志供后续适配。

触发条件

当用户提出以下需求时使用本技能：

• "帮我下载这个短视频" / "下载这个视频链接"
• "帮我下载这些短视频"
• "批量下载抖音/快手/小红书视频"
• "从 Excel / TXT 文件里下载短视频链接"
• "下载多平台短视频"
• "短视频批量下载"
• 用户提供一个或多个短视频平台 URL 并要求下载

使用方法

输入方式

本工具支持三种输入方式，每次运行选择其中一种：

> 传入1条URL即为单条下载，传入多条URL即为批量下载，逻辑统一，无需区分模式。

1. 从 Excel 文件下载（批量）

将包含短视频 URL 的 Excel 文件（.xlsx）准备好。支持以下格式：
- 纯 URL 列（每行一个 URL）
- 文案+URL 混合文本（自动提取 URL）
- 多平台 URL 混合（自动检测平台）

python scripts/video_download.py --excel /path/to/urls.xlsx

2. 从 TXT 文件下载（批量）

将 URL 写入 TXT 文件，每行一个 URL 或含 URL 的文本均可：

# urls.txt 示例
https://v.douyin.com/xxx/
https://v.kuaishou.com/yyy/
这是一个有趣的视频 https://xhslink.com/zzz 快来看看

python scripts/video_download.py --txt /path/to/urls.txt

3. 直接传入 URL 下载（单条/少量）

直接在命令行传入 URL，支持单条或多条：

# 单条下载
python scripts/video_download.py --url "https://v.douyin.com/xxx/"

# 多条批量下载（逗号分隔）
python scripts/video_download.py --url "https://v.douyin.com/xxx/, https://v.kuaishou.com/yyy/"

# 多条批量下载（空格分隔）
python scripts/video_download.py --url "https://v.douyin.com/xxx/ https://xhslink.com/zzz"

通用选项

# 指定输出目录（适用于所有输入方式）
python scripts/video_download.py --excel /path/to/urls.xlsx --output /path/to/videos/
python scripts/video_download.py --url "https://v.douyin.com/xxx/" --output /path/to/videos/

# 强制重新下载（会提示确认）
python scripts/video_download.py --url "https://v.douyin.com/xxx/" --fresh

查看结果

运行完成后，输出目录中包含：
- 001_视频标题.mp4 ~ NNN_视频标题.mp4：下载的视频文件
- video_mapping.json：映射文件（记录序号、视频ID、标题、URL、平台、下载时间）
- 下载报告.txt：下载报告（含平台统计）

如果遇到未知平台，还会生成：
- unknown_platform_log.json：未知平台网络特征日志

命令行参数

> --excel、--txt、--url 三选一，不可同时使用。

四重校验机制

下载视频时执行四重校验，确保文件完整性：

校验失败的视频不会保存到磁盘，直接触发重试。

3次递增重试机制

未知平台自适配机制

当遇到未知平台的 URL 时，脚本自动执行以下流程：

1. detect_platform() 返回 unknown
2. 自动切换到 extract_generic() 通用提取器
3. 拦截所有网络响应：
   - Content-Type含video → 直接捕获视频URL
   - JSON响应 → 递归搜索视频URL特征字段
   - 页面 <video> 标签 → 提取src属性
4. 无论成功与否，记录到 unknown_platform_log.json
5. 成功 → 四重校验下载；失败 → 跳过，等待人工分析

日志内容包含：URL、域名、API端点列表（URL+状态码+JSON顶层键）、视频响应列表、是否成功提取。

如何添加新平台

详见 references/platform_adaptation_guide.md。

依赖

• Python 3.8+
• playwright（浏览器自动化）
• requests（视频下载）
• openpyxl（仅 --excel 方式需要）

安装命令：

pip install playwright requests openpyxl
playwright install chromium

限制

1. 依赖 Playwright Chromium 浏览器，首次需运行 playwright install chromium
2. 快手/小红书/B站提取器为实验性实现，首次使用可能需要根据实际API响应调整
3. 未知平台通用提取器不保证100%成功，取决于平台反爬策略和API结构
4. 文件名限制80字符（超出截断）
5. 不支持私密视频下载
6. --fresh 参数会删除映射文件，使用前会提示确认
7. B站视频下载需要Referer头（脚本已自动添加）
8. 本工具仅用于下载公开可访问的视频内容，请遵守各平台用户协议和版权规定

合规声明

本工具通过浏览器自动化方式访问公开可访问的视频内容，不破解加密、不绕过付费墙、不下载私密内容。使用者需确保下载行为符合当地法律法规和平台用户协议，下载的内容仅供个人学习使用，不得用于商业用途或侵权传播。