视频转写工作台

一个可独立使用的轻量视频转写工具：输入公开视频链接或完整分享文案，返回中文逐字稿和分段时间戳。当前版本首先支持抖音，输入源可以继续扩展。

当前能力

• 识别短链接、完整视频链接和包含链接的分享文案。
• 使用独立浏览器访问视频页面并捕获实际媒体请求。
• 临时下载视频，使用 FFmpeg 提取 16 kHz 单声道音频。
• 可选本地 faster-whisper / FunASR（Paraformer、SenseVoice）或 Qwen3-ASR-Flash API 完成中文语音识别。
• 文字修正是独立可选阶段：可不修正，也可用 Qwen3.7-Plus 修正同音错字。
• 支持本地/云端转写与修正开/关的四种自由组合。
• 可在工作台内配置 API 地址、模型与实体词表；macOS 上的 API Key 存入系统钥匙串。
• 支持 Excel / CSV 批量导入、批次队列监控和 Excel 汇总导出，单批最多 200 条。
• 支持在同一个工作台粘贴抖音博主主页，采集公开作品链接、勾选后直接加入批量转写。
• 提供网页操作台和 REST API。
• 返回整段逐字稿、分段起止时间和基础来源信息。
• 任务结果持久化为 JSON；临时视频和音频默认处理后删除。

运行要求

• macOS、Linux 或 Windows
• Python 3.11 或更新版本
• FFmpeg
• 首次安装 Playwright 时需要下载 Chromium
• 只有使用 Qwen 转写或文字修正时，才需要阿里云百炼 DashScope API Key
• 使用 FunASR（Paraformer / SenseVoice）时依赖会额外安装 PyTorch（体积较大），仅本地 CPU 运行也可；首次选择对应模型时会自动从 ModelScope 下载

macOS 快速开始

安装 Python 和 FFmpeg：

brew install python@3.11 ffmpeg

进入项目并创建独立环境：

cd video-transcript-workbench
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e ".[dev]"
playwright install chromium

创建配置并启动：

cp .env.example .env
python run.py

浏览器打开：

http://127.0.0.1:8765

首次使用时，进入「模型配置」选择处理链。「本地模型 + 不修正」可以直接运行；选择任何 Qwen 阶段时，再填写 DashScope API Key 并测试连接。

可选：macOS 桌面应用

项目附带一个 macOS 桌面应用，可双击启动本地后端，无需手动打开终端：

./scripts/build_macos_app.sh

脚本会在项目上级目录生成 视频转写工作台.app。也可以直接双击项目根目录中的 启动服务.command 调试服务；关闭它打开的终端窗口即可停止服务。

接口文档：

http://127.0.0.1:8765/docs

API 使用

创建转写任务：

curl -X POST http://127.0.0.1:8765/api/v1/transcriptions \
  -H 'Content-Type: application/json' \
  -d '{"input":"https://v.douyin.com/你的短链接/"}'

响应示例：

{
  "id": "任务ID",
  "status": "queued",
  "status_url": "/api/v1/transcriptions/任务ID"
}

查询任务：

curl http://127.0.0.1:8765/api/v1/transcriptions/任务ID

任务完成后，响应中的 transcript.text 是完整逐字稿，transcript.segments 包含每段文字的 start 和 end 秒数。

下载结果：

GET /api/v1/transcriptions/{任务ID}/text
GET /api/v1/transcriptions/{任务ID}/json

批量任务与 Excel

工作台左侧进入「批量任务」，有三种创建方式：

1. 粘贴包含 /user/ 的抖音博主主页，选择最近 20/50/100/200 条或全部公开作品；扫描后勾选作品，再加入批量转写。
2. 下载导入模板，在「视频链接」列中每行填写一条抖音链接，再上传 .xlsx 或 .csv。
3. 直接在页面中每行粘贴一条链接。

主页扫描不会自动产生转写费用。采集结果可先导出为 Excel 可直接打开的 UTF-8 CSV；只有点击「加入批量转写」后才创建任务。「全部公开作品」会持续滚动到主页末尾，单次加入批量队列仍限制为 200 条。

