> Discover all available pages from the documentation index: https://mastra.zisheng.pro/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()`

在运行时更新会话配置。此方法可修改声音设置、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 的可用语音 speaker 列表。

返回：`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' }。在 native-audio 模型上，assistant 转录由服务器的 output\_audio\_transcription 通道驱动，而非 modelTurn.parts.text。

**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`): 随 token 用量信息一起发出。回调接收 { 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 模型（ID 中包含 `native-audio` 的任何模型，例如 `gemini-2.5-flash-native-audio-preview-12-2025`）会将文本输出拆分到两个通道：

- 模型的口语回复以音频和 `output_audio_transcription` 转录的形式传递，并以 `writing` 事件公开，其 `role: 'assistant'`。
- 模型的内部推理以 `modelTurn.parts.text` 的形式传递，并以 `thinking` 事件公开。

非 native-audio 模型没有 `output_audio_transcription` 通道，因此 `modelTurn.parts.text` 就是口语响应本身，并以 `writing` 事件发出。此时不会发出 `thinking` 事件。

输入转录、输出转录和插话检测 (`realtime_input_config.activity_handling = 'START_OF_ACTIVITY_INTERRUPTS'`) 会在设置 payload 中自动启用，无需额外配置。

## 可用模型

可使用以下 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 使用 WebSocket 进行实时通信
- 输入音频以 16kHz PCM16 处理，输出音频以 24kHz PCM16 处理
- 使用其他方法前，必须通过 `connect()` 连接 Voice 实例
- 完成后始终调用 `close()`，以正确清理资源
- Vertex AI 身份验证需要适当的 IAM 权限（`aiplatform.user` 角色）
- 会话恢复功能可从网络中断中恢复
- API 支持文本和音频的实时交互