voice.connect()

The connect() method establishes a WebSocket or WebRTC connection for real-time speech-to-speech communication. This method must be called before using other real-time features like send() or answer().

Usage example

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

const speaker = new Speaker({
  sampleRate: 24000,
  channels: 1,
  bitDepth: 16,
})

const voice = new OpenAIRealtimeVoice({
  apiKey: process.env.OPENAI_API_KEY,
  speaker: 'alloy',
})
// Connect to the real-time service
await voice.connect()
// Now you can use real-time features
voice.on('speaker', stream => {
  stream.pipe(speaker)
})

Parameters

options?:

Record<string, unknown>

Provider-specific connection options

Return value

Returns a Promise<void> that resolves when the connection is successfully established.

Provider-specific options

Connection configuration depends on the real-time voice provider.

OpenAI Realtime

connect() accepts an optional requestContext for tool execution:

options.requestContext?:

RequestContext

Runtime context passed to tools called during the session.

See Request context for how to populate runtime values.

Set connectTimeoutMs in the OpenAIRealtimeVoice constructor, not in the connect() call:

connectTimeoutMs?:

number

= 15000

Connection handshake deadline in milliseconds. Must be a positive, finite number no greater than 2,147,483,647. Applies only to connection setup, not to an established session.

Connection failures

For OpenAI Realtime, connect() waits for both the WebSocket to open and the server to create a session. It rejects if the connection fails, the server reports an error during the handshake, or the socket closes before the session is ready. A silent handshake times out after 15,000 milliseconds by default.

Catch connection failures directly. An error event listener doesn't replace handling the rejected promise:

import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'

const voice = new OpenAIRealtimeVoice({
  apiKey: process.env.OPENAI_API_KEY,
  connectTimeoutMs: 30_000,
})

try {
  await voice.connect()
} catch (error) {
  console.error('Could not connect to the realtime service:', error)
}

A failed handshake closes its socket and clears its pending waits. You can retry with connect() on the same instance.

Using with CompositeVoice

When using CompositeVoice, the connect() method forwards its options to the configured real-time provider. It throws if no real-time provider is configured:

import { CompositeVoice } from '@mastra/core/voice'
import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
const realtimeVoice = new OpenAIRealtimeVoice()
const voice = new CompositeVoice({
  realtime: realtimeVoice,
})
// This will use the OpenAIRealtimeVoice provider
await voice.connect()

Notes

• This method is only implemented by real-time voice providers that support speech-to-speech capabilities
• Providers that inherit the base connect() implementation log a debug message and resolve without establishing a connection
• The connection must be established before using other real-time methods like send() or answer()
• When you're done with the voice instance, call close() to properly clean up resources
• Some providers may automatically reconnect on connection loss, depending on their implementation
• Connection errors will typically be thrown as exceptions that should be caught and handled

Related methods

• voice.send(): Sends audio data to the voice provider
• voice.answer(): Triggers the voice provider to respond
• voice.close(): Disconnects from the real-time service
• voice.on(): Registers an event listener for voice events