系统会识别「视频链接」「抖音链接」「链接」「URL」「source_url」等表头，自动忽略无效内容和重复链接。每个批次沿用创建时的模型链路配置，页面会分别显示每条视频的进度和失败原因。

批次完成后可以导出一个 Excel 工作簿：

• 任务汇总：每条视频一行，包含来源、模型、状态、完整逐字稿和错误信息。
• 完整文本分段：按任务和时间戳保存全部分段文字，避免长文本受单元格长度影响。
• 字段说明：说明如何把工作簿交给 Codex 继续提取旅居结构化字段。

相关接口：

POST /api/v1/batches
POST /api/v1/creators/scan
POST /api/v1/batches/import?filename=待导入.xlsx
GET  /api/v1/batches
GET  /api/v1/batches/template.xlsx
GET  /api/v1/batches/{批次ID}
GET  /api/v1/batches/{批次ID}/xlsx

模型与 API 配置

推荐直接在工作台的「模型配置」页中管理。转写与修正是两个独立阶段：

转写引擎	文字修正	是否需要 API
本地模型（Whisper / Paraformer / SenseVoice）	关	否
本地模型	Qwen 修正	是
Qwen3-ASR-Flash	关	是
Qwen3-ASR-Flash	Qwen 修正	是

配置	默认值	说明
转写引擎	本地模型	可切换为 Qwen3-ASR-Flash
本地模型	small	可选 medium、large-v3、paraformer-large、sensevoice-small；首次使用会下载
文字修正	关	开启后才调用校对模型
API 地址	https://dashscope.aliyuncs.com/compatible-mode/v1	阿里云百炼北京地域的 OpenAI 兼容端点
ASR 模型	qwen3-asr-flash	转录中文语音和方言
校对模型	qwen3.7-plus	保守修正同音错字与标点
上下文与实体词表	空	用换行分隔地名、村名、人名和行业词

macOS 上的 API Key 保存到 Keychain，不会写入 data/settings/ai.json。也可以用 DASHSCOPE_API_KEY 环境变量提供，它的优先级高于钥匙串。

运行配置

常用环境变量位于 .env：

配置	默认值	说明
MAX_CONCURRENT_JOBS	1	同时运行的任务数
MAX_MEDIA_MB	500	单条视频最大下载体积
KEEP_MEDIA	false	是否保留临时视频和音频
BROWSER_HEADLESS	true	是否使用无界面浏览器
WHISPER_DEVICE	cpu	本地 Whisper 的运行设备
WHISPER_COMPUTE_TYPE	int8	本地 CPU 模式的默认精度
FUNASR_DEVICE	cpu	本地 FunASR（Paraformer / SenseVoice）运行设备，可选 cuda:0
HF_HOME	./data/models	本地模型缓存目录（FunASR 模型缓存在其 modelscope/ 子目录）

数据目录

data/
├── batches/    # 批次、条目顺序和当时使用的模型链路
├── browser-profile/ # 博主主页采集所需的本地浏览器状态
├── jobs/       # 任务与逐字稿 JSON
├── media/      # 处理中临时媒体；默认完成后删除
├── models/     # 本地 Whisper 与 FunASR（ModelScope）模型缓存
└── settings/   # 非敏感的模型和词表配置

整个 data/ 目录已加入 .gitignore，不会在正常提交时上传到 GitHub。

Docker

docker compose up --build

启动后访问 http://127.0.0.1:8765。Docker 中可以通过 DASHSCOPE_API_KEY 环境变量提供凭证；首次构建需要安装浏览器。

测试

source .venv/bin/activate
ruff check .
pytest

使用边界

本项目只用于处理公开、且使用者有权整理的内容。请保留原始来源，不要绕过登录、付费、隐私或平台验证，不要公开再分发未经授权的完整视频或完整逐字稿。平台页面与风控规则可能变化，捕获失败时应停止并检查，不应高频重试。