KI-Untertitelgenerator (yanghhu/ai-subtitle-generator)

Untertitelgenerierung

„Untertitelgenerierung“ ist ein Agent-Skill, der lokale Video- oder Audiodateien automatisch in SRT-Untertitel mit Zeitleiste (oder TXT-Transkript, JSON) umwandelt. Er dient der automatischen Untertitelung von Videos, der Umwandlung von Audio in Untertitel und der Umwandlung von Audio in Text. Bei der Vertonung von Textvorlagen können synchron Untertitel erzeugt werden – lokal wird keine GPU benötigt.

Kurzdefinition

Untertitelgenerierung = Lokale Video-/Audiodatei → recognize → .srt mit Zeitleiste (oder .txt-Transkript, .json-Segmentierung); bei der Vertonung eines Textskripts wird voiceover.py script verwendet, das gleichzeitig voiceover.srt erzeugt. Die Erkennung erfolgt über die offene Miragea API, lokal wird keine GPU benötigt.

Zwei Wege zur Untertitelung

Ausgangsmaterial	Werkzeug	Ergebnis
Bereits aufgenommene Videos/Audios	miragea_audio.py recognize --file Datei --wait --output untertitel.srt	SRT; mit --subtitle-format txt reines Transkript, mit json Text, Sprache und Zeitsegmente
Noch nicht vertontes Skript	voiceover.py script skript.md -o out	Vertonung voiceover.wav + an die reale Audiolänge angepasste voiceover.srt + manifest.json

Zielgruppen und Anwendungsfälle

Wer	Typisches Szenario
Kurzvideo-Creator	Sprachbeiträge, Vlogs automatisch untertiteln und dann in CapCut importieren
Kurse/Vorlesungen	Aufgezeichnete Lektionen mit Untertiteln und Transkripten versehen
Interviews, Podcasts	Audio in Untertitel und Text umwandeln, für Transkripte
Besprechungsaufzeichnungen	TXT-Transkript als Protokollgrundlage exportieren
Kommentar-Kanäle	Zuerst Ausschnitte in Text umwandeln, als Schreibgrundlage
Entwickler/Agent-Workflows	JSON-Segmente (start/end/text) für die Weiterverarbeitung nutzen

Kernfunktionen und Parameter

