Google

Mastra 中的 Google Voice 实现使用 Google Cloud 服务提供文本转语音 (TTS) 和语音转文本 (STT) 功能。它支持多种声音和语言、高级音频配置选项，以及标准 API 密钥身份验证和面向企业部署的 Vertex AI 模式。

使用示例
使用示例的直接链接

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

构造函数参数
构造函数参数的直接链接

speechModel?:

GoogleModelConfig

= { apiKey: process.env.GOOGLE_API_KEY }

文本转语音功能的配置

GoogleModelConfig

apiKey?:

string

Google Cloud API 密钥。未提供时使用 GOOGLE_API_KEY 环境变量。vertexAI 为 true 时不使用。

keyFilename?:

string

服务账号 JSON 密钥文件的路径。未提供时使用 GOOGLE_APPLICATION_CREDENTIALS 环境变量。

credentials?:

object

包含 client_email 和 private_key 属性的内存中服务账号凭据对象。

listeningModel?:

GoogleModelConfig

= { apiKey: process.env.GOOGLE_API_KEY }

语音转文本功能的配置

GoogleModelConfig

apiKey?:

string

Google Cloud API 密钥。未提供时使用 GOOGLE_API_KEY 环境变量。vertexAI 为 true 时不使用。

keyFilename?:

string

服务账号 JSON 密钥文件的路径。未提供时使用 GOOGLE_APPLICATION_CREDENTIALS 环境变量。

credentials?:

object

包含 client_email 和 private_key 属性的内存中服务账号凭据对象。

speaker?:

string

= 'en-US-Casual-K'

文本转语音使用的默认声音 ID

vertexAI?:

boolean

= false

为企业部署启用 Vertex AI 模式。使用基于项目的身份验证，而非 API 密钥。必须设置 'project'。

project?:

string

Google Cloud 项目 ID（vertexAI 为 true 时必需）。未提供时使用 GOOGLE_CLOUD_PROJECT 环境变量。

location?:

string

= 'us-central1'

Vertex AI 的 Google Cloud 区域。未提供时使用 GOOGLE_CLOUD_LOCATION 环境变量。

方法
方法的直接链接

`speak()`
speak的直接链接

使用 Google Cloud Text-to-Speech 服务将文本转换为语音。

input:

string | NodeJS.ReadableStream

要转换为语音的文本。如果提供流，则先将其转换为文本。

options?:

object

语音合成选项

GoogleSpeakOptions

speaker?:

string

此次请求使用的声音 ID。

languageCode?:

string

声音的语言代码（例如 'en-US'）。默认为从 speaker ID 推导出的语言代码，无法推导时为 'en-US'。

input?:

ISynthesizeSpeechRequest['input']

传递给 Google Cloud TTS API 的富输入对象。支持 ssml、markup、prompt（Gemini-TTS 风格控制）、customPronunciations 和 multiSpeakerMarkup。如果对象中未提供 text、ssml、markup 或 multiSpeakerMarkup，则会自动将位置参数 input 用作 text 字段。

voice?:

ISynthesizeSpeechRequest['voice']

与默认配置（name 和 languageCode）合并的声音配置。支持 modelName（例如 'gemini-2.5-flash-preview-tts'）和 multiSpeakerVoiceConfig。

audioConfig?:

ISynthesizeSpeechRequest['audioConfig']

Google Cloud Text-to-Speech API 提供的音频配置选项。

返回：Promise<NodeJS.ReadableStream>

`listen()`
listen的直接链接

使用 Google Cloud Speech-to-Text 服务将语音转换为文本。支持 v1（默认）和 v2 API。v2 API 通过自动解码新增对 AAC-in-MP4 音频（iOS Safari）的支持。

v1（默认）
v1（默认）的直接链接

audioStream:

NodeJS.ReadableStream

要转录的音频流

options?:

GoogleListenOptionsV1

v1 识别选项

GoogleListenOptionsV1

config?:

IRecognitionConfig

