> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/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 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>`): 在連線建立後完成的 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()`

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

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

傳回值： `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 key 可透過建構函式選項或 `OPENAI_API_KEY` 環境變數提供
- OpenAI Realtime Voice API 使用 WebSockets 進行即時通訊
- 伺服器端語音活動偵測（VAD）可提高語音偵測的準確度
- 所有音訊資料均以 Int16Array 格式處理
- 使用其他方法前，必須先透過 `connect()` 連接語音實例
- 使用完畢後，必須呼叫 `close()` 以妥善清理資源
- 記憶體管理由 OpenAI Realtime API 處理