yyert123/Videountertitel

Video-Untertitel

Ein Befehl verwandelt eine Video- (oder Audio-) Datei in angenehm lesbare Untertitel und optional in ein untertiteltes MP4. Rohe Spracherkennungssegmente brechen oft mitten im Wort („Zent“ / „rum“) und sind zu lang; diese Fähigkeit stellt vollständige Wörter wieder her und formt sie in korrekte Untertitel um.

Wann verwenden

• „Füge diesem Video Untertitel hinzu“, „Erstelle ein SRT für meinen Vortrag“, „Brenne Untertitel ein“.
• „Erstelle TikTok/Reels/Shorts-Untertitel“ -> verwende --style shorts --burn.
• Der Benutzer benötigt eine .vtt für ein <track>-Element auf einer Website oder für einen YouTube-Upload.

Schritte

1. Überprüfen, ob MIRAGEA_API_KEY gesetzt ist (niemals ausgeben). Falls nicht vorhanden, den Benutzer auffordern, einen Schlüssel unter https://miragea.ai zu erstellen und mit export MIRAGEA_API_KEY=... zu setzen.

2. Das Skript auf die Benutzerdatei anwenden:

   python3 scripts/captions.py pfad/zu/video.mp4                 # -> video.srt + video.vtt
   python3 scripts/captions.py pfad/zu/video.mp4 --burn          # + video.captioned.mp4
   python3 scripts/captions.py pfad/zu/kurzvideo.mp4 --style shorts --burn   # Pop-Untertitel, zentriert
   

3. Das ausgegebene JSON lesen (srt, vtt, video, cues) und dem Benutzer die Pfade mitteilen.

4. Falls der Benutzer die Wortwahl korrigieren möchte, den .srt-Text bearbeiten (Zeitstempel beibehalten) und erneut mit --burn ausführen: das Transkript wird in <datei>.transcript.json zwischengespeichert, sodass erneute Durchläufe kostenlos sind.

Optionen

Flag	Standard	Beschreibung
--style standard	ja	2 Zeilen × 42 Zeichen, 1–7 s pro Untertitel (Rundfunkkonventionen)
--style shorts		1–3 Wörter pro Untertitel, GROSSBUCHSTABEN, zentriert beim Einbrennen
--burn	aus	Schreibt <name>.captioned.mp4 (H.264, originale Audiospur kopiert)
--upper	aus	Großbuchstaben für Standard-Untertitel
--out-dir VERZ	neben der Eingabe	Zielverzeichnis für Ausgaben
--force	aus	Ignoriere zwischengespeichertes Transkript und transkribiere neu

Kosten und Grenzen

Es wird nur eine 16-kHz-Mono-Audiospur hochgeladen (nicht das Video), bis zu 90 Minuten / 1 GB pro Datei.
Miragea berechnet 3 Punkte pro Sekunde Audio; zwischengespeicherte erneute Durchläufe sind kostenlos. Aktuelle Preise unter GET https://miragea.ai/v1/capabilities.

Fehlerbehebung

• ffmpeg nicht gefunden -> ffmpeg installieren (brew install ffmpeg, sudo apt install ffmpeg, winget install ffmpeg).
• 401 -> der Schlüssel ist falsch; 402 -> Guthaben aufladen auf miragea.ai; 429 -> warten und erneut ausführen (wiederholen ist sicher).
• Untertitel bei musiklastigen Clips etwas zu früh/spät: nach Kürzen der Einleitung mit --force erneut ausführen.

Siehe examples/ für Beispielausgaben.