Google Gemini Live Voice
GeminiLiveVoice クラスは、Google の Gemini Live API を用いてリアルタイムの音声インタラクション機能を提供します。双方向の音声ストリーミング、ツール呼び出し、セッション管理に対応し、標準の Google API 認証および Vertex AI 認証の両方をサポートします。
使用例
import { GeminiLiveVoice } from "@mastra/voice-google-gemini-live";
import { playAudio, getMicrophoneStream } from "@mastra/node-audio";
// Gemini API で初期化(API キーを使用)
const voice = new GeminiLiveVoice({
apiKey: process.env.GOOGLE_API_KEY, // Gemini API に必須
model: "gemini-2.0-flash-exp",
speaker: "Puck", // 既定の声
debug: true,
});
// または Vertex AI で初期化(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",
});
// もしくは VoiceConfig パターンを使用(他プロバイダーとの一貫性のため推奨)
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 },
},
},
},
});
// 接続を確立(他のメソッドを使う前に必須)
await voice.connect();
// イベントリスナーを設定
voice.on("speaker", (audioStream) => {
// オーディオストリームを処理(NodeJS.ReadableStream)
playAudio(audioStream);
});
voice.on("writing", ({ text, role }) => {
// 音声認識結果を処理
console.log(`${role}: ${text}`);
});
voice.on("turnComplete", ({ timestamp }) => {
// ターン完了を処理
console.log("Turn completed at:", timestamp);
});
// テキスト読み上げ
await voice.speak("Hello, how can I help you today?", {
speaker: "Charon", // 既定の声を上書き
responseModalities: ["AUDIO", "TEXT"],
});
// 音声入力を処理
const microphoneStream = getMicrophoneStream();
await voice.send(microphoneStream);
// セッション設定を更新
await voice.updateSessionConfig({
speaker: "Kore",
instructions: "回答はより簡潔にしてください。",
});
// 終了時に切断
await voice.disconnect();
// または同期ラッパーを使用
voice.close();
設定
コンストラクターのオプション
apiKey?:
model?:
speaker?:
vertexAI?:
project?:
location?:
serviceAccountKeyFile?:
serviceAccountEmail?:
instructions?:
sessionConfig?:
debug?:
セッション構成
interrupts?:
interrupts.enabled?:
interrupts.allowUserInterruption?:
contextCompression?:
メソッド
connect()
Gemini Live API への接続を確立します。speak、listen、send メソッドを使用する前に呼び出す必要があります。
runtimeContext?:
returns:
speak()
テキストを音声に変換してモデルへ送信します。入力は文字列または読み取り可能なストリームを受け付けます。
input:
options?:
options.speaker?:
options.languageCode?:
options.responseModalities?:
戻り値: Promise<void>
(レスポンスは speaker
および writing
イベントで送出されます)
listen()
音声認識のために音声入力を処理します。音声データの読み取り可能なストリームを受け取り、文字起こし結果を返します。
audioStream:
options?:
戻り値: Promise<string>
- 文字起こしテキスト
send()
ライブマイク入力などの連続音声ストリーミングのシナリオにおいて、音声データをリアルタイムで Gemini サービスにストリーミングします。
audioData:
戻り値: Promise<void>
updateSessionConfig()
セッション設定を動的に更新します。これにより、音声設定、スピーカーの選択、その他のランタイム設定を変更できます。
config:
戻り値: Promise<void>
addTools()
音声インスタンスにツール群を追加します。ツールにより、モデルは会話中に追加のアクションを実行できます。GeminiLiveVoice を Agent に追加すると、Agent に設定されたツールは自動的に音声インターフェースで利用可能になります。
tools:
戻り値: void
addInstructions()
モデルのシステム指示を追加または更新します。
instructions?:
戻り値: void
answer()
モデルからの応答をトリガーします。このメソッドは主に、Agent と統合した際に内部的に使用されます。
options?:
戻り値: Promise<void>
getSpeakers()
Gemini Live API で利用可能な音声スピーカーの一覧を返します。
戻り値: Promise<Array<{ voiceId: string; description?: string }>>
disconnect()
Gemini Live のセッションから切断し、リソースをクリーンアップします。クリーンアップを適切に処理する非同期メソッドです。
戻り値: Promise<void>
close()
disconnect() の同期ラッパー。内部で disconnect() を呼び出しますが、await はしません。
戻り値: void
on()
音声イベントのイベントリスナーを登録します。
event:
callback:
戻り値: void
off()
以前に登録したイベントリスナーを削除します。
event:
callback:
戻り値: void
イベント
GeminiLiveVoice クラスは次のイベントを発行します:
speaker:
speaking:
writing:
session:
turnComplete:
toolCall:
usage:
error:
interrupt:
利用可能なモデル
次の 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 の API キーを使う最も簡単な方法:
const voice = new GeminiLiveVoice({
apiKey: "your-api-key", // Gemini API には必須
model: "gemini-2.0-flash-exp",
});
Vertex AI(本番)
OAuth 認証と Google Cloud Platform を用いた本番環境向けの利用:
// サービス アカウント鍵ファイルを使用
const voice = new GeminiLiveVoice({
vertexAI: true,
project: "your-gcp-project",
location: "us-central1",
serviceAccountKeyFile: "/path/to/service-account.json",
});
// アプリケーション デフォルト認証情報を使用
const voice = new GeminiLiveVoice({
vertexAI: true,
project: "your-gcp-project",
location: "us-central1",
});
// サービス アカウントの代理(インパーソネーション)を使用
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 }) => {
// セッション再開のためにハンドルを保存
saveSessionHandle(handle, expiresAt);
});
// 以前のセッションを再開する
const voice = new GeminiLiveVoice({
sessionConfig: {
enableResumption: true,
maxDuration: "2h",
},
});
ツール呼び出し
会話中にモデルが関数を呼び出せるようにします:
import { z } from 'zod';
voice.addTools({
weather: {
description: "天気情報を取得します",
parameters: z.object({
location: z.string(),
}),
execute: async ({ location }) => {
const weather = await getWeather(location);
return weather;
},
},
});
voice.on("toolCall", ({ name, args, id }) => {
console.log(`ツールが呼び出されました: ${name} 引数:`, args);
});
注意事項
- Gemini Live API はリアルタイム通信に WebSocket を使用します
- 音声は入力が 16kHz の PCM16、出力が 24kHz の PCM16 として処理されます
- 他のメソッドを使用する前に、voice インスタンスは
connect()
で接続しておく必要があります - リソースを適切に解放するため、処理完了時には必ず
close()
を呼び出してください - Vertex AI の認証には適切な IAM 権限(
aiplatform.user
ロール)が必要です - セッションの再開機能により、ネットワーク中断から復旧できます
- 本 API はテキストおよび音声でのリアルタイムな対話をサポートします