huanghai/aiData

Fork 0

Files

HuangHai d89388ab51 'commit'

2026-01-20 14:05:19 +08:00

20 KiB

Raw Blame History

抖音下载器 - 功能需求文档

1. 产品概述

1.1 产品定义

抖音批量下载器是一个基于Python的命令行工具，提供抖音平台内容的批量下载能力，支持视频、图集、音乐、直播等多种内容类型的无水印下载。

1.2 核心价值

无水印下载 - 去除抖音水印，获得原始高清内容
批量处理 - 支持用户主页、合集等批量下载
完整元数据 - 保存作品完整信息（标题、作者、发布时间等）
自动化管理 - 自动Cookie获取、智能重试、增量更新
灵活配置 - 支持多种配置方式和自定义选项

2. 核心功能列表

2.1 功能模块总览

抖音下载器功能架构
│
├── 📥 内容下载功能
│   ├── 单个视频下载
│   ├── 批量视频下载
│   ├── 图集下载
│   ├── 用户主页下载
│   ├── 合集下载
│   ├── 音乐集合下载
│   └── 直播下载
│
├── 🍪 认证管理功能
│   ├── 自动获取Cookie
│   ├── 手动配置Cookie
│   ├── Cookie验证
│   └── Cookie刷新
│
├── ⚙️ 下载控制功能
│   ├── 并发下载控制
│   ├── 智能重试机制
│   ├── 速率限制
│   ├── 增量下载
│   ├── 时间范围过滤
│   └── 数量限制
│
├── 💾 数据管理功能
│
└── 🔧 配置管理功能

2.2 功能优先级

优先级	功能模块	包含功能
P0 核心	单个视频下载	单个视频无水印下载
P0 核心	批量下载	用户主页批量下载
P0 核心	Cookie管理	自动/手动获取Cookie
P1 重要	多类型下载	图集、合集、音乐下载
P1 重要	增量更新	只下载新增内容
P1 重要	元数据保存	JSON格式完整信息
P2 优化	附加内容	封面、头像、音乐下载
P2 优化	下载控制	重试、速率限制、数量控制
P3 扩展	时间过滤	按时间范围筛选内容
P3 扩展	直播下载	实时直播流录制

3. 下载功能详细说明

3.1 单个视频下载

功能描述

下载单个抖音视频，支持短链接和直链两种格式。

支持链接

分享短链接：https://v.douyin.com/xxxxx/
网页直链：https://www.douyin.com/video/1234567890123456789

下载内容

内容项	格式	是否必需	说明
视频文件	MP4	✅ 必需	无水印视频
视频封面	JPG	⚪ 可选	作品封面图
背景音乐	MP3	⚪ 可选	原声音频
作者头像	JPG	⚪ 可选	作者头像图片
元数据	JSON	⚪ 可选	完整作品信息

配置示例

link:
  - https://v.douyin.com/xxxxx/
music: true      # 是否下载音乐
cover: true      # 是否下载封面
avatar: true     # 是否下载头像
json: true       # 是否保存元数据

文件命名规则

[作品标题]_[作品ID].mp4
[作品标题]_[作品ID]_cover.jpg
[作品标题]_[作品ID]_music.mp3
[作品标题]_[作品ID]_data.json

3.2 批量视频下载

功能描述

支持多个链接批量下载，可同时处理多个单独的视频链接。

配置示例

link:
  - https://v.douyin.com/xxxxx1/
  - https://v.douyin.com/xxxxx2/
  - https://www.douyin.com/video/1234567890123456789
  - https://www.douyin.com/video/9876543210987654321
thread: 5        # 并发下载数量

批量处理特性

支持任意数量视频链接
并发下载提升效率
单个失败不影响其他
实时进度显示
统计下载成功/失败数量

3.3 图集下载

功能描述

下载抖音图文作品（图集），支持多图作品的完整下载。

支持链接

https://www.douyin.com/note/xxxxx

下载内容

内容项	说明
所有图片	JPG格式，无水印
背景音乐	MP3格式
作者头像	JPG格式
元数据	JSON格式，包含图片列表

文件组织结构

