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

## 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 | ⚪ 可选 | 完整作品信息 |

#### 配置示例
```yaml
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 批量视频下载

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

#### 配置示例
```yaml
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)
下载用户发布的所有作品（包括视频和图集）

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

##### 模式2：喜欢的作品 (like)
下载用户喜欢/收藏的作品（需要Cookie权限）

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

##### 模式3：所有合集 (mix)
下载用户创建的所有合集

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

##### 混合模式
同时下载多种类型的内容

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

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

---

### 3.5 合集下载

#### 功能描述
下载单个合集（专辑）内的所有作品。

#### 支持链接
- `https://www.douyin.com/collection/xxxxx`

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

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

---

### 3.6 音乐集合下载

#### 功能描述
下载使用特定背景音乐的所有作品。

#### 支持链接
- `https://www.douyin.com/music/xxxxx`

#### 配置示例
```yaml
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**
```bash
pip install playwright
playwright install chromium
```

**步骤2：运行工具**
```bash
python cookie_extractor.py
```

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

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

#### 提取模式

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

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

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

---

### 4.3 手动获取Cookie

#### 功能描述
通过浏览器开发者工具手动复制Cookie。

#### 工具名称
`get_cookies_manual.py`

#### 使用步骤

**步骤1：运行工具**
```bash
python get_cookies_manual.py
```

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

**步骤3：获取Cookie**

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

**步骤4：粘贴Cookie**
```
请粘贴Cookie内容:
[粘贴你复制的Cookie]
```

**步骤5：自动保存**
- 工具自动解析Cookie
- 验证Cookie有效性
- 保存到配置文件

#### 关键Cookie字段

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

---

### 4.4 Cookie配置方式

#### 方式1：自动获取（最简单）
```yaml
cookies: auto
```

#### 方式2：整串Cookie
```yaml
cookies: "msToken=xxx; ttwid=xxx; odin_tt=xxx; passport_csrf_token=xxx; sid_guard=xxx;"
```

#### 方式3：键值对方式
```yaml
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：环境变量
```bash
export DOUYIN_COOKIE="msToken=xxx; ttwid=xxx; ..."
python downloader.py -u "链接"
```

---

### 4.5 Cookie管理功能

#### Cookie验证
自动验证Cookie是否有效：
- 检查必需字段
- 测试API访问
- 显示验证结果

#### Cookie刷新
定期刷新Cookie保持有效性：
- 检测Cookie即将过期
- 自动重新获取
- 无缝更新配置

#### Cookie备份与恢复
```bash
# 备份
python get_cookies_manual.py
选择: 3. 备份Cookie

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

---

## 5. 下载控制功能

### 5.1 并发下载控制

#### 功能描述
控制同时下载的文件数量，提升下载效率。

#### 配置参数
```yaml
thread: 5        # 并发数量：1-20
```

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

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

---

### 5.2 智能重试机制

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

#### 配置参数
```yaml
retry_times: 3   # 重试次数：1-10
```

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

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

#### 不重试场景
- HTTP 404 内容不存在
- HTTP 403 权限不足
- Cookie失效
- 链接格式错误

---

### 5.3 速率限制

#### 功能描述
控制请求频率，避免触发反爬虫机制。

#### 限制策略
```python
max_per_second: 2      # 每秒最多2个请求
min_interval: 0.5      # 最小请求间隔500ms
```

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

#### 适用场景
- 大量批量下载
- 长时间运行
- 多用户主页下载
- 合集批量下载

---

### 5.4 增量下载

#### 功能描述
只下载新增内容，避免重复下载已有文件。

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

#### 工作原理
1. 数据库记录已下载作品ID
2. 获取内容列表时查询数据库
3. 跳过已下载的作品
4. 只下载新增作品
5. 下载完成后更新数据库

#### 数据库表结构
```sql
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
);
```

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

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

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

---

### 5.5 时间范围过滤

#### 功能描述
根据发布时间筛选要下载的内容。

#### 配置参数
```yaml
start_time: "2024-01-01"   # 开始时间
end_time: "2024-12-31"     # 结束时间
```

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

#### 过滤规则
| 配置 | 含义 |
|-----|------|
| start_time: "2024-01-01"<br>end_time: "" | 2024年1月1日之后的作品 |
| start_time: ""<br>end_time: "2024-12-31" | 2024年12月31日之前的作品 |
| start_time: "2024-01-01"<br>end_time: "2024-12-31" | 2024年全年的作品 |
| start_time: ""<br>end_time: "" | 不限制时间 |

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

---

### 5.6 数量限制

#### 功能描述
限制各类内容的下载数量。

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

#### 数量规则
- `0` = 下载全部
- `> 0` = 下载指定数量（最新的N个）

#### 示例配置

**场景1：只要最新内容**
```yaml
number:
  post: 10      # 只下载最新10个作品
```

**场景2：全部下载**
```yaml
number:
  post: 0       # 下载所有作品
```

**场景3：混合配置**
```yaml
number:
  post: 0       # 发布的全部下载
  like: 50      # 喜欢的只要50个
  allmix: 0     # 所有合集
  mix: 10       # 但每个合集只要10个作品
```

---

## 6. 数据管理功能

### 6.1 元数据保存

#### 功能描述
以JSON格式保存作品的完整信息。

#### 启用配置
```yaml
json: true       # 启用元数据保存
```

#### 保存内容

**视频作品元数据**
```json
{
  "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
  }
}
```

**图集作品元数据**
```json
{
  "aweme_id": "7123456789012345678",
  "desc": "图集标题",
  "images": [
    {
      "url": "https://...",
      "width": 1080,
      "height": 1440
    },
    ...
  ],
  "music": {...},
  "statistics": {...}
}
```

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

---

### 6.2 数据库记录

#### 功能描述
使用SQLite数据库记录下载历史和作品信息。

#### 启用配置
```yaml
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 | 文件保存路径 |

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

#### 数据库操作

**查询下载历史**
```sql
SELECT * FROM aweme ORDER BY download_time DESC LIMIT 10;
```

**统计下载数量**
```sql
SELECT COUNT(*) FROM aweme;
```

**按作者统计**
```sql
SELECT author_name, COUNT(*) as count
FROM aweme
GROUP BY author_id
ORDER BY count DESC;
```

---

### 6.3 文件组织管理

#### 功能描述
自动组织下载的文件，建立清晰的目录结构。

#### 启用配置
```yaml
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]/
    └── ...
```

**简化组织方式**
```yaml
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库显示美观的进度条：
- 实时更新进度百分比
- 显示当前下载速度
- 预估剩余时间
- 彩色状态标识