OpenAI Realtime Voice
OpenAIRealtimeVoice クラスは、OpenAI の WebSocket ベース API を使用したリアルタイム Voice 対話機能を提供します。リアルタイムの音声間通信、Voice Activity Detection、イベントベースの音声ストリーミングをサポートします。
使用例使用例への直接リンク
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?:
apiKey?:
speaker?:
Voice Activity Detection（VAD）の設定Voice Activity Detection（VAD）の設定への直接リンク
type?:
threshold?:
prefix_padding_ms?:
silence_duration_ms?:
メソッドメソッドへの直接リンク
connect()connectへの直接リンク
OpenAI Realtime サービスへの接続を確立します。speak、listen、send 関数を使用する前に呼び出す必要があります。
returns:
speak()speakへの直接リンク
設定された Voice モデルを使用して speaking イベントを送出します。入力には文字列または読み取り可能なストリームを指定できます。
input:
options?:
speaker?:
戻り値：Promise<void>
listen()listenへの直接リンク
音声認識用の音声入力を処理します。音声データの読み取り可能なストリームを受け取り、文字起こしテキストを含む 'listening' イベントを送出します。
audioData:
戻り値： Promise<void>
send()sendへの直接リンク
ライブマイク入力など継続的な音声ストリーミングのために、OpenAI サービスへ音声データをリアルタイムでストリーミングします。
audioData:
戻り値： Promise<void>
updateConfig()updateconfigへの直接リンク
Voice インスタンスのセッション設定を更新します。Voice 設定、ターン検出、その他のパラメーターを変更できます。
sessionConfig:
戻り値：void
addTools()addtoolsへの直接リンク
Voice インスタンスに一連の Tool を追加します。Tool により、モデルは会話中に追加のアクションを実行できます。OpenAIRealtimeVoice を Agent に追加すると、Agent に設定された Tool が Voice インターフェースで自動的に利用可能になります。
tools?:
戻り値： void
close()closeへの直接リンク
OpenAI Realtime セッションから切断してリソースを解放します。Voice インスタンスの使用を終えたら呼び出してください。
戻り値： void
getSpeakers()getspeakersへの直接リンク
使用可能な Voice Speaker の一覧を返します。
戻り値：Promise<Array<{ voiceId: string; [key: string]: any }>>
on()onへの直接リンク
Voice イベントのイベントリスナーを登録します。
event:
callback:
戻り値： void
off()offへの直接リンク
以前に登録したイベントリスナーを削除します。
event:
callback:
戻り値： void
イベントイベントへの直接リンク
OpenAIRealtimeVoice クラスは次のイベントを送出します。
speaking:
writing:
error:
OpenAI Realtime イベントOpenAI Realtime イベントへの直接リンク
'openAIRealtime:' プレフィックスを付けて、OpenAI Realtime ユーティリティイベントもリッスンできます。
openAIRealtime:conversation.created:
openAIRealtime:conversation.interrupted:
openAIRealtime:conversation.updated:
openAIRealtime:conversation.item.appended:
openAIRealtime:conversation.item.completed:
使用可能な Voice使用可能な Voiceへの直接リンク
次の Voice オプションを利用できます。
alloy：ニュートラルでバランスの取れた Voiceash：明瞭で正確な Voiceballad：旋律的で滑らかな Voicecoral：温かく親しみやすい Voiceecho：響きがあり深みのある Voicesage：落ち着きと思慮深さのある Voiceshimmer：明るくエネルギッシュな Voiceverse：多用途で表現力豊かな Voice
注意事項注意事項への直接リンク
- API キーは、コンストラクターオプションまたは
OPENAI_API_KEY環境変数で指定できます - OpenAI Realtime Voice API はリアルタイム通信に WebSocket を使用します
- サーバー側の Voice Activity Detection（VAD）は、より高精度な発話検出を提供します
- すべての音声データは Int16Array 形式で処理されます
- ほかのメソッドを使用する前に、Voice インスタンスを
connect()で接続する必要があります - リソースを適切に解放するため、使用後は必ず
close()を呼び出してください - メモリ管理は OpenAI Realtime API が処理します