Downloaded/
└── [作者昵称]/
    └── [作品标题]_[作品ID]/
        ├── [作品标题]_1.jpg
        ├── [作品标题]_2.jpg
        ├── [作品标题]_3.jpg
        ├── [作品标题]_music.mp3
        ├── avatar.jpg
        └── data.json

3.4 用户主页下载

功能描述

批量下载指定用户主页的所有作品，支持多种下载模式。

支持链接

https://www.douyin.com/user/MS4wLjABAAAA...

下载模式

模式1：发布的作品 (post)

下载用户发布的所有作品（包括视频和图集）

link:
  - https://www.douyin.com/user/xxxxx
mode:
  - post
number:
  post: 0          # 0表示全部，>0表示最新N个
increase:
  post: false      # 是否增量下载

模式2：喜欢的作品 (like)

下载用户喜欢/收藏的作品（需要Cookie权限）

mode:
  - like
number:
  like: 50         # 下载最近喜欢的50个作品
increase:
  like: true       # 启用增量更新

模式3：所有合集 (mix)

下载用户创建的所有合集

mode:
  - mix
number:
  allmix: 0        # 合集数量，0表示全部
  mix: 0           # 每个合集内作品数量
increase:
  allmix: false
  mix: false

混合模式

同时下载多种类型的内容

mode:
  - post           # 发布的作品
  - like           # 喜欢的作品
  - mix            # 所有合集

文件组织结构

Downloaded/
└── [作者昵称]_[用户ID]/
    ├── post/                    # 发布的作品
    │   ├── [作品1]/
    │   ├── [作品2]/
    │   └── ...
    ├── like/                    # 喜欢的作品
    │   ├── [作品1]/
    │   └── ...
    └── mix/                     # 合集
        ├── [合集1名称]/
        │   ├── [作品1]/
        │   └── ...
        └── [合集2名称]/
            └── ...

3.5 合集下载

功能描述

下载单个合集（专辑）内的所有作品。

支持链接

https://www.douyin.com/collection/xxxxx

配置示例

link:
  - https://www.douyin.com/collection/7123456789012345678
number:
  mix: 0           # 下载数量，0=全部
increase:
  mix: false       # 增量更新

下载内容

合集内所有作品（视频/图集）
每个作品的完整信息
合集元数据（JSON）

3.6 音乐集合下载

功能描述

下载使用特定背景音乐的所有作品。

支持链接

https://www.douyin.com/music/xxxxx

配置示例

link:
  - https://www.douyin.com/music/7123456789012345678
number:
  music: 20        # 下载前20个使用该音乐的作品
increase:
  music: false

应用场景

收集热门音乐相关作品
研究音乐使用趋势
素材收集

3.7 直播下载

功能描述

录制正在进行的直播流（实验性功能）。

支持链接

https://live.douyin.com/xxxxx

功能特性

实时直播流录制
自动检测直播状态
断线自动重连
分段保存直播文件

注意事项

需要主播开播状态
录制质量取决于直播质量
文件大小较大，注意磁盘空间

4. Cookie管理功能

4.1 为什么需要Cookie

抖音API需要用户登录状态才能访问内容，Cookie包含登录凭证：

访问用户主页内容
下载喜欢的作品
获取完整视频信息
避免访问限制

4.2 自动获取Cookie（推荐）

功能描述

使用Playwright自动化工具，打开浏览器自动获取Cookie。

工具名称

cookie_extractor.py

使用步骤

步骤1：安装Playwright

pip install playwright
playwright install chromium

步骤2：运行工具

python cookie_extractor.py

步骤3：选择提取方式

请选择Cookie提取方式:
1. 使用浏览器自动提取（推荐）
2. 从已有浏览器复制Cookie
请输入选项 (1-2): 1

步骤4：完成登录

工具自动打开浏览器
在浏览器中扫码/输入手机号登录
登录成功后工具自动提取Cookie
Cookie自动保存到配置文件

提取模式

模式	说明	适用场景
可视模式	显示浏览器窗口	首次使用、调试
无头模式	后台运行	自动化脚本

配置方式

# 方式1：配置文件指定自动获取
cookies: auto

# 方式2：配置选项指定
auto_cookie: true

4.3 手动获取Cookie

