douyin-video-downloader Skill

本 skill 是一个本地 Node.js 抖音视频与直接音频下载工具。

功能

• 获取抖音视频信息
• 列出可用视频清晰度/码率候选
• 按指定清晰度下载 MP4
• 下载视频时同步下载封面图，默认选择中档尺寸
• 支持单独下载封面图
• 下载抖音音乐详情接口暴露的直接音频文件
• 从采集库批量下载直接音频
• 用本地 SQLite 采集库记录用户、列表页、视频、统计和音乐信息
• 自动打开用户主页并复用本地浏览器登录态，自动翻页采集列表
• 下载完整性检查、临时文件保护和有限重试（视频、封面、直接音频共用）
• 从采集库导出 JSON/CSV，或按批次下载库里的视频
• 默认尽量使用无水印播放地址

使用方法

先确定 {SKILL_DIR} 为本 SKILL.md 所在目录。

查看视频信息、清晰度和封面候选

node {SKILL_DIR}/douyin-video.js info "抖音分享链接" --cover-size medium

下载默认清晰度

node {SKILL_DIR}/douyin-video.js download "抖音分享链接" -o ./videos

默认选择 best，即脚本能识别到的最高质量候选。

视频下载会同时下载封面图，并把视频、封面和 metadata 路径都写入 metadata JSON。

指定清晰度下载

node {SKILL_DIR}/douyin-video.js download "抖音分享链接" --quality best -o ./videos
node {SKILL_DIR}/douyin-video.js download "抖音分享链接" --quality 720p -o ./videos
node {SKILL_DIR}/douyin-video.js download "抖音分享链接" --quality 0 -o ./videos

--quality 支持：

• best：最高质量
• lowest：最低质量
• 720p / 1080p 这类清晰度标签
• 数字序号：使用 info 输出中的候选序号
• ratio、format、gear_name 等候选标签的部分匹配

指定封面尺寸下载

node {SKILL_DIR}/douyin-video.js download "抖音分享链接" --cover-size medium -o ./videos
node {SKILL_DIR}/douyin-video.js download "抖音分享链接" --cover-size origin -o ./videos
node {SKILL_DIR}/douyin-video.js download "抖音分享链接" --cover-size 0 -o ./videos
node {SKILL_DIR}/douyin-video.js cover "抖音分享链接" --cover-size medium -o ./videos

--cover-size 支持：

• medium：默认，中档尺寸
• small：较小封面候选
• large / best：按返回宽高选择较大封面
• origin：原始封面字段
• raw：原始/未处理封面字段
• dynamic / animated：动态封面候选
• gaussian / blur：模糊封面候选
• 数字序号：使用 info 输出中的封面候选序号
• none：不下载封面

下载直接音频

node {SKILL_DIR}/douyin-video.js audio "抖音分享链接" -o ./audios

audio 命令会先解析视频对应的 music.mid/id，再请求抖音音乐详情接口获取 music.play_url 并下载原始音频文件。没有直接音频地址时会报错，不会从 MP4 中抽取音频。

视频、封面和音频命令会合并写入同一个 metadata JSON，不会因为后执行音频而覆盖之前的视频或封面文件路径。

创建 SQLite 采集库

node {SKILL_DIR}/douyin-video.js db-init --db ./douyin_collection.sqlite

采集库包含：

• users：用户资料
• crawl_pages：每次列表页接口响应
• videos：视频标题、链接、封面、时长、发布时间等
• video_stats：点赞、评论、收藏、转发、播放、下载等统计字段
• music：音乐 ID、标题、作者、时长、直接音频地址等
• video_downloads：后续批量下载的成功/失败状态、文件路径和错误信息
• media_downloads：音频等媒体文件的成功/失败状态、文件路径和错误信息

导入用户视频列表接口 JSON

用户主页列表通常需要登录态和抖音 Web 签名参数。先用浏览器打开用户主页并登录，再把 /aweme/v1/web/aweme/post/ 接口响应体保存成 JSON 文件，然后导入：

node {SKILL_DIR}/douyin-video.js db-import-post-json \
  --db ./douyin_collection.sqlite \
  --input ./post_1036.json \
  --limit 100

默认规则：同一个用户列表只采集前 100 条视频信息。可以重复导入多个分页 JSON；同一个 aweme_id 会覆盖更新，不会重复插入；达到 100 条后继续导入分页只记录列表页响应，不再插入新视频。

采集完成后，必须告知用户已经抓取完毕，并询问是否开始下载。不能在采集完成后自动下载全部视频。

自动采集用户主页

node {SKILL_DIR}/douyin-video.js collect-user "抖音用户主页 URL" \
  --db ./douyin_collection.sqlite \
  -o ./collection \
  --account default \
  --limit 100

collect-user 会：

