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

# Google Gemini Live Voice

GeminiLiveVoice クラスは、Google Gemini Live API を使用したリアルタイム Voice 対話機能を提供します。双方向音声ストリーミング、Tool 呼び出し、セッション管理、標準の Google API と Vertex AI の両認証方式をサポートします。

## 使用例

```typescript
import { GeminiLiveVoice } from '@mastra/voice-google-gemini-live'
import { playAudio, getMicrophoneStream } from '@mastra/node-audio'

// Initialize with Gemini API (using API key)
const voice = new GeminiLiveVoice({
  apiKey: process.env.GOOGLE_API_KEY, // Required for Gemini API
  model: 'gemini-2.0-flash-exp',
  speaker: 'Puck', // Default voice
  debug: true,
})

// Or initialize with Vertex AI (using OAuth)
const voiceWithVertexAI = new GeminiLiveVoice({
  vertexAI: true,
  project: 'your-gcp-project',
  location: 'us-central1',
  serviceAccountKeyFile: '/path/to/service-account.json',
  model: 'gemini-2.0-flash-exp',
  speaker: 'Puck',
})

// Or use the VoiceConfig pattern (recommended for consistency with other providers)
const voiceWithConfig = new GeminiLiveVoice({
  speechModel: {
    name: 'gemini-2.0-flash-exp',
    apiKey: process.env.GOOGLE_API_KEY,
  },
  speaker: 'Puck',
  realtimeConfig: {
    model: 'gemini-2.0-flash-exp',
    apiKey: process.env.GOOGLE_API_KEY,
    options: {
      debug: true,
      sessionConfig: {
        interrupts: { enabled: true },
      },
    },
  },
})

// Establish connection (required before using other methods)
await voice.connect()

// Set up event listeners
voice.on('speaker', audioStream => {
  // Handle audio stream (NodeJS.ReadableStream)
  playAudio(audioStream)
})

voice.on('writing', ({ text, role }) => {
  // Handle transcribed text
  console.log(`${role}: ${text}`)
})

voice.on('turnComplete', ({ timestamp }) => {
  // Handle turn completion
  console.log('Turn completed at:', timestamp)
})

// Convert text to speech
await voice.speak('Hello, how can I help you today?', {
  speaker: 'Charon', // Override default voice
  responseModalities: ['AUDIO', 'TEXT'],
})

// Process audio input
const microphoneStream = getMicrophoneStream()
await voice.send(microphoneStream)

// Update session configuration
await voice.updateSessionConfig({
  speaker: 'Kore',
  instructions: 'Be more concise in your responses',
})

// When done, disconnect
await voice.disconnect()
// Or use the synchronous wrapper
voice.close()
```

## 設定

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

**apiKey** (`string`): Gemini API 認証用の Google API キー。Vertex AI を使用しない場合は必須です。

**model** (`GeminiVoiceModel`): リアルタイム Voice 対話に使用するモデル ID。 (Default: `'gemini-2.0-flash-exp'`)

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

**vertexAI** (`boolean`): 認証に Gemini API ではなく Vertex AI を使用します。 (Default: `false`)

**project** (`string`): Google Cloud プロジェクト ID（Vertex AI では必須）。

**location** (`string`): Vertex AI の Google Cloud リージョン。 (Default: `'us-central1'`)

**serviceAccountKeyFile** (`string`): Vertex AI 認証用のサービスアカウント JSON キーファイルへのパス。

**serviceAccountEmail** (`string`): 権限借用に使用するサービスアカウントのメールアドレス（キーファイルの代替）。

**instructions** (`string`): モデルのシステム指示。

**sessionConfig** (`GeminiSessionConfig`): 中断およびコンテキスト設定を含むセッション設定。

**sessionConfig.interrupts** (`object`): 中断処理の設定。

**sessionConfig.interrupts.enabled** (`boolean`): 中断処理を有効にします。

**sessionConfig.interrupts.allowUserInterruption** (`boolean`): ユーザーによるモデル応答の中断を許可します。

**sessionConfig.contextCompression** (`boolean`): コンテキストの自動圧縮を有効にします。

**debug** (`boolean`): トラブルシューティング用のデバッグログを有効にします。 (Default: `false`)

## メソッド

### `connect()`

Gemini Live API への接続を確立します。speak、listen、send メソッドを使用する前に呼び出す必要があります。

**requestContext** (`object`): 接続用の省略可能なリクエストコンテキスト。

**returns** (`Promise<void>`): 接続が確立されると解決する Promise。

### `speak()`

テキストを音声に変換してモデルに送信します。入力には文字列または読み取り可能なストリームを指定できます。

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

**options** (`GeminiLiveVoiceOptions`): 省略可能な音声設定。

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

