Google Gemini Live Voice

GeminiLiveVoice 类使用 Google Gemini Live API 提供实时语音交互功能。它支持双向音频流、Tool 调用、会话管理，以及标准 Google API 和 Vertex AI 两种身份验证方法。

使用示例
使用示例的直接链接

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

= 'gemini-2.0-flash-exp'

用于实时语音交互的模型 ID。

speaker?:

GeminiVoiceName

= 'Puck'

语音合成的默认声音 ID。

vertexAI?:

boolean

= false

使用 Vertex AI 而非 Gemini API 进行身份验证。

project?:

string

Google Cloud 项目 ID（Vertex AI 必需）。

location?:

string

= 'us-central1'

Vertex AI 的 Google Cloud 区域。

serviceAccountKeyFile?:

string

用于 Vertex AI 身份验证的服务账号 JSON 密钥文件路径。

serviceAccountEmail?:

string

用于模拟身份的服务账号电子邮件（密钥文件的替代方式）。

instructions?:

string

模型的系统指令。

sessionConfig?:

GeminiSessionConfig

会话配置，包括中断和上下文设置。

GeminiSessionConfig

interrupts?:

object

中断处理配置。

interrupts.enabled?:

boolean

启用中断处理。

interrupts.allowUserInterruption?:

boolean

允许用户中断模型响应。

contextCompression?:

boolean

启用自动上下文压缩。

debug?:

boolean

= false

启用调试日志以排查问题。

方法
方法的直接链接

`connect()`
connect的直接链接

建立与 Gemini Live API 的连接。使用 speak、listen 或 send 方法之前必须调用此方法。

requestContext?:

object

连接的可选请求上下文。

returns:

Promise<void>

建立连接后解析的 Promise。

`speak()`
speak的直接链接

将文本转换为语音并发送给模型。输入可以是字符串或可读流。

input:

string | NodeJS.ReadableStream

要转换为语音的文本或文本流。

options?:

GeminiLiveVoiceOptions

可选的语音配置。

GeminiLiveVoiceOptions

speaker?:

GeminiVoiceName

此次特定语音请求使用的声音 ID。

languageCode?:

string

响应的语言代码。

responseModalities?:

('AUDIO' | 'TEXT')[]

要从模型接收的响应模态。

返回：Promise<void>（响应通过 speaker 和 writing 事件发出）

`sendContext()`
sendcontext的直接链接

将对话历史发送到实时会话中，而不触发模型响应。在冷连接时，可用此方法注入之前的对话轮次（例如来自 Mastra Memory），让模型在用户发言前就获得上下文。

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

可选配置。

object

turnComplete?:

boolean

是否将该轮次标记为完成并触发模型响应。

返回：Promise<void>

`listen()`
listen的直接链接

处理用于语音识别的音频输入。接收音频数据的可读流，并返回转录文本。

audioStream:

NodeJS.ReadableStream

要转录的音频流。

options?:

GeminiLiveVoiceOptions

可选的听写配置。

返回：Promise<string> —— 转录文本

`send()`
send的直接链接

将音频数据实时流式传输到 Gemini 服务，适用于实时麦克风输入等连续音频流场景。

audioData:

NodeJS.ReadableStream | Int16Array

要发送到服务的音频流或缓冲区。

返回：Promise<void>

`updateSessionConfig()`
updatesessionconfig的直接链接

在运行时更新会话配置。此方法可修改声音设置、speaker 选择以及其他运行时配置。

config:

Partial<GeminiLiveVoiceConfig>

要应用的配置更新。

返回：Promise<void>

`addTools()`
addtools的直接链接

向 Voice 实例添加一组 Tool。Tool 允许模型在对话期间执行其他操作。将 GeminiLiveVoice 添加到 Agent 时，为该 Agent 配置的所有 Tool 都会自动对 Voice 接口可用。

tools:

ToolsInput

要配备的 Tool 配置。

返回：void

`addInstructions()`
addinstructions的直接链接

添加或更新模型的系统指令。

instructions?:

string

要设置的系统指令。

返回：void

`answer()`
answer的直接链接

触发模型响应。此方法主要在与 Agent 集成时供内部使用。

