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

# Google Gemini Live Voice

GeminiLiveVoice 類別使用 Google Gemini Live API 提供即時語音互動功能。它支援雙向音訊串流、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`): 即時語音互動使用的模型 ID。 (Default: `'gemini-2.0-flash-exp'`)

**speaker** (`GeminiVoiceName`): 語音合成的預設語音 ID。 (Default: `'Puck'`)

**vertexAI** (`boolean`): 使用 Vertex AI，而非 Gemini API 進行驗證。 (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`): 此語音請求使用的語音 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()`

在執行階段更新工作階段設定。可修改語音設定與語音選擇，也能修改其他執行階段設定。

**config** (`Partial<GeminiLiveVoiceConfig>`): 要套用的設定更新。

回傳：`Promise<void>`

### `addTools()`

將一組 Tools 加入 Voice 執行個體。Tools 可讓模型在對話期間執行其他動作。GeminiLiveVoice 加入 Agent 時，為 Agent 設定的任何 Tools 都會自動提供給 Voice 介面。

**tools** (`ToolsInput`): 要配備的 Tools 設定。

回傳：`void`

### `addInstructions()`

新增或更新模型的系統指示。

**instructions** (`string`): 要設定的系統指示。

回傳：`void`

### `answer()`

觸發模型回應。此方法主要在與 Agent 整合時由內部使用。

**options** (`Record<string, unknown>`): 回答請求的選用參數。

回傳：`Promise<void>`

### `getSpeakers()`

回傳 Gemini Live API 可用的語音清單。

回傳：`Promise<Array<{ voiceId: string; description?: string }>>`

### `disconnect()`

中斷 Gemini Live 工作階段的連線並清理資源。此非同步方法會妥善處理清理作業。

回傳：`Promise<void>`

### `close()`

disconnect() 的同步包裝函式。內部呼叫 disconnect()，但不等待其完成。

回傳：`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' }。在原生音訊模型上，助理轉錄由伺服器的 output\_audio\_transcription 通道驅動，而不是 modelTurn.parts.text。

**thinking** (`event`): 在原生音訊模型上發出，包含來自 modelTurn.parts.text 的模型思考鏈／推理文字。回呼會收到 { text: string }。此事件不會在非原生音訊模型上觸發；在這類模型上，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 }。

## 原生音訊行為

原生音訊 Gemini Live 模型（ID 包含 `native-audio` 的任何模型，例如 `gemini-2.5-flash-native-audio-preview-12-2025`）會將文字輸出分到兩個通道：

- 模型說出的回覆會以音訊加上 `output_audio_transcription` 轉錄提供，並以 `role: 'assistant'` 的 `writing` 呈現。
- 模型的內部推理會以 `modelTurn.parts.text` 提供，並以 `thinking` 呈現。

非原生音訊模型沒有 `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`

## 可用語音

可使用下列語音選項：

- `Puck`（預設）：自然對話、友善
- `Charon`：低沉、權威
- `Kore`：中性、專業
- `Fenrir`：溫暖、平易近人

## 驗證方法

### 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 使用 WebSockets 進行即時通訊
- 輸入音訊會以 16kHz PCM16 處理，輸出音訊則以 24kHz PCM16 處理
- Voice 執行個體必須先透過 `connect()` 連線，才能使用其他方法
- 完成後一律呼叫 `close()`，以正確清理資源
- Vertex AI 驗證需要適當的 IAM 權限（`aiplatform.user` 角色）
- 工作階段恢復功能可從網路中斷中復原
- 此 API 支援使用文字與音訊進行即時互動