Google Gemini Live 語音

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），部分較舊的模型則只接受用戶角色的輪次。

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 的直接連結

在執行期間更新工作階段設定。此方法可修改語音設定及講者選擇，也可修改其他執行期間設定。

config:

Partial<GeminiLiveVoiceConfig>

要套用的設定更新。

傳回：Promise<void>

`addTools()`
addtools 的直接連結

向語音實例加入一組 Tool。Tool 讓模型可在對話期間執行其他操作。將 GeminiLiveVoice 加入 Agent 後，為該 Agent 設定的所有 Tool 均會自動供語音介面使用。

tools:

ToolsInput

要配備的 Tool 設定。

傳回：void

`addInstructions()`
addinstructions 的直接連結

加入或更新模型的系統指示。

instructions?:

string

要設定的系統指示。

傳回：void

`answer()`
answer 的直接連結

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

options?:

Record<string, unknown>

回答請求的選填參數。

傳回：Promise<void>

`getSpeakers()`
getspeakers 的直接連結

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

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

disconnect()
disconnect() 的直接連結

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

傳回：Promise<void>

`close()`
close 的直接連結

disconnect() 的同步包裝函數。此方法會在內部調用 disconnect()，但不會等待其完成。

傳回：void

`on()`
on 的直接連結

為語音事件註冊事件監聽器。

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' }。在原生音訊模型上，助理轉錄由伺服器的 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

連同 token 用量資料一併發出。回呼會接收 { 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'）會在設定 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 使用 WebSockets 進行實時通訊
輸入音訊以 16kHz PCM16 處理，輸出音訊則以 24kHz PCM16 處理
使用其他方法前，必須先使用 connect() 連接語音實例
完成後務必調用 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:

原生音訊行為原生音訊行為 的直接連結

可用模型可用模型 的直接連結

可用語音可用語音 的直接連結

驗證方式驗證方式 的直接連結

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 的直接連結

事件
事件的直接連結

原生音訊行為
原生音訊行為的直接連結

可用模型
可用模型的直接連結

可用語音
可用語音的直接連結

驗證方式
驗證方式的直接連結

Gemini API（開發）
Gemini API（開發）的直接連結

Vertex AI（生產環境）
Vertex AI（生產環境）的直接連結

進階功能
進階功能的直接連結

工作階段管理
工作階段管理的直接連結

Tool 調用
Tool 調用的直接連結

注意事項
注意事項的直接連結