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

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

= { apiKey: process.env.GOOGLE_API_KEY }

Configuration de la fonctionnalité de synthèse vocale.

GoogleModelConfig

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.

keyFilename?:

string

Chemin vers le fichier de clé JSON du compte de service. Utilise la variable d’environnement GOOGLE_APPLICATION_CREDENTIALS par défaut.

credentials?:

object

Objet d’identifiants de compte de service en mémoire, avec les propriétés client_email et private_key.

listeningModel?:

GoogleModelConfig

= { apiKey: process.env.GOOGLE_API_KEY }

Configuration de la fonctionnalité de reconnaissance vocale.

GoogleModelConfig

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.

keyFilename?:

string

Chemin vers le fichier de clé JSON du compte de service. Utilise la variable d’environnement GOOGLE_APPLICATION_CREDENTIALS par défaut.

credentials?:

object

Objet d’identifiants de compte de service en mémoire, avec les propriétés client_email et private_key.

speaker?:

string

= 'en-US-Casual-K'

ID de voix à utiliser par défaut pour la synthèse vocale.

vertexAI?:

boolean

= false

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

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

= 'us-central1'

Région Google Cloud pour Vertex AI. Utilise la variable d’environnement GOOGLE_CLOUD_LOCATION par défaut.

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.

GoogleSpeakOptions

speaker?:

string

ID de la voix à utiliser pour cette requête.

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

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.

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.

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.

GoogleListenOptionsV1

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

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.

GoogleListenOptionsV2

v2:

true

Active le chemin d’API v2.

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.

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

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

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