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

# Google

L’implémentation Google Voice de Mastra propose des fonctionnalités de synthèse vocale (TTS) et de reconnaissance vocale (STT) à l’aide des services Google Cloud. Elle prend en charge plusieurs voix et langues, des options avancées de configuration audio, ainsi que l’authentification standard par clé API et le mode Vertex AI pour les déploiements en entreprise.

## Exemple d’utilisation

```typescript
import { GoogleVoice } from '@mastra/voice-google'

// Initialize with default configuration (uses GOOGLE_API_KEY environment variable)
const voice = new GoogleVoice()

// Text-to-Speech (plain text)
const audioStream = await voice.speak('Hello, world!', {
  languageCode: 'en-US',
  audioConfig: {
    audioEncoding: 'LINEAR16',
  },
})

// Text-to-Speech with SSML
const ssmlStream = await voice.speak('ignored', {
  input: {
    ssml: '<speak>Take <say-as interpret-as="unit">5 mg</say-as> daily.</speak>',
  },
})

// Text-to-Speech with Gemini-TTS model
const geminiStream = await voice.speak('Hello from Gemini TTS!', {
  voice: { name: 'Kore', modelName: 'gemini-2.5-flash-preview-tts' },
  input: { prompt: 'Warm, calm tone.' },
})

// Speech-to-Text
const transcript = await voice.listen(audioStream, {
  config: {
    encoding: 'LINEAR16',
    languageCode: 'en-US',
  },
})

// Get available voices for a specific language
const voices = await voice.getSpeakers({ languageCode: 'en-US' })
```

## Paramètres du constructeur

**speechModel** (`GoogleModelConfig`): Configuration de la fonctionnalité de synthèse vocale. (Default: `{ apiKey: process.env.GOOGLE_API_KEY }`)

**speechModel.apiKey** (`string`): Clé API Google Cloud. Utilise la variable d’environnement GOOGLE\_API\_KEY par défaut. N’est pas utilisée lorsque vertexAI est défini sur true.

**speechModel.keyFilename** (`string`): Chemin vers le fichier de clé JSON du compte de service. Utilise la variable d’environnement GOOGLE\_APPLICATION\_CREDENTIALS par défaut.

**speechModel.credentials** (`object`): Objet d’identifiants de compte de service en mémoire, avec les propriétés client\_email et private\_key.

**listeningModel** (`GoogleModelConfig`): Configuration de la fonctionnalité de reconnaissance vocale. (Default: `{ apiKey: process.env.GOOGLE_API_KEY }`)

**listeningModel.apiKey** (`string`): Clé API Google Cloud. Utilise la variable d’environnement GOOGLE\_API\_KEY par défaut. N’est pas utilisée lorsque vertexAI est défini sur true.

**listeningModel.keyFilename** (`string`): Chemin vers le fichier de clé JSON du compte de service. Utilise la variable d’environnement GOOGLE\_APPLICATION\_CREDENTIALS par défaut.

**listeningModel.credentials** (`object`): Objet d’identifiants de compte de service en mémoire, avec les propriétés client\_email et private\_key.

**speaker** (`string`): ID de voix à utiliser par défaut pour la synthèse vocale. (Default: `'en-US-Casual-K'`)

**vertexAI** (`boolean`): Active le mode Vertex AI pour les déploiements en entreprise. Utilise une authentification basée sur un projet plutôt que des clés API. Nécessite de définir 'project'. (Default: `false`)

**project** (`string`): ID du projet Google Cloud (requis lorsque vertexAI est défini sur true). Utilise la variable d’environnement GOOGLE\_CLOUD\_PROJECT par défaut.

**location** (`string`): Région Google Cloud pour Vertex AI. Utilise la variable d’environnement GOOGLE\_CLOUD\_LOCATION par défaut. (Default: `'us-central1'`)

## Méthodes

### `speak()`

Convertit du texte en parole à l’aide du service Google Cloud Text-to-Speech.

**input** (`string | NodeJS.ReadableStream`): Texte à convertir en parole. Si un flux est fourni, il est d’abord converti en texte.

**options** (`object`): Options de synthèse vocale.

**options.speaker** (`string`): ID de la voix à utiliser pour cette requête.

**options.languageCode** (`string`): Code de langue de la voix (par exemple, 'en-US'). Utilise par défaut le code de langue dérivé de l’ID du locuteur, ou 'en-US'.

**options.input** (`ISynthesizeSpeechRequest['input']`): Objet d’entrée enrichi transmis à l’API Google Cloud TTS. Prend en charge ssml, markup, prompt (pilotage de type Gemini-TTS), customPronunciations et multiSpeakerMarkup. Lorsqu’il est fourni sans text, ssml, markup ni multiSpeakerMarkup, l’argument input positionnel est automatiquement utilisé comme champ text.

