Compétence TTS (Text-to-Speech)
Cette compétence guide l'implémentation de la fonctionnalité de synthèse vocale (TTS) à l'aide du package z-ai-web-dev-sdk, permettant la conversion de texte en fichier audio de parole naturelle.
Chemin de la compétence
Emplacement de la compétence : {project_path}/skills/TTS
Cette compétence se trouve au chemin ci-dessus dans votre projet.
Scripts de référence : Des exemples de scripts de test sont disponibles dans le répertoire {Emplacement de la compétence}/scripts/ pour des tests et une référence rapides. Voir {Emplacement de la compétence}/scripts/tts.ts pour un exemple fonctionnel.
Aperçu
La synthèse vocale vous permet de créer des applications qui génèrent de l'audio parlé à partir d'un texte saisi, en prenant en charge plusieurs voix, vitesses et formats de sortie pour divers cas d'utilisation.
IMPORTANT : z-ai-web-dev-sdk DOIT être utilisé uniquement dans le code backend. Ne l'utilisez jamais dans le code côté client.
Limitations et contraintes de l'API
Avant d'implémenter la fonctionnalité TTS, soyez conscient de ces limitations importantes :
Contraintes du texte d'entrée
- Longueur maximale : 1024 caractères par requête
- Le texte dépassant cette limite doit être divisé en morceaux plus petits
Paramètres audio
- Plage de vitesse : 0.5 à 2.0
- 0.5 = moitié vitesse (plus lent)
- 1.0 = vitesse normale (par défaut)
- 2.0 = vitesse double (plus rapide)
- Plage de volume : Supérieur à 0, jusqu'à 10
- Par défaut : 1.0
- Les valeurs doivent être supérieures à 0 (exclusif) et jusqu'à 10 (inclus)
Format et streaming
- Limitation du streaming : Lorsque
stream: trueest activé, seul le formatpcmest pris en charge - Non-streaming : Prend en charge les formats
wav,pcmetmp3 - Taux d'échantillonnage : 24000 Hz (recommandé)
Bonne pratique pour les textes longs
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;
}
Prérequis
Le package z-ai-web-dev-sdk est déjà installé. Importez-le comme indiqué dans les exemples ci-dessous.
Utilisation en ligne de commande (CLI) (pour les tâches simples)
Pour les conversions simples de texte en parole, vous pouvez utiliser la CLI z-ai au lieu d'écrire du code. C'est idéal pour la génération audio rapide, le test des voix ou l'automatisation simple.
TTS basique
# Convertir du texte en parole (format WAV par défaut)
z-ai tts --input "Bonjour le monde" --output ./bonjour.wav
# Utilisation d'options courtes
z-ai tts -i "Bonjour le monde" -o ./bonjour.wav
Différentes voix et vitesses
# Utiliser une voix spécifique
z-ai tts -i "Bienvenue dans notre service" -o ./bienvenue.wav --voice tongtong
# Ajuster la vitesse de parole (0.5-2.0)
z-ai tts -i "Ceci est une parole plus rapide" -o ./rapide.wav --speed 1.5
# Parole plus lente
z-ai tts -i "Ceci est une parole plus lente" -o ./lente.wav --speed 0.8
Différents formats de sortie
# Format MP3
z-ai tts -i "Bonjour le monde" -o ./bonjour.mp3 --format mp3
# Format WAV (par défaut)
z-ai tts -i "Bonjour le monde" -o ./bonjour.wav --format wav
# Format PCM
z-ai tts -i "Bonjour le monde" -o ./bonjour.pcm --format pcm
Sortie en streaming
# Génération audio en streaming
z-ai tts -i "Ceci est un texte plus long qui sera diffusé en streaming" -o ./stream.wav --stream
Paramètres CLI
--input, -i <texte>: Requis - Texte à convertir en parole (max 1024 caractères)--output, -o <chemin>: Requis - Chemin du fichier audio de sortie--voice, -v <voix>: Optionnel - Type de voix (par défaut : tongtong)--speed, -s <nombre>: Optionnel - Vitesse de parole, 0.5-2.0 (par défaut : 1.0)--format, -f <format>: Optionnel - Format de sortie : wav, mp3, pcm (par défaut : wav)--stream: Optionnel - Activer la sortie en streaming (prend uniquement en charge le format pcm)
Quand utiliser la CLI vs le SDK
Utilisez la CLI pour :
- Conversions rapides de texte en parole
- Tester différentes voix et vitesses
- Génération audio par lots simple
- Scripts d'automatisation en ligne de commande
Utilisez le SDK pour :
- Génération audio dynamique dans les applications
- Intégration avec des services web
- Pipelines de traitement audio personnalisés
- Applications de production avec des exigences complexes
Implémentation TTS de base
Synthèse vocale simple
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
});
// Obtenir le tableau de l'objet Response
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
console.log(`Audio sauvegardé dans ${outputPath}`);
return outputPath;
}
// Utilisation
await textToSpeech('Bonjour le monde !', './output.wav');
Options de plusieurs voix
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, // Voix disponibles : tongtong, chuichui, xiaochen, jam, kazi, douji, luodo
speed: 1.0,
response_format: 'wav',
stream: false
});
// Obtenir le tableau de l'objet Response
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
return outputPath;
}
// Utilisation
await generateWithVoice('Bienvenue dans notre service', 'tongtong', './bienvenue.wav');
Vitesse réglable
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function generateWithSpeed(text, speed, outputPath) {
const zai = await ZAI.create();
// Plage de vitesse : 0.5 à 2.0 (contrainte API)
// 0.5 = moitié vitesse (plus lent)
// 1.0 = vitesse normale (par défaut)
// 2.0 = vitesse double (plus rapide)
// Les valeurs en dehors de cette plage entraîneront des erreurs API
const response = await zai.audio.tts.create({
input: text,
voice: 'tongtong',
speed: speed,
response_format: 'wav',
stream: false
});
// Obtenir le tableau de l'objet Response
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
return outputPath;
}
// Utilisation - narration plus lente
await generateWithSpeed('Ceci est une annonce importante', 0.8, './lent.wav');
// Utilisation - narration plus rapide
await generateWithSpeed('Mise à jour rapide', 1.3, './rapide.wav');
Volume réglable
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function generateWithVolume(text, volume, outputPath) {
const zai = await ZAI.create();
// Plage de volume : supérieur à 0, jusqu'à 10 (contrainte API)
// Les valeurs doivent être > 0 (exclusif) et <= 10 (inclus)
// Par défaut : 1.0 (volume normal)
const response = await zai.audio.tts.create({
input: text,
voice: 'tongtong',
speed: 1.0,
volume: volume, // Paramètre optionnel
response_format: 'wav',
stream: false
});
// Obtenir le tableau de l'objet Response
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
fs.writeFileSync(outputPath, buffer);
return outputPath;
}
// Utilisation - audio plus fort
await generateWithVolume('Ceci est une annonce', 5.0, './fort.wav');
// Utilisation - audio plus faible
await generateWithVolume('Message chuchoté', 0.5, './faible.wav');
Cas d'utilisation avancés
Traitement par lots
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 = [];
// Assurez-vous que le répertoire de sortie existe
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
});
// Obtenir le tableau de l'objet Response
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;
}
// Utilisation
const texts = [
'Bienvenue au chapitre un',
'Bienvenue au chapitre deux',
'Bienvenue au chapitre trois'
];
const results = await batchTextToSpeech(texts, './sortie-audio');
console.log('Généré :', results.length, 'fichiers audio');
Génération de contenu dynamique
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
});
// Obtenir le tableau de l'objet Response
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;
}
}
// Utilisation
const generator = new TTSGenerator();
await generator.initialize();
await generator.saveAudio(
'Bonjour, ceci est un test',
'./output.wav',
{ speed: 1.2 }
);
Exemple de route API Next.js
import { NextRequest, NextResponse } from 'next/server';
export async function POST(req: NextRequest) {
try {
const { text, voice = 'tongtong', speed = 1.0 } = await req.json();
// Importer le SDK ZAI
const ZAI = (await import('z-ai-web-dev-sdk')).default;
// Créer une instance du SDK
const zai = await ZAI.create();
// Générer l'audio TTS
const response = await zai.audio.tts.create({
input: text.trim(),
voice: voice,
speed: speed,
response_format: 'wav',
stream: false,
});
// Obtenir le tableau de l'objet Response
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(new Uint8Array(arrayBuffer));
// Retourner l'audio en réponse
return new NextResponse(buffer, {
status: 200,
headers: {
'Content-Type': 'audio/wav',
'Content-Length': buffer.length.toString(),
'Cache-Control': 'no-cache',
},
});
} catch (error) {
console.error('Erreur API TTS :', error);
return NextResponse.json(
{
error: error instanceof Error ? error.message : 'Échec de la génération vocale, veuillez réessayer plus tard',
},
{ status: 500 }
);
}
}
Bonnes pratiques
1. Préparation du texte
function prepareTextForTTS(text) {
// Supprimer les espaces blancs excessifs
text = text.replace(/\s+/g, ' ').trim();
// Développer les abréviations courantes pour une meilleure prononciation
const abbreviations = {
'Dr.': 'Docteur',
'M.': 'Monsieur',
'Mme': 'Madame',
'etc.': 'et cetera'
};
for (const [abbr, full] of Object.entries(abbreviations)) {
text = text.replace(new RegExp(abbr, 'g'), full);
}
return text;
}
2. Gestion des erreurs
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function safeTTS(text, outputPath) {
try {
// Valider l'entrée
if (!text || text.trim().length === 0) {
throw new Error('Le texte d\'entrée ne peut pas être vide');
}
if (text.length > 1024) {
throw new Error('Le texte d\'entrée dépasse la longueur maximale de 1024 caractères');
}
const zai = await ZAI.create();
const response = await zai.audio.tts.create({
input: text,
voice: 'tongtong',
speed: 1.0,
response_format: 'wav',
stream: false
});
// Obtenir le tableau de l'objet Response
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('Erreur TTS :', error);
return {
success: false,
error: error.message
};
}
}
3. Réutilisation de l'instance SDK
import ZAI from 'z-ai-web-dev-sdk';
// Créer une instance singleton
let zaiInstance = null;
async function getZAIInstance() {
if (!zaiInstance) {
zaiInstance = await ZAI.create();
}
return zaiInstance;
}
// Utilisation
const zai = await getZAIInstance();
const response = await zai.audio.tts.create({ ... });
Cas d'utilisation courants
- Livres audio et podcasts : Convertir du contenu écrit en format audio
- E-learning : Créer une narration pour du contenu éducatif
- Accessibilité : Fournir des versions audio de contenu textuel
- Assistants vocaux : Générer des réponses dynamiques
- Annonces : Créer des notifications audio automatisées
- Systèmes IVR : Générer des invites pour les systèmes téléphoniques
- Localisation de contenu : Créer de l'audio dans différentes langues
Exemples d'intégration
Point de terminaison API Express.js
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 = './sortie-audio';
async function initZAI() {
zaiInstance = await ZAI.create();
if (!fs.existsSync(outputDir)) {
fs.mkdirSync(outputDir, { recursive: true });
}
}
app.post('/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: 'Le texte est requis et doit comporter au maximum 1024 caractères'
});
}
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));
const outputPath = path.join(outputDir, `tts-${Date.now()}.${format}`);
fs.writeFileSync(outputPath, buffer);
res.json({
success: true,
path: outputPath,
size: buffer.length
});
} catch (error) {
console.error('Erreur TTS :', error);
res.status(500).json({ success: false, error: error.message });
}
});
app.listen(3000, () => {
console.log('Serveur TTS prêt sur le port 3000');
initZAI();
});
Exemple de pipeline de streaming
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function streamTTS(text, outputPath) {
const zai = await ZAI.create();
const response = await zai.audio.tts.create({
input: text,
voice: 'tongtong',
speed: 1.0,
response_format: 'pcm', // Le streaming nécessite le format pcm
stream: true
});
if (!response.ok) {
throw new Error(`Erreur de streaming TTS : ${response.status}`);
}
// Traiter les données en streaming
const reader = response.body.getReader();
const chunks = [];
while (true) {
const { done, value } = await reader.read();
if (done) break;
chunks.push(value);
}
// Combiner tous les chunks
const fullBuffer = Buffer.concat(chunks);
fs.writeFileSync(outputPath, fullBuffer);
console.log(`Audio streamé sauvegardé dans ${outputPath}`);
return outputPath;
}
// Utilisation
streamTTS('Ceci est un texte long avec sortie en streaming', './stream-output.pcm');
Dépannage
Problèmes courants et solutions
-
Erreur : "Le texte d'entrée dépasse la longueur maximale"
- Solution : Utilisez la fonction
splitTextIntoChunks()pour diviser le texte en morceaux de moins de 1024 caractères - Exemple :
const chunks = splitTextIntoChunks(longText, 1000); for (const chunk of chunks) { await textToSpeech(chunk, `./output-${Date.now()}.wav`); } - Solution : Utilisez la fonction
-
Erreur : "Vitesse invalide"
- Solution : Assurez-vous que la vitesse est comprise entre 0.5 et 2.0
- Vérifiez :
speed >= 0.5 || speed <= 2.0
-
Erreur : Format PCM avec streaming
- Solution : Lorsque vous utilisez
stream: true, réglezresponse_formatsurpcm - Exemple correct :
response_format: 'pcm', stream: true
- Solution : Lorsque vous utilisez
Journalisation et débogage
import ZAI from 'z-ai-web-dev-sdk';
async function debugTTS(text, options = {}) {
console.log('Paramètres TTS :', { text, ...options });
try {
const zai = await ZAI.create();
console.log('Instance ZAI créée avec succès');
const response = await zai.audio.tts.create({
input: text,
voice: options.voice || 'tongtong',
speed: options.speed || 1.0,
response_format: options.format || 'wav',
stream: options.stream || false
});
console.log('Réponse API reçue :', response.status);
const arrayBuffer = await response.arrayBuffer();
console.log('Taille du tampon audio :', arrayBuffer.byteLength);
return Buffer.from(new Uint8Array(arrayBuffer));
} catch (error) {
console.error('Erreur de débogage TTS :', error);
throw error;
}
}
Référence API
zai.audio.tts.create()
Crée une requête de synthèse vocale.
Paramètres :
| Paramètre | Type | Requis | Par défaut | Description |
|---|---|---|---|---|
input | string | Oui | - | Texte à convertir (max 1024 caractères) |
voice | string | Non | 'tongtong' | Identifiant de la voix (voir les voix disponibles) |
speed | number | Non | 1.0 | Vitesse de parole (0.5 à 2.0) |
volume | number | Non | 1.0 | Volume (supérieur à 0, jusqu'à 10) |
response_format | string | Non | 'wav' | Format de sortie : 'wav', 'mp3', 'pcm' |
stream | boolean | Non | false | Activer la sortie en streaming (nécessite le format pcm) |
Retourne : Promise<Response> - Un objet Response contenant les données audio.
Voix disponibles
tongtong- Voix féminine standardchuichui- Voix féminine doucexiaochen- Voix masculine standardie