功能描述

通过浏览器开发者工具手动复制Cookie。

工具名称

get_cookies_manual.py

使用步骤

步骤1：运行工具

python get_cookies_manual.py

步骤2：选择功能

Cookie管理工具
1. 获取新的Cookie
2. 查看当前Cookie
3. 备份Cookie
4. 恢复Cookie
5. 退出
请选择 (1-5): 1

步骤3：获取Cookie

打开浏览器访问 https://www.douyin.com
登录你的抖音账号
按 F12 打开开发者工具
切换到 Network 标签
刷新页面（F5）
点击任意请求
在请求头中找到 Cookie 字段
复制整个Cookie字符串

步骤4：粘贴Cookie

请粘贴Cookie内容:
[粘贴你复制的Cookie]

步骤5：自动保存

工具自动解析Cookie
验证Cookie有效性
保存到配置文件

关键Cookie字段

字段名	必需性	说明
msToken	✅ 必需	主要认证令牌
ttwid	✅ 必需	设备标识
odin_tt	✅ 必需	用户标识
passport_csrf_token	⚪ 可选	CSRF保护
sid_guard	⚪ 可选	会话保护

4.4 Cookie配置方式

方式1：自动获取（最简单）

cookies: auto

方式2：整串Cookie

cookies: "msToken=xxx; ttwid=xxx; odin_tt=xxx; passport_csrf_token=xxx; sid_guard=xxx;"

方式3：键值对方式

cookies:
  msToken: YOUR_MS_TOKEN_HERE
  ttwid: YOUR_TTWID_HERE
  odin_tt: YOUR_ODIN_TT_HERE
  passport_csrf_token: YOUR_CSRF_TOKEN_HERE
  sid_guard: YOUR_SID_GUARD_HERE

方式4：环境变量

export DOUYIN_COOKIE="msToken=xxx; ttwid=xxx; ..."
python downloader.py -u "链接"

4.5 Cookie管理功能

Cookie验证

自动验证Cookie是否有效：

检查必需字段
测试API访问
显示验证结果

Cookie刷新

定期刷新Cookie保持有效性：

检测Cookie即将过期
自动重新获取
无缝更新配置

Cookie备份与恢复

# 备份
python get_cookies_manual.py
选择: 3. 备份Cookie

# 恢复
python get_cookies_manual.py
选择: 4. 恢复Cookie

5. 下载控制功能

5.1 并发下载控制

功能描述

控制同时下载的文件数量，提升下载效率。

配置参数

thread: 5        # 并发数量：1-20

并发策略

低并发 (1-3)：网络不稳定时使用
中并发 (5-10)：默认推荐配置
高并发 (10-20)：网络条件好时使用

性能影响

并发数	速度	CPU占用	网络占用	适用场景
1-3	慢	低	低	网络不稳定
5-10	快	中	中	日常使用
10-20	很快	高	高	批量下载

5.2 智能重试机制

功能描述

下载失败时自动重试，提高下载成功率。

配置参数

retry_times: 3   # 重试次数：1-10

重试策略

第1次失败 → 等待1秒 → 重试
第2次失败 → 等待2秒 → 重试
第3次失败 → 等待5秒 → 重试
第4次失败 → 标记失败，记录日志

重试场景

网络连接超时
HTTP 5xx 服务器错误
HTTP 429 请求过多
临时网络故障
数据传输中断

不重试场景

HTTP 404 内容不存在
HTTP 403 权限不足
Cookie失效
链接格式错误

5.3 速率限制

功能描述

控制请求频率，避免触发反爬虫机制。

限制策略

max_per_second: 2      # 每秒最多2个请求
min_interval: 0.5      # 最小请求间隔500ms

保护机制

自动控制请求速度
避免账号被封禁
避免IP被限制
符合平台使用规范

适用场景

大量批量下载
长时间运行
多用户主页下载
合集批量下载

5.4 增量下载

功能描述

只下载新增内容，避免重复下载已有文件。

启用条件

database: true           # 必须启用数据库
increase:
  post: true            # 对应模式启用增量
  like: true
  mix: true

工作原理