**options.voice** (`ISynthesizeSpeechRequest['voice']`): Configuration de la voix fusionnée avec les valeurs par défaut (name et languageCode). Prend en charge modelName (par exemple, 'gemini-2.5-flash-preview-tts') et multiSpeakerVoiceConfig.

**options.audioConfig** (`ISynthesizeSpeechRequest['audioConfig']`): Options de configuration audio de l’API Google Cloud Text-to-Speech.

Renvoie : `Promise<NodeJS.ReadableStream>`

### `listen()`

Convertit la parole en texte à l’aide du service Google Cloud Speech-to-Text. Prend en charge les API v1 (par défaut) et v2. L’API v2 ajoute la prise en charge de l’audio AAC dans MP4 (Safari sur iOS) grâce au décodage automatique.

#### v1 (par défaut)

**audioStream** (`NodeJS.ReadableStream`): Flux audio à transcrire.

**options** (`GoogleListenOptionsV1`): Options de reconnaissance v1.

**options.config** (`IRecognitionConfig`): Configuration de reconnaissance v1 de l’API Google Cloud Speech-to-Text.

#### v2

Transmettez `v2: true` pour utiliser l’API Cloud Speech-to-Text v2, qui prend en charge des formats audio supplémentaires tels qu’AAC dans MP4 (Safari sur iOS).

L’appel `recognize` de v2 est autorisé par IAM et n’accepte pas une authentification uniquement par clé API. Configurez des identifiants de compte de service dans `listeningModel` (ou définissez `GOOGLE_APPLICATION_CREDENTIALS`) et définissez `GOOGLE_CLOUD_PROJECT` afin que le chemin du reconnaisseur puisse être résolu, même lorsque `vertexAI` n’est pas activé.

```typescript
import { GoogleVoice } from '@mastra/voice-google'

// v2 listen() requires service account credentials, not just GOOGLE_API_KEY.
// Set GOOGLE_CLOUD_PROJECT so the recognizer path can be resolved.
const voice = new GoogleVoice({
  listeningModel: { keyFilename: process.env.GOOGLE_APPLICATION_CREDENTIALS },
})

const transcript = await voice.listen(iosSafariAacStream, {
  v2: true,
  config: {
    autoDecodingConfig: {},
  },
})
```

> **Remarque:** `listen({ v2: true })` échoue avec `PERMISSION_DENIED` sur `speech.recognizers.recognize` lorsque seule la variable `GOOGLE_API_KEY` est définie. Une requête par clé API ne porte aucune identité OAuth ; accorder `roles/speech.client` à un compte utilisateur ne suffit donc pas — le rôle doit être accordé au compte de service présenté dans la requête. Cela s’applique quel que soit le réglage de `vertexAI` ; `speak()` et `listen()` v1 fonctionnent toujours avec une clé API seule.

**audioStream** (`NodeJS.ReadableStream`): Flux audio à transcrire.

**options** (`GoogleListenOptionsV2`): Options de reconnaissance v2.

**options.v2** (`true`): Active le chemin d’API v2.

**options.config** (`v2.IRecognitionConfig`): Configuration de reconnaissance v2. Utilise par défaut le décodage automatique avec languageCodes: \['en-US'] et model: 'long'. Définissez autoDecodingConfig: {} pour détecter automatiquement le format audio, ou utilisez explicitDecodingConfig pour spécifier un encodage tel que MP4\_AAC, M4A\_AAC ou MOV\_AAC.

**options.recognizer** (`string`): Chemin de ressource du reconnaisseur v2. Utilise par défaut projects/{project}/locations/global/recognizers/\_, où {project} est résolu à partir de l’option project du constructeur, de GOOGLE\_CLOUD\_PROJECT ou du projet par défaut du client.

Renvoie : `Promise<string>`

### `getSpeakers()`

Renvoie un tableau d’options de voix disponibles, dont chaque élément contient :

**voiceId** (`string`): Identifiant unique de la voix.

**languageCodes** (`string[]`): Liste des codes de langue pris en charge par cette voix.

### `isUsingVertexAI()`

Vérifie si le mode Vertex AI est activé.

Renvoie : `boolean` — `true` si Vertex AI est utilisé, `false` sinon.

### `getProject()`

Obtient l’ID du projet Google Cloud configuré.

Renvoie : `string | undefined` — l’ID du projet ou `undefined` s’il n’est pas défini.

### `getLocation()`

Obtient l’emplacement ou la région Google Cloud configuré.

Renvoie : `string` — l’emplacement (par défaut : `'us-central1'`).

## Authentification

Le fournisseur Google Voice prend en charge deux méthodes d’authentification :

### Mode standard (clé API)

