抖音视频文案提取 & 本地音视频转录

一句话定位

从抖音链接或本地媒体文件提取语音 → Whisper 本地转录为中文文本 → agent 整理纠错 → 输出可读 Markdown。

触发场景（满足任一即命中）

抖音链接场景

本地媒体文件场景

> 关键判断逻辑：用户消息中同时出现「抖音链接/分享文本」或「本地媒体文件路径」+「获取文本内容」的意图时触发。

> 文件路径可以是绝对路径（如 D:\videos\test.mp4）、相对路径（如 ./recording.wav），或 WorkBuddy 的 @"..." 附件引用语法。

Agent 执行指引

> 跨机器迁移注意：.env_config.json 由 setup_env.py 自动生成，包含机器特定路径。

> 迁移到新机器后必须重新运行 python scripts/setup_env.py，不能直接复制配置文件。

执行此技能时，agent 必须按以下顺序确定 Python 解释器：

import json, os
from pathlib import Path

SKILL_DIR = Path("{skill_install_dir}")  # 运行时替换为实际安装路径
config_file = SKILL_DIR / ".env_config.json"

if config_file.exists():
    config = json.loads(config_file.read_text())
    PYTHON_EXE = config["venv_python"]    # 如 /path/to/venv/bin/python
else:
    # 环境未配置，提示用户运行 setup_env.py
    print("请先运行: python scripts/setup_env.py")
    sys.exit(1)

所有脚本必须用 PYTHON_EXE 运行，不得使用系统默认 python。

快速开始

# 1. 首次使用：配置环境（仅需一次）
python scripts/setup_env.py

# 2a. 抖音链接 → 转录
python scripts/fetch_douyin_video.py <抖音短链接>

# 2b. 抖音链接 → 转录（指定输出目录）
python scripts/fetch_douyin_video.py <抖音短链接> --output ./result

# 2c. 本地文件 → 转录
python scripts/transcribe_local.py <视频或音频文件路径>

# 2d. 本地文件 → 转录（指定输出目录）
python scripts/transcribe_local.py audio.mp3 --output ./result

首次配置

scripts/setup_env.py 自动完成以下全部步骤：

1. 检测兼容的 Python（需要 3.10–3.12，不兼容 3.13）
2. 创建独立 venv（位于 {skill_dir}/venv/）
3. 按正确顺序安装依赖：numpy<2 → requests/imageio[ffmpeg] → playwright → openai-whisper
4. 安装 Chromium 浏览器（Playwright 使用）
5. 验证所有包可正常导入
6. 保存配置到 .env_config.json（后续脚本自动读取）

python scripts/setup_env.py
python scripts/setup_env.py --force           # 强制重建
python scripts/setup_env.py --mirror=pypi     # 使用官方源

环境要求

环境验证

python scripts/verify_env.py       # 检查所有依赖
python scripts/verify_env.py --fix # 检查并自动修复
python scripts/verify_env.py --json # JSON 输出（供程序调用）

工作流程

模式 A：抖音链接 → 转录

抖音短链接 → Playwright 捕获视频 URL → 下载视频 → Whisper 转录 → agent 整理 → 保存 Markdown

模式 B：本地文件 → 转录

本地文件路径 → 格式验证 → Whisper 转录 → agent 整理 → 保存 Markdown

两种模式共用 scripts/transcribe.py 中的转录和 MD 写入逻辑。

步骤 1（仅抖音模式）：Playwright 捕获视频 URL

无需登录即可提取。Chrome 无头模式下打开短链接，首次等待 8 秒让 JS 填充 video.src，如果未捕获则自动增加等待时间（13 秒）重试一次。Playwright 失败时自动回退到 Douyin API 方案获取视频 URL。

> 为什么不用网络拦截？ 登录模态框覆盖时网络拦截失效，但 DOM 中 video.src 已就绪。

步骤 2（仅抖音模式）：下载视频（文件名含时间戳）

所有产物共用同一个 YYYYMMDD_HHMMSS 时间戳，重复运行不会覆盖。

from scripts.transcribe import make_timestamp
ts = make_timestamp()  # "20260618_112500"
video_path = f"douyin_video_{ts}.mp4"

步骤 3：Whisper 转录

使用 medium 模型（~1.4GB，首次自动下载后缓存于 ~/.cache/whisper/）。

脚本内置模型缓存损坏自动修复：若检测到模型文件不完整或加载崩溃，自动删除缓存并重新下载。

步骤 4：整理纠错 → 保存 Markdown

脚本不调用外部 LLM。转录完成后输出原始文本，由 agent 自身完成整理：

