RaphaelEvanW/autopulse-captions

AutoPulse Captions

Pipeline: video → Whisper (Wort-Zeitstempel) → Mini-ML-Korrektur (EN/ID) → Mikro-Chunk .ass (Hervorhebung des aktiven Wortes) → optionaler Vorschau-Editor → FFmpeg-Burn-in.

Finde PROJECT_DIR (den Ordner, der generate_captions.py und gpu_check.py enthält):

1. Wenn generate_captions.py im selben Verzeichnis wie dieses SKILL.md liegt, ist PROJECT_DIR dieses Verzeichnis.
2. Wenn dieses SKILL.md in .agents/skills/autopulse-captions/ liegt, ist PROJECT_DIR das Repository-Root (../../..).
3. Andernfalls Standardwert: C:\Users\Evan\.gemini\antigravity\scratch\autopulse-captions.

Alle folgenden Befehle werden von PROJECT_DIR aus ausgeführt. Python-Ausführbare Datei (PY): PROJECT_DIR/.venv/Scripts/python.exe (Windows) oder PROJECT_DIR/.venv/bin/python (macOS/Linux).

0. Ersteinrichtung (nur wenn .venv/ oder hardware_profile.json fehlt)

1. Zuerst Hardware prüfen (keine Installation nötig, kein Netzwerk): python gpu_check.py – zeigt an, welches Whisper-Modell passt (z.B. RTX 3060 → large-v3, GTX 1650 Ti 4 GB → large-v3-turbo, keine GPU → CPU large-v3-turbo/small).
2. Erstelle die venv mit Python 3.10–3.12 (3.13 max; 3.14 hat keine CTranslate2-Räder): py -3.11 -m venv .venv (Windows) / python3.11 -m venv .venv.
3. Installiere Abhängigkeiten passend zur Hardware (benötigt Netzwerk): PY install.py --download-model (füge --install-ffmpeg auf Windows hinzu, wenn FFmpeg fehlt). Es installiert CUDA 12 Runtime-Bibliotheken nur, wenn eine NVIDIA GPU gefunden wird, testet die GPU und schreibt hardware_profile.json.
4. Überprüfung: Der Installer endet mit SELESAI -> Whisper: <model> / <device> / <compute>.

1. Vor dem Ausführen fragen (ERFORDERLICH)

Vor der Transkription eines neuen Videos MUSST du den Benutzer zuerst fragen (mit ask_question oder Klartext, falls nicht im Prompt angegeben) – nicht raten:

• Untertitelsprache:
  1. Englisch (--lang en)
  2. Bahasa Indonesia (--lang id)
  3. Indonesisches Audio → Englische Untertitel (--lang id --translate)
  4. Automatisch erkennen (--lang auto)
• Nur wenn unklar: ob sie ins Video eingebrannt werden sollen (--burn) oder nur .ass generiert werden soll.

Gib --lang immer explizit an, wenn der Agent das Skript ausführt (die interaktive Eingabeaufforderung des Skripts erscheint nur in einem echten interaktiven Terminal).

2. Untertitel generieren

PY generate_captions.py "<video>" --lang en --burn --output-video "<out>.mp4"

• Modell/Gerät/Compute standardmäßig auf auto (von gpu_check.py) mit automatischem Fallback (z.B. large-v3 → large-v3-turbo → CPU) bei Out-of-Memory- oder CUDA-Fehlern. Überschreibe --model nur, wenn der Benutzer es verlangt.
• Ausrichtung (Hochformat / Querformat / Quadratisch) wird per ffprobe erkannt; Schriftgröße, Abstände und Zeilenlänge passen sich automatisch an.
• Der erste Lauf eines Modells lädt es von Hugging Face herunter (benötigt Netzwerk).
• Ausgaben neben der Eingabe: <name>.ass, <name>_raw_words.json, <name>_captioned.mp4; plus last_run.json und eine aktualisierte preview_player.html.

Überprüfung: Exit-Code 0, die Log-Zeile model dipakai: ..., und das Ausgabevideo existiert. Melde dem Benutzer das verwendete Modell und die Liste der verdächtigen Wörter, die das Skript ausgibt.

3. Überprüfen & Überarbeiten (wenn es verdächtige Wörter gibt oder der Benutzer Änderungen wünscht)

1. Öffne PROJECT_DIR/preview_player.html im Browser (--open-preview macht das). Der Benutzer bearbeitet Wörter/Zeitstempel, fügt fehlende Wörter ein (➕ Kata), und klickt dann 💾 Simpan words.json (lädt words_revised.json herunter).
2. Neu rendern aus dem überarbeiteten JSON – dies trainiert auch Mini-ML (learned_memory.json, getrennte en/id-Profile) durch Abgleich mit der letzten rohen Whisper-Ausgabe:

   PY generate_captions.py "<pfad>/words_revised.json" --burn --output-video "<out>.mp4"
   

   Das Quellvideo wird aus last_run.json übernommen (überschreiben mit --video).

4. Verkettung nach Videogenerierung

Wenn ein anderer Schritt ein Video erzeugt hat (z.B. draft.mp4), frage nach der Sprache und führe dann Schritt 2 für diese Datei mit --output-video final.mp4 aus.

Fehlerbehebung

Symptom	Lösung
No module named faster_whisper	Verwende PY aus .venv oder führe Schritt 0 aus
Jede GPU-Option schlägt fehl, fällt auf CPU zurück	NVIDIA-Treiber aktualisieren, PY install.py erneut ausführen
Langsam auf CPU	Erwartet (~1× Echtzeit). Für Entwürfe --model small vorschlagen
ffmpeg tidak ditemukan	winget install Gyan.FFmpeg / brew install ffmpeg / apt install ffmpeg
Falsche Wörter / Slang / Namen	Editor verwenden (Schritt 3), damit Mini-ML lernt; oder --hotwords "Name1 Name2"
Übersetzungsqualität schlecht	--translate verwendet niemals turbo (nicht darauf trainiert); benötigt ≥ ~3,6 GB freien VRAM für large-v3

Vollständige Flag-Referenz: references/cli.md · Wie Mini-ML funktioniert: references/mini-ml.md