> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt # MastraVoice La classe MastraVoice est une classe de base abstraite qui définit l’interface principale des services vocaux dans Mastra. Toutes les implémentations de Providers vocaux (comme OpenAI, Deepgram, PlayAI et Speechify) étendent cette classe afin de fournir leurs fonctionnalités propres. La classe prend désormais en charge les fonctionnalités de conversion parole-parole en temps réel au moyen de connexions WebSocket. ## Exemple d’utilisation ```typescript import { MastraVoice } from '@mastra/core/voice' // Create a voice provider implementation class MyVoiceProvider extends MastraVoice { constructor(config: { speechModel?: BuiltInModelConfig listeningModel?: BuiltInModelConfig speaker?: string realtimeConfig?: { model?: string apiKey?: string options?: unknown } }) { super({ speechModel: config.speechModel, listeningModel: config.listeningModel, speaker: config.speaker, realtimeConfig: config.realtimeConfig, }) } // Implement required abstract methods async speak( input: string | NodeJS.ReadableStream, options?: { speaker?: string }, ): Promise { // Implement text-to-speech conversion } async listen( audioStream: NodeJS.ReadableStream, options?: unknown, ): Promise { // Implement speech-to-text conversion } async getSpeakers(): Promise> { // Return list of available voices } // Optional speech-to-speech methods async connect(): Promise { // Establish WebSocket connection for speech-to-speech communication } async send(audioData: NodeJS.ReadableStream | Int16Array): Promise { // Stream audio data in speech-to-speech } async answer(): Promise { // Trigger voice provider to respond } addTools(tools: Array): void { // Add tools for the voice provider to use } close(): void { // Close WebSocket connection } on(event: string, callback: (data: unknown) => void): void { // Register event listener } off(event: string, callback: (data: unknown) => void): void { // Remove event listener } } ``` ## Paramètres du constructeur **config** (`VoiceConfig`): Objet de configuration du service vocal **config.speechModel** (`BuiltInModelConfig`): Configuration du modèle de synthèse vocale **config.speechModel.name** (`string`): Nom du modèle à utiliser **config.speechModel.apiKey** (`string`): Clé d’API du service de modèle **config.listeningModel** (`BuiltInModelConfig`): Configuration du modèle de transcription vocale **config.listeningModel.name** (`string`): Nom du modèle à utiliser **config.listeningModel.apiKey** (`string`): Clé d’API du service de modèle **config.speaker** (`string`): ID par défaut du locuteur/de la voix à utiliser **config.name** (`string`): Nom de l’instance du Provider vocal **config.realtimeConfig** (`object`): Configuration des fonctionnalités de conversion parole-parole en temps réel **config.realtimeConfig.model** (`string`): Modèle à utiliser pour les fonctionnalités de conversion parole-parole en temps réel **config.realtimeConfig.apiKey** (`string`): Clé d’API du service en temps réel **config.realtimeConfig.options** (`unknown`): Options propres au Provider pour les fonctionnalités en temps réel ## Méthodes abstraites Ces méthodes doivent être implémentées par toute classe qui étend MastraVoice. ### `speak()` Convertit du texte en parole à l’aide du modèle de synthèse vocale configuré. ```typescript abstract speak( input: string | NodeJS.ReadableStream, options?: { speaker?: string; [key: string]: unknown; } ): Promise ``` Objectif : - Reçoit une entrée textuelle et la convertit en parole à l’aide du service de synthèse vocale du Provider - Accepte à la fois une chaîne et un flux en entrée pour davantage de flexibilité - Permet de remplacer le locuteur ou la voix par défaut au moyen des options - Renvoie un flux de données audio qui peut être lu ou enregistré - Peut ne rien renvoyer si l’audio est géré par l’émission de l’événement 'speaking' ### `listen()` Convertit la parole en texte à l’aide du modèle d’écoute configuré. ```typescript abstract listen( audioStream: NodeJS.ReadableStream, options?: { [key: string]: unknown; } ): Promise ``` Objectif : - Reçoit un flux audio et le convertit en texte à l’aide du service de transcription vocale du Provider - Accepte les options propres au Provider pour configurer la transcription - Peut renvoyer une transcription textuelle complète ou un flux de texte transcrit - Tous les Providers ne prennent pas en charge cette fonctionnalité (par exemple PlayAI et Speechify) - Peut ne rien renvoyer si la transcription est gérée par l’émission de l’événement 'writing' ### `getSpeakers()` Renvoie la liste des voix disponibles prises en charge par le Provider. ```typescript abstract getSpeakers(): Promise> ``` Objectif : - Récupère auprès du Provider la liste des voix/locuteurs disponibles - Chaque voix doit posséder au minimum une propriété voiceId - Les Providers peuvent inclure des métadonnées supplémentaires sur chaque voix - Sert à découvrir les voix disponibles pour la synthèse vocale ## Méthodes facultatives Ces méthodes disposent d’implémentations par défaut, mais peuvent être remplacées par les Providers vocaux qui prennent en charge les fonctionnalités de conversion parole-parole. ### `connect()` Établit une connexion WebSocket ou WebRTC pour la communication. ```typescript connect(config?: unknown): Promise ``` Objectif : - Initialise une connexion au service vocal à des fins de communication - Doit être appelée avant d’utiliser des fonctionnalités telles que send() ou answer() - Renvoie une Promise qui est résolue une fois la connexion établie - La configuration est propre au Provider ### `send()` Envoie des données audio en streaming et en temps réel au Provider vocal. ```typescript send(audioData: NodeJS.ReadableStream | Int16Array): Promise ``` Objectif : - Envoie des données audio au Provider vocal afin qu’il les traite en temps réel - Utile pour les scénarios de streaming audio continu, tels que l’entrée en direct d’un microphone - Prend en charge les formats audio ReadableStream et Int16Array - La connexion doit être établie avant l’appel de cette méthode ### `answer()` Déclenche la génération d’une réponse par le Provider vocal. ```typescript answer(): Promise ``` Objectif : - Envoie un signal au Provider vocal pour qu’il génère une réponse - Utilisée dans les conversations en temps réel pour inviter l’IA à répondre - La réponse est émise par l’intermédiaire du système d’événements (par exemple, l’événement 'speaking') ### `addTools()` Fournit au Provider vocal des Tools utilisables pendant les conversations. ```typescript addTools(tools: Array): void ``` Objectif : - Ajoute des Tools que le Provider vocal peut utiliser pendant les conversations - Les Tools peuvent étendre les fonctionnalités du Provider vocal - L’implémentation est propre au Provider ### `close()` Ferme la connexion WebSocket ou WebRTC. ```typescript close(): void ``` Objectif : - Ferme la connexion au service vocal - Libère les ressources et arrête tout traitement en temps réel en cours - Doit être appelée lorsque vous avez fini d’utiliser l’instance vocale ### `on()` Enregistre un écouteur pour les événements vocaux. ```typescript on( event: E, callback: (data: E extends keyof VoiceEventMap ? VoiceEventMap[E] : unknown) => void, ): void ``` Objectif : - Enregistre une fonction de callback appelée lorsque l’événement indiqué survient - Les événements standard comprennent 'speaking', 'writing' et 'error' - Les Providers peuvent également émettre des événements personnalisés - La structure des données de l’événement dépend de son type ### `off()` Supprime un écouteur d’événement. ```typescript off( event: E, callback: (data: E extends keyof VoiceEventMap ? VoiceEventMap[E] : unknown) => void, ): void ``` Objectif : - Supprime un écouteur d’événement précédemment enregistré - Sert à nettoyer les gestionnaires d’événements lorsqu’ils ne sont plus nécessaires ## Système d’événements La classe MastraVoice comprend un système d’événements pour la communication en temps réel. Les types d’événements standard comprennent : **speaking** (`{ text: string; audioStream?: NodeJS.ReadableStream; audio?: Int16Array }`): Émis lorsque le Provider vocal parle ; contient les données audio **writing** (`{ text: string, role: string }`): Émis lorsque la parole est transcrite en texte **error** (`{ message: string; code?: string; details?: unknown }`): Émis lorsqu’une erreur survient ## Propriétés protégées **listeningModel** (`BuiltInModelConfig | undefined`): Configuration du modèle de transcription vocale **speechModel** (`BuiltInModelConfig | undefined`): Configuration du modèle de synthèse vocale **speaker** (`string | undefined`): ID par défaut du locuteur/de la voix **realtimeConfig** (`{ model?: string; apiKey?: string; options?: unknown } | undefined`): Configuration des fonctionnalités de conversion parole-parole en temps réel ## Prise en charge de la télémétrie MastraVoice intègre la télémétrie grâce à la méthode `traced`, qui encapsule les appels de méthode avec un suivi des performances et une surveillance des erreurs. ## Remarques - MastraVoice est une classe abstraite qui ne peut pas être instanciée directement - Les implémentations doivent fournir une implémentation concrète de toutes les méthodes abstraites - La classe fournit une interface cohérente entre les différents Providers de services vocaux - Les fonctionnalités de conversion parole-parole sont facultatives et propres au Provider - Le système d’événements permet une communication asynchrone pour les interactions en temps réel - La télémétrie est automatiquement prise en charge pour tous les appels de méthode