**options.languageCode** (`string`): 応答の言語コード。

**options.responseModalities** (`('AUDIO' | 'TEXT')[]`): モデルから受信する応答モダリティ。

戻り値：`Promise<void>`（応答は `speaker` および `writing` イベントで送出されます）

### `sendContext()`

モデルの応答を開始せずに、会話履歴をライブセッションへ送信します。コールド接続時に以前のターン（Mastra Memory から取得したものなど）を追加し、ユーザーが話す前にモデルへコンテキストを与えるために使用します。

```typescript
await voice.sendContext([
  { role: 'user', content: 'What is the weather?' },
  { role: 'assistant', content: 'It is 72°F in San Francisco.' },
])

// Model stays silent until the user actually speaks.
await voice.send(micStream)
```

**turns** (`IncrementalTurn[]`): セッションに追加する以前の会話ターン。各ターンには role（"user" または "assistant"）と content 文字列があります。新しいモデル（例：gemini-2.5-flash-native-audio-preview-12-2025）は両方のロールをサポートします。一部の古いモデルは user ロールのターンだけを受け付けます。

**options** (`object`): 省略可能な設定。

**options.turnComplete** (`boolean`): ターンを完了としてマークし、モデルの応答を開始するかどうか。

戻り値：`Promise<void>`

### `listen()`

音声認識用の音声入力を処理します。音声データの読み取り可能なストリームを受け取り、文字起こしテキストを返します。

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

**options** (`GeminiLiveVoiceOptions`): 省略可能なリスニング設定。

戻り値：`Promise<string>` - 文字起こしされたテキスト

### `send()`

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

**audioData** (`NodeJS.ReadableStream | Int16Array`): サービスに送信する音声ストリームまたはバッファ。

戻り値： `Promise<void>`

### `updateSessionConfig()`

実行時にセッション設定を更新します。Voice 設定、Speaker の選択、その他の実行時設定を変更できます。

**config** (`Partial<GeminiLiveVoiceConfig>`): 適用する設定の更新。

戻り値：`Promise<void>`

### `addTools()`

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

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

戻り値：`void`

### `addInstructions()`

モデルのシステム指示を追加または更新します。

**instructions** (`string`): 設定するシステム指示。

戻り値： `void`

### `answer()`

モデルからの応答を開始します。このメソッドは、Agent と統合した際に主に内部で使用されます。

**options** (`Record<string, unknown>`): answer リクエストの省略可能なパラメーター。

戻り値： `Promise<void>`

### `getSpeakers()`

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

戻り値：`Promise<Array<{ voiceId: string; description?: string }>>`

### `disconnect()`

Gemini Live セッションから切断してリソースを解放します。クリーンアップを適切に処理する非同期メソッドです。

戻り値： `Promise<void>`

### `close()`

disconnect() の同期ラッパーです。内部で disconnect() を await せずに呼び出します。

戻り値： `void`

### `on()`

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

**event** (`string`): リッスンするイベント名。

**callback** (`Function`): イベント発生時に呼び出す関数。

戻り値： `void`

### `off()`

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

**event** (`string`): リッスンを停止するイベント名。

**callback** (`Function`): 削除する特定のコールバック関数。

戻り値： `void`

## イベント

GeminiLiveVoice クラスは次のイベントを送出します。

**speaker** (`event`): モデルから音声データを受信したときに送出されます。コールバックは NodeJS.ReadableStream を受け取ります。

**speaking** (`event`): 音声メタデータとともに送出されます。コールバックは { audioData?: Int16Array, sampleRate?: number } を受け取ります。

**writing** (`event`): 文字起こしテキストを利用できるときに送出されます。コールバックは { text: string, role: 'assistant' | 'user' } を受け取ります。native-audio モデルでは、アシスタントの文字起こしは modelTurn.parts.text ではなく、サーバーの output\_audio\_transcription チャンネルによって提供されます。

**thinking** (`event`): native-audio モデルで、modelTurn.parts.text から取得したモデルの思考連鎖／推論テキストとともに送出されます。コールバックは { text: string } を受け取ります。非 native-audio モデルでは modelTurn.parts.text が発話応答となり、代わりに writing として送出されるため、このイベントは発生しません。

**session** (`event`): セッション状態が変化したときに送出されます。コールバックは { state: 'connecting' | 'connected' | 'disconnected' | 'disconnecting' | 'updated', config?: object } を受け取ります。

**turnComplete** (`event`): 会話のターンが完了したときに送出されます。コールバックは { timestamp: number } を受け取ります。

**toolCall** (`event`): モデルが Tool 呼び出しを要求したときに送出されます。コールバックは { name: string, args: object, id: string } を受け取ります。

**usage** (`event`): トークン使用量情報とともに送出されます。コールバックは { inputTokens: number, outputTokens: number, totalTokens: number, modality: string } を受け取ります。

