OpenAI Realtime Voice

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-4o-mini-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();

設定

コンストラクタオプション

音声アクティビティ検出（VAD）設定

メソッド

connect()

OpenAI リアルタイムサービスへの接続を確立します。speak、listen、send 関数を使用する前に呼び出す必要があります。

speak()

設定された音声モデルを使用して発話イベントを発行します。入力として文字列またはリーダブルストリームのいずれかを受け付けます。

戻り値: Promise<void>

listen()

音声認識のために音声入力を処理します。音声データのリーダブルストリームを受け取り、書き起こされたテキストとともに ‘listening’ イベントを発行します。

戻り値: Promise<void>

send()

ライブマイク入力など、連続的な音声ストリーミングシナリオのために、音声データをリアルタイムで OpenAI サービスにストリーミングします。

戻り値: Promise<void>

updateConfig()

音声インスタンスのセッション設定を更新します。これにより、音声設定やターン検出、その他のパラメータを変更できます。

戻り値: void

addTools()

音声インスタンスにツールセットを追加します。ツールを追加することで、モデルが会話中に追加のアクションを実行できるようになります。OpenAIRealtimeVoice が Agent に追加されている場合、Agent に設定されたツールは自動的に音声インターフェースでも利用可能になります。

戻り値: void

close()

OpenAI リアルタイムセッションから切断し、リソースをクリーンアップします。音声インスタンスの使用が終了したら呼び出してください。

戻り値: void

getSpeakers()

利用可能な音声スピーカーのリストを返します。

戻り値: Promise<Array<{ voiceId: string; [key: string]: any }>>

on()

音声イベントのイベントリスナーを登録します。

戻り値: void

off()

以前に登録したイベントリスナーを削除します。

戻り値: void

イベント

OpenAIRealtimeVoiceクラスは以下のイベントを発生させます：

OpenAI Realtimeイベント

OpenAI Realtimeユーティリティイベント も’openAIRealtime:‘を接頭辞として付けることでリッスンできます：

利用可能な音声

以下の音声オプションが利用できます：

• alloy: ニュートラルでバランスが取れている
• ash: クリアで正確
• ballad: メロディックで滑らか
• coral: 暖かく親しみやすい
• echo: 共鳴して深みがある
• sage: 落ち着いて思慮深い
• shimmer: 明るくエネルギッシュ
• verse: 多才で表現力豊か

メモ

• APIキーはコンストラクタオプションまたはOPENAI_API_KEY環境変数を通じて提供できます
• OpenAI リアルタイム音声APIはリアルタイム通信にWebSocketsを使用しています
• サーバーサイドの音声アクティビティ検出（VAD）は音声検出のための精度が向上します
• すべての音声データはInt16Array形式で処理されます
• 音声インスタンスは他のメソッドを使用する前にconnect()で接続する必要があります
• 終了時には必ずclose()を呼び出してリソースを適切にクリーンアップしてください
• メモリ管理はOpenAI リアルタイムAPIによって処理されます