TTS (Text-to-Speech) Skill
Dieser Skill führt durch die Implementierung der Text-to-Speech (TTS)-Funktionalität mit dem z-ai-web-dev-sdk-Paket und ermöglicht die Umwandlung von Text in natürlich klingende Sprachausgabe.
Skills-Pfad
Skill-Speicherort: {project_path}/skills/TTS
Dieser Skill befindet sich unter dem oben genannten Pfad in Ihrem Projekt.
Referenzskripte: Beispieltestskripte finden Sie im Verzeichnis {Skill-Speicherort}/scripts/ zum schnellen Testen und als Referenz. Siehe {Skill-Speicherort}/scripts/tts.ts für ein funktionierendes Beispiel.
Überblick
Text-to-Speech ermöglicht es Ihnen, Anwendungen zu entwickeln, die aus Texteingaben gesprochene Audiodateien generieren, und unterstützt verschiedene Stimmen, Geschwindigkeiten und Ausgabeformate für unterschiedliche Anwendungsfälle.
WICHTIG: z-ai-web-dev-sdk darf NUR im Backend-Code verwendet werden. Verwenden Sie es niemals im clientseitigen Code.
API-Beschränkungen und -Einschränkungen
Bevor Sie die TTS-Funktionalität implementieren, beachten Sie diese wichtigen Einschränkungen:
Eingabetext-Einschränkungen
- Maximale Länge: 1024 Zeichen pro Anfrage
- Text, der diese Grenze überschreitet, muss in kleinere Teile aufgeteilt werden
Audio-Parameter
- Geschwindigkeitsbereich: 0,5 bis 2,0
- 0,5 = halbe Geschwindigkeit (langsamer)
- 1,0 = normale Geschwindigkeit (Standard)
- 2,0 = doppelte Geschwindigkeit (schneller)
- Lautstärkebereich: Größer als 0, bis 10
- Standard: 1,0
- Werte müssen größer als 0 (exklusiv) und bis einschließlich 10 (inklusive) sein
Format und Streaming
- Streaming-Einschränkung: Wenn
stream: trueaktiviert ist, wird nur daspcm-Format unterstützt - Nicht-Streaming: Unterstützt die Formate
wav,pcmundmp3 - Abtastrate: 24000 Hz (empfohlen)
Bewährte Methode für langen Text
function splitTextIntoChunks(text, maxLength = 1000) {
const chunks = [];
const sentences = text.match(/[^.!?]+[.!?]+/g) || [text];
let currentChunk = '';
for (const sentence of sentences) {
if ((currentChunk + sentence).length <= maxLength) {
currentChunk += sentence;
} else {
if (currentChunk) chunks.push(currentChunk.trim());
currentChunk = sentence;
}
}
if (currentChunk) chunks.push(currentChunk.trim());
return chunks;
}
Voraussetzungen
Das z-ai-web-dev-sdk-Paket ist bereits installiert. Importieren Sie es wie in den folgenden Beispielen gezeigt.
CLI-Verwendung (für einfache Aufgaben)
Für einfache Text-to-Speech-Umwandlungen können Sie die z-ai-CLI anstelle des Schreibens von Code verwenden. Dies ist ideal für schnelle Audioerstellung, das Testen von Stimmen oder einfache Automatisierung.
Einfaches TTS
# Text in Sprache umwandeln (Standard-WAV-Format)
z-ai tts --input "Hallo, Welt" --output ./hallo.wav
# Mit kurzen Optionen
z-ai tts -i "Hallo, Welt" -o ./hallo.wav
Verschiedene Stimmen und Geschwindigkeit
# Bestimmte Stimme verwenden
z-ai tts -i "Willkommen bei unserem Service" -o ./willkommen.wav --voice tongtong
# Sprachgeschwindigkeit anpassen (0,5-2,0)
z-ai tts -i "Dies ist schnellere Sprache" -o ./schnell.wav --speed 1.5
# Langsamere Sprache
z-ai tts -i "Dies ist langsamere Sprache" -o ./langsam.wav --speed 0.8
Verschiedene Ausgabeformate
# MP3-Format
z-ai tts -i "Hallo Welt" -o ./hallo.mp3 --format mp3
# WAV-Format (Standard)
z-ai tts -i "Hallo Welt" -o ./hallo.wav --format wav
# PCM-Format
z-ai tts -i "Hallo Welt" -o ./hallo.pcm --format pcm
Streaming-Ausgabe
# Stream-Audioerstellung
z-ai tts -i "Dies ist ein längerer Text, der gestreamt wird" -o ./stream.wav --stream
CLI-Parameter
--input, -i <text>: Erforderlich - Text, der in Sprache umgewandelt werden soll (max. 1024 Zeichen)--output, -o <pfad>: Erforderlich - Ausgabedateipfad für die Audiodatei--voice, -v <stimme>: Optional - Stimmtyp (Standard: tongtong)--speed, -s <zahl>: Optional - Sprachgeschwindigkeit, 0,5-2,0 (Standard: 1,0)--format, -f <format>: Optional - Ausgabeformat: wav, mp3, pcm (Standard: wav)--stream: Optional - Streaming-Ausgabe aktivieren (unterstützt nur pcm-Format)
Wann CLI vs. SDK verwenden
CLI verwenden für:
- Schnelle Text-to-Speech-Umwandlungen
- Testen verschiedener Stimmen und Geschwindigkeiten
- Einfache Batch-Audioerstellung
- Befehlszeilen-Automatisierungsskripte
SDK verwenden für:
- Dynamische Audioerstellung in Anwendungen
- Integration mit Webservices
- Benutzerdefinierte Audioverarbeitungspipelines
- Produktionsanwendungen mit komplexen Anforderungen
Einfache TTS-Implementierung
Einfache Text-to-Speech-Ausgabe
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function textToSpeech(text, outputPath) {
const zai = await ZAI.create();
const response = await zai.audio.tts.create({
input: text,
voice: 'tongtong',
speed: 1.0,
response_format: 'wav',
stream: false
});
// ArrayBuffer aus dem Response-Objekt holen
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
console.log(`Audio gespeichert unter ${outputPath}`);
return outputPath;
}
// Verwendung
await textToSpeech('Hallo, Welt!', './output.wav');
Mehrere Stimmenoptionen
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function generateWithVoice(text, voice, outputPath) {
const zai = await ZAI.create();
const response = await zai.audio.tts.create({
input: text,
voice: voice, // Verfügbare Stimmen: tongtong, chuichui, xiaochen, jam, kazi, douji, luodo
speed: 1.0,
response_format: 'wav',
stream: false
});
// ArrayBuffer aus dem Response-Objekt holen
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
return outputPath;
}
// Verwendung
await generateWithVoice('Willkommen bei unserem Service', 'tongtong', './willkommen.wav');
Anpassbare Geschwindigkeit
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function generateWithSpeed(text, speed, outputPath) {
const zai = await ZAI.create();
// Geschwindigkeitsbereich: 0,5 bis 2,0 (API-Einschränkung)
// 0,5 = halbe Geschwindigkeit (langsamer)
// 1,0 = normale Geschwindigkeit (Standard)
// 2,0 = doppelte Geschwindigkeit (schneller)
// Werte außerhalb dieses Bereichs führen zu API-Fehlern
const response = await zai.audio.tts.create({
input: text,
voice: 'tongtong',
speed: speed,
response_format: 'wav',
stream: false
});
// ArrayBuffer aus dem Response-Objekt holen
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
return outputPath;
}
// Verwendung - langsamere Erzählung
await generateWithSpeed('Dies ist eine wichtige Ankündigung', 0.8, './langsam.wav');
// Verwendung - schnellere Erzählung
await generateWithSpeed('Schnelles Update', 1.3, './schnell.wav');
Anpassbare Lautstärke
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function generateWithVolume(text, volume, outputPath) {
const zai = await ZAI.create();
// Lautstärkebereich: größer als 0, bis 10 (API-Einschränkung)
// Werte müssen > 0 (exklusiv) und <= 10 (inklusiv) sein
// Standard: 1.0 (normale Lautstärke)
const response = await zai.audio.tts.create({
input: text,
voice: 'tongtong',
speed: 1.0,
volume: volume, // Optionaler Parameter
response_format: 'wav',
stream: false
});
// ArrayBuffer aus dem Response-Objekt holen
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
return outputPath;
}
// Verwendung - lauteres Audio
await generateWithVolume('Dies ist eine Ankündigung', 5.0, './laut.wav');
// Verwendung - leiseres Audio
await generateWithVolume('Geflüsterte Nachricht', 0.5, './leise.wav');
Fortgeschrittene Anwendungsfälle
Batch-Verarbeitung
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
import path from 'path';
async function batchTextToSpeech(textArray, outputDir) {
const zai = await ZAI.create();
const results = [];
// Sicherstellen, dass das Ausgabeverzeichnis existiert
if (!fs.existsSync(outputDir)) {
fs.mkdirSync(outputDir, { recursive: true });
}
for (let i = 0; i < textArray.length; i++) {
try {
const text = textArray[i];
const outputPath = path.join(outputDir, `audio_${i + 1}.wav`);
const response = await zai.audio.tts.create({
input: text,
voice: 'tongtong',
speed: 1.0,
response_format: 'wav',
stream: false
});
// ArrayBuffer aus dem Response-Objekt holen
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
results.push({
success: true,
text,
path: outputPath
});
} catch (error) {
results.push({
success: false,
text: textArray[i],
error: error.message
});
}
}
return results;
}
// Verwendung
const texts = [
'Willkommen zu Kapitel eins',
'Willkommen zu Kapitel zwei',
'Willkommen zu Kapitel drei'
];
const results = await batchTextToSpeech(texts, './audio-output');
console.log('Erstellt:', results.length, 'Audiodateien');
Dynamische Inhaltserstellung
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
class TTSGenerator {
constructor() {
this.zai = null;
}
async initialize() {
this.zai = await ZAI.create();
}
async generateAudio(text, options = {}) {
const {
voice = 'tongtong',
speed = 1.0,
format = 'wav'
} = options;
const response = await this.zai.audio.tts.create({
input: text,
voice: voice,
speed: speed,
response_format: format,
stream: false
});
// ArrayBuffer aus dem Response-Objekt holen
const arrayBuffer = await response.arrayBuffer();
return Buffer.from(new Uint8Array(arrayBuffer));
}
async saveAudio(text, outputPath, options = {}) {
const buffer = await this.generateAudio(text, options);
if (buffer) {
fs.writeFileSync(outputPath, buffer);
return outputPath;
}
return null;
}
}
// Verwendung
const generator = new TTSGenerator();
await generator.initialize();
await generator.saveAudio(
'Hallo, dies ist ein Test',
'./output.wav',
{ speed: 1.2 }
);
Next.js-API-Routenbeispiel
import { NextRequest, NextResponse } from 'next/server';
export async function POST(req: NextRequest) {
try {
const { text, voice = 'tongtong', speed = 1.0 } = await req.json();
// ZAI SDK importieren
const ZAI = (await import('z-ai-web-dev-sdk')).default;
// SDK-Instanz erstellen
const zai = await ZAI.create();
// TTS-Audio generieren
const response = await zai.audio.tts.create({
input: text.trim(),
voice: voice,
speed: speed,
response_format: 'wav',
stream: false,
});
// ArrayBuffer aus dem Response-Objekt holen
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
// Audio als Antwort zurückgeben
return new NextResponse(buffer, {
status: 200,
headers: {
'Content-Type': 'audio/wav',
'Content-Length': buffer.length.toString(),
'Cache-Control': 'no-cache',
},
});
} catch (error) {
console.error('TTS-API-Fehler:', error);
return NextResponse.json(
{
error: error instanceof Error ? error.message : 'Spracherzeugung fehlgeschlagen, bitte versuchen Sie es später erneut',
},
{ status: 500 }
);
}
}
Bewährte Methoden
1. Textvorbereitung
function prepareTextForTTS(text) {
// Übermäßige Leerzeichen entfernen
text = text.replace(/\s+/g, ' ').trim();
// Häufige Abkürzungen für bessere Aussprache erweitern
const abbreviations = {
'Dr.': 'Doktor',
'Mr.': 'Mister',
'Mrs.': 'Misses',
'etc.': 'et cetera'
};
for (const [abbr, full] of Object.entries(abbreviations)) {
text = text.replace(new RegExp(abbr, 'g'), full);
}
return text;
}
2. Fehlerbehandlung
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function safeTTS(text, outputPath) {
try {
// Eingabe validieren
if (!text || text.trim().length === 0) {
throw new Error('Texteingabe darf nicht leer sein');
}
if (text.length > 1024) {
throw new Error('Texteingabe überschreitet die maximale Länge von 1024 Zeichen');
}
const zai = await ZAI.create();
const response = await zai.audio.tts.create({
input: text,
voice: 'tongtong',
speed: 1.0,
response_format: 'wav',
stream: false
});
// ArrayBuffer aus dem Response-Objekt holen
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
return {
success: true,
path: outputPath,
size: buffer.length
};
} catch (error) {
console.error('TTS-Fehler:', error);
return {
success: false,
error: error.message
};
}
}
3. Wiederverwendung der SDK-Instanz
import ZAI from 'z-ai-web-dev-sdk';
// Singleton-Instanz erstellen
let zaiInstance = null;
async function getZAIInstance() {
if (!zaiInstance) {
zaiInstance = await ZAI.create();
}
return zaiInstance;
}
// Verwendung
const zai = await getZAIInstance();
const response = await zai.audio.tts.create({ ... });
Häufige Anwendungsfälle
- Hörbücher & Podcasts: Schriftliche Inhalte in Audioformat umwandeln
- E-Learning: Erstellung einer Erzählung für Bildungsinhalte
- Barrierefreiheit: Bereitstellung von Audioversionen von Textinhalten
- Sprachassistenten: Generieren dynamischer Antworten
- Ankündigungen: Erstellung automatisierter Audio-Benachrichtigungen
- IVR-Systeme: Generierung von Telefonansagen
- Inhaltslokalisierung: Erstellung von Audio in verschiedenen Sprachen
Integrationsbeispiele
Express.js-API-Endpunkt
import express from 'express';
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
import path from 'path';
const app = express();
app.use(express.json());
let zaiInstance;
const outputDir = './audio-output';
async function initZAI() {
zaiInstance = await ZAI.create();
if (!fs.existsSync(outputDir)) {
fs.mkdirSync(outputDir, { recursive: true });
}
}
// ... (weiterer Code folgt)
// Endpunkt zur TTS-Generierung
app.post('/api/tts', async (req, res) => {
try {
const { text, voice = 'tongtong', speed = 1.0, format = 'wav' } = req.body;
if (!text || text.length > 1024) {
return res.status(400).json({ error: 'Ungültige Eingabe: Text muss zwischen 1 und 1024 Zeichen liegen' });
}
const response = await zaiInstance.audio.tts.create({
input: text,
voice: voice,
speed: speed,
response_format: format,
stream: false
});
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
// Optional: In Datei speichern
const fileName = `tts-${Date.now()}.${format}`;
const filePath = path.join(outputDir, fileName);
fs.writeFileSync(filePath, buffer);
res.set('Content-Type', `audio/${format}`);
res.send(buffer);
} catch (error) {
console.error('Fehler bei TTS-Generierung:', error);
res.status(500).json({ error: 'Fehler bei der Spracherzeugung' });
}
});
initZAI().then(() => {
app.listen(3000, () => console.log('Server läuft auf Port 3000'));
});
Fehlerbehebung (Troubleshooting)
Häufige Fehler
| Fehler | Ursache | Lösung |
|---|---|---|
Eingabe zu lang | Text überschreitet 1024 Zeichen | Text in kleinere Teile aufteilen |
Ungültige Geschwindigkeit | Geschwindigkeit außerhalb von 0,5-2,0 | Geschwindigkeit auf 0,5-2,0 beschränken |
Ungültige Lautstärke | Lautstärke außerhalb von 0 bis 10 | Lautstärke auf 0-10 beschränken |
Nicht unterstütztes Format beim Streaming | Streaming mit nicht-PCM-Format | Bei aktiviertem Streaming auf PCM-Format ändern |
Debugging-Tipps
# Testen mit kurzer Eingabe
z-ai tts -i "Test" -o ./test.wav
# Lautstärke explizit angeben
z-ai tts -i "Test" -o ./test.wav --volume 1.0
# Ausgabeverzeichnis überprüfen
ls -la ./test.wav
Referenzen
Lizenz
Dieser Skill wird unter der MIT-Lizenz bereitgestellt. Siehe LICENSE-Datei für Details.