TTS (Text-to-Speech)

Was macht TTS (Text-to-Speech)?

Wandelt jeden Text in Sprachaudio um. Unterstützt zwei Backends (Kokoro lokal, Noiz Cloud), zwei Modi (einfach oder zeitgenau) und pro-Segment-Stimmsteuerung.

Auslöser

• Text zu Sprache / TTS / sprechen / sagen
• Sprachklon / Dubbing
• EPUB zu Audio / SRT zu Audio / in Audio konvertieren
• 语音 / 说 / 讲 / 说话

Einfacher Modus – Text zu Audio

speak ist die Standardeinstellung – der Unterbefehl kann weggelassen werden:

# Basisnutzung (speak ist implizit)
python3 skills/tts/scripts/tts.py -t "Hallo Welt"          # -o pfad zum Speichern hinzufügen
python3 skills/tts/scripts/tts.py -f artikel.txt -o ausgabe.mp3

# Sprachklon – lokaler Dateipfad oder URL
python3 skills/tts/scripts/tts.py -t "Hallo" --ref-audio ./ref.wav
python3 skills/tts/scripts/tts.py -t "Hallo" --ref-audio https://example.com/meine_stimme.wav -o klon.wav

# Sprachnachrichtenformat
python3 skills/tts/scripts/tts.py -t "Hallo" --format opus -o nachricht.opus
python3 skills/tts/scripts/tts.py -t "Hallo" --format ogg -o nachricht.ogg

Die Integration von Drittanbietern (Feishu/Telegram/Discord) ist in ref_3rd_party.md dokumentiert.

Timeline-Modus – SRT zu zeitlich ausgerichtetem Audio

Für präzises pro-Segment-Timing (Dubbing, Untertitel, Video-Narration).

Schritt 1: SRT abrufen oder erstellen

Wenn der Benutzer keine SRT-Datei hat, aus Text generieren:

python3 skills/tts/scripts/tts.py to-srt -i artikel.txt -o artikel.srt
python3 skills/tts/scripts/tts.py to-srt -i artikel.txt -o artikel.srt --cps 15 --gap 500

--cps = Zeichen pro Sekunde (Standard 4, gut für Chinesisch; ~15 für Englisch). Der Agent kann SRT auch manuell erstellen.

Schritt 2: Eine Stimmkarte (Voice-Map) erstellen

JSON-Datei, die Standard- und pro-Segment-Stimmeinstellungen steuert. segments-Schlüssel unterstützen einzelne Indizes wie "3" oder Bereiche wie "5-8".

Kokoro-Stimmkarte:

{
  "default": { "voice": "zf_xiaoni", "lang": "cmn" },
  "segments": {
    "1": { "voice": "zm_yunxi" },
    "5-8": { "voice": "af_sarah", "lang": "en-us", "speed": 0.9 }
  }
}

Noiz-Stimmkarte (fügt emo, reference_audio-Unterstützung hinzu). reference_audio kann ein lokaler Pfad oder eine URL sein (eigenes Audio des Benutzers; nur Noiz):

{
  "default": { "voice_id": "voice_123", "target_lang": "zh" },
  "segments": {
    "1": { "voice_id": "voice_host", "emo": { "Joy": 0.6 } },
    "2-4": { "reference_audio": "./refs/guest.wav" }
  }
}

Dynamisches Zerschneiden von Referenzaudio: Wenn Sie ein Video übersetzen oder synchronisieren und möchten, dass jeder Satz automatisch das Audio des Originalvideos zum exakt gleichen Zeitstempel als Referenzaudio verwendet, verwenden Sie das Argument --ref-audio-track anstatt reference_audio in der Karte zu setzen:

python3 skills/tts/scripts/tts.py render --srt eingabe.srt --voice-map vm.json --ref-audio-track original_video.mp4 -o ausgabe.wav

Vollständige Beispiele finden Sie in examples/.

Schritt 3: Rendern

python3 skills/tts/scripts/tts.py render --srt eingabe.srt --voice-map vm.json -o ausgabe.wav
python3 skills/tts/scripts/tts.py render --srt eingabe.srt --voice-map vm.json --backend noiz --auto-emotion -o ausgabe.wav

Wann wählt man was?

Bedarf	Empfohlen
Einfach Text vorlesen, kein Schnickschnack	Kokoro (Standard)
EPUB/PDF-Hörbuch mit Kapiteln	Kokoro (native Unterstützung)
Stimm-Mischung ("v1:60,v2:40")	Kokoro
Sprachklon aus Referenzaudio	Noiz
Emotionssteuerung (emo-Parameter)	Noiz
Exakte serverseitige Dauer pro Segment	Noiz

