Synthèse vocale Python : enregistrer l'audio dans un fichier WAV

Pour convertir du texte en parole en Python, envoyez un texte à un modèle vocal et enregistrez l’audio renvoyé. Ce guide utilise le SDK Python de Cartesia pour générer un fichier WAV avec Sonic.

Il vous faut Python 3.9 ou ultérieur, Internet et un compte Cartesia avec accès API. L’exemple cible la version 4.2.0 du SDK.¹ Il appelle une API hébergée : votre texte quitte votre machine. Pour une synthèse hors ligne, utilisez un moteur local.

Installer le SDK Python

Créez un environnement virtuel dans le dossier du projet :

python -m venv .venv

Sous macOS ou Linux, activez-le avec :

source .venv/bin/activate

Sous Windows PowerShell :

.venv\Scripts\Activate.ps1

Installez ensuite la version utilisée dans ce guide :

python -m pip install "cartesia==4.2.0"

Si votre système utilise python3 plutôt que python, employez cette commande pour créer l’environnement. Fixer la version du SDK stabilise les noms de méthodes de l’exemple. À chaque mise à niveau, consultez les notes de version.

Définir la clé API

Créez une clé dans le playground Cartesia avec les autorisations de synthèse vocale nécessaires. Définissez-la dans le terminal où vous exécuterez Python.

Sous macOS ou Linux :

export CARTESIA_API_KEY="your-api-key"

Sous Windows PowerShell :

$env:CARTESIA_API_KEY = "your-api-key"

Remplacez your-api-key par votre clé. Traitez-la comme un mot de passe : ne l’ajoutez pas à Git, à un notebook public ou au code du navigateur. En production, utilisez le gestionnaire de secrets du serveur. Si une clé est exposée, révoquez-la et créez-en une autre.

Générer et enregistrer un fichier WAV

Enregistrez ce code dans speak.py :

import os
from pathlib import Path

from cartesia import Cartesia

api_key = os.environ.get("CARTESIA_API_KEY")
if not api_key:
    raise SystemExit("Set CARTESIA_API_KEY before running this script.")

output_path = Path("hello.wav")

with Cartesia(api_key=api_key) as client:
    response = client.tts.generate(
        model_id="sonic-latest",
        transcript="Hello from Python. Your first audio file is ready.",
        voice="e07c00bc-4134-4eae-9ea4-1a55fb45746b",
        output_format={
            "container": "wav",
            "encoding": "pcm_f32le",
            "sample_rate": 44100,
        },
    )
    response.write_to_file(output_path)

print(f"Saved audio to {output_path.resolve()}")

Exécutez-le depuis le même terminal :

python speak.py

Après une requête réussie, ouvrez hello.wav dans un lecteur compatible avec le PCM à virgule flottante dans un conteneur WAV. Le script affiche le chemin complet pour éviter toute ambiguïté sur le dossier utilisé. Il enregistre l’audio sans le lire automatiquement. Une nouvelle exécution écrase hello.wav et effectue une nouvelle requête API.

La requête suit l’exemple publié du SDK.¹ L’identifiant vocal vient de cet exemple. Vous pouvez le remplacer par celui d’une voix accessible à votre compte.

Choisir la voix, le modèle et le format audio

transcript contient le texte que Sonic doit prononcer. Commencez par une phrase avant d’envoyer un document long. Utilisez un texte que vous acceptez de transmettre à l’API et évitez d’inscrire des transcriptions privées dans les journaux de l’application.

voice choisit le locuteur. Testez une phrase dans le générateur de voix, puis utilisez l’identifiant choisi dans la requête. Un nom affiché n’est pas un identifiant de voix. Pour une voix clonée, assurez-vous d’avoir l’autorisation du locuteur.

L’exemple utilise sonic-latest, comme la référence du SDK. Un alias de modèle peut changer indépendamment du SDK installé. Pour des tests de production reproductibles, choisissez un identifiant précis dans la documentation des modèles et consignez-le avec l’identifiant vocal et le texte de test.

Le format de sortie décrit le fichier audio :

Le PCM brut n’a pas d’en-tête WAV. Renommer son fichier en .wav ne le convertit pas. Si vous envoyez l’audio à un système téléphonique ou à un autre service, vérifiez le conteneur, l’encodage et la fréquence requis avant la génération.

Résoudre les erreurs courantes

Pour demander de l’aide, indiquez les versions de Python et du SDK, le code d’état et l’identifiant de requête éventuellement renvoyé. Retirez d’abord les clés et les textes privés.

Quand préférer la diffusion en continu

Enregistrer un WAV convient à la narration, aux voix off et à la vérification d’une intégration. Une application conversationnelle peut devoir lire l’audio avant que toute la réponse soit prête, ou accepter le texte au fil de sa génération par un LLM.

Dans ce cas, installez la prise en charge WebSocket dans le même environnement :

python -m pip install "cartesia[websockets]==4.2.0"

Partez ensuite de l’exemple WebSocket à entrée continue du SDK.¹ Il faudra aussi gérer lecture, mémoire tampon et interruptions. Écrire les fragments sur disque ne suffit pas à faire parler l’application en temps réel.

Une fois l’exemple court fonctionnel, remplacez le texte par une phrase de votre application. Écoutez noms, nombres et abréviations avant un lot plus important. Vérifiez les tarifs API et conservez les identifiants de modèle et de voix avec les résultats.