抖音视频下载器

概述

下载抖音视频的最高可用清晰度版本，自动尝试无水印源，并将原始抖音链接写入文件元数据的 comment 字段，方便后续快速回溯源头。

核心原理：利用 iesdouyin.com 分享页的 SSR 渲染特性，从 HTML 中提取嵌入的视频数据（window._ROUTER_DATA），无需浏览器 cookies 或 TikHub API Token。

前置条件

• ffmpeg：已安装在 /usr/local/bin/ffmpeg（用于元数据写入和音视频合并）
• Python 3：系统自带 /usr/bin/python3
• requests：Python HTTP 库（通常已安装）

工作流程

第一步：提取 aweme_id

从用户输入中提取视频的 aweme_id（19位数字ID）。支持以下输入格式：

第二步：从 iesdouyin 获取视频数据

请求 iesdouyin 分享页（无需 cookies）：

GET https://www.iesdouyin.com/share/video/{aweme_id}/
User-Agent: 移动端 Safari UA

从返回 HTML 中解析 window._ROUTER_DATA JSON 对象。关键数据路径：

_ROUTER_DATA.loaderData["video_(id)/page"].videoInfoRes.item_list[0]

从中提取：

• 视频标题（desc）
• 作者（author.nickname）
• 视频 URL 列表（video.play_addr.url_list）
• video_id（video.play_addr.uri，用于构建自定义 URL）
• 多码率列表（video.bit_rate[]）
• 下载地址（video.download_addr.url_list）

第三步：选择最佳视频源

按以下优先级选择视频 URL：

1. download_addr（通常无水印，优先级最高）
2. 自行构建无水印 URL：用 video_id + 遍历所有 ratio 参数，选文件最大的
• URL 模板：https://aweme.snssdk.com/aweme/v1/play/?video_id={video_id}&ratio={ratio}&line=0
• ratio 优先级：default > 1080p > 720p > 540p > 480p
• 关键：ratio=default 通常返回最高码率 HEVC 编码版本，比 1080p 更大
3. play_addr 中 playwm→play 替换：将有水印 URL 中的 playwm 替换为 play
4. bit_rate 中最高码率
5. play_addr 原始 URL（有水印，最后备选）

选择方式：对所有候选 URL 发送 HEAD 请求，比较 Content-Length，选最大的。

第四步：下载视频

使用 Python requests 流式下载，支持进度显示。请求头需包含：

User-Agent: 桌面端 Chrome UA
Referer: https://www.douyin.com/

第五步：写入元数据注释

使用 ffmpeg 将原始抖音链接写入 MP4 文件的 comment 元数据字段：

ffmpeg -y -i input.mp4 -c copy -metadata "comment=原始抖音链接URL" output.mp4

此操作为无损复制（-c copy），不重新编码，瞬间完成。

验证元数据：

ffmpeg -i output.mp4 -f ffmetadata -
# 输出中应包含: comment=https://v.douyin.com/XXXX/

使用脚本（推荐方式）

skill 包含完整的下载脚本 scripts/douyin_download.py，可直接运行：

# 基本用法
/usr/bin/python3 scripts/douyin_download.py "https://v.douyin.com/Jt5SfKMp5GE/" --output-dir /Users/dingo/Desktop/12

# 使用 aweme_id
/usr/bin/python3 scripts/douyin_download.py "7392175895160573218" --output-dir ~/Downloads

脚本路径：scripts/douyin_download.py（相对于 skill 目录）

脚本自动完成上述全部5个步骤：解析 ID → 获取数据 → 选择最佳源 → 下载 → 写入元数据。

批量下载

对于多个链接，逐个调用脚本即可：

for url in "https://v.douyin.com/xxx/" "https://v.douyin.com/yyy/"; do
    /usr/bin/python3 scripts/douyin_download.py "$url" --output-dir /目标目录
done

音视频分离处理

部分抖音视频（尤其是某些 ratio 参数）可能只包含视频轨道而无音频。脚本内置的多清晰度测试机制会自动选择包含音视频的版本（通常 ratio=default 包含完整音视频）。

如果确实遇到音视频分离的情况，处理方式：

1. 分别下载视频和音频文件
2. 使用 ffmpeg 合并：

ffmpeg -y -i video.mp4 -i audio.mp4 -c:v copy -c:a aac -metadata "comment=原始链接" output.mp4

故障排查

注意事项

• iesdouyin 方案无需 TikHub API Token、无需浏览器 cookies
• 下载的视频仅供个人学习使用，请尊重原创者版权
• 短链接有时效性，建议及时下载
• ratio=default 通常返回 HEVC(H.265) 编码的最高码率版本，文件较大但画质最好