Wenn der Benutzer Emotionssteuerung + Sprachklon + präzise Dauer zusammen benötigt, ist Noiz das einzige Backend, das alle drei unterstützt.

Gastmodus (ohne API-Key)

Wenn kein API-Key konfiguriert ist, fällt tts.py automatisch in den Gastmodus – einen eingeschränkten Noiz-Endpunkt, der keine Authentifizierung erfordert. Der Gastmodus unterstützt nur --voice-id, --speed und --format; Sprachklon, Emotion, Dauer und Timeline-Rendering sind nicht verfügbar.

# Gastmodus (wird automatisch erkannt, wenn kein API-Key gesetzt ist)
python3 skills/tts/scripts/tts.py -t "Hallo" --voice-id 883b6b7c -o hallo.wav

# Explizites Backend-Override zur Verwendung von Kokoro
python3 skills/tts/scripts/tts.py -t "Hallo" --backend kokoro

Verfügbare Gast-Stimmen (15 integriert):

voice_id	name	lang	gender	tone
063a4491	販売員（なおみ）	ja	F	喜び
4252b9c8	落ち着いた女性	ja	F	穏やか
578b4be2	熱血漢（たける）	ja	M	怒り
a9249ce7	安らぎ（みなと）	ja	M	穏やか
f00e45a1	旅人（かいと）	ja	M	穏やか
b4775100	悦悦｜社交分享	zh	F	Joyful
77e15f2c	婉青｜情绪抚慰	zh	F	Calm
ac09aeb4	阿豪｜磁性主持	zh	M	Calm
87cb2405	建国｜知识科普	zh	M	Calm
3b9f1e27	小明｜科技达人	zh	M	Joyful
95814add	Science Narration	en	M	Calm
883b6b7c	The Mentor (Alex)	en	M	Joyful
a845c7de	The Naturalist (Silas)	en	M	Calm
5a68d66b	The Healer (Serena)	en	F	Calm
0e4ab6ec	The Mentor (Maya)	en	F	Calm

Sicherheit und Datenweitergabe

Dieses Skill führt zur Laufzeit folgende Datei- und Netzwerkoperationen aus:

• Anmeldeinformationsspeicherung: Wenn Sie config --set-api-key ausführen, wird der Schlüssel in ~/.config/noiz/api_key gespeichert (Berechtigungen 0600). Die Umgebungsvariable NOIZ_API_KEY wird ebenfalls als Alternative unterstützt.
• Legacy-Schlüsselmigration: Wenn ~/.noiz_api_key existiert und ~/.config/noiz/api_key nicht, wird der Schlüssel an den neuen Speicherort kopiert (nicht gelöscht). Eine Meldung wird ausgegeben; die alte Datei bleibt zur manuellen Entfernung unberührt.
• Netzwerkaufrufe (Noiz-Backend): Text und optionales Referenzaudio werden zur Synthese an https://noiz.ai/v1/ hochgeladen. Es werden keine Daten gesendet, es sei denn, Sie rufen einen Noiz-Befehl auf.
• Referenzaudio-Download: Wenn --ref-audio eine URL ist, wird die Datei in eine temporäre Datei heruntergeladen, für den API-Aufruf verwendet und dann gelöscht. Wenn keine voice-id oder kein ref-audio angegeben wird, wird ein Standard-Referenzaudio von storage.googleapis.com oder noiz.ai heruntergeladen.
• Temporäre Dateien: Temporäre Audio-/Textdateien können während der Synthese erstellt und nach der Verwendung bereinigt werden.
• ffmpeg: Wird nur im Timeline-render-Modus aufgerufen, um das endgültige Audio zusammenzusetzen.

Es werden keine Dateien außerhalb des Ausgabepfads und ~/.config/noiz/ geändert. Das Kokoro-Backend läuft vollständig offline ohne Netzwerkzugriff.

Anforderungen

• ffmpeg im PATH (nur Timeline-Modus)
• requests-Paket: uv pip install requests (für Noiz-Backend erforderlich)
• Holen Sie sich Ihren API-Key unter Noiz Developer und führen Sie dann python3 skills/tts/scripts/tts.py config --set-api-key IHR_SCHLÜSSEL aus (der Gastmodus funktioniert ohne Schlüssel, hat aber eingeschränkte Funktionen)
• Kokoro: Falls bereits installiert, übergeben Sie --backend kokoro, um das lokale Backend zu verwenden

Noiz-API-Authentifizierung

Verwenden Sie ausschließlich den base64-codierten API-Key als Authorization – ohne Präfix (z.B. kein APIKEY oder Bearer ). Jegliches Präfix führt zu 401.

Backend-Details und vollständige Argumentreferenz finden Sie in reference.md.