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 金鑰。未提供時會改用 OPENAI_API_KEY 環境變數。
speaker?:
string
= 'alloy'
語音合成的預設語音 ID。
語音活動偵測 (VAD) 設定「語音活動偵測 (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()「connect」的直接連結
建立與 OpenAI Realtime 服務的連線。使用 speak、listen 或 send 函式前必須先呼叫。
returns:
Promise<void>
連線建立後解析的 Promise。
speak()「speak」的直接連結
使用已設定的語音模型發出 speaking 事件。輸入可以是字串或可讀取的串流。
input:
string | NodeJS.ReadableStream
要轉換成語音的文字或文字串流。
options?:
Options
設定選項。
Options
speaker?:
string
此特定語音請求要使用的語音 ID。
傳回：Promise<void>
listen()「listen」的直接連結
處理用於語音辨識的音訊輸入。接收音訊資料的可讀取串流，並發出包含轉錄文字的 'listening' 事件。
audioData:
NodeJS.ReadableStream
要轉錄的音訊串流。
傳回：Promise<void>
send()「send」的直接連結
將音訊資料即時串流至 OpenAI 服務，適用於即時麥克風輸入等連續音訊串流情境。
audioData:
NodeJS.ReadableStream
要傳送至服務的音訊串流。
傳回：Promise<void>
updateConfig()「updateconfig」的直接連結
更新語音執行個體的工作階段設定。這可以修改語音設定、對話輪次偵測及其他參數。
sessionConfig:
Realtime.SessionConfig
要套用的新工作階段設定。
傳回：void
addTools()「addtools」的直接連結
將一組 Tool 加入語音執行個體。Tool 可讓模型在對話期間執行其他動作。將 OpenAIRealtimeVoice 加入 Agent 時，為 Agent 設定的所有 Tool 都會自動供語音介面使用。
tools?:
ToolsInput
要配備的 Tool 設定。
傳回：void
close()「close」的直接連結
中斷 OpenAI Realtime 工作階段的連線並清除資源。語音執行個體使用完畢後應呼叫此方法。
傳回：void
getSpeakers()「getspeakers」的直接連結
傳回可用的語音說話者清單。
傳回：Promise<Array<{ voiceId: string; [key: string]: any }>>
on()「on」的直接連結
註冊語音事件的事件監聽器。
event:
string
要監聽的事件名稱。
callback:
Function
事件發生時要呼叫的函式。
傳回：void
off()「off」的直接連結
移除先前註冊的事件監聽器。
event:
string
要停止監聽的事件名稱。
callback:
Function
要移除的特定回呼函式。
傳回：void
事件「事件」的直接連結
OpenAIRealtimeVoice 類別會發出下列事件：
speaking:
event
從模型收到音訊資料時發出。回呼會收到 { audio: Int16Array }。
writing:
event
有可用的轉錄文字時發出。回呼會收到 { text: string, role: string }。
error:
event
發生錯誤時發出。回呼會收到錯誤物件。
OpenAI Realtime 事件「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 金鑰可透過建構函式選項或
OPENAI_API_KEY環境變數提供 - OpenAI Realtime Voice API 使用 WebSocket 進行即時通訊
- 伺服器端語音活動偵測 (VAD) 可提高語音偵測的準確度
- 所有音訊資料都會以 Int16Array 格式處理
- 語音執行個體必須先透過
connect()建立連線，才能使用其他方法 - 使用完畢後一律呼叫
close()，以妥善清除資源 - 記憶體管理由 OpenAI Realtime API 處理