ahkamboh/agent-caption

agent-caption — SKILL

Du bist ein KI-Untertitelungs-Agent. Dieses Repo fügt präzise, perfekt getimte Untertitel/Untertitel zu jedem Video oder Audio in jeder Sprache hinzu (standardmäßig Englisch), sowohl für Sprache als auch Musik, mit erstklassiger Hinglish / Code-Switching-Unterstützung. Läuft auf Windows, macOS und Linux.

Repo: https://github.com/ahkamboh/agent-caption — Klonen: git clone https://github.com/ahkamboh/agent-caption Diese Datei, roh (für Chat-Agenten zum Abrufen): https://raw.githubusercontent.com/ahkamboh/agent-caption/master/SKILL.md

Kernprinzip: Wörter kommen von der Spracherkennung, aber das TIMING kommt vom Forced Alignment auf der Wellenform – niemals rohe ASR-Zeitstempel. Daher driften Untertitel nie zu früh oder zu spät, selbst wenn das Transkript Rechtschreibfehler enthält.

Einmalige Einrichtung (Windows / macOS / Linux)

Erfordert: Python 3.10+, ffmpeg, ~4 GB Speicherplatz. (torch liefert Wheels bis 3.14; wenn whisperx für ein brandneues Python kein Wheel hat, verwende 3.11–3.12.)

python setup.py        # plattformübergreifend: erstellt ./.venv-whisperx und installiert alles
# macOS/Linux Komfort: bash setup.sh      ·      Windows Komfort: setup.bat

ffmpeg: macOS brew install ffmpeg · Ubuntu sudo apt install ffmpeg · Windows winget install ffmpeg. Modelle (Whisper large-v3 – die Voreinstellung – MMS_FA, whisperX) werden beim ersten Start automatisch heruntergeladen.

Einfachster Weg – der Ein-Befehl-Wrapper (BEVORZUGE DIESEN)

Führe für „Untertitel dieses Video“-Anfragen einfach den Top-Level-Wrapper aus. Er transkribiert → aligniert → brennt mit automatisch proportionierte Untertitel (korrekte Größe/Abstände/Ausrichtung für jede Auflösung) und fällt auf einen libass-freien Renderer (Pillow + overlay) zurück, wenn das ffmpeg des Benutzers keine Untertitelunterstützung hat:

python caption.py <video>                                  # Englisch, clean, proportioniert -> <video>.captioned.mp4
python caption.py <video> --hinglish --style tiktok        # Hinglish + TikTok-Box
python caption.py <video> --lang ur --pos center --size 6  # andere Sprache / Platzierung / Größe
python caption.py <video> --srt                            # nur eine .srt schreiben (kein Einbrennen)
python caption.py <video> --from-srt DATEI                  # bestehende .srt einbrennen, proportioniert

15 Stile (gebündelte Schriftarten): clean (Standard) bold hormozi green beast impact bebas tiktok pill boxed yellow neon gradient minimal subtitle. Greife nur auf die einzelnen Skripte unten zu, wenn du das rohe Transkript, benutzerdefiniertes Rendering oder Übersetzung benötigst.

Modell: large-v3 ist die VOREINSTELLUNG (beste Genauigkeit) – kein Flag erforderlich; setup.py lädt es vorab herunter. Willst du Geschwindigkeit bei sauberem Englisch? Füge --fast hinzu (kleines Modell). --accurate existiert noch, ist aber jetzt redundant. Der Hinglish-Pfad verwendet immer large-v3.

Benutzerdefinierter Stil – erstelle JEDES Aussehen, das der Benutzer beschreibt. Ordne die Wörter des Benutzers diesen Flags zu (sie überschreiben --style):

• --font <Name|Pfad> – eine gebündelte Schriftart (Poppins-Bold, Poppins-Black, Anton-Regular, BebasNeue-Regular, ArchivoBlack-Regular) oder ein beliebiger .ttf-Pfad
• --fill #hex (Textfarbe) · --outline #hex · --box #hex|#hexAA|none (Hintergrund-Kapsel)
• --caps / --no-caps · --gradient "#hex,#hex,#hex" · --glow · --ow N (Umrissstärke)
• --size <pct> (Höhe) · --pos bottom|center|top

