> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# 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

```typescript
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`): Identifiant du modèle à utiliser pour les interactions vocales en temps réel. (Default: `'gemini-2.0-flash-exp'`)

**speaker** (`GeminiVoiceName`): Identifiant de voix par défaut pour la synthèse vocale. (Default: `'Puck'`)

**vertexAI** (`boolean`): Utilise Vertex AI au lieu de l'API Gemini pour l'authentification. (Default: `false`)

**project** (`string`): Identifiant du projet Google Cloud (obligatoire pour Vertex AI).

**location** (`string`): Région Google Cloud de Vertex AI. (Default: `'us-central1'`)

**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.

**sessionConfig.interrupts** (`object`): Configuration de la gestion des interruptions.

**sessionConfig.interrupts.enabled** (`boolean`): Active la gestion des interruptions.

**sessionConfig.interrupts.allowUserInterruption** (`boolean`): Autorise l'utilisateur à interrompre les réponses du modèle.

**sessionConfig.contextCompression** (`boolean`): Active la compression automatique du contexte.

**debug** (`boolean`): Active la journalisation de débogage pour la résolution des problèmes. (Default: `false`)

## 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.

**options.speaker** (`GeminiVoiceName`): Identifiant de voix à utiliser pour cette requête vocale précise.

**options.languageCode** (`string`): Code de langue de la réponse.

**options.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.

```typescript
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.

**options.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](https://makersuite.google.com/app/apikey) :

```typescript
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 :

```typescript
// 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 :

```typescript
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 :

```typescript
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