voice.speak()

La méthode speak() est une fonction centrale disponible dans tous les Providers Voice de Mastra qui convertit le texte en parole. Elle reçoit du texte en entrée et renvoie un flux audio qui peut être lu ou enregistré.

Paramètres

input:

string | NodeJS.ReadableStream

Texte à convertir en parole. Il peut s'agir d'une chaîne ou d'un flux de texte lisible.

options?:

object

Options de synthèse vocale

object

speaker?:

string

Identifiant Voice à utiliser pour cette requête précise. Remplace le speaker par défaut défini dans le constructeur.

Valeur renvoyée

Renvoie une Promise<NodeJS.ReadableStream | void>, où :

• NodeJS.ReadableStream : flux de données audio pouvant être lu ou enregistré
• void : lors de l'utilisation d'un Provider Voice en temps réel qui émet l'audio au moyen d'événements au lieu de le renvoyer directement

Options propres au Provider

Chaque Provider Voice peut prendre en charge des options supplémentaires propres à son implémentation. En voici quelques exemples :

OpenAI

options?:

Options

Options de configuration.

Options

speed?:

number

Multiplicateur de vitesse de la parole. Les valeurs comprises entre 0,25 et 4,0 sont prises en charge.

ElevenLabs

options?:

Options

Options de configuration.

Options

stability?:

number

Stabilité de la voix. Des valeurs élevées produisent une parole plus stable et moins expressive.

similarity_boost?:

number

Clarté de la voix et similarité avec la voix originale.

Google

options?:

Options

Options de configuration.

Options

languageCode?:

string

Code de langue de la voix (par exemple, 'en-US').

audioConfig?:

object

Options de configuration audio de l'API Google Cloud Text-to-Speech.

Murf

options?:

Options

Options de configuration.

Options

properties?:

object

Configuration de properties.

object

rate?:

number

Multiplicateur de débit de parole.

pitch?:

number

Réglage de la hauteur de la voix.

format?:

'MP3' | 'WAV' | 'FLAC' | 'ALAW' | 'ULAW'

Format audio de sortie.

Exemple d'utilisation

import { OpenAIVoice } from '@mastra/voice-openai'
// Initialize a voice provider
const voice = new OpenAIVoice({
  speaker: 'alloy', // Default voice
})
// Basic usage with default settings
const audioStream = await voice.speak('Hello, world!')
// Using a different voice for this specific request
const audioStreamWithDifferentVoice = await voice.speak('Hello again!', {
  speaker: 'nova',
})
// Using provider-specific options
const audioStreamWithOptions = await voice.speak('Hello with options!', {
  speaker: 'echo',
  speed: 1.2, // OpenAI-specific option
})
// Using a text stream as input
import { Readable } from 'stream'
const textStream = Readable.from(['Hello', ' from', ' a', ' stream!'])
const audioStreamFromTextStream = await voice.speak(textStream)

Utilisation avec CompositeVoice

Avec CompositeVoice, la méthode speak() délègue l'opération au Provider de parole configuré :

import { CompositeVoice } from '@mastra/core/voice'
import { OpenAIVoice } from '@mastra/voice-openai'
import { PlayAIVoice } from '@mastra/voice-playai'

const voice = new CompositeVoice({
  output: new PlayAIVoice(),
  input: new OpenAIVoice(),
})

// This will use the PlayAIVoice provider
const audioStream = await voice.speak('Hello, world!')

Utilisation des Model Providers AI SDK

Vous pouvez également utiliser directement des modèles de parole AI SDK avec CompositeVoice :

import { CompositeVoice } from '@mastra/core/voice'
import { openai } from '@ai-sdk/openai'
import { elevenlabs } from '@ai-sdk/elevenlabs'

// Use AI SDK speech models
const voice = new CompositeVoice({
  output: elevenlabs.speech('eleven_turbo_v2'), // AI SDK model
  input: openai.transcription('whisper-1'), // AI SDK model
})

// Works the same way
const audioStream = await voice.speak('Hello from AI SDK!')

// Provider-specific options can be passed through
const audioWithOptions = await voice.speak('Hello with options!', {
  speaker: 'Rachel', // ElevenLabs voice
  providerOptions: {
    elevenlabs: {
      stability: 0.5,
      similarity_boost: 0.75,
    },
  },
})

Consultez la référence de CompositeVoice pour en savoir plus sur l'intégration d'AI SDK.

Providers Voice en temps réel

Avec des Providers Voice en temps réel tels que OpenAIRealtimeVoice, la méthode speak() se comporte différemment :

• Au lieu de renvoyer un flux audio, elle émet un événement 'speaking' contenant les données audio
• Vous devez enregistrer un écouteur d'événements pour recevoir les chunks audio

import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
import Speaker from '@mastra/node-speaker'

const speaker = new Speaker({
  sampleRate: 24100, // Audio sample rate in Hz - standard for high-quality audio on MacBook Pro
  channels: 1, // Mono audio output (as opposed to stereo which would be 2)
  bitDepth: 16, // Bit depth for audio quality - CD quality standard (16-bit resolution)
})

const voice = new OpenAIRealtimeVoice()
await voice.connect()
// Register event listener for audio chunks
voice.on('speaker', stream => {
  // Handle audio chunk (e.g., play it or save it)
  stream.pipe(speaker)
})
// This will emit 'speaking' events instead of returning a stream
await voice.speak('Hello, this is realtime speech!')

Remarques

• Le comportement de speak() peut varier légèrement d'un Provider à l'autre, mais toutes les implémentations suivent la même interface de base.
• Avec un Provider Voice en temps réel, la méthode peut ne pas renvoyer directement un flux audio, mais émettre plutôt un événement 'speaking'.
• Si un flux de texte est fourni en entrée, le Provider le convertit généralement en chaîne avant de le traiter.
• Le format audio du flux renvoyé dépend du Provider. Les formats courants incluent MP3, WAV et OGG.
• Pour des performances optimales, pensez à fermer ou terminer le flux audio lorsque vous n'en avez plus besoin.