Google Cloud Speech-to-Text API 提供的 v1 识别配置

v2
v2的直接链接

传入 v2: true 即可使用 Cloud Speech-to-Text v2 API，该 API 支持 AAC-in-MP4（iOS Safari）等其他音频格式。

v2 recognize 调用通过 IAM 授权，不接受仅使用 API 密钥的身份验证。请在 listeningModel 上配置服务账号凭据（或设置 GOOGLE_APPLICATION_CREDENTIALS），并设置 GOOGLE_CLOUD_PROJECT，以便解析 recognizer 路径；即使未启用 vertexAI，也必须如此。

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: {},
  },
})

备注

listen({ v2: true }) 会因 PERMISSION_DENIED 而无法调用 speech.recognizers.recognize；只设置 GOOGLE_API_KEY 时就会出现此问题。API 密钥请求不携带 OAuth 身份，因此向用户账号授予 roles/speech.client 无济于事——必须将该角色授予请求中使用的服务账号。无论 vertexAI 如何设置，都是如此；speak() 和 v1 listen() 仍可仅凭 API 密钥运行。

audioStream:

NodeJS.ReadableStream

要转录的音频流

options:

GoogleListenOptionsV2

v2 识别选项

GoogleListenOptionsV2

v2:

true

启用 v2 API 路径

config?:

v2.IRecognitionConfig

v2 识别配置。默认使用 languageCodes: ['en-US'] 和 model: 'long' 进行自动解码。设置 autoDecodingConfig: {} 可自动检测音频格式，也可使用 explicitDecodingConfig 指定 MP4_AAC、M4A_AAC 或 MOV_AAC 等编码。

recognizer?:

string

v2 recognizer 资源路径。默认为 projects/{project}/locations/global/recognizers/_，其中 {project} 从构造函数的 project 选项、GOOGLE_CLOUD_PROJECT 或客户端的默认项目中解析。

返回：Promise<string>

`getSpeakers()`
getspeakers的直接链接

返回可用声音选项的数组，其中每个节点包含：

voiceId:

string

声音的唯一标识符

languageCodes:

string[]

此声音支持的语言代码列表

`isUsingVertexAI()`
isusingvertexai的直接链接

检查是否已启用 Vertex AI 模式。

返回：boolean —— 使用 Vertex AI 时为 true，否则为 false

`getProject()`
getproject的直接链接

获取配置的 Google Cloud 项目 ID。

返回：string | undefined —— 项目 ID；如果未设置，则为 undefined

`getLocation()`
getlocation的直接链接

获取配置的 Google Cloud 位置/区域。

返回：string —— 位置（默认值：'us-central1'）

身份验证
身份验证的直接链接

Google Voice Provider 支持两种身份验证方法：

标准模式（API 密钥）
标准模式（API 密钥）的直接链接

使用 Google Cloud API 密钥进行身份验证。适用于 speak() 和 v1 listen()，但不适用于 listen({ v2: true })；后者通过 IAM 授权，需要服务账号凭据（参见 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',
})

Vertex AI 模式（服务账号）
Vertex AI 模式（服务账号）的直接链接

通过服务账号使用基于 Google Cloud 项目的身份验证。建议用于生产和企业部署。

优势：

安全性更高（代码中不含 API 密钥）
基于 IAM 的访问控制
项目级结算与配额
审计日志
企业功能

配置选项：

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

所需权限
所需权限的直接链接

IAM 角色
IAM 角色的直接链接

对于 Text-to-Speech：

roles/texttospeech.admin - Text-to-Speech Admin（完全访问权限）
roles/texttospeech.editor - Text-to-Speech Editor（创建和管理）
roles/texttospeech.viewer - Text-to-Speech Viewer（只读）

对于 Speech-to-Text：

roles/speech.client - Speech-to-Text 客户端