agent 整理完毕后调用 scripts/transcribe.py 中的 write_cleaned_md() 写入 .md 文件。

Agent 调用方式（写入整理后的 MD）：

# 抖音来源
cd <工作目录> && <venv_python> -c "
import sys
sys.path.insert(0, '<skill_dir>/scripts')
from transcribe import write_cleaned_md

md_path = write_cleaned_md(
    cleaned_text='''<整理后的文本>''',
    source='<原始短链接>',
    source_type='douyin',
    timestamp='<时间戳>',
    output_dir='<工作目录>'
)
print(f'MD saved: {md_path}')
"

# 本地文件来源
cd <工作目录> && <venv_python> -c "
import sys
sys.path.insert(0, '<skill_dir>/scripts')
from transcribe import write_cleaned_md

md_path = write_cleaned_md(
    cleaned_text='''<整理后的文本>''',
    source='<源文件名>',
    source_type='local',
    timestamp='<时间戳>',
    output_dir='<工作目录>'
)
print(f'MD saved: {md_path}')
"

产物清单

所有文件存放在运行脚本时的当前目录。本地文件模式不会复制或移动原始媒体文件，直接读取源文件。

支持的媒体格式

视频格式

音频格式

常见问题排查

技术要点

1. 登录墙绕过（抖音模式）：video.src 由 JS 在登录模态框出现前填充，直接 DOM 查询即可捕获
2. API 备用方案（抖音模式）：Playwright 捕获失败时，自动回退到 Douyin web aweme detail API 获取视频 URL，双重保障
3. Playwright 延迟导入（抖音模式）：playwright 不再硬导入，脚本在没有 playwright 时仍可运行（自动走 API 路径）
4. Playwright 重试机制（抖音模式）：首次捕获等待 8 秒，失败后自动增加等待时间（13 秒）重试一次
5. CDN URL 有效期（抖音模式）：抖音签名 URL（v26-web.douyinvod.com/...）有效约 24 小时，捕获后立即下载
6. Douyin API 编码修复：智能检测 API 返回的 latin1 编码问题，仅在确实存在乱码时才做二次解码，不破坏正常 UTF-8 文本
7. video ID 多格式提取：支持 /video/、/note/（图文笔记）、/modal/、/share/video/、?modal_id= 五种 URL 格式
8. 本地文件零拷贝：transcribe_local.py 直接从源文件路径读取，不复制文件，节省磁盘空间
9. 模型选择：硬编码 medium，中文最佳性价比（准确率与 large 差距小而速度快一倍）
10. FFmpeg 来源：imageio[ffmpeg] 自动提供，无需系统安装
11. 环境隔离：所有依赖安装在 skill 目录下的独立 venv 中，不影响系统 Python
12. 代码复用：转录和 MD 写入逻辑集中在 scripts/transcribe.py，两个入口脚本共享
13. GPU 加速：自动检测 CUDA，有 GPU 时使用 GPU 加速转录（速度提升 5-10 倍），无 GPU 时使用 CPU
14. initial_prompt：默认设置中文提示文本，提升中文+英文混合识别准确率
15. 依赖分层：本地转录只需核心依赖（whisper、requests、ffmpeg），抖音模式额外需要 playwright
16. Windows UTF-8：脚本入口自动 sys.stdout.reconfigure(encoding='utf-8')，解决 GBK 控制台中文乱码
17. 进度与预估：自动获取媒体时长，根据模型大小和 CPU/GPU 预估转录耗时；计时从模型加载完毕后开始（不含模型加载）；转录后输出实际耗时和速度倍率

文件结构

douyin-transcribe-lz/
├── SKILL.md                          # 本文件
├── .env_config.json                  # 机器特定配置（setup_env.py 自动生成，勿手动编辑）
├── scripts/
│   ├── transcribe.py                 # 共享模块：转录 + MD 写入（核心逻辑）
│   ├── fetch_douyin_video.py         # 抖音模式入口：捕获 → 下载 → 转录
│   ├── transcribe_local.py           # 本地模式入口：格式验证 → 转录
│   ├── setup_env.py                  # 环境自动配置（支持 Windows/macOS/Linux）
│   └── verify_env.py                 # 环境快速检测（支持 --fix 自动修复）
├── references/
│   └── whisper_usage.md              # Whisper 参数详解
└── venv/                             # 隔离 Python 环境（setup_env.py 自动创建，不提交到版本控制）
    └── ...

> .env_config.json 和 venv/ 是运行时生成的文件，跨机器迁移后需重新运行 setup_env.py 生成。