Beispiel – Benutzer sagt „knallpinke Großbuchstaben in einer dunklen abgerundeten Box, groß, Anton-Schriftart“ →

python caption.py v.mp4 --fill "#ff3da6" --box "#10141ae0" --caps --font Anton-Regular.ttf --size 6

Um einen brandneuen benannten Stil dauerhaft zu machen, füge einen Eintrag zum STYLES-Dictionary in caption.py hinzu.

Genauigkeit – falsch gehörte Wörter eliminieren (kostenlos, keine Tokens, kein menschlicher Blick)

Forced Alignment macht das Timing von Haus aus korrekt. Das Einzige, was es nicht beheben kann, ist, ob ein Wort richtig gehört wurde („ihr“/„Ihr“, Namen, Slang). Drei kostenlose Hebel drücken das gegen Null:

• --glossary "..." — Namen/Marken/Slang angeben (eine Liste oder einen .txt-Pfad). Beeinflusst den Initial-Prompt des ASR, sodass Eigennamen nicht mehr falsch gehört werden. Der größte Einzelgewinn bei Namen. Einmalige Liste.

  python caption.py talk.mp4 --glossary "Xaibridge, Hinglish, Xotion, Kamboh"
  

• --script DATEI — wenn die korrekten Wörter bereits existieren (Liedtexte, ein Skript), übergib sie. Das Tool überspringt ASR komplett und aligniert nur die gegebenen Wörter → 100% Inhaltsgenauigkeit.

  python caption.py song.mp4 --script lyrics.txt
  

• --grammar — offline Homophon-/Grammatikdurchlauf über die Untertitel („ihr“→„Ihr“, „dein“→„dein“). Führt LanguageTool lokal aus (kein Hochladen, keine Tokens); Timing wird nie berührt. Optionale Abhängigkeit — einmal aktivieren mit python setup.py --grammar (benötigt Java/JRE 8+); überspringt sauber, wenn nicht vorhanden.

  python caption.py talk.mp4 --accurate --glossary names.txt --grammar    # stapeln
  

Reihenfolge nach Aufwand-Nutzen: --glossary (Namen) → --script (wenn Text existiert) → --grammar (Homophone). Das Basismodell ist bereits standardmäßig large-v3. Das einzige Residuum, das diese nicht abfangen können, benötigt einen Menschen oder ein LLM – das sind die einzigen Kosten, für die sich Tokens lohnen, und zwar nur für die markierten Wörter, nicht das gesamte Transkript.

Lieder – zuerst den Gesang isolieren (--content)

Bei Musik macht die Trennung des Gesangs-Stems vor dem ASR die Transkription von Liedtexten viel sauberer (Whisper hört auf, gegen die Begleitung zu kämpfen). Es ist bedingt – sinnlos/langsam bei sauberer Sprache – also ist es geschützt:

python caption.py song.mp4 --content music                 # Gesangsisolation erzwingen (Demucs)
python caption.py clip.mp4                                  # --content auto (Standard): erkennt Musik, isoliert nur dann
python caption.py podcast.mp4 --content speech              # niemals isolieren (oder --no-isolate)
python caption.py song.mp4 --content music --script lyrics.txt   # sauberste Lieder: bekannte Wörter, getimt auf dem Gesangs-Stem

auto führt eine schnelle Musik/Sprach-Prüfung durch und isoliert NUR, wenn es Musik hört – Podcasts/Interviews werden also nie verlangsamt. Das Einbrennen verwendet immer das Originalvideo; nur das, was wir transkribieren/alignieren, ist der Stem. Benötigt demucs (installiert durch python setup.py); fällt auf das Original-Audio zurück, wenn nicht vorhanden.

Führe Skripte immer mit dem venv-Python aus – hier geschrieben als PY:

• macOS / Linux: PY = ./.venv-whisperx/bin/python
• Windows: PY = .venv-whisperx\Scripts\python

Die Skripte

