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

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.

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

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() 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.
• Pour de meilleures performances, envisagez de supprimer les écouteurs d’événements lorsqu’ils ne sont plus nécessaires.