OpenAI Realtime voice

OpenAIRealtimeVoice 类使用 OpenAI 基于 WebSocket 的 API 提供实时语音交互功能。它支持实时语音到语音、语音活动检测以及基于事件的音频流。

使用示例

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

配置

构造函数选项

model?:

string

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

用于实时语音交互的模型 ID。

apiKey?:

string

OpenAI API key。未提供时使用 OPENAI_API_KEY 环境变量。

speaker?:

string

= 'alloy'

用于语音合成的默认音色 ID。

语音活动检测（VAD）配置

type?:

string

= 'server_vad'

要使用的 VAD 类型。服务端 VAD 的准确率更高。

threshold?:

number

= 0.5

语音检测灵敏度（0.0–1.0）。

prefix_padding_ms?:

number

= 1000

检测到语音前要包含的音频毫秒数。

silence_duration_ms?:

number

= 1000

结束一个轮次前的静音毫秒数。

方法

connect()

建立与 OpenAI Realtime 服务的连接。使用 speak、listen 或 send 函数前必须调用此方法。

returns:

Promise<void>

连接建立后 resolve 的 Promise。

speak()

使用已配置的语音模型触发 speaking 事件。输入可以是字符串或可读流。

input:

string | NodeJS.ReadableStream

要转换为语音的文本或文本流。

options?:

Options

配置选项。

Options

speaker?:

string

用于本次特定语音请求的音色 ID。

返回： Promise<void>

listen()

处理音频输入以进行语音识别。接收音频数据的可读流，并通过 listening 事件发出转写文本。

audioData:

NodeJS.ReadableStream

要转写的音频流。

返回： Promise<void>

send()

将音频数据实时流式传输到 OpenAI 服务，适用于麦克风实时输入等连续音频流场景。

audioData:

NodeJS.ReadableStream

要发送到服务的音频流。

返回： Promise<void>

updateConfig()

更新语音实例的 session 配置。此方法可修改音色设置、轮次检测及其他参数。

sessionConfig:

Realtime.SessionConfig

要应用的新 session 配置。

返回： void

addTools()

向语音实例添加一组 Tool。Tool 允许模型在对话期间执行其他操作。将 OpenAIRealtimeVoice 添加到 Agent 后，为 Agent 配置的所有 Tool 都会自动提供给语音接口。

tools?:

ToolsInput

要配备的 Tool 配置。

返回： void

close()

断开 OpenAI Realtime session 并清理资源。使用完语音实例后应调用此方法。

返回： void

getSpeakers()

返回可用 speaker 列表。

返回： Promise<Array<{ voiceId: string; [key: string]: any }>>

on()

注册语音事件监听器。

event:

string

要监听的事件名称。

callback:

Function

事件发生时要调用的函数。

返回： void

off()

移除之前注册的事件监听器。

event:

string

要停止监听的事件名称。

callback:

Function

要移除的特定回调函数。

返回： void

事件

OpenAIRealtimeVoice 类会触发以下事件：

speaking:

event

从模型收到音频数据时触发。回调接收 { audio: Int16Array }。

writing:

event

转写文本可用时触发。回调接收 { text: string, role: string }。

error:

event

发生错误时触发。回调接收错误对象。

OpenAI Realtime 事件

还可以添加 openAIRealtime: 前缀来监听 OpenAI Realtime 实用事件：

openAIRealtime:conversation.created:

event

创建新对话时触发。

openAIRealtime:conversation.interrupted:

event

对话被中断时触发。

openAIRealtime:conversation.updated:

event

对话更新时触发。

openAIRealtime:conversation.item.appended:

event

向对话追加项目时触发。

openAIRealtime:conversation.item.completed:

event

对话中的项目完成时触发。

可用音色

可使用以下音色选项：

• alloy: 中性且均衡
• ash: 清晰且准确
• ballad: 悦耳且流畅
• coral: 温暖且亲切
• echo: 浑厚且低沉
• sage: 沉稳且富有思考感
• shimmer: 明亮且充满活力
• verse: 多变且富有表现力

注意事项

• 可以通过构造函数选项或 OPENAI_API_KEY 环境变量提供 API key
• OpenAI Realtime Voice API 使用 WebSocket 进行实时通信
• 服务端语音活动检测（VAD）可提高语音检测准确率
• 所有音频数据都以 Int16Array 格式处理
• 使用其他方法前，必须通过 connect() 连接语音实例
• 完成后始终调用 close()，以正确清理资源
• 内存管理由 OpenAI Realtime API 处理