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

# OpenAI Realtime 語音

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 金鑰。未提供時會改用 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>`): 連線建立後解析的 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()`

更新語音執行個體的工作階段設定。這可以修改語音設定、對話輪次偵測及其他參數。

**sessionConfig** (`Realtime.SessionConfig`): 要套用的新工作階段設定。

傳回：`void`

### `addTools()`

將一組 Tool 加入語音執行個體。Tool 可讓模型在對話期間執行其他動作。將 OpenAIRealtimeVoice 加入 Agent 時，為 Agent 設定的所有 Tool 都會自動供語音介面使用。

**tools** (`ToolsInput`): 要配備的 Tool 設定。

傳回：`void`

### `close()`

中斷 OpenAI Realtime 工作階段的連線並清除資源。語音執行個體使用完畢後應呼叫此方法。

傳回：`void`

### `getSpeakers()`

傳回可用的語音說話者清單。

傳回：`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`：多變且富有表現力

## 注意事項

- API 金鑰可透過建構函式選項或 `OPENAI_API_KEY` 環境變數提供
- OpenAI Realtime Voice API 使用 WebSocket 進行即時通訊
- 伺服器端語音活動偵測 (VAD) 可提高語音偵測的準確度
- 所有音訊資料都會以 Int16Array 格式處理
- 語音執行個體必須先透過 `connect()` 建立連線，才能使用其他方法
- 使用完畢後一律呼叫 `close()`，以妥善清除資源
- 記憶體管理由 OpenAI Realtime API 處理