video-subtitler

Video Subtitler 用于从视频或音频源生成整洁、带时间码的 .srt 字幕，整个处理在本地设备完成。其流水线为：把媒体取到本地 → 提取音频 → 用 Whisper 转写为 SRT → 清理错别字与品牌名。

一、前提工具

• ffmpeg / ffprobe：用于音频提取和媒体探测。可用 which ffmpeg ffprobe 检查，用 brew install ffmpeg 安装。
• whisper-cli（whisper.cpp）：转写器。体积小（约 8 MB）、MIT 许可、纯 C/C++，不依赖 Python/PyTorch，在 Apple Silicon 上运行较快，可直接写出 SRT。可用 which whisper-cli 检查，用 brew install whisper-cpp 安装。
• yt-dlp：仅当输入是 YouTube URL 时需要，用 brew install yt-dlp 安装。 whisper.cpp 需要 GGML 模型文件（未随工具提供）。可先查找磁盘上已有模型再决定是否下载。 替代转写器包括 openai-whisper（pip 安装）和 npx hyperframes transcribe，但依赖更重，默认使用 whisper.cpp。

二、工作流程

1. 把媒体取到本地。YouTube URL 只需音频时：yt-dlp -f "ba/b" -x --audio-format mp3 -o "%(title)s.%(ext)s" "<URL>"。本地文件则确认存在并探测：ffprobe -v error -show_entries format=duration,size,format_name -of default=noprint_wrappers=1 INPUT；以及 ffprobe -v error -select_streams a -show_entries stream=codec_name,channels,sample_rate -of default=noprint_wrappers=1 INPUT。
2. 提取音频为 Whisper 友好的 WAV：ffmpeg -y -i INPUT -vn -ac 1 -ar 16000 -c:a pcm_s16le BASENAME.wav。参数含义为去掉视频、单声道、16 kHz、16 位 PCM。始终提取音频而非直接喂完整视频，速度更快并规避容器/编码问题。
3. 直接转写为 SRT：whisper-cli -m MODEL.bin -f BASENAME.wav -osrt -of BASENAME --max-len 42 --split-on-word --prompt "Retool, Replit, ServiceNow, OAuth"。输出 BASENAME.srt，使用标准 HH:MM:SS,mmm 时间码。--max-len 与 --split-on-word 把每条字幕限制在约 42 个可读字符并按词边界断行；--prompt 用于预先注入品牌/产品名与术语的正确拼写；-l auto 用于非英语或未知语言音频，默认 en，whisper.cpp 按源语言转写，不会自动翻译。噪声、音乐或高准确性场景可用更大模型。
4. （可选）基于词级 JSON 自定义字幕分组：仅当原生分段不够理想、需要更细控制时使用。先用词级 JSON 转写，再运行脚本 python3 SKILL_DIR/scripts/json_to_srt.py transcript.json BASENAME.srt --max-chars 42 --max-dur 5.0 --max-gap 0.8 --max-words 12，脚本按行长、时长、停顿间隔和句末标点分组输出 SRT。多数任务不需要此步。
5. 最终清理。Whisper 即便有 --prompt 也可能弄错专有名词和大小写，需要人工扫一遍：用 sed -i '' 's/^ //' BASENAME.srt 去掉每行前导空格；用 grep -niE "replet|retool|service ?now|salesforce|workday|netsuite|oauth|github|postgres" BASENAME.srt 查找可疑错误；就地修正误听品牌拼写、品牌小写、产品/技术术语大小写和上下文同音错字，URL 保持小写；再用 grep -oE "Replit|Retool|ServiceNow|Salesforce|OAuth" BASENAME.srt | sort | uniq -c 验证修正结果。
6. 清理中间文件：rm -f BASENAME.wav，并报告最终 .srt 路径和字幕条数。

三、获取 Whisper 模型 whisper.cpp 需要 GGML .bin 模型。先查找磁盘已有模型：find ~ /opt/homebrew -iname "ggml-*.bin" 2>/dev/null。常见位置包括 ~/.cache/hyperframes/whisper/models/、~/Library/Application Support/MacWhisper/models/。若没有，从 Hugging Face 下载：curl -L -o ggml-base.en.bin https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin。模型选择：ggml-base.en.bin 约 148 MB，适合清晰英语语音，是不错的默认；ggml-small.en.bin 约 466 MB，英语准确度更好；ggml-small.bin 约 466 MB，用于非英语/未知语言；ggml-medium.bin / ggml-large-v3.bin 为 1.5 / 3.1 GB，用于噪声音频、音乐或最大准确性。.en 模型仅用于英语音频，其他语言用非 .en 模型并配合 -l <code> 或 -l auto。

四、替代转写器 若 whisper-cli 不可用且无法安装，按偏好顺序：openai-whisper（pip install -U openai-whisper），参考实现，也能直接写 SRT：whisper BASENAME.wav --model small --output_format srt，但会引入 PyTorch（约 2 GB+），较重；npx hyperframes transcribe BASENAME.wav --model small，仅在已安装 HyperFrames 时合适，它输出词级 JSON，需配合第 4 步才能得到 SRT。

五、说明与适用场景 适合为本地视频/音频或 YouTube 素材生成字幕，并可上传到 YouTube：YouTube Studio → 视频 → 字幕 → 添加语言 → 上传文件 → 带时间码 → 选择 .srt。转写耗时随音频长度和模型大小增加，base.en/small.en 是清晰英语的较好平衡点。使用示例中的 SKILL_DIR、MODEL、BASENAME、INPUT 需替换为真实值。官方资料未提供收费、价格或平台支持等额外信息。