Voix Google Gemini Live

La classe GeminiLiveVoice fournit des fonctionnalités d'interaction vocale en temps réel au moyen de l'API Gemini Live de Google. Elle prend en charge le streaming audio bidirectionnel, les appels de Tool, la gestion des sessions, ainsi que les méthodes d'authentification standard de l'API Google et de Vertex AI.

Exemple d'utilisation

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()

Configuration

Options du constructeur

apiKey?:

string

Clé d'API Google pour l'authentification auprès de l'API Gemini. Obligatoire sauf avec Vertex AI.

model?:

GeminiVoiceModel

= 'gemini-2.0-flash-exp'

Identifiant du modèle à utiliser pour les interactions vocales en temps réel.

speaker?:

GeminiVoiceName

= 'Puck'

Identifiant de voix par défaut pour la synthèse vocale.

vertexAI?:

boolean

= false

Utilise Vertex AI au lieu de l'API Gemini pour l'authentification.

project?:

string

Identifiant du projet Google Cloud (obligatoire pour Vertex AI).

location?:

string

= 'us-central1'

Région Google Cloud de Vertex AI.

serviceAccountKeyFile?:

string

Chemin du fichier de clé JSON du compte de service pour l'authentification Vertex AI.

serviceAccountEmail?:

string

Adresse e-mail du compte de service pour l'emprunt d'identité (alternative au fichier de clé).

instructions?:

string

Instructions système destinées au modèle.

sessionConfig?:

GeminiSessionConfig

Configuration de la session, notamment les paramètres d'interruption et de contexte.

GeminiSessionConfig

interrupts?:

object

Configuration de la gestion des interruptions.

interrupts.enabled?:

boolean

Active la gestion des interruptions.

interrupts.allowUserInterruption?:

boolean

Autorise l'utilisateur à interrompre les réponses du modèle.

contextCompression?:

boolean

Active la compression automatique du contexte.

debug?:

boolean

= false

Active la journalisation de débogage pour la résolution des problèmes.

Méthodes

connect()

Établit une connexion à l'API Gemini Live. Cette méthode doit être appelée avant d'utiliser les méthodes speak, listen ou send.

requestContext?:

object

Contexte de requête facultatif de la connexion.

returns:

Promise<void>

Promise résolue une fois la connexion établie.

speak()

Convertit le texte en parole et l'envoie au modèle. Accepte en entrée une chaîne ou un stream lisible.

input:

string | NodeJS.ReadableStream

Texte ou stream de texte à convertir en parole.

options?:

GeminiLiveVoiceOptions

Configuration vocale facultative.

GeminiLiveVoiceOptions

speaker?:

GeminiVoiceName

Identifiant de voix à utiliser pour cette requête vocale précise.

languageCode?:

string

Code de langue de la réponse.

responseModalities?:

('AUDIO' | 'TEXT')[]

Modalités de réponse à recevoir du modèle.

Renvoie : Promise<void> (les réponses sont émises via les événements speaker et writing)

sendContext()

Envoie l'historique de la conversation dans la session en direct sans déclencher de réponse du modèle. Utilisez cette méthode pour initialiser les tours précédents, par exemple depuis Mastra Memory, lors d'une nouvelle connexion afin que le modèle dispose du contexte avant que l'utilisateur ne parle.

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[]

Tours de conversation précédents à injecter dans la session. Chaque tour comporte un role ("user" ou "assistant") et une chaîne content. Les modèles récents prennent en charge les deux rôles, par exemple gemini-2.5-flash-native-audio-preview-12-2025. Certains modèles plus anciens acceptent uniquement les tours du rôle user.

options?:

object

Configuration facultative.

object

turnComplete?:

boolean

Indique si le tour doit être marqué comme terminé et déclencher une réponse du modèle.

Renvoie : Promise<void>

listen()

Traite une entrée audio pour la reconnaissance vocale. Accepte un stream lisible de données audio et renvoie le texte transcrit.

audioStream:

NodeJS.ReadableStream

Stream audio à transcrire.

options?:

GeminiLiveVoiceOptions

Configuration facultative de l'écoute.

Renvoie : Promise<string> - Le texte transcrit

send()

Diffuse les données audio en temps réel vers le service Gemini pour les scénarios de streaming audio continu, tels que l'entrée d'un microphone en direct.

audioData:

NodeJS.ReadableStream | Int16Array

Stream ou buffer audio à envoyer au service.

Renvoie : Promise<void>

updateSessionConfig()

Met à jour la configuration de la session à l'exécution. Cette méthode permet de modifier les paramètres vocaux, la sélection de la voix et d'autres configurations d'exécution.

config:

Partial<GeminiLiveVoiceConfig>

Mises à jour de configuration à appliquer.

Renvoie : Promise<void>

addTools()

Ajoute un ensemble de Tools à l'instance Voice. Les Tools permettent au modèle d'effectuer des actions supplémentaires pendant les conversations. Lorsque GeminiLiveVoice est ajouté à un Agent, tous les Tools configurés pour cet Agent sont automatiquement accessibles à l'interface Voice.

tools:

ToolsInput

Configuration des Tools à fournir.

Renvoie : void

addInstructions()

Ajoute ou met à jour les instructions système du modèle.

instructions?:

string

Instructions système à définir.

Renvoie : void

answer()

Déclenche une réponse du modèle. Cette méthode est principalement utilisée en interne lors de l'intégration avec un Agent.

