43college media-transcriber — 音视频逐字稿转录
作者：43 COLLEGE 凯寓 (KAIYU) 出品 版本：v1.0
使用 OpenAI Whisper 将视频/音频文件转为带时间戳的逐字稿。支持说话人识别和 Claude 标点恢复。
第一次运行时会自动创建虚拟环境、安装依赖并下载 Whisper 模型（turbo 约 1.5GB），全程自动，无需手动配置。
重要：首次转录前必须提前告知用户——模型下载 + 依赖安装可能需要 5-15 分钟（取决于网速），期间终端可能长时间没有新输出，这不是卡死。务必在执行转录命令前向用户说明这一点，避免用户中途强制中断导致环境损坏。
如果运行报错缺少 ffmpeg 或需要配置说话人识别，读 SETUP.md 完成首次配置。
跨平台兼容
| 项目 | macOS / Linux | Windows |
|---|---|---|
| Python | python3 |
python |
| 路径分隔符 | / |
\ |
| 脚本路径 | ${CLAUDE_SKILL_DIR}/scripts/transcribe.py |
${CLAUDE_SKILL_DIR}\scripts\transcribe.py |
关于
${CLAUDE_SKILL_DIR}：这是文档占位符，代表本 skill 的安装目录（通常是~/.claude/skills/media-transcriber/）。Claude 在 bash 里执行命令时会自动替换成实际路径，用户不要直接复制这串到终端——直接复制粘贴会因变量未定义而失败。要么把命令交给 AI 执行，要么自行替换成具体目录。
调用方式
质量模式（默认推荐）
带说话人识别 + Claude 标点恢复，适合正式内容沉淀。速度约为实时的 1/2（turbo 模型，CPU）。
# 预检环境和权限（推荐首次运行）
python3 ${CLAUDE_SKILL_DIR}/scripts/transcribe.py --check
# 质量模式：说话人识别 + 标点恢复
python3 ${CLAUDE_SKILL_DIR}/scripts/transcribe.py "video.mp4" --language zh --diarize --punctuate
# 指定说话人数量（不指定则自动检测）
python3 ${CLAUDE_SKILL_DIR}/scripts/transcribe.py "video.mp4" --language zh --diarize --punctuate --speakers 2
# 整个文件夹批量转录（质量模式）
python3 ${CLAUDE_SKILL_DIR}/scripts/transcribe.py "/path/to/folder" --language zh --diarize --punctuate
# 强制覆盖已有逐字稿
python3 ${CLAUDE_SKILL_DIR}/scripts/transcribe.py "video.mp4" --language zh --diarize --punctuate --overwrite
Python 内联调用：
import sys; sys.path.insert(0, f"{CLAUDE_SKILL_DIR}/scripts")
from transcribe import transcribe_file
transcribe_file("video.mp4", language="zh", diarize=True, punctuate=True)
快速模式
无说话人识别、无标点恢复，速度快 3-5 倍，适合快速预览内容。
# 快速模式：仅转录，无说话人，无标点
python3 ${CLAUDE_SKILL_DIR}/scripts/transcribe.py "video.mp4" --language zh
# Windows 快速模式
python ${CLAUDE_SKILL_DIR}\scripts\transcribe.py "C:\path\to\video.mp4" --language zh
环境信息
- 虚拟环境: 首次运行自动创建在 skill 目录的
venv/ - 模型存储:
models/（本地化，不依赖系统缓存） - 自动安装: openai-whisper, numpy<2.4, numba, anthropic
- 按需安装: pyannote-audio（仅
--diarize时安装） - GPU: 无 CUDA 时自动回退 CPU
模型选择
| 模型 | 大小 | CPU 速度 | 中文质量 | 场景 |
|---|---|---|---|---|
turbo |
1.5GB | ~2x 实时 | 优秀 | 默认推荐 |
medium |
1.4GB | ~3x 实时 | 良好 | turbo 备选 |
small |
461MB | ~1x 实时 | 一般 | 追求速度 |
base |
139MB | ~0.3x 实时 | 较差 | 快速预览 |
"Nx 实时" = 1 分钟音频需 N 分钟处理（CPU）
输出格式
每个文件生成 <原文件名>_逐字稿.txt：
无说话人识别（默认）：
# 文件名
[00:00 - 00:05] 文本内容
[00:05 - 00:12] 文本内容
---
# 完整文本
完整的文本内容。
有说话人识别（--diarize）：
# 文件名
**[说话人A]**
[00:00 - 00:05] 文本内容
**[说话人B]**
[00:05 - 00:12] 文本内容
---
# 完整文本
[说话人A] 第一段话内容。
[说话人B] 第二段话内容。
支持格式：.mp4 .mkv .avi .mov .wmv .flv .webm .mp3 .wav .flac .aac .ogg .m4a .wma
关键设计
- 自动 bootstrap: 首次运行自动创建 venv 并安装依赖，之后直接用
python3调用即可，无需 activate - 防幻觉:
condition_on_previous_text=False阻止错误传播 + ffprobe 时长过滤超时段落 - 标点引导: 指定
--language zh时自动注入initial_prompt引导标点输出 - Claude 标点恢复:
--punctuate调用 Claude Haiku 对全文做整体标点恢复 - 说话人匹配: 按时间重叠量将 Whisper 片段匹配到 pyannote 说话人段落
- 按需安装: pyannote-audio 体积大，仅在使用
--diarize时自动安装 - 模型本地化: Whisper 模型存放在
models/目录，通过download_root加载
已知限制
- NumPy 版本: numba 需要 numpy<2.4，已在自动安装时固定版本
- 长视频内存: 超 2 小时视频 turbo 模型约需 4-6GB RAM
- 背景音乐: 末尾纯音乐段可能残留少量误识别
- 说话人识别精度: 多人同时说话时准确率下降
- 标点恢复速度: Claude API 调用约 3-10 秒延迟