media-transcriber 是由 43 COLLEGE 凯寓（KAIYU）出品的音视频逐字稿转录技能，版本 v1.0。它使用 OpenAI Whisper 将视频/音频文件转为带时间戳的逐字稿，并支持说话人识别和 Claude 标点恢复。
用途 当用户提供视频路径并要求转录、生成逐字稿、提取字幕时使用此技能。适合将会议、访谈、课程等音视频内容沉淀为文字稿。
主要能力
- 使用 OpenAI Whisper 进行音视频转录，输出带时间戳的逐字稿。
- 支持说话人识别（--diarize），按时间重叠量将 Whisper 片段匹配到 pyannote 说话人段落。
- 支持 Claude 标点恢复（--punctuate），调用 Claude Haiku 对全文做整体标点恢复。
- 支持单文件转录和整个文件夹批量转录。
- 支持强制覆盖已有逐字稿（--overwrite）。
- 支持指定说话人数量（--speakers），不指定则自动检测。
- 提供预检环境和权限命令（--check）。
- 支持 Python 内联调用。
使用方式 首次运行时会自动创建虚拟环境、安装依赖并下载 Whisper 模型（turbo 约 1.5GB），全程自动，无需手动配置。重要：首次转录前必须提前告知用户——模型下载 + 依赖安装可能需要 5-15 分钟（取决于网速），期间终端可能长时间没有新输出，这不是卡死。务必在执行转录命令前向用户说明这一点，避免用户中途强制中断导致环境损坏。如果运行报错缺少 ffmpeg 或需要配置说话人识别，读 SETUP.md 完成首次配置。
跨平台兼容：macOS / Linux 使用 python3，Windows 使用 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。
模型选择
- turbo：1.5GB，CPU 速度约 2x 实时，中文质量优秀，默认推荐。
- medium：1.4GB，约 3x 实时，中文质量良好，turbo 备选。
- small：461MB，约 1x 实时，中文质量一般，追求速度。
- base：139MB，约 0.3x 实时，中文质量较差，快速预览。 "Nx 实时" = 1 分钟音频需 N 分钟处理（CPU）。
输出格式 每个文件生成 <原文件名>_逐字稿.txt。无说话人识别（默认）时，输出包含文件名、带时间戳的文本行，以及完整文本。有说话人识别（--diarize）时，输出按说话人分段，包含说话人标签、带时间戳的文本行，以及完整文本。 支持格式：.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 秒延迟。