Google Gemini Live Voice

GeminiLiveVoice クラスは、Google Gemini Live API を使用したリアルタイム Voice 対話機能を提供します。双方向音声ストリーミング、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'

リアルタイム Voice 対話に使用するモデル ID。

speaker?:

GeminiVoiceName

= 'Puck'

音声合成に使用するデフォルトの Voice ID。

vertexAI?:

boolean

= false

認証に Gemini API ではなく Vertex AI を使用します。

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

この音声リクエストに使用する Voice 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への直接リンク

実行時にセッション設定を更新します。Voice 設定、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 で使用可能な Voice Speaker の一覧を返します。

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

`disconnect()`
disconnectへの直接リンク

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

戻り値： Promise<void>

`close()`
closeへの直接リンク

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

戻り値： 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 モデルでは、アシスタントの文字起こしは 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 の動作への直接リンク

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への直接リンク

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

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

認証方法
認証方法への直接リンク

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 を使用します
音声は入力では 16 kHz PCM16、出力では 24 kHz PCM16 として処理されます
ほかのメソッドを使用する前に、Voice インスタンスを 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:

native-audio の動作native-audio の動作への直接リンク

使用可能なモデル使用可能なモデルへの直接リンク

使用可能な Voice使用可能な Voiceへの直接リンク

認証方法認証方法への直接リンク

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 の動作への直接リンク

使用可能なモデル
使用可能なモデルへの直接リンク

使用可能な Voice
使用可能な Voiceへの直接リンク

認証方法
認証方法への直接リンク

Gemini API（開発環境）
Gemini API（開発環境）への直接リンク

Vertex AI（本番環境）
Vertex AI（本番環境）への直接リンク

高度な機能
高度な機能への直接リンク

セッション管理
セッション管理への直接リンク

Tool 呼び出し
Tool 呼び出しへの直接リンク

注意事項
注意事項への直接リンク