**error** (`event`): エラーが発生したときに送出されます。コールバックは { message: string, code?: string, details?: unknown } を受け取ります。

**interrupt** (`event`): 処理中のモデル応答に重ねてユーザーが話し始めたとき、割り込みにより送出されます。サーバーは現在のターンの後続音声をキャンセルします。コールバックは { type: 'user', timestamp: number } を受け取ります。

## native-audio の動作

native-audio Gemini Live モデル（`gemini-2.5-flash-native-audio-preview-12-2025` など、ID に `native-audio` を含むモデル）は、テキスト出力を2つのチャンネルに分けます。

- モデルの発話応答は、音声と `output_audio_transcription` の文字起こしとして配信され、`role: 'assistant'` の `writing` として公開されます。
- モデルの内部推論は `modelTurn.parts.text` として配信され、`thinking` として公開されます。

非 native-audio モデルには `output_audio_transcription` チャンネルがないため、`modelTurn.parts.text` 自体が発話応答となり、`writing` として送出されます。`thinking` イベントは発生しません。

入力の文字起こし、出力の文字起こし、割り込み検出（`realtime_input_config.activity_handling = 'START_OF_ACTIVITY_INTERRUPTS'`）は、セットアップペイロードで自動的に有効になります。追加設定は不要です。

## 使用可能なモデル

次の Gemini Live モデルを利用できます。

- `gemini-2.0-flash-exp`（デフォルト）
- `gemini-2.0-flash-exp-image-generation`
- `gemini-2.0-flash-live-001`
- `gemini-live-2.5-flash-preview-native-audio`
- `gemini-2.5-flash-exp-native-audio-thinking-dialog`
- `gemini-live-2.5-flash-preview`
- `gemini-2.6.flash-preview-tts`

## 使用可能な Voice

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

- `Puck`（デフォルト）：会話的で親しみやすい Voice
- `Charon`：深みがあり威厳のある Voice
- `Kore`：ニュートラルでプロフェッショナルな Voice
- `Fenrir`：温かく親しみやすい Voice

## 認証方法

### Gemini API（開発環境）

[Google AI Studio](https://makersuite.google.com/app/apikey) の API キーを使用する最も簡単な方法です。

```typescript
const voice = new GeminiLiveVoice({
  apiKey: 'your-api-key', // Required for Gemini API
  model: 'gemini-2.0-flash-exp',
})
```

### Vertex AI（本番環境）

OAuth 認証と Google Cloud Platform を使用する本番環境向けの方法です。

```typescript
// Using service account key file
const voice = new GeminiLiveVoice({
  vertexAI: true,
  project: 'your-gcp-project',
  location: 'us-central1',
  serviceAccountKeyFile: '/path/to/service-account.json',
})

// Using Application Default Credentials
const voice = new GeminiLiveVoice({
  vertexAI: true,
  project: 'your-gcp-project',
  location: 'us-central1',
})

// Using service account impersonation
const voice = new GeminiLiveVoice({
  vertexAI: true,
  project: 'your-gcp-project',
  location: 'us-central1',
  serviceAccountEmail: 'service-account@project.iam.gserviceaccount.com',
})
```

## 高度な機能

### セッション管理

Gemini Live API は、ネットワーク中断に対応するセッション再開をサポートします。

```typescript
voice.on('sessionHandle', ({ handle, expiresAt }) => {
  // Store session handle for resumption
  saveSessionHandle(handle, expiresAt)
})

// Resume a previous session
const voice = new GeminiLiveVoice({
  sessionConfig: {
    enableResumption: true,
    maxDuration: '2h',
  },
})
```

### Tool 呼び出し

会話中にモデルが関数を呼び出せるようにします。

```typescript
import { z } from 'zod'

voice.addTools({
  weather: {
    description: 'Get weather information',
    parameters: z.object({
      location: z.string(),
    }),
    execute: async ({ location }) => {
      const weather = await getWeather(location)
      return weather
    },
  },
})

voice.on('toolCall', ({ name, args, id }) => {
  console.log(`Tool called: ${name} with args:`, args)
})
```

## 注意事項

- Gemini Live API はリアルタイム通信に WebSocket を使用します
- 音声は入力では 16 kHz PCM16、出力では 24 kHz PCM16 として処理されます
- ほかのメソッドを使用する前に、Voice インスタンスを `connect()` で接続する必要があります
- リソースを適切に解放するため、使用後は必ず `close()` を呼び出してください
- Vertex AI 認証には適切な IAM 権限（`aiplatform.user` ロール）が必要です
- セッション再開により、ネットワーク中断から復旧できます
- API はテキストと音声によるリアルタイム対話をサポートします