> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# 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

**options.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.

**options.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').

**options.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.

**options.properties.rate** (`number`): Multiplicateur de débit de parole.

**options.properties.pitch** (`number`): Réglage de la hauteur de la voix.

**options.properties.format** (`'MP3' | 'WAV' | 'FLAC' | 'ALAW' | 'ULAW'`): Format audio de sortie.

## Exemple d'utilisation

```typescript
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é :

```typescript
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` :

```typescript
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](https://mastra.zisheng.pro/fr/reference/voice/composite-voice) 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

```typescript
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.