Skip to main content

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
Direct link to 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
Direct link to Parameters

options?:

Record<string, unknown>
Provider-specific connection options

Return value
Direct link to Return value

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

Provider-specific options
Direct link to Provider-specific options

Connection configuration depends on the real-time voice provider.

OpenAI Realtime
Direct link to 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
Direct link to 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
Direct link to 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
Direct link to 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
On this page