数据库记录已下载作品ID
获取内容列表时查询数据库
跳过已下载的作品
只下载新增作品
下载完成后更新数据库

数据库表结构

CREATE TABLE aweme (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    aweme_id TEXT UNIQUE NOT NULL,
    desc TEXT,
    create_time INTEGER,
    download_time INTEGER,
    author_id TEXT,
    author_name TEXT
);

应用场景

定期备份：每天/每周备份新作品
持续监控：跟踪用户更新
节省空间：不重复下载
节省时间：跳过已有内容

示例使用

# 首次下载：下载所有作品
link:
  - https://www.douyin.com/user/xxxxx
mode:
  - post
increase:
  post: false
database: true

# 后续更新：只下载新作品
increase:
  post: true   # 改为true启用增量

5.5 时间范围过滤

功能描述

根据发布时间筛选要下载的内容。

配置参数

start_time: "2024-01-01"   # 开始时间
end_time: "2024-12-31"     # 结束时间

时间格式

标准格式：YYYY-MM-DD
例如：2024-01-01、2024-12-31
留空表示不限制

过滤规则

配置	含义
start_time: "2024-01-01" end_time: ""	2024年1月1日之后的作品
start_time: "" end_time: "2024-12-31"	2024年12月31日之前的作品
start_time: "2024-01-01" end_time: "2024-12-31"	2024年全年的作品
start_time: "" end_time: ""	不限制时间

应用场景

下载特定时期的作品
限定活动期间的内容
只要最新的N天内容
排除旧内容

5.6 数量限制

功能描述

限制各类内容的下载数量。

配置参数

number:
  post: 50      # 用户发布的作品数量
  like: 30      # 用户喜欢的作品数量
  allmix: 5     # 下载的合集数量
  mix: 20       # 单个合集内作品数量
  music: 10     # 音乐集合作品数量

数量规则

0 = 下载全部
> 0 = 下载指定数量（最新的N个）

示例配置

场景1：只要最新内容

number:
  post: 10      # 只下载最新10个作品

场景2：全部下载

number:
  post: 0       # 下载所有作品

场景3：混合配置

number:
  post: 0       # 发布的全部下载
  like: 50      # 喜欢的只要50个
  allmix: 0     # 所有合集
  mix: 10       # 但每个合集只要10个作品

6. 数据管理功能

6.1 元数据保存

功能描述

以JSON格式保存作品的完整信息。

启用配置

json: true       # 启用元数据保存

保存内容

视频作品元数据

{
  "aweme_id": "7123456789012345678",
  "desc": "作品标题/描述",
  "create_time": 1704038400,
  "author": {
    "uid": "MS4wLjABAAAA...",
    "nickname": "作者昵称",
    "avatar_url": "https://..."
  },
  "video": {
    "play_url": "https://...",
    "cover_url": "https://...",
    "duration": 15,
    "ratio": "720p"
  },
  "music": {
    "title": "音乐名称",
    "author": "音乐作者",
    "play_url": "https://..."
  },
  "statistics": {
    "digg_count": 1234,
    "comment_count": 567,
    "share_count": 89,
    "play_count": 12345
  }
}

图集作品元数据

{
  "aweme_id": "7123456789012345678",
  "desc": "图集标题",
  "images": [
    {
      "url": "https://...",
      "width": 1080,
      "height": 1440
    },
    ...
  ],
  "music": {...},
  "statistics": {...}
}

应用场景

数据分析和研究
内容管理和检索
批量处理和编辑
信息备份和归档

6.2 数据库记录

功能描述

使用SQLite数据库记录下载历史和作品信息。

启用配置

database: true   # 启用数据库

数据库文件

文件名：data.db
格式：SQLite 3
位置：项目根目录

表结构

aweme表（作品记录）

字段	类型	说明
id	INTEGER	主键，自增
aweme_id	TEXT	作品唯一ID（唯一索引）
desc	TEXT	作品描述
create_time	INTEGER	发布时间戳
download_time	INTEGER	下载时间戳
author_id	TEXT	作者ID
author_name	TEXT	作者昵称
aweme_type	TEXT	作品类型（video/image）
file_path	TEXT	文件保存路径

功能特性