Utilise une clé API Google Cloud pour l’authentification. Couvre `speak()` et `listen()` v1. Ne couvre pas `listen({ v2: true })`, qui est autorisé par IAM et nécessite des identifiants de compte de service (voir [v2](#v2)).

```typescript
// Using environment variable (GOOGLE_API_KEY)
const voice = new GoogleVoice()

// Using explicit API key
const voice = new GoogleVoice({
  speechModel: { apiKey: 'your-api-key' },
  listeningModel: { apiKey: 'your-api-key' },
  speaker: 'en-US-Casual-K',
})
```

### Mode Vertex AI (compte de service)

Utilise l’authentification Google Cloud basée sur un projet avec des comptes de service. Recommandé pour les déploiements de production et en entreprise.

**Avantages :**

- Sécurité renforcée (aucune clé API dans le code)
- Contrôle d’accès basé sur IAM
- Facturation et quotas à l’échelle du projet
- Journalisation d’audit
- Fonctionnalités d’entreprise

**Options de configuration :**

```typescript
// Using Application Default Credentials (ADC)
// Set GOOGLE_APPLICATION_CREDENTIALS and GOOGLE_CLOUD_PROJECT env vars
const voice = new GoogleVoice({
  vertexAI: true,
  project: 'your-gcp-project',
  location: 'us-central1', // Optional, defaults to 'us-central1'
})

// Using service account key file
const voice = new GoogleVoice({
  vertexAI: true,
  project: 'your-gcp-project',
  speechModel: {
    keyFilename: '/path/to/service-account.json',
  },
  listeningModel: {
    keyFilename: '/path/to/service-account.json',
  },
})

// Using in-memory credentials
const voice = new GoogleVoice({
  vertexAI: true,
  project: 'your-gcp-project',
  speechModel: {
    credentials: {
      client_email: 'service-account@project.iam.gserviceaccount.com',
      private_key: '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----',
    },
  },
})
```

#### Autorisations requises

#### Rôles IAM

Pour Text-to-Speech :

- `roles/texttospeech.admin` — Administrateur Text-to-Speech (accès complet)
- `roles/texttospeech.editor` — Éditeur Text-to-Speech (créer et gérer)
- `roles/texttospeech.viewer` — Lecteur Text-to-Speech (lecture seule)

Pour Speech-to-Text :

- `roles/speech.client` — Client Speech-to-Text

Accordez `roles/speech.client` au compte de service dont la requête présente les identifiants (via `keyFilename`, `credentials` ou `GOOGLE_APPLICATION_CREDENTIALS`). Ce rôle est requis spécifiquement pour `listen({ v2: true })`, et pas seulement pour le mode Vertex AI. L’accorder à un compte utilisateur n’a aucun effet sur les requêtes limitées à une clé API, qui ne portent aucune identité à autoriser.

#### Champs d’application OAuth

Pour la synthèse Text-to-Speech synchrone :

- `https://www.googleapis.com/auth/cloud-platform` — Accès complet aux services Google Cloud Platform

Pour les opérations Text-to-Speech sur de l’audio long :

- `locations.longAudioSynthesize` — Créer des opérations de synthèse d’audio long
- `operations.get` — Obtenir l’état d’une opération
- `operations.list` — Lister les opérations

## Remarques importantes

1. **Authentification** : une clé API Google Cloud (mode standard) ou des identifiants de compte de service (mode Vertex AI) sont requis.

2. **Variables d’environnement :**

   - `GOOGLE_API_KEY` — Clé API pour le mode standard
   - `GOOGLE_CLOUD_PROJECT` — ID du projet pour le mode Vertex AI
   - `GOOGLE_CLOUD_LOCATION` — Emplacement pour le mode Vertex AI (par défaut : 'us-central1')
   - `GOOGLE_APPLICATION_CREDENTIALS` — Chemin vers le fichier de clé du compte de service

3. La voix par défaut est `'en-US-Casual-K'`.

4. Les services de synthèse et de reconnaissance vocales utilisent tous deux LINEAR16 comme encodage audio par défaut.

5. La méthode `speak()` prend en charge une configuration audio avancée par l’intermédiaire de l’API Google Cloud Text-to-Speech.

6. La méthode `listen()` prend en charge diverses configurations de reconnaissance par l’intermédiaire de l’API Google Cloud Speech-to-Text.

7. `listen({ v2: true })` nécessite des identifiants de compte de service et `GOOGLE_CLOUD_PROJECT` ; la méthode échoue avec `PERMISSION_DENIED` lorsque seule la variable `GOOGLE_API_KEY` est définie. `speak()` et `listen()` v1 fonctionnent avec une clé API seule.

8. Les voix disponibles peuvent être filtrées par code de langue avec la méthode `getSpeakers()`.

9. Le mode Vertex AI fournit des fonctionnalités d’entreprise, notamment le contrôle IAM, les journaux d’audit et la facturation à l’échelle du projet.