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

# Voix OpenAI Realtime

La classe OpenAIRealtimeVoice fournit des fonctionnalités d'interaction vocale en temps réel au moyen de l'API OpenAI fondée sur WebSocket. Elle prend en charge les échanges vocaux en temps réel, la détection d'activité vocale et le streaming audio fondé sur des événements.

## Exemple d'utilisation

```typescript
import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
import { playAudio, getMicrophoneStream } from '@mastra/node-audio'

// Initialize with default configuration using environment variables
const voice = new OpenAIRealtimeVoice()

// Or initialize with specific configuration
const voiceWithConfig = new OpenAIRealtimeVoice({
  apiKey: 'your-openai-api-key',
  model: 'gpt-5.1-realtime-preview-2024-12-17',
  speaker: 'alloy', // Default voice
})

voiceWithConfig.updateSession({
  turn_detection: {
    type: 'server_vad',
    threshold: 0.6,
    silence_duration_ms: 1200,
  },
})

// Establish connection
await voice.connect()

// Set up event listeners
voice.on('speaker', ({ audio }) => {
  // Handle audio data (Int16Array) pcm format by default
  playAudio(audio)
})

voice.on('writing', ({ text, role }) => {
  // Handle transcribed text
  console.log(`${role}: ${text}`)
})

// Convert text to speech
await voice.speak('Hello, how can I help you today?', {
  speaker: 'echo', // Override default voice
})

// Process audio input
const microphoneStream = getMicrophoneStream()
await voice.send(microphoneStream)

// When done, disconnect
voice.connect()
```

## Configuration

### Options du constructeur

**model** (`string`): Identifiant du modèle à utiliser pour les interactions vocales en temps réel. (Default: `'gpt-5.1-realtime-preview-2024-12-17'`)

**apiKey** (`string`): Clé d'API OpenAI. Utilise la variable d'environnement OPENAI\_API\_KEY comme valeur de repli.

**speaker** (`string`): Identifiant de voix par défaut pour la synthèse vocale. (Default: `'alloy'`)

### Configuration de la détection d'activité vocale (VAD)

**type** (`string`): Type de VAD à utiliser. La VAD côté serveur offre une meilleure précision. (Default: `'server_vad'`)

**threshold** (`number`): Sensibilité de la détection vocale (0.0-1.0). (Default: `0.5`)

**prefix\_padding\_ms** (`number`): Nombre de millisecondes d'audio à inclure avant la détection de la parole. (Default: `1000`)

**silence\_duration\_ms** (`number`): Nombre de millisecondes de silence avant de terminer un tour de parole. (Default: `1000`)

## Méthodes

### `connect()`

Établit une connexion au service OpenAI Realtime. Cette méthode doit être appelée avant d'utiliser les fonctions speak, listen ou send.

**returns** (`Promise<void>`): Promise résolue une fois la connexion établie.

### `speak()`

Émet un événement speaking au moyen du modèle vocal configuré. Accepte en entrée une chaîne ou un stream lisible.

**input** (`string | NodeJS.ReadableStream`): Texte ou stream de texte à convertir en parole.

**options** (`Options`): Options de configuration.

**options.speaker** (`string`): Identifiant de voix à utiliser pour cette requête vocale précise.

Renvoie : `Promise<void>`

### `listen()`

Traite une entrée audio pour la reconnaissance vocale. Accepte un stream lisible de données audio et émet un événement 'listening' contenant le texte transcrit.

**audioData** (`NodeJS.ReadableStream`): Stream audio à transcrire.

Renvoie : `Promise<void>`

### `send()`

Diffuse les données audio en temps réel vers le service OpenAI pour des scénarios de streaming audio continu, tels que l'entrée d'un microphone en direct.

**audioData** (`NodeJS.ReadableStream`): Stream audio à envoyer au service.

Renvoie : `Promise<void>`

### `updateConfig()`

Met à jour la configuration de session de l'instance Voice. Cette méthode permet de modifier les paramètres de voix, la détection des tours de parole et d'autres paramètres.

**sessionConfig** (`Realtime.SessionConfig`): Nouvelle configuration de session à appliquer.

Renvoie : `void`

### `addTools()`

Ajoute un ensemble de Tools à l'instance Voice. Les Tools permettent au modèle d'effectuer des actions supplémentaires pendant les conversations. Lorsque OpenAIRealtimeVoice est ajouté à un Agent, tous les Tools configurés pour cet Agent sont automatiquement accessibles à l'interface Voice.

**tools** (`ToolsInput`): Configuration des Tools à fournir.

Renvoie : `void`

### `close()`

Se déconnecte de la session OpenAI Realtime et libère les ressources. Cette méthode doit être appelée lorsque vous avez terminé d'utiliser l'instance Voice.

Renvoie : `void`

### `getSpeakers()`

Renvoie la liste des voix disponibles.

Renvoie : `Promise<Array<{ voiceId: string; [key: string]: any }>>`

### `on()`

Enregistre un écouteur d'événements Voice.

**event** (`string`): Nom de l'événement à écouter.

**callback** (`Function`): Fonction à appeler lorsque l'événement se produit.

Renvoie : `void`

### `off()`

Supprime un écouteur d'événements précédemment enregistré.

**event** (`string`): Nom de l'événement à ne plus écouter.

**callback** (`Function`): Fonction de rappel précise à supprimer.

Renvoie : `void`

## Événements

La classe OpenAIRealtimeVoice émet les événements suivants :

**speaking** (`event`): Émis lorsque des données audio sont reçues du modèle. Le callback reçoit { audio: Int16Array }.

**writing** (`event`): Émis lorsque le texte transcrit est disponible. Le callback reçoit { text: string, role: string }.

**error** (`event`): Émis lorsqu'une erreur se produit. Le callback reçoit l'objet d'erreur.

### Événements OpenAI Realtime

Vous pouvez également écouter les [événements utilitaires OpenAI Realtime](https://github.com/openai/openai-realtime-api-beta#reference-client-utility-events) en leur ajoutant le préfixe 'openAIRealtime:' :

**openAIRealtime:conversation.created** (`event`): Émis lorsqu'une nouvelle conversation est créée.

**openAIRealtime:conversation.interrupted** (`event`): Émis lorsqu'une conversation est interrompue.

**openAIRealtime:conversation.updated** (`event`): Émis lorsqu'une conversation est mise à jour.

**openAIRealtime:conversation.item.appended** (`event`): Émis lorsqu'un élément est ajouté à la conversation.

**openAIRealtime:conversation.item.completed** (`event`): Émis lorsqu'un élément de la conversation est terminé.

## Voix disponibles

Les options de voix suivantes sont disponibles :

- `alloy` : neutre et équilibrée
- `ash` : claire et précise
- `ballad` : mélodieuse et douce
- `coral` : chaleureuse et amicale
- `echo` : résonnante et profonde
- `sage` : calme et posée
- `shimmer` : claire et énergique
- `verse` : polyvalente et expressive

## Remarques

- Les clés d'API peuvent être fournies au moyen des options du constructeur ou de la variable d'environnement `OPENAI_API_KEY`
- L'API OpenAI Realtime Voice utilise WebSockets pour la communication en temps réel
- La détection d'activité vocale (VAD) côté serveur offre une meilleure précision pour détecter la parole
- Toutes les données audio sont traitées au format Int16Array
- L'instance Voice doit être connectée avec `connect()` avant d'utiliser les autres méthodes
- Appelez toujours `close()` lorsque vous avez terminé afin de libérer correctement les ressources
- La gestion de la mémoire est assurée par l'API OpenAI Realtime