yanghhu/ai-voiceover

KI-Sprachausgabe (AI Voiceover)

Nutze das voiceover-CLI (Paket ai-voiceover-studio, Python 3.9+), um Sprachaufnahmen zu generieren.

Setup-Prüfung

1. voiceover --version — falls fehlend: pip install -e "<repo>[edge]" ([edge] = kostenlose Stimmen, [yaml] = voices.yaml).
2. Führe voiceover doctor --json aus und behebe alle gemeldeten fail (es werden niemals Schlüssel ausgegeben).
3. Engines: Ohne Schlüssel wird die kostenlose edge-Engine verwendet (Internet nötig, kein Konto). MIRAGEA_API_KEY schaltet auf die Standard-Engine Miragea um (Stimmklonung, expressive Modelle); OPENAI_API_KEY aktiviert --provider openai. Fordere den Benutzer niemals auf, einen Schlüssel in den Chat einzufügen, gib ihn niemals aus und schreibe ihn niemals in Dateien.
4. MP3-Ausgabe und Video benötigen ffmpeg (mit libass für eingebrannte Untertitel).

Arbeitsablauf: Skript vertonen

1. Skript vorbereiten (Markdown oder TXT). Ein Sprecher-Tag pro Zeile oder Absatz:

   [SPRECHER]: Eröffnungszeile.
   Unmarkierte Zeilen setzen den aktuellen Sprecher fort.
   
   [ALEX](tags=aufgeregt, speed=1.1): Ein anderer Charakter.
   [pause 1]
   

   Überschriften, HTML-Kommentare, Codeblöcke und Tabellen werden ignoriert.
2. Stimmen (optional). Ohne eine Stimmen-Datei erhält jeder Sprecher automatisch eine eigene Stimme, die aus der Sprache des Skripts gewählt wird. Zur Auswahl: voiceover voices --json (ergänze --provider edge --filter de-DE für Edge-Stimmen wie de-DE-KatjaNeural; bei Miragea voice_id = Schauspieler-ID). Wenn zwei Stimmen denselben Namen haben, frage den Benutzer, welche gemeint ist. Bei Miragea kann eine Stimme auch eine öffentliche Referenz-Audio-URL plus deren exaktes Transkript sein (reference_text). Klone nur Stimmen, die dem Benutzer gehören oder deren Nutzung erlaubt ist.
3. voices.json schreiben, falls der Benutzer Stimmen ausgewählt hat (Schlüssel in Großbuchstaben):

   {"SPRECHER": {"actor_id": "de-DE-KatjaNeural"}, "ALEX": {"actor_id": "de-DE-ConradNeural", "speed": 1.05}}
   

4. Trockentest (offline, validiert Sprecher und Timing): voiceover script script.md -o out/ --dry-run --json
5. Generieren: voiceover script script.md [--voices voices.json] -o out/ --json Ausgabe: out/voiceover.mp3, out/voiceover.srt, out/manifest.json, out/segments/.
6. Gib die gespeicherten Pfade und die Dauer an. Melde keinen Erfolg, es sei denn, der Befehl endete mit Exit-Code 0.

Weitere Befehle

• Einzeilig: voiceover say "Text" [--voice <voice id|https://ref.wav>] [--ref-text "..."] [--lang de] -o zeile.mp3
• Gesichtsloses Video: voiceover video [--images slides/] --script script.md -o video.mp4 [--style clean|box|bold|minimal] [--size 1080x1920] [--speaker-labels] [--subtitles burn|sidecar|none] Untertitel werden standardmäßig eingebrannt. Ein Bild pro Segment ergibt exaktes Folien-Timing; ohne --images wird ein Farbverlaufshintergrund verwendet. Für Shorts verwende --size 1080x1920 --style bold.
• Untertitel aus Spracherkennung statt Timing (Miragea): ergänze --subtitles recognize (ein zusätzlicher API-Aufruf).
• Aufgabe nach Wartezeit-Timeout fortsetzen: voiceover task <task_id> --wait -o out.mp3.

Regeln

• Das erneute Ausführen desselben Befehls ist sicher: unveränderte Segmente kommen aus dem Cache und Remote- Anfragen verwenden Idempotenz-Schlüssel. Verwende --fresh nur, wenn der Benutzer eine neue Aufnahme möchte.
• Bei einem Wartezeit-Timeout behalte die gemeldete task_id und setze mit voiceover task fort; reiche nicht erneut ein.
• Exit-Codes: 0 ok, 1 Provider-Aufgabe fehlgeschlagen, 2 Nutzungs-/Konfigurations-/API-Fehler. Mit --json sind Fehler {"error": {"code", "message", "http_status", "retryable"}, "task_id"?}.
• 401: Schlüssel abgelehnt → Benutzer prüft die Schlüsselvariable. 403: Konto hat keinen API-Zugriff. 429: Kontingent-/Ratenlimit → warten, keine Schleife. 400: Text/Stimme/Geschwindigkeit/Tags korrigieren.
• proxy_unsupported (edge): Setze VOICEOVER_EDGE_PROXY oder entferne HTTPS_PROXY für den Befehl.
• Sprachen: edge deckt 75 Sprachen ab; Miragea deckt Chinesisch, Englisch, Japanisch, Koreanisch, Deutsch, Französisch, Russisch, Portugiesisch, Spanisch, Italienisch ab (mit Stimmklonung).