> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt

# OpenAI Realtime Voice

OpenAIRealtimeVoice クラスは、OpenAI の WebSocket ベース API を使用したリアルタイム Voice 対話機能を提供します。リアルタイムの音声間通信、Voice Activity Detection、イベントベースの音声ストリーミングをサポートします。

## 使用例

```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`): リアルタイム Voice 対話に使用するモデル ID。 (Default: `'gpt-5.1-realtime-preview-2024-12-17'`)

**apiKey** (`string`): OpenAI API キー。未指定の場合は OPENAI\_API\_KEY 環境変数を使用します。

**speaker** (`string`): 音声合成に使用するデフォルトの Voice ID。 (Default: `'alloy'`)

### Voice Activity Detection（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()`

設定された Voice モデルを使用して speaking イベントを送出します。入力には文字列または読み取り可能なストリームを指定できます。

**input** (`string | NodeJS.ReadableStream`): 音声に変換するテキストまたはテキストストリーム。

**options** (`Options`): 設定オプション。

**options.speaker** (`string`): この音声リクエストに使用する Voice ID。

戻り値：`Promise<void>`

### `listen()`

音声認識用の音声入力を処理します。音声データの読み取り可能なストリームを受け取り、文字起こしテキストを含む 'listening' イベントを送出します。

**audioData** (`NodeJS.ReadableStream`): 文字起こしする音声ストリーム。

戻り値： `Promise<void>`

### `send()`

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

**audioData** (`NodeJS.ReadableStream`): サービスに送信する音声ストリーム。

戻り値： `Promise<void>`

### `updateConfig()`

Voice インスタンスのセッション設定を更新します。Voice 設定、ターン検出、その他のパラメーターを変更できます。

**sessionConfig** (`Realtime.SessionConfig`): 適用する新しいセッション設定。

戻り値：`void`

### `addTools()`

Voice インスタンスに一連の Tool を追加します。Tool により、モデルは会話中に追加のアクションを実行できます。OpenAIRealtimeVoice を Agent に追加すると、Agent に設定された Tool が Voice インターフェースで自動的に利用可能になります。

**tools** (`ToolsInput`): 設定する Tool の設定。

戻り値： `void`

### `close()`

OpenAI Realtime セッションから切断してリソースを解放します。Voice インスタンスの使用を終えたら呼び出してください。

戻り値： `void`

### `getSpeakers()`

使用可能な Voice Speaker の一覧を返します。

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

### `on()`

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

**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`): 会話内の項目が完了したときに送出されます。

## 使用可能な Voice

次の Voice オプションを利用できます。

- `alloy`：ニュートラルでバランスの取れた Voice
- `ash`：明瞭で正確な Voice
- `ballad`：旋律的で滑らかな Voice
- `coral`：温かく親しみやすい Voice
- `echo`：響きがあり深みのある Voice
- `sage`：落ち着きと思慮深さのある Voice
- `shimmer`：明るくエネルギッシュな Voice
- `verse`：多用途で表現力豊かな Voice

## 注意事項

- API キーは、コンストラクターオプションまたは `OPENAI_API_KEY` 環境変数で指定できます
- OpenAI Realtime Voice API はリアルタイム通信に WebSocket を使用します
- サーバー側の Voice Activity Detection（VAD）は、より高精度な発話検出を提供します
- すべての音声データは Int16Array 形式で処理されます
- ほかのメソッドを使用する前に、Voice インスタンスを `connect()` で接続する必要があります
- リソースを適切に解放するため、使用後は必ず `close()` を呼び出してください
- メモリ管理は OpenAI Realtime API が処理します