• 使用固定浏览器 profile；指定 --account 时使用 ~/.agents/douyin-video-downloader/accounts/<account>/browser-profile
• 优先复用已有登录态；如果 sessionid / sid_guard 有效，就直接抓取
• 如果登录态不可用，打开浏览器并提示用户扫码登录
• 等用户登录后继续抓取 /aweme/v1/web/aweme/post/
• 清理旧页面请求列表，从请求游标 max_cursor=0 的第一页开始；按顺序处理预加载页，再滚动作品列表触发下一页
• 每页请求游标必须等于上一页响应游标，确保分页衔接；逐页保存原始 JSON 和导入 SQLite
• 达到上限、has_more=0 时正常结束；游标重复、无新增作品、接口异常或下一页超时时停止并保留已采集数据
• 导出 JSON/CSV；后续页失败时也导出已经采集的数据
• 采集完成后只提示完成，不自动下载

默认采集库上限为 100 条；--limit 0 表示不设作品数量上限（仍有 1000 页安全上限）。重复作品更新现有记录，不占用新增名额。达到上限时仍可更新当前页的已有记录。

检查登录状态

node {SKILL_DIR}/douyin-video.js check-login --account default

check-login 会打开或复用账号对应的浏览器 profile，并检查抖音登录 cookie 是否可用。登录有效时返回 0；未登录时返回 2，并提示用户在打开的浏览器里扫码登录。这个命令只检查登录状态，不采集、不下载。

可选参数：

--account default
--browser-session douyin-video-downloader
--profile-dir ~/.agents/douyin-video-downloader/browser-profile
--login-timeout 180
--reuse-session

--account 是推荐的账号隔离方式。没有指定 --profile-dir 时，账号名会自动映射到独立 browser profile；没有指定 --browser-session 时，账号名也会用于生成稳定 session 名称。--browser-session 会被规范为较短的安全名称，避免 Playwright CLI socket 路径过长。已有登录浏览器 session 时，可以加 --reuse-session 直接复用，不重新打开浏览器。

如果本机没有 Playwright CLI 运行环境，命令会提示安装依赖，不会自动安装。

导出采集库

node {SKILL_DIR}/douyin-video.js db-export --db ./douyin_collection.sqlite -o ./videos.json
node {SKILL_DIR}/douyin-video.js db-export --db ./douyin_collection.sqlite -o ./videos.csv --format csv

从采集库按批下载视频

node {SKILL_DIR}/douyin-video.js db-download-batch \
  --db ./douyin_collection.sqlite \
  -o ./videos \
  --quality best \
  --cover-size medium \
  --delay-seconds 5 \
  --confirm-every 10 \
  --download-limit 100

批量下载按采集库里的列表页地址顺序处理：第一个网址下载完成后，至少等待 5 秒，再打开第二个网址。下载地址、封面和 metadata 优先从 SQLite 中保存的列表接口 raw_json 生成，只有缺少原始数据时才回退到重新解析视频页。每个视频下载时默认同步下载中档封面，可用 --cover-size 选择其他封面尺寸。每成功下载 10 个视频后必须询问用户是否继续；用户确认继续后，才能继续下载。--download-limit 是本次命令的总下载上限。已成功下载的视频会记录在 video_downloads 表中，后续同一清晰度会跳过。

从采集库批量下载音频

node {SKILL_DIR}/douyin-video.js db-download-audio-batch \
  --db ./douyin_collection.sqlite \
  -o ./audios \
  --delay-seconds 5 \
  --download-limit 100

批量音频下载优先使用采集库 music.play_url 中的直接音频地址，不从视频抽取音频。下载状态记录在 media_downloads 表中；已成功下载的音频会跳过。每条音频之间至少等待 5 秒，--download-limit 是本次命令的总下载上限。

注意

• 下载和采集能力依赖抖音页面结构、Web 接口和 CDN 地址规则，平台调整后可能需要更新解析逻辑。
• 用户主页列表接口通常需要登录浏览器上下文；本 skill 不包含登录绕过逻辑。
• 音频下载只使用抖音音乐详情接口返回的直接音频地址，不会用 ffmpeg 从视频中抽取。
• 列表采集和视频下载是两个独立步骤；没有用户确认时，不执行批量下载。
• 下载进度默认每 5% 输出一次；需要更安静时可以加 --quiet。

下载可靠性

• 视频、封面和直接音频统一使用最多 4 次下载尝试（首次 + 3 次重试）。
• 网络中断、60 秒无数据超时、HTTP 408/425/429 和 5xx 可重试，等待默认为 1/2/4 秒；参考 Retry-After，但单次等待最多 30 秒。
• 其他 HTTP 错误、HTML/JSON 页面和本地磁盘权限或空间错误直接失败。
• 每次重试从零开始写独立 .part 临时文件，避免拼接重复数据；本版本不做跨进程断点续传。
• 完成时校验 HTTP 流正常结束、文件非空；有 Content-Length 时要求字节数完全一致。没有长度时只能验证完整 HTTP 流，不能确认源站媒体本身是否完整。
• 校验通过后才将临时文件重命名为最终文件；失败清理本次临时文件并保留之前的正式文件。强制终止进程可能留下 .part，后续下载不会复用它。
• 这些检查不等于媒体解码检查或源站哈希校验。遇到验证页面时交由用户正常处理，不绕过验证。

开发验证

运行 npm test 执行离线回归测试，覆盖多页采集、去重和上限、截断与超时重试、正式文件保护，以及清晰度/封面/直接音频兼容性。