> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# OpenAI Realtime voice

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

## 使用示例

```typescript
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`): 用于实时语音交互的模型 ID。 (Default: `'gpt-5.1-realtime-preview-2024-12-17'`)

**apiKey** (`string`): OpenAI API key。未提供时使用 OPENAI\_API\_KEY 环境变量。

**speaker** (`string`): 用于语音合成的默认音色 ID。 (Default: `'alloy'`)

### 语音活动检测（VAD）配置

**type** (`string`): 要使用的 VAD 类型。服务端 VAD 的准确率更高。 (Default: `'server_vad'`)

**threshold** (`number`): 语音检测灵敏度（0.0–1.0）。 (Default: `0.5`)

**prefix\_padding\_ms** (`number`): 检测到语音前要包含的音频毫秒数。 (Default: `1000`)

**silence\_duration\_ms** (`number`): 结束一个轮次前的静音毫秒数。 (Default: `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 实用事件](https://github.com/openai/openai-realtime-api-beta#reference-client-utility-events)：

**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 处理