基于 FastAPI 的本地 Web 工具。扫码登录抖音后，可以下载单条视频，也可以把视频里的声音通过本机 ASR 转成可复制文案。
- 本地 Web 页面：访问
http://127.0.0.1:8787/使用。 - 扫码登录：通过 Playwright 获取抖音登录二维码，并保存 Cookie。
- 视频解析：解析单条抖音视频信息和可选清晰度。
- 下载任务：异步下载视频，前端轮询进度，完成后保存 MP4 文件。
- 字幕解析：自动发现本地完整的
small/medium模型，用户可在页面手动选择；默认使用small。 - 本地 ASR：使用 faster-whisper、CPU
int8识别视频语音，不依赖云端转写接口。 - 简体与标点：中文结果自动繁转简，并为缺少标点的中文分段和中文空格补基础逗号、句号。
- 文案结果：显示真实时间分段，页面全文、复制内容和 UTF-8 TXT 使用同一结果。
- 双 Tab 页面：“视频下载”和“字幕解析”共用本机 Cookie 与登录状态。
- 结果持久化：字幕清单和 TXT 保存在
data/transcripts/，重启后仍可查看。
macOS / Linux：
./start.shWindows：
start.bat也可以直接运行跨平台启动器：
python start.py启动后打开：
http://127.0.0.1:8787/
可通过环境变量调整监听地址：
HOST=0.0.0.0 PORT=8787 ./start.sh手动启动方式：
pip install -r requirements.txt
python -m playwright install chromium
python packaging/windows/download_model.py --model small --destination models/faster-whisper-small
# 可选：下载效果更好但速度更慢的 medium
python packaging/windows/download_model.py --model medium --destination models/faster-whisper-medium
python -m uvicorn api_server:app --host 127.0.0.1 --port 8787源码模式至少准备一个模型。程序只展示核心文件完整的本地模型，不会联网临时下载：
| 页面选项 | 本地目录 | 适用场景 |
|---|---|---|
Small |
models/faster-whisper-small/ |
默认，速度优先 |
Medium |
models/faster-whisper-medium/ |
效果更好，CPU 识别更慢 |
当前不支持 large-v3。Windows v1.2.0 完整绿色版同时附带 small 和 medium。
绿色版附带 Windows Python 运行时、Playwright Chromium、small/medium 模型和 OpenCC 数据。同事完整解压后双击 抖音视频工具.exe，程序会启动本地服务并打开默认浏览器；关闭控制台窗口即可退出。
可复现的 PyInstaller Windows 产物应在 Windows 环境构建。macOS 可以复用已经验证的 Windows 运行时组装绿色目录，但不能完成目标 Windows 双击验收。仓库提供手动工作流 .github/workflows/build-windows-portable.yml，也可以在 Windows PowerShell 中运行：
./packaging/windows/build.ps1输出：
releases/抖音视频工具-v1.2.0-win64.zip：首次发送的完整绿色版。
首发版本就是最新版本，不生成同版本更新包。后续版本需要更新包时，再使用 -BuildUpdatePackage -MinimumVersion "1.2.0" 构建。
详细构建和验收步骤见 docs/windows-release.md。
- 把
更新包-vX.Y.Z.zip放到绿色版程序根目录。 - 双击根目录
一键更新.bat。 - 更新器结束正在运行的工具，校验清单、文件大小和 SHA-256，再替换程序核心。
- 成功后自动重新启动；失败会恢复
_rollback/中的旧核心。
普通更新不会覆盖 config.json、douyin_cookie.txt、data/、downloads/、models/、browsers/ 或 一键更新.bat。更新包可以携带新版 updater.ps1：更新器会在核心程序更新成功后最后一步自更新自己（旧版会备份进 _rollback/）。v1.2.1 之前的旧更新器不支持该机制，且存在顶层目录名解析缺陷；旧安装应使用 修复包 一次完成更新器与程序更新：把 修复包-X.Y.Z.zip 内全部文件解压到根目录后双击 一键更新.bat 即可（在子文件夹里直接双击该 bat 也可以）。
首次安装必须发送完整绿色包；更新包不能代替完整包。
# 健康检查
curl http://127.0.0.1:8787/health
# 创建扫码登录会话，返回 session_id 和二维码 base64
curl -X POST http://127.0.0.1:8787/auth/session \
-H 'Content-Type: application/json' \
-d '{"qr_timeout":30}'
# 查询扫码状态
curl http://127.0.0.1:8787/auth/session/<session_id>
# 解析视频信息和可选清晰度
curl -X POST http://127.0.0.1:8787/parse/video \
-H 'Content-Type: application/json' \
-d '{"url":"抖音分享链接","session_id":"<session_id>"}'
# 创建带进度的下载任务
curl -X POST http://127.0.0.1:8787/download/video/task \
-H 'Content-Type: application/json' \
-d '{"url":"抖音分享链接","session_id":"<session_id>","quality":"1080p"}'
# 查询下载进度
curl http://127.0.0.1:8787/download/video/task/<task_id>
# 下载完成后获取 mp4 文件
curl -o douyin.mp4 http://127.0.0.1:8787/download/video/task/<task_id>/file
# 创建字幕任务
curl -X POST http://127.0.0.1:8787/transcription/tasks \
-H 'Content-Type: application/json' \
-d '{"url":"抖音分享链接","session_id":"<session_id>","model":"medium"}'
# 查看本机可选择的 ASR 模型
curl http://127.0.0.1:8787/asr/models
# 查询字幕任务详情
curl http://127.0.0.1:8787/transcription/tasks/<task_id>
# 下载 UTF-8 TXT 文案
curl -o transcript.txt http://127.0.0.1:8787/transcription/tasks/<task_id>/textdouyin-parse/
├── api_server.py # FastAPI 服务入口，托管 Web 页面和 API
├── web/index.html # 本地 Web 页面
├── docs/ # README 截图等说明资源
├── services/
│ ├── douyin_login.py # 扫码登录、Cookie 读写
│ ├── download_service.py # 视频解析和下载
│ ├── download_tasks.py # 异步下载任务
│ ├── transcription_service.py # faster-whisper 模型与语音转写
│ └── transcription_tasks.py # 单并发队列与字幕持久化
├── douyin_video_parser.py # 抖音视频解析核心逻辑
├── abogus.py # a_bogus 算法实现
├── xbogus.py # X-Bogus 算法实现
├── server_runtime.py # exe 内嵌/后台启动服务运行时
├── desktop_launcher.py # Windows EXE 启动入口
├── runtime_paths.py # 源码/绿色版便携路径
├── packaging/ # Windows 构建、更新与校验脚本
├── start.py # 跨平台源码启动器
├── start.sh # macOS/Linux 启动脚本
├── start.bat # Windows 启动脚本
├── tests/test_local_api_helpers.py
└── requirements.txt
以下文件或目录由本地运行产生，不应提交到远程仓库：
config.json：保存 Cookie 和下载目录配置。douyin_cookie.txt：旧版本 Cookie 文件。当前版本首次读取后会迁移到config.json并删除该文件。downloads/：默认下载目录。data/transcripts/：字幕任务 JSON 清单与 TXT 文案。models/faster-whisper-small/：本地 Small ASR 模型。models/faster-whisper-medium/：本地 Medium ASR 模型。__pycache__/：Python 缓存。
先在页面中创建扫码登录会话并完成登录，或者确认 config.json 中已有有效 Cookie。
程序会区分以下情况并给出对应提示：
| 提示 | 原因 | 处理 |
|---|---|---|
| 无法识别视频链接 | 链接不是抖音视频/图集分享链接 | 重新复制抖音 App 的分享链接 |
| Cookie 已失效，请在页面上重新扫码登录 | 登录态过期 | 在页面重新扫码登录 |
| 请求被抖音风控拦截（签名校验未通过） | 抖音升级风控，程序签名方案过时 | 更新程序版本 |
| 请求过于频繁被抖音限流 | 短时间解析太多次 | 稍等一分钟再试 |
| 请求抖音超时 / 网络请求失败 | 本机网络问题 | 检查网络后重试 |
| 抖音返回错误（status_code=…）或未返回作品数据 | 作品不存在、已删除或不可见 | 换个作品链接 |
| 当前页面只支持视频，不支持图集 | 链接是图集 | 暂不支持图集下载 |
2026-09 起抖音对网页接口启用了 Argus 风控（x-secsdk-web-signature 签名校验），解析请求已按对应算法签名。如果再次出现“被抖音风控拦截”，说明抖音更换了签名盐值，需要更新 douyin_video_parser.py 中的 WEB_SIGN_SALT。
源码模式执行：
python packaging/windows/download_model.py --model small --destination models/faster-whisper-small如果选择 medium，对应目录必须是 models/faster-whisper-medium/。绿色版出现该错误说明发布包不完整，应重新解压完整绿色版；不要用普通更新包代替首次安装包。
简体和基础标点处理只应用于升级后新创建的字幕任务。历史任务不会自动改写；使用原链接重新识别一次即可。
当前版本针对 i5-10400F 使用 CPU int8，以减少 CUDA/cuDNN 体积和驱动兼容问题。程序不承诺固定识别耗时，字幕任务会单并发运行以避免整机过载；medium 通常比 small 更慢。
确认已安装依赖并执行过：
python -m playwright install chromium本工具仅供学习交流使用，请勿用于商业用途。下载的视频请遵守相关法律法规和平台规定。