自动记录下载历史
支持增量下载判断
防止重复下载
下载统计和查询
数据持久化保存

数据库操作

查询下载历史

SELECT * FROM aweme ORDER BY download_time DESC LIMIT 10;

统计下载数量

SELECT COUNT(*) FROM aweme;

按作者统计

SELECT author_name, COUNT(*) as count
FROM aweme
GROUP BY author_id
ORDER BY count DESC;

6.3 文件组织管理

功能描述

自动组织下载的文件，建立清晰的目录结构。

启用配置

folderstyle: true    # 启用文件夹组织

组织结构

标准组织方式

Downloaded/
├── [作者昵称1]_[用户ID]/
│   ├── post/                           # 发布的作品
│   │   ├── [作品标题1]_[ID]/
│   │   │   ├── [作品标题1].mp4
│   │   │   ├── [作品标题1]_cover.jpg
│   │   │   ├── [作品标题1]_music.mp3
│   │   │   ├── avatar.jpg
│   │   │   └── data.json
│   │   └── [作品标题2]_[ID]/
│   │       └── ...
│   ├── like/                           # 喜欢的作品
│   │   └── ...
│   └── mix/                            # 合集
│       ├── [合集名称1]/
│       │   └── ...
│       └── [合集名称2]/
│           └── ...
└── [作者昵称2]_[用户ID]/
    └── ...

简化组织方式

folderstyle: false   # 禁用文件夹组织

Downloaded/
├── [作品标题1]_[ID].mp4
├── [作品标题1]_[ID]_cover.jpg
├── [作品标题2]_[ID].mp4
└── ...

命名规则

文件名安全处理

移除特殊字符：/ \ : * ? " < > |
替换为下划线：_
限制长度：最多100字符
保留扩展名

示例

原标题：今天天气真好！#旅行 #vlog
文件名：今天天气真好_旅行_vlog_7123456789012345678.mp4

6.4 下载统计

功能描述

实时显示下载进度和统计信息。

统计信息

下载过程中显示

正在下载: [作品标题]
进度: [████████--] 80% (8/10)
成功: 7 | 失败: 1 | 跳过: 0
速度: 2.5 MB/s
剩余时间: 00:02:15

下载完成后显示

========================================
下载完成统计
========================================
总计: 100
成功: 95
失败: 3
跳过: 2
成功率: 95.0%
耗时: 00:15:32
========================================

实时进度条

使用Rich库显示美观的进度条：

实时更新进度百分比
显示当前下载速度
预估剩余时间
彩色状态标识

20 KiB Raw Blame History Unescape Escape

抖音下载器 - 功能需求文档

1. 产品概述

1.1 产品定义

1.2 核心价值

2. 核心功能列表

2.1 功能模块总览

2.2 功能优先级

3. 下载功能详细说明

3.1 单个视频下载

功能描述

支持链接

下载内容

配置示例

文件命名规则

3.2 批量视频下载

功能描述

配置示例

批量处理特性

3.3 图集下载

功能描述

支持链接

下载内容

文件组织结构

3.4 用户主页下载

功能描述

支持链接

下载模式

模式1：发布的作品 (post)

模式2：喜欢的作品 (like)

模式3：所有合集 (mix)

混合模式

文件组织结构

3.5 合集下载

功能描述

支持链接

配置示例

下载内容

3.6 音乐集合下载

功能描述

支持链接

配置示例

应用场景

3.7 直播下载

功能描述

支持链接

功能特性

注意事项

4. Cookie管理功能

4.1 为什么需要Cookie

4.2 自动获取Cookie（推荐）

功能描述

工具名称

使用步骤

提取模式

配置方式

4.3 手动获取Cookie

功能描述

工具名称

使用步骤

关键Cookie字段

4.4 Cookie配置方式

方式1：自动获取（最简单）

方式2：整串Cookie

方式3：键值对方式

方式4：环境变量

4.5 Cookie管理功能

Cookie验证

Cookie刷新

Cookie备份与恢复

5. 下载控制功能

5.1 并发下载控制

功能描述

配置参数

并发策略

性能影响

5.2 智能重试机制

功能描述

配置参数

重试策略

20 KiB

Raw Blame History