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

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<NodeJS.ReadableStream | void> {
    // Implement text-to-speech conversion
  }

  async listen(
    audioStream: NodeJS.ReadableStream,
    options?: unknown,
  ): Promise<string | NodeJS.ReadableStream | void> {
    // Implement speech-to-text conversion
  }

  async getSpeakers(): Promise<Array<{ voiceId: string; [key: string]: unknown }>> {
    // Return list of available voices
  }

  // Optional speech-to-speech methods
  async connect(): Promise<void> {
    // Establish WebSocket connection for speech-to-speech communication
  }

  async send(audioData: NodeJS.ReadableStream | Int16Array): Promise<void> {
    // Stream audio data in speech-to-speech
  }

  async answer(): Promise<void> {
    // Trigger voice provider to respond
  }

  addTools(tools: Array<unknown>): 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

BuiltInModelConfig

name:

string

Nom du modèle à utiliser

apiKey?:

string

Clé d’API du service de modèle

config.listeningModel?:

BuiltInModelConfig

Configuration du modèle de transcription vocale

BuiltInModelConfig

name:

string

Nom du modèle à utiliser

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

object

model?:

string

Modèle à utiliser pour les fonctionnalités de conversion parole-parole en temps réel

apiKey?:

string

Clé d’API du service en temps réel

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é.

abstract speak(
  input: string | NodeJS.ReadableStream,
  options?: {
    speaker?: string;
    [key: string]: unknown;
  }
): Promise<NodeJS.ReadableStream | void>

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é.

abstract listen(
  audioStream: NodeJS.ReadableStream,
  options?: {
    [key: string]: unknown;
  }
): Promise<string | NodeJS.ReadableStream | void>

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.

abstract getSpeakers(): Promise<Array<{ voiceId: string; [key: string]: unknown }>>

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.

connect(config?: unknown): Promise<void>

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.

send(audioData: NodeJS.ReadableStream | Int16Array): Promise<void>

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.

answer(): Promise<void>

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.

addTools(tools: Array<Tool>): 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.

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.

on<E extends VoiceEventType>(
  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.

off<E extends VoiceEventType>(
  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