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

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

= 'gpt-5.1-realtime-preview-2024-12-17'

Identifiant du modèle à utiliser pour les interactions vocales en temps réel.

apiKey?:

string

Clé d'API OpenAI. Utilise la variable d'environnement OPENAI_API_KEY comme valeur de repli.

speaker?:

string

= 'alloy'

Identifiant de voix par défaut pour la synthèse vocale.

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

type?:

string

= 'server_vad'

Type de VAD à utiliser. La VAD côté serveur offre une meilleure précision.

threshold?:

number

= 0.5

Sensibilité de la détection vocale (0.0-1.0).

prefix_padding_ms?:

number

= 1000

Nombre de millisecondes d'audio à inclure avant la détection de la parole.

silence_duration_ms?:

number

= 1000

Nombre de millisecondes de silence avant de terminer un tour de parole.

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