options?:

Record<string, unknown>

Paramètres facultatifs de la requête de réponse.

Renvoie : Promise<void>

getSpeakers()

Renvoie la liste des voix disponibles pour l'API Gemini Live.

Renvoie : Promise<Array<{ voiceId: string; description?: string }>>

disconnect()

Se déconnecte de la session Gemini Live et libère les ressources. Cette méthode asynchrone gère correctement le nettoyage.

Renvoie : Promise<void>

close()

Wrapper synchrone de disconnect(). Appelle disconnect() en interne sans attendre sa résolution.

Renvoie : void

on()

Enregistre un écouteur d'événements Voice.

event:

string

Nom de l'événement à écouter.

callback:

Function

Fonction à appeler lorsque l'événement se produit.

Renvoie : void

off()

Supprime un écouteur d'événements précédemment enregistré.

event:

string

Nom de l'événement à ne plus écouter.

callback:

Function

Fonction de rappel précise à supprimer.

Renvoie : void

Événements

La classe GeminiLiveVoice émet les événements suivants :

speaker:

event

Émis lorsque des données audio sont reçues du modèle. Le callback reçoit un NodeJS.ReadableStream.

speaking:

event

Émis avec les métadonnées audio. Le callback reçoit { audioData?: Int16Array, sampleRate?: number }.

writing:

event

Émis lorsque le texte transcrit est disponible. Le callback reçoit { text: string, role: 'assistant' | 'user' }. Sur les modèles native-audio, la transcription de l'assistant provient du canal output_audio_transcription du serveur plutôt que de modelTurn.parts.text.

thinking:

event

Émis sur les modèles native-audio avec le texte de la chaîne de pensée ou du raisonnement du modèle provenant de modelTurn.parts.text. Le callback reçoit { text: string }. N'est pas déclenché sur les modèles non native-audio, où modelTurn.parts.text constitue la réponse prononcée et est émis comme writing.

session:

event

Émis lors des changements d'état de la session. Le callback reçoit { state: 'connecting' | 'connected' | 'disconnected' | 'disconnecting' | 'updated', config?: object }.

turnComplete:

event

Émis lorsqu’un tour de conversation est terminé. Le callback reçoit { timestamp: number }.

toolCall:

event

Émis lorsque le modèle demande un appel de Tool. Le callback reçoit { name: string, args: object, id: string }.

usage:

event

Émis avec les informations d'utilisation des tokens. Le callback reçoit { inputTokens: number, outputTokens: number, totalTokens: number, modality: string }.

error:

event

Émis lorsqu'une erreur se produit. Le callback reçoit { message: string, code?: string, details?: unknown }.

interrupt:

event

Émis lors d'une interruption lorsque l'utilisateur commence à parler par-dessus une réponse du modèle en cours. Le serveur annule tout audio supplémentaire pour le tour actuel. Le callback reçoit { type: 'user', timestamp: number }.

Comportement native-audio

Les modèles Gemini Live native-audio, c'est-à-dire ceux dont l'identifiant contient native-audio, tels que gemini-2.5-flash-native-audio-preview-12-2025, répartissent la sortie textuelle entre deux canaux :

• La réponse prononcée du modèle est transmise sous forme audio avec une transcription output_audio_transcription, puis exposée comme writing avec role: 'assistant'.
• Le raisonnement interne du modèle est transmis sous la forme modelTurn.parts.text et exposé comme thinking.

Les modèles non native-audio ne possèdent pas de canal output_audio_transcription ; modelTurn.parts.text constitue donc la réponse prononcée elle-même et est émis comme writing. L'événement thinking n'est pas déclenché.

La transcription de l'entrée et de la sortie, ainsi que la détection des interruptions (realtime_input_config.activity_handling = 'START_OF_ACTIVITY_INTERRUPTS'), sont automatiquement activées dans le payload de configuration. Aucune configuration supplémentaire n'est nécessaire.

Modèles disponibles

Les modèles Gemini Live suivants sont disponibles :

• gemini-2.0-flash-exp (par défaut)
• 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

Voix disponibles

Les options de voix suivantes sont disponibles :

• Puck (par défaut) : conversationnelle, amicale
• Charon : profonde, assurée
• Kore : neutre, professionnelle
• Fenrir : chaleureuse, accessible

Méthodes d'authentification

API Gemini (développement)

La méthode la plus simple utilise une clé d'API provenant de Google AI Studio :

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

Vertex AI (production)

Pour une utilisation en production avec l'authentification OAuth et 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',
})

Fonctionnalités avancées

Gestion des sessions

L'API Gemini Live prend en charge la reprise des sessions afin de gérer les interruptions réseau :

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',
  },
})

Appels de Tool

Autorisez le modèle à appeler des fonctions pendant les conversations :

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)
})

Remarques

• L'API Gemini Live utilise WebSockets pour la communication en temps réel
• L'audio est traité en PCM16 à 16 kHz pour l'entrée et en PCM16 à 24 kHz pour la sortie
• L'instance Voice doit être connectée avec connect() avant d'utiliser les autres méthodes
• Appelez toujours close() lorsque vous avez terminé afin de libérer correctement les ressources
• L'authentification Vertex AI nécessite les autorisations IAM appropriées (rôle aiplatform.user)
• La reprise des sessions permet de récupérer après des interruptions réseau
• L'API prend en charge les interactions en temps réel avec du texte et de l'audio