options?:

Record<string, unknown>

answer 请求的可选参数。

返回：Promise<void>

`getSpeakers()`
getspeakers的直接链接

返回 Gemini Live API 的可用语音 speaker 列表。

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

`disconnect()`
disconnect的直接链接

断开与 Gemini Live 会话的连接并清理资源。这是用于正确处理清理操作的异步方法。

返回：Promise<void>

`close()`
close的直接链接

disconnect() 的同步封装。在内部调用 disconnect()，但不等待其完成。

返回：void

`on()`
on的直接链接

为 Voice 事件注册事件监听器。

event:

string

要监听的事件名称。

callback:

Function

事件发生时要调用的函数。

返回：void

`off()`
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 行为的直接链接

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（开发）
Gemini API（开发）的直接链接

最简单的方法是使用 Google AI Studio 提供的 API 密钥：

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

Vertex AI（生产）
Vertex AI（生产）的直接链接

在生产环境中使用 OAuth 身份验证和 Google Cloud Platform：

// 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 支持恢复会话，以应对网络中断：

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 调用
Tool 调用的直接链接

让模型能够在对话期间调用函数：

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 支持文本和音频的实时交互

使用示例使用示例的直接链接

配置配置的直接链接

构造函数选项构造函数选项的直接链接

apiKey?:

model?:

speaker?:

vertexAI?:

project?:

location?:

serviceAccountKeyFile?:

serviceAccountEmail?:

instructions?:

sessionConfig?:

interrupts?:

interrupts.enabled?:

interrupts.allowUserInterruption?:

contextCompression?:

debug?:

方法方法的直接链接

connect()connect的直接链接

requestContext?:

returns:

speak()speak的直接链接

input:

options?:

speaker?:

languageCode?:

responseModalities?:

sendContext()sendcontext的直接链接

turns:

options?:

turnComplete?:

listen()listen的直接链接

audioStream:

options?:

send()send的直接链接

audioData:

updateSessionConfig()updatesessionconfig的直接链接

config:

addTools()addtools的直接链接

tools:

addInstructions()addinstructions的直接链接

instructions?:

answer()answer的直接链接

options?:

getSpeakers()getspeakers的直接链接

disconnect()disconnect的直接链接

close()close的直接链接

on()on的直接链接

event:

callback:

off()off的直接链接

event:

callback:

事件事件的直接链接

speaker:

speaking:

writing:

thinking:

session:

turnComplete:

toolCall:

usage:

error:

interrupt:

Native-audio 行为Native-audio 行为的直接链接

可用模型可用模型的直接链接

可用声音可用声音的直接链接

身份验证方法身份验证方法的直接链接

Gemini API（开发）Gemini API（开发）的直接链接

Vertex AI（生产）Vertex AI（生产）的直接链接

高级功能高级功能的直接链接

会话管理会话管理的直接链接

Tool 调用Tool 调用的直接链接

说明说明的直接链接

使用示例
使用示例的直接链接

配置
配置的直接链接

构造函数选项
构造函数选项的直接链接

方法
方法的直接链接

`connect()`
connect的直接链接

`speak()`
speak的直接链接

`sendContext()`
sendcontext的直接链接

`listen()`
listen的直接链接

`send()`
send的直接链接

`updateSessionConfig()`
updatesessionconfig的直接链接

`addTools()`
addtools的直接链接

`addInstructions()`
addinstructions的直接链接

`answer()`
answer的直接链接

`getSpeakers()`
getspeakers的直接链接

`disconnect()`
disconnect的直接链接

`close()`
close的直接链接

`on()`
on的直接链接

`off()`
off的直接链接

事件
事件的直接链接

Native-audio 行为
Native-audio 行为的直接链接

可用模型
可用模型的直接链接

可用声音
可用声音的直接链接

身份验证方法
身份验证方法的直接链接

Gemini API（开发）
Gemini API（开发）的直接链接

Vertex AI（生产）
Vertex AI（生产）的直接链接

高级功能
高级功能的直接链接

会话管理
会话管理的直接链接

Tool 调用
Tool 调用的直接链接

说明
说明的直接链接