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

# voice.on()

La méthode `on()` enregistre des écouteurs d’événements Voice. Elle est particulièrement importante pour les fournisseurs Voice en temps réel, où les événements servent à transmettre le texte transcrit, les réponses audio et d’autres changements d’état.

## Exemple d’utilisation

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

// Initialize a real-time voice provider
const voice = new OpenAIRealtimeVoice({
  realtimeConfig: {
    model: 'gpt-5.1-realtime',
    apiKey: process.env.OPENAI_API_KEY,
  },
})

// Connect to the real-time service
await voice.connect()

// Register event listener for transcribed text
voice.on('writing', event => {
  if (event.role === 'user') {
    process.stdout.write(chalk.green(event.text))
  } else {
    process.stdout.write(chalk.blue(event.text))
  }
})

// Listen for audio data and play it
const speaker = new Speaker({
  sampleRate: 24100,
  channels: 1,
  bitDepth: 16,
})

voice.on('speaker', stream => {
  stream.pipe(speaker)
})

// Register event listener for errors
voice.on('error', ({ message, code, details }) => {
  console.error(`Error ${code}: ${message}`, details)
})
```

## Paramètres

**event** (`string`): Nom de l’événement à écouter. Consultez la documentation des événements Voice pour obtenir la liste des événements disponibles.

**callback** (`function`): Fonction de rappel appelée lorsque l’événement se produit. Sa signature dépend de l’événement concerné.

## Valeur renvoyée

Cette méthode ne renvoie aucune valeur.

## Événements

Pour obtenir la liste détaillée des événements et la structure de leurs charges utiles, consultez la documentation des [événements Voice](https://mastra.zisheng.pro/fr/reference/voice/voice.events).

Les événements courants comprennent :

- `speaking` : émis lorsque des données audio sont disponibles
- `speaker` : émis avec un flux pouvant être transmis à une sortie audio
- `writing` : émis lorsque du texte est transcrit ou généré
- `error` : émis lorsqu’une erreur se produit
- `tool-call-start` : émis juste avant l’exécution d’un Tool
- `tool-call-result` : émis lorsque l’exécution d’un Tool est terminée

Les fournisseurs Voice peuvent prendre en charge des ensembles d’événements différents, dont la structure des charges utiles varie.

## Utilisation avec `CompositeVoice`

Avec `CompositeVoice`, la méthode `on()` délègue au fournisseur en temps réel configuré :

```typescript
import { CompositeVoice } from '@mastra/core/voice'
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 realtimeVoice = new OpenAIRealtimeVoice()
const voice = new CompositeVoice({
  realtime: realtimeVoice,
})

// Connect to the real-time service
await voice.connect()

// This will register the event listener with the OpenAIRealtimeVoice provider
voice.on('speaker', stream => {
  stream.pipe(speaker)
})
```

## Remarques

- Cette méthode s’utilise principalement avec les fournisseurs Voice en temps réel qui prennent en charge la communication fondée sur des événements.
- Si elle est appelée sur un fournisseur Voice qui ne prend pas en charge les événements, elle consigne un avertissement et n’effectue aucune action.
- Les écouteurs d’événements doivent être enregistrés avant l’appel des méthodes susceptibles d’émettre des événements.
- Pour supprimer un écouteur d’événement, utilisez la méthode [voice.off()](https://mastra.zisheng.pro/fr/reference/voice/voice.off) avec le même nom d’événement et la même fonction de rappel.
- Plusieurs écouteurs peuvent être enregistrés pour un même événement.
- La fonction de rappel reçoit des données différentes selon le type d’événement ; consultez [Événements Voice](https://mastra.zisheng.pro/fr/reference/voice/voice.events).
- Pour de meilleures performances, envisagez de supprimer les écouteurs d’événements lorsqu’ils ne sont plus nécessaires.