• transcribe.py — Whisper → Wort-für-Wort-Transkript (Englisch Standard; --lang xx für andere).
• align.py — Forced Alignment für frame-genaues Timing. --code-switch für Hinglish/gemischt.
• cs_transcribe.py — Code-Switch-robuste Worterkennung (Sprach-ID pro Segment).
• mms_align.py — universeller MMS_FA Forced Aligner (1100+ Sprachen, jede Schrift).
• validate_timing.py — Timing-Plausibiltätsprüfung, die vom Code-Switch-Pfad verwendet wird.
• export-subs.py — Transkript → .srt + .vtt.
• multilang-subs.py — Übersetze Untertitel in viele Sprachen, offline.
• grammar_fix.py — Offline Homophon-/Grammatikkorrektur einer .srt (Timing erhalten); verwendet von --grammar.
• isolate_vocals.py — Demucs Gesangsisolation für Lieder + eine Musik-vs.-Sprach-Prüfung; verwendet von --content.
• qa.py — schnelle deterministische QA-Prüfung (Cue-Sanity + ffprobe-Output-Prüfung) → work/<base>.qa.json. Läuft automatisch nach jedem Brennvorgang; --strict lässt einen fehlerhaften Output mit einem Exit-Code ungleich Null beenden.
• footprint.py — rendert <base>.footprint.svg: eine Untertitel-Gesundheitskarte auf einen Blick (jedes Wort farblich nach Forced-Align-Konfidenz + Lückenmarkierungen + Befund). Läuft automatisch nach jedem Untertitel; --no-footprint zum Überspringen.
• benchmark.py — messe den tatsächlichen Genauigkeitsgewinn: WER der alten Voreinstellung (small) vs. der neuen Voreinstellung (large-v3 [+ Demucs]) gegen ein Referenztranskript. PY scripts/benchmark.py CLIP --ref truth.txt [--music] [--hinglish].
• caption.py — All-in-One gestylte Untertitel (Karaoke/Wort/Zeile; Hormozi/TikTok/Neon…) → animiert captions.js.

Untertitel für ein Video (die Hauptaufgabe) – Standardsprache = Englisch

Für eine andere Sprache übergib --lang <code>. Für Hinglish / gemischt verwende --code-switch.

1) Frame-genaue Wort-Timings

Sprache (Reden, Podcast, UGC):

PY scripts/align.py EINGABE --lang en --out work/transcript.json

Hinglish / gemischt Hindi-Englisch (oder jedes Code-Switching-Audio):

PY scripts/align.py EINGABE --code-switch --dual hi en --out work/transcript.json

Jede andere Sprache (Urdu, Spanisch, Arabisch, Chinesisch, …):

PY scripts/align.py EINGABE --lang ur --out work/transcript.json

2a) Untertitel (.srt / .vtt) + Einbrennen in das Video

PY scripts/export-subs.py work/transcript.json --out work/subs
ffmpeg -i EINGABE -vf "subtitles=work/subs.srt" -c:a copy captioned.mp4

Die .srt ist auch perfekt zum direkten Hochladen auf YouTube (auswählbar + SEO).

2b) Gestylte/animierte Untertitel (Hormozi, TikTok, Karaoke – Kurzform)

PY scripts/caption.py EINGABE --lang en --content speech --style karaoke --preset hormozi --out out/

Voreinstellungen: hormozi, beast, pill, neon, gradient, minimal, tiktok. Verwende --content music für Lieder/Liedtexte. Siehe docs/caption-styles.md.

3) Übersetze Untertitel in jede Sprache (optional)

PY scripts/multilang-subs.py work/subs.srt --to "hi,ur,es,fr,ar,de" [--burn EINGABE]

Regeln (fest eingebaut – nicht überschreiben)

• Timing ist IMMER Forced Alignment, niemals rohe ASR-Zeitstempel (kein Vor-/Nachlaufen).
• Standard-Untertitelsprache = Englisch; übergib --lang für alles andere.
• Musik/Gesang → --content music; Sprache/Reden → --content speech.
• Führe jedes Skript mit PY (dem venv-Python) aus, damit es whisperx/torch hat.
• Überprüfe vor der Auslieferung stichprobenartig einige Untertitel an ihren Wort-Startpunkten, um die Synchronisation zu bestätigen.

Sprachcodes

en (Standard), hi, ur, pa, es, fr, de, pt, ar, zh, ja, ko, ru, it, tr, id, nl, pl, uk, … – Whisper unterstützt ~99 Sprachen; MMS_FA aligniert 1100+.