请将 roles/speech.client 授予请求所使用凭据对应的服务账号（通过 keyFilename、credentials 或 GOOGLE_APPLICATION_CREDENTIALS 指定）。此角色是 listen({ v2: true }) 特别要求的，并非只在 Vertex AI 模式下需要。仅使用 API 密钥的请求不携带可供授权的身份，因此将该角色授予用户账号不会生效。

OAuth scope
OAuth scope的直接链接

对于同步 Text-to-Speech 合成：

https://www.googleapis.com/auth/cloud-platform - 对 Google Cloud Platform 服务的完全访问权限

对于长音频 Text-to-Speech 操作：

locations.longAudioSynthesize - 创建长音频合成操作
operations.get - 获取操作状态
operations.list - 列出操作

重要说明
重要说明的直接链接

身份验证：需要 Google Cloud API 密钥（标准模式）或服务账号凭据（Vertex AI 模式）。
环境变量：
- GOOGLE_API_KEY - 标准模式的 API 密钥
- GOOGLE_CLOUD_PROJECT - Vertex AI 模式的项目 ID
- GOOGLE_CLOUD_LOCATION - Vertex AI 模式的位置（默认为 'us-central1'）
- GOOGLE_APPLICATION_CREDENTIALS - 服务账号密钥文件的路径
默认声音设置为 'en-US-Casual-K'。
文本转语音和语音转文本服务均使用 LINEAR16 作为默认音频编码。
speak() 方法通过 Google Cloud Text-to-Speech API 支持高级音频配置。
listen() 方法通过 Google Cloud Speech-to-Text API 支持多种识别配置。
listen({ v2: true }) 需要服务账号凭据和 GOOGLE_CLOUD_PROJECT；如果只设置 API 密钥，则会因 PERMISSION_DENIED 而失败，此处的 API 密钥是 GOOGLE_API_KEY。speak() 和 v1 listen() 可仅凭 API 密钥运行。
可使用 getSpeakers() 方法按语言代码筛选可用声音。
Vertex AI 模式提供 IAM 控制、审计日志和项目级结算等企业功能。

使用示例使用示例的直接链接

构造函数参数构造函数参数的直接链接

speechModel?:

apiKey?:

keyFilename?:

credentials?:

listeningModel?:

apiKey?:

keyFilename?:

credentials?:

speaker?:

vertexAI?:

project?:

location?:

方法方法的直接链接

speak()speak的直接链接

input:

options?:

speaker?:

languageCode?:

input?:

voice?:

audioConfig?:

listen()listen的直接链接

v1（默认）v1（默认）的直接链接

audioStream:

options?:

config?:

v2v2的直接链接

audioStream:

options:

v2:

config?:

recognizer?:

getSpeakers()getspeakers的直接链接

voiceId:

languageCodes:

isUsingVertexAI()isusingvertexai的直接链接

getProject()getproject的直接链接

getLocation()getlocation的直接链接

身份验证身份验证的直接链接

标准模式（API 密钥）标准模式（API 密钥）的直接链接

Vertex AI 模式（服务账号）Vertex AI 模式（服务账号）的直接链接

所需权限所需权限的直接链接

IAM 角色IAM 角色的直接链接

OAuth scopeOAuth scope的直接链接

重要说明重要说明的直接链接

使用示例
使用示例的直接链接

构造函数参数
构造函数参数的直接链接

方法
方法的直接链接

`speak()`
speak的直接链接

`listen()`
listen的直接链接

v1（默认）
v1（默认）的直接链接

v2
v2的直接链接

`getSpeakers()`
getspeakers的直接链接

`isUsingVertexAI()`
isusingvertexai的直接链接

`getProject()`
getproject的直接链接

`getLocation()`
getlocation的直接链接

身份验证
身份验证的直接链接

标准模式（API 密钥）
标准模式（API 密钥）的直接链接

Vertex AI 模式（服务账号）
Vertex AI 模式（服务账号）的直接链接

所需权限
所需权限的直接链接

IAM 角色
IAM 角色的直接链接

OAuth scope
OAuth scope的直接链接

重要说明
重要说明的直接链接