RaphaelEvanW/autopulse-captions

AutoPulse Captions

管線：影片 → Whisper（單字時間戳） → Mini-ML 校正（EN/ID） → 微片段 .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