OpenAI Realtime 語音

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>

在連線建立後完成的 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 工具事件：

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 處理