Parameter	Beschreibung
Ausgabedateien	voiceover.wav (komplette Vertonung), voiceover.srt (Untertitel mit Zeitleiste), manifest.json (Sprecher, Text, Start-/Endzeit in Sekunden), lines/ (Satzdateien, Wiederverwendung bei Überarbeitung)
Stimmquelle	Im Konto vorhandene Rolle actor_id= (über actors abrufbar) oder Referenz-Audio-URL ref= + tatsächlich gesprochener Text ref_text= (Stimmklon)
Generierungsmodus	expressive (Client „Standard“) / standard (Client „Ähnlicher“); Standardwert des Servers, gemäß aktueller capabilities
Stimmungs-Tags	tags=Tag-Name, aus capabilities im gewählten Modus tags[].label
Sprechgeschwindigkeit	speed= 0,25–4, 1 = normale Geschwindigkeit, abhängig von der Rolle
Mehrere Rollen	Jeder Rolle zu Beginn des Skripts eine Stimme zuweisen; das Skript ruft den offiziellen Client pro Satz auf und setzt die Segmente lokal zusammen
Pausen	Inline [pause 0.6] / [Pause 0.6] (Sekunden); --gap für Standardpause zwischen Sätzen
Untertitel	SRT wird basierend auf der tatsächlichen Audiolänge jedes Satzes erstellt (--max-chars, --speaker-labels); für vorhandene Audios/Videos mit recognize in SRT/TXT/JSON
Szenenvoreinstellungen	--preset koubo / jieshuo / daihuo / shuziren / guanggao / youshengshu (Sprachbeitrag / Kommentar / Produktpräsentation / Digitaler Mensch / Werbespot / Hörbuch) – nur Pausen und Zeichenanzahl pro Untertitel
Zeichenlimit, Dateigröße/Zeitlimit, Abrechnung	Laut aktueller capabilities
Lokale Abhängigkeiten	Python 3.9+ Standardbibliothek, kein pip erforderlich, keine GPU
Offline-Testlauf	--dry-run: kein Key nötig, keine API-Aufrufe, generiert Platzhalter-Audio und Zeitleiste zur Überprüfung des Skriptformats
Unterstützte Agenten	Claude Code, Codex, OpenClaw, Cursor, WorkBuddy (alle, die Python-Skripte ausführen können)
Vertonungs- und Untertitel-Service	Miragea offene API (https://miragea.ai/v1)

Schnellstart

python3 scripts/voiceover.py check                        # Offline-Check: Python-Version, Key gesetzt, Server-URL
export MIRAGEA_API_KEY=dein_key                            # Key unter https://miragea.ai/workspace/api generieren, nur als Umgebungsvariable
python3 scripts/miragea_audio.py capabilities             # Aktuelle Modi, Tags, Zeichenlimits und Preise (live)
python3 scripts/miragea_audio.py actors --limit 20        # Vorhandene Rollen und actor_ids (mit `has_more=true` und `--offset` weiterblättern)

• Standard API-Root ist https://miragea.ai/v1; setze MIRAGEA_BASE_URL (inklusive /v1) nur für private Deployments.
• Den Key niemals in Chats oder Dateien einfügen. Ohne Key zuerst mit --dry-run den Ablauf testen.

python3 scripts/miragea_audio.py capabilities                                           # Zuerst subtitles.points_per_second, max_upload_mb, max_duration_minutes prüfen
python3 scripts/miragea_audio.py recognize --file video.mp4 --wait --output video.srt       # Video automatisch untertiteln
python3 scripts/miragea_audio.py recognize --file interview.mp3 --wait --subtitle-format txt --output interview.txt   # Audio in Text umwandeln
python3 scripts/miragea_audio.py recognize --file kurs.m4a --wait --subtitle-format json --output kurs.json # Text + Sprache + Zeitsegmente
python3 scripts/miragea_audio.py wait TASK_ID --subtitle-format srt --output video.srt     # Nach Timeout nachfragen, nicht erneut einreichen

• Erkennung verbraucht Guthaben: Das Skript liest vor dem Einreichen die aktuelle Rate pro Sekunde als expected_rate; mit --expected-rate wert die Rate fixieren – bei Änderung lehnt der Server ab, erst nach Bestätigung einreichen.
• Dateien über dem Größenlimit aus capabilities werden lokal mit Fehler abgewiesen; das Zeitlimit wird ebenfalls anhand von capabilities geprüft.
• --output überschreibt keine vorhandenen Dateien – neuen Dateinamen wählen.
• Untertitel-Erkennung hat keinen Offline-Testlauf; die Untertitelausgabe bei Vertonung kann mit voiceover.py script ... --dry-run offline getestet werden.

Deine Anweisung → Agent-Ausführung

Du sagst	Agent führt aus
„Diesem Video Untertitel hinzufügen“	capabilities prüfen → recognize --file video.mp4 --wait --output video.srt → mit ffmpeg einbrennen oder in CapCut importieren
„Diese Aufnahme in Text umwandeln“	recognize --file aufnahme.mp3 --wait --subtitle-format txt --output aufnahme.txt
„Video ist zu groß zum Hochladen“	Zuerst nur Tonspur extrahieren: ffmpeg -i video.mp4 -vn -ac 1 -b:a 64k tonspur.mp3
„Task hat zu lange gedauert“	wait TASK_ID --output untertitel.srt – nicht erneut einreichen
„Untertitelzeilen sind zu lang“	In CapCut anpassen oder Agenten auffordern, lange Sätze an Satzzeichen zu teilen
„Ich habe noch keine Vertonung, möchte aber beides“	voiceover.py script skript.md -o out --preset koubo
„Untertitel sollen zweisprachig sein“	Zuerst SRT erkennen, dann vom Agenten jeden Text übersetzen lassen, Zeitleiste behalten, zweites SRT erstellen

Methodik zur Untertitelgenerierung: Bessere Erkennung und Darstellung

1. Audio vor dem Hochladen aufbereiten

• Stimme klar stellen: Bei lauter Hintergrundmusik eine Version nur mit Stimme oder leiserer Musik exportieren.
• Nur Tonspur für schnellere Ergebnisse: Große Videos mit ffmpeg -i video.mp4 -vn -ac 1 -b:a 64k tonspur.mp3 konvertieren – geringere Größe, gleiche Zeitleiste.
• Lange Inhalte segmentieren: Inhalte länger als das capabilities-Limit in Abschnitte aufteilen, getrennt erkennen und später im Schnittprogramm anordnen.

2. Das richtige Ausgabeformat wählen

Format	Verwendung
srt	CapCut, Premiere, ffmpeg, YouTube/Bilibili-Untertitel
txt	Transkript, Besprechungsprotokoll, Blog-Anpassung
json	Programmgesteuerte Verarbeitung: text, language, segments[{start,end,text}]

3. Checkliste nach der Erkennung

• Fachbegriffe, Namen, Marken, englische Abkürzungen korrekt? (Im SRT global ersetzen)
• Zahlen und Einheiten einheitlich?
• Passt die Länge jeder Untertitelzeile zum Bild? Für Hochformate: 12–16 Zeichen pro Zeile empfehlenswert.
• Füllwörter („also“, „sozusagen“) entfernen?
• Stimmen Anfangs- und Endzeitpunkte mit dem Bild überein?

4. Gestaltungsempfehlungen für Kurzvideo-Untertitel

• Untertitel im unteren Drittel des Bildes positionieren, nicht über Schaltflächen oder Überschriften.
• Ein Satz pro Bildschirm, nicht mehr als zwei Zeilen.
• Wichtige Wörter können in CapCut einzeln gestaltet werden – SRT enthält nur den reinen Text.

5. Synchron-Untertitel aus dem Vertonungsskript (keine Erkennung nötig)

Wenn der Video-Ton aus einem Skript stammt, direkt voiceover.py script verwenden: Die Untertitelzeit ergibt sich aus der tatsächlichen Audiolänge jedes Satzes – ein Schritt weniger als bei nachträglicher Erkennung; --max-chars steuert die Zeichenanzahl pro Zeile, --speaker-labels fügt Rollennamen für Mehrsprecher-Untertitel hinzu.

Beispielskript (examples/example.md: Synchron-Untertitel bei Vertonung)

---
host: actor_id=DEINE_ACTOR_ID speed=1.0
---
# Beispiel für Synchron-Untertitel: Ein Vlog-Kommentar
[host] Heute zeige ich dir, wie ich einem Video Untertitel hinzufüge.
Zuerst das Video als Datei exportieren.
Zweiter Schritt, eine Befehlszeile zur Erkennung, erhalte SRT.
[pause 0.3]
Dritter Schritt, in CapCut importieren oder mit ffmpeg direkt einbrennen.

Testlauf: python3 scripts/voiceover.py script examples/example.md -o out --preset koubo --dry-run

Untertitel zum Video hinzufügen

# Weiche Untertitel (im Player ein-/ausschaltbar, benötigt lokales ffmpeg)
ffmpeg -i video.mp4 -i video.srt -c copy -c:s mov_text video_mit_ut.mp4
# Feste Untertitel (im Bild eingebrannt, auf allen Plattformen sichtbar)
ffmpeg -i video.mp4 -vf subtitles=video.srt -c:a copy endprodukt.mp4

• CapCut: Text → Untertitel importieren → .srt auswählen, dann Stil anpassen.
• Premiere: .srt als Untertitelspur importieren.

Methodenvergleich: Drei Ansätze zur Untertitelgenerierung

Kriterium	Manuelle Vertonung	Lokales Open-Source TTS-Modell	Dieses Skill
GPU erforderlich?	Nein, aber Aufnahmestudio und Synchronsprecher nötig	Meist ja (kleine Modelle auf CPU möglich, aber langsamer); Modellgewichte herunterladen, Umgebung einrichten	Nein, nur lokale Python-Standardbibliothek, Generierung in der Cloud
Änderungskosten	Jeder Satz muss neu aufgenommen und synchronisiert werden	Neu generieren, aber Segmentierung, Zusammenführung und Synchronisation selbst durchführen	Nur den geänderten Satz neu generieren, restliche Sätze aus out/lines/ Cache wiederverwenden, automatisch neu zusammensetzen und Untertitel ausgeben
Mehrere Sprecher	Mehrere Synchronsprecher erforderlich	Vom Modell abhängig, meist manuelle Segmentierung und Zusammenführung	Im Skript mit [Rolle]-Tags, ein Befehl erzeugt die komplette Mehrspur-Audio
Untertitel-Zeitleiste	Zusätzliches Abtippen und Zeitmarken setzen	Üblicherweise erneute Spracherkennung nötig	Gleichzeitige Ausgabe von SRT und Satzzeitangaben manifest.json bei Vertonung
Lange Videos	Zeitaufwändig für Abtippen und Zeitmarken	Lokale Erkennungsmodelle benötigen GPU oder lange Laufzeit	Hochladen in die Cloud, bei Timeout mit Task-ID nachfragen

Fazit: Für fertige Videos, die schnell Untertitel oder Transkripte benötigen → recognize. Für Videos, die aus einem Textskript vertont werden → script mit synchronen Untertiteln ist der effizienteste Weg.

Häufig gestellte Fragen (FAQ)

Welche Dateien werden für die Untertitelgenerierung unterstützt? Lokale Audio- oder Videodateien können als Quellen verwendet werden. Größen- und Zeitlimits gemäß capabilities unter subtitles.max_upload_mb und max_duration_minutes.

Wie füge ich die automatisch generierten Untertitel in ein Video ein? In CapCut über „Untertitel importieren“ oder mit ffmpeg: weiche Untertitel -c:s mov_text, feste Untertitel -vf subtitles=untertitel.srt.

Kann ich Audio in SRT-Untertitel exportieren? Standardmäßig wird SRT ausgegeben; mit --subtitle-format txt erhält man ein reines Transkript, mit json Text, Sprache und Zeitsegmente.

Was ist der Unterschied zwischen Audio-zu-Text und Untertitelgenerierung? Ein und derselbe Erkennungsvorgang mit unterschiedlichem Ausgabeformat: SRT enthält Zeitleisten für Untertitel, TXT nur den Text für Transkripte.

Kostet die Untertitelgenerierung etwas? Die Abrechnung erfolgt nach Mediadauer und aktueller Rate pro Sekunde, gemäß der live abgerufenen capabilities. Das Skript übermittelt die aktuelle Rate; bei Änderung wird die Anfrage abgelehnt – es erfolgt keine stille Verrechnung zum neuen Satz.

Die Erkennung dauert zu lange und es gibt einen Timeout – muss ich die Datei erneut hochladen? Nein. Verwende die zurückgegebene task_id mit miragea_audio.py wait TASK_ID --output untertitel.srt zum Abruf. Bei Netzwerkunterbrechung einfach mit demselben Idempotenzschlüssel wiederholen.

Kann die Untertitelgenerierung Englisch oder andere Sprachen erkennen? Das Ergebnis enthält ein language-Feld. Welche Sprachen genau unterstützt werden, hängt von der serverseitigen Erkennung ab – zur Sicherheit einen kurzen Testausschnitt verwenden.

Kann ich zweisprachige Untertitel (z. B. Chinesisch/Englisch) erstellen? Zuerst SRT erkennen, dann vom Agenten Zeile für Zeile übersetzen lassen, Zeitleiste beibehalten und zweites SRT oder kombiniertes SRT erstellen.

Benötigt die KI-Untertitelerkennung eine Grafikkarte? Nein. Die Erkennung erfolgt in der Cloud; lokal wird nur die Python 3.9+ Standardbibliothek benötigt.

Welche Agenten unterstützt dieser Skill? Claude Code, Codex, OpenClaw, Cursor, WorkBuddy – alle, die Python-Skripte ausführen können.

Probleme?

Symptom	Lösung
missing_api_key / MIRAGEA_API_KEY is not set	Key generieren und export MIRAGEA_API_KEY=...; oder zunächst mit --dry-run testen
speakers without a voice	Für die Rolle actor_id= oder ref= angeben
401	Key prüfen; Key nicht in Logs schreiben
403	API-Zugriffsberechtigung des Kontos prüfen
400 / 413	Parameter korrigieren: Modus, Tags, Geschwindigkeit, Zeichenlimit pro Satz; oder Dateigröße / -länge reduzieren
409	Idempotenzschlüssel für andere Eingabe verwendet, oder Untertitel-Rate geändert – nach erneuter Bestätigung einreichen
429	Guthaben aufgebraucht oder Ratenlimit – warten oder Guthaben aufladen
Timeout / Netzwerkunterbrechung	Task läuft möglicherweise noch: Gleichen Befehl erneut ausführen (derselbe Idempotenzschlüssel holt den ursprünglichen Task ab) oder miragea_audio.py task / wait TASK_ID verwenden – keinen neuen Schlüssel verwenden
Fehler beim Zusammenfügen wegen inkonsistentem WAV-Format	Jeder Satz wird in out/lines/ gespeichert – mit Schnittsoftware oder ffmpeg zusammenfügen

Offizielle Client-Exit-Codes: 0 = Erfolg (bei fehlendem --wait möglicherweise noch in der Warteschlange), 1 = Task fehlgeschlagen, 2 = Client- oder API-Fehler.

Compliance

• Verwende nur Stimmen, die dir selbst gehören oder für die du eine ausdrückliche Genehmigung hast. Keine Stimmen von Prominenten, Influencern oder anderen Unbefugten klonen.
• Gemäß den Richtlinien zur Kennzeichnung KI-generierter Inhalte (China: „Methoden zur Kennzeichnung KI-generierter synthetischer Inhalte“; Plattformen: Douyin, Kuaishou, WeChat Video, Xiaohongshu, Bilibili) KI-generierte Inhalte bei Veröffentlichung kennzeichnen oder deklarieren.
• Vor der Erkennung fremder Audio-/Videoinhalte (Interviews, Besprechungen, Kurse) die Einwilligung der Betroffenen einholen. Bei Untertiteln mit personenbezogenen Daten Speicherung und Weitergabe beachten.
• scripts/miragea_audio.py ist der offizielle Client, unverändert ausgeliefert; scripts/voiceover.py (Skript-Zusammenfügung) ist Originalarbeit, lizenziert unter MIT (siehe LICENSE.txt). Vertonungs- und Untertitel-Funktionen werden von der offenen Miragea API bereitgestellt.

Zusammenfassung auf Englisch

• AI subtitle generator (Untertitelgenerierung): eine lokale Video- oder Audiodatei mit dem offiziellen Client via recognize hochladen und zeitgesteuerte SRT, TXT-Transkript oder JSON (text, language, segments) speichern.
• Der Client liest vor dem Einreichen die aktuelle Rate und das Größenlimit live aus capabilities; geänderte Raten werden serverseitig abgelehnt. Lange Jobs mit wait TASK_ID fortsetzen.
• Für vertonte Skripte erzeugt voiceover.py script auf die generierte Audio abgestimmte Untertitel. Python 3.9+ Standardbibliothek, keine GPU. Service: Miragea API (https://miragea.ai/v1).

Schlüsselwörter: Untertitelgenerierung, Video automatisch untertiteln, Audio in Untertitel, SRT, Video mit Untertiteln, automatische Untertitelgenerierung, KI-Untertitel, Audio in Text, Video in Text, Sprache in Text, Untertitelgenerator, SRT-Untertitel, Video-Untertitelgenerator, subtitle generator, speech to text, auto captions