zaddy99999/captions

captions 是做什么的？

本地单词级转录、短视频字幕样式设计与烧录。

脚本位于 scripts/ 目录：

脚本	功能
transcribe.py	使用 faster-whisper（启用 word_timestamps=True）生成 words.json（缓存结果）
make-captions.mjs	将 words.json 转换为 ASS（支持当前单词高亮）和 SRT 格式
burn.mjs	使用 libass 的 ass / subtitles 滤镜烧录 ASS/SRT 字幕
snap-to-words.mjs	将剪切点移动到最近的单词间隙

工作流程

1. 转录（每个源文件只需执行一次，结果会缓存）：

   pip install faster-whisper            # 只需执行一次
   python3 scripts/transcribe.py --input clip.mp4 --out edit/clip.words.json --model small --language en
   

   首次运行会从 Hugging Face 下载模型。如果下载被阻止，脚本会以退出码 4 和一条 JSON fix 消息退出，而不会抛出堆栈跟踪，并且永远不会写入虚假转录。将 --model 指向本地的 CTranslate2 模型文件夹即可离线工作。
2. 生成字幕：

   node scripts/make-captions.mjs --words edit/clip.words.json --out-ass edit/clip.ass --out-srt edit/clip.srt
   

   样式来自品牌包（captions 块：字号、边距、轮廓、高亮；colors.accent 是当前单词的颜色）。
3. 烧录作为视觉处理的最后一步：

   node scripts/burn.mjs --input edit/clip-hook.mp4 --subs edit/clip.ass --out edit/clip-captioned.mp4
   

   当字幕字体是一个文件而非已安装字体时，使用 --fonts-dir。
4. 验证：使用 render-qc 校对样片：确保字幕可读、在安全区域内、不覆盖钩板。

规则

• 切勿在单词内部进行剪切。在分割语音之前，先将剪切点对齐到单词间隙： node scripts/snap-to-words.mjs --words edit/clip.words.json --markers edit/cuts.json --out edit/cuts.json
• 字幕放在最后处理：在剪切、叠加和色彩调整之后。如果在转录后对剪辑进行了修剪，请向 make-captions.mjs 传递 --offset -<修剪的秒数>。
• 对于短视频，每个字幕块包含 1 到 3 个单词（由 maxWords、maxChars 控制）。字幕块会在标点符号和停顿处断开。
• 保持字幕不进入底部约 15% 的区域（平台 UI）并远离钩板：调整 captions.marginV。
• 转录结果会被缓存：只有当音频发生变化时才使用 --force 重新运行。
• 逐一检查单词是否与音频匹配；whisper 可能会听错名字和专业术语。如有需要，手动修正 words.json。

没有 ffmpeg libass 的情况

如果 burn.mjs 报告没有 ass 滤镜，说明 ffmpeg 构建缺少 libass。请安装一个完整构建版本（大多数包管理器都提供），或者将 SRT 作为单独的字幕轨上传而不要烧录进去。