RaphaelEvanW/autopulse-captions

AutoPulse Captions

流程：视频 → Whisper（单词时间戳） → Mini-ML 校正（英语/印尼语） → 微块 .ass 字幕（活动单词高亮） → 可选的预览编辑器 → FFmpeg 烧录。

定位 PROJECT_DIR（包含 generate_captions.py 和 gpu_check.py 的文件夹）：

1. 如果 generate_captions.py 与此 SKILL.md 在同一目录，则 PROJECT_DIR 为该目录。
2. 如果此 SKILL.md 位于 .agents/skills/autopulse-captions/ 内，则 PROJECT_DIR 为仓库根目录（../../..）。
3. 否则，默认路径为 C:\Users\Evan\.gemini\antigravity\scratch\autopulse-captions。

以下所有命令均在 PROJECT_DIR 中运行。 Python 可执行文件（PY）：PROJECT_DIR/.venv/Scripts/python.exe（Windows）或 PROJECT_DIR/.venv/bin/python（macOS/Linux）。

0. 首次设置（仅在 .venv/ 或 hardware_profile.json 缺失时执行）

1. 先检查硬件（无需安装，无需网络）： python gpu_check.py — 显示适合的 Whisper 模型（例如 RTX 3060 → large-v3， GTX 1650 Ti 4 GB → large-v3-turbo，无 GPU → CPU large-v3-turbo/small）。
2. 使用 Python 3.10–3.12（最高 3.13；3.14 没有 CTranslate2 轮子）创建虚拟环境： py -3.11 -m venv .venv（Windows）/ python3.11 -m venv .venv。
3. 根据硬件安装依赖（需要网络）： PY install.py --download-model（如果 Windows 上缺少 FFmpeg，可添加 --install-ffmpeg）。 仅当检测到 NVIDIA GPU 时，它才会安装 CUDA 12 运行时库，对 GPU 进行冒烟测试， 并写入 hardware_profile.json。
4. 验证：安装程序以 SELESAI -> Whisper: <模型> / <设备> / <计算> 结束。

1. 运行前询问（必需）

在转写新视频之前，务必先使用 ask_question 询问用户（如果提示中没有明确指定，也可使用纯文本）— 不要猜测：

• 字幕语言：
  1. 英语（--lang en）
  2. 印尼语（--lang id）
  3. 印尼语音频 → 英文字幕（--lang id --translate）
  4. 自动检测（--lang auto）
• 仅当不清楚时：询问是直接烧录到视频中（--burn）还是只生成 .ass 文件。

当代理运行脚本时，始终显式传递 --lang 参数（脚本自身的交互式提示仅在真正的交互式终端中出现）。

2. 生成字幕

PY generate_captions.py "<视频>" --lang en --burn --output-video "<输出>.mp4"

• 模型/设备/计算默认为 auto（来自 gpu_check.py），并带有自动回退（例如 large-v3 → large-v3-turbo → CPU）在内存不足或 CUDA 错误时。除非用户要求，否则不要覆盖 --model。
• 方向（竖屏/横屏/正方形）通过 ffprobe 检测；字体大小、边距和行长会自动调整。
• 首次运行某模型时，会从 Hugging Face 下载该模型（需要网络）。
• 输出文件位于输入文件旁边：<名称>.ass、<名称>_raw_words.json、 <名称>_captioned.mp4；以及 last_run.json 和更新的 preview_player.html。

验证：退出代码为 0，日志行 model dipakai: ...，且输出视频存在。 向用户报告所使用的模型以及脚本打印的可疑单词列表。

3. 审阅与修订（当存在可疑单词或用户要求更改时）

1. 在浏览器中打开 PROJECT_DIR/preview_player.html（--open-preview 可自动打开）。 用户编辑单词/时间戳，插入遗漏的单词（➕ Kata），然后点击 💾 Simpan words.json（下载 words_revised.json）。
2. 从修订后的 JSON 重新渲染 — 这也会训练 Mini-ML（learned_memory.json， 分别保存 en/id 配置文件），方法是将修订后的数据与上一次原始 Whisper 输出进行比较：

   PY generate_captions.py "<路径>/words_revised.json" --burn --output-video "<输出>.mp4"
   

   源视频取自 last_run.json（可使用 --video 覆盖）。

4. 视频生成后的链式处理

当其他步骤生成了视频（例如 draft.mp4）时，先询问语言问题，然后对该文件运行步骤 2，使用 --output-video final.mp4。

故障排除

症状	解决方案
No module named faster_whisper	使用 .venv 中的 PY，或运行步骤 0
所有 GPU 选项失败，回退到 CPU	更新 NVIDIA 驱动程序，重新运行 PY install.py
CPU 上速度慢	这是预期的（约 1× 实时）。建议在草稿时使用 --model small
ffmpeg tidak ditemukan	winget install Gyan.FFmpeg / brew install ffmpeg / apt install ffmpeg
错误的单词 / 俚语 / 名称	使用编辑器（步骤 3），以便 Mini-ML 学习；或使用 --hotwords "名称1 名称2"
翻译质量差	--translate 从不使用 turbo（未针对其训练）；需要 ≥ ~3.6 GB 可用 VRAM 以用于 large-v3

完整命令参考：references/cli.md · Mini-ML 工作原理：references/mini-ml.md