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

# Google

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

## 使用示例

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

## 构造函数参数

**speechModel** (`GoogleModelConfig`): 文本转语音功能的配置 (Default: `{ apiKey: process.env.GOOGLE_API_KEY }`)

**speechModel.apiKey** (`string`): Google Cloud API 密钥。未提供时使用 GOOGLE\_API\_KEY 环境变量。vertexAI 为 true 时不使用。

**speechModel.keyFilename** (`string`): 服务账号 JSON 密钥文件的路径。未提供时使用 GOOGLE\_APPLICATION\_CREDENTIALS 环境变量。

**speechModel.credentials** (`object`): 包含 client\_email 和 private\_key 属性的内存中服务账号凭据对象。

**listeningModel** (`GoogleModelConfig`): 语音转文本功能的配置 (Default: `{ apiKey: process.env.GOOGLE_API_KEY }`)

**listeningModel.apiKey** (`string`): Google Cloud API 密钥。未提供时使用 GOOGLE\_API\_KEY 环境变量。vertexAI 为 true 时不使用。

**listeningModel.keyFilename** (`string`): 服务账号 JSON 密钥文件的路径。未提供时使用 GOOGLE\_APPLICATION\_CREDENTIALS 环境变量。

**listeningModel.credentials** (`object`): 包含 client\_email 和 private\_key 属性的内存中服务账号凭据对象。

**speaker** (`string`): 文本转语音使用的默认声音 ID (Default: `'en-US-Casual-K'`)

**vertexAI** (`boolean`): 为企业部署启用 Vertex AI 模式。使用基于项目的身份验证，而非 API 密钥。必须设置 'project'。 (Default: `false`)

**project** (`string`): Google Cloud 项目 ID（vertexAI 为 true 时必需）。未提供时使用 GOOGLE\_CLOUD\_PROJECT 环境变量。

**location** (`string`): Vertex AI 的 Google Cloud 区域。未提供时使用 GOOGLE\_CLOUD\_LOCATION 环境变量。 (Default: `'us-central1'`)

## 方法

### `speak()`

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

**input** (`string | NodeJS.ReadableStream`): 要转换为语音的文本。如果提供流，则先将其转换为文本。

**options** (`object`): 语音合成选项

**options.speaker** (`string`): 此次请求使用的声音 ID。

**options.languageCode** (`string`): 声音的语言代码（例如 'en-US'）。默认为从 speaker ID 推导出的语言代码，无法推导时为 'en-US'。

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

**options.voice** (`ISynthesizeSpeechRequest['voice']`): 与默认配置（name 和 languageCode）合并的声音配置。支持 modelName（例如 'gemini-2.5-flash-preview-tts'）和 multiSpeakerVoiceConfig。

**options.audioConfig** (`ISynthesizeSpeechRequest['audioConfig']`): Google Cloud Text-to-Speech API 提供的音频配置选项。

返回：`Promise<NodeJS.ReadableStream>`

### `listen()`

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

#### v1（默认）

**audioStream** (`NodeJS.ReadableStream`): 要转录的音频流

**options** (`GoogleListenOptionsV1`): v1 识别选项

**options.config** (`IRecognitionConfig`): Google Cloud Speech-to-Text API 提供的 v1 识别配置

#### 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`，也必须如此。

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

> **备注:** `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 识别选项

**options.v2** (`true`): 启用 v2 API 路径

**options.config** (`v2.IRecognitionConfig`): v2 识别配置。默认使用 languageCodes: \['en-US'] 和 model: 'long' 进行自动解码。设置 autoDecodingConfig: {} 可自动检测音频格式，也可使用 explicitDecodingConfig 指定 MP4\_AAC、M4A\_AAC 或 MOV\_AAC 等编码。

**options.recognizer** (`string`): v2 recognizer 资源路径。默认为 projects/{project}/locations/global/recognizers/\_，其中 {project} 从构造函数的 project 选项、GOOGLE\_CLOUD\_PROJECT 或客户端的默认项目中解析。

返回：`Promise<string>`

### `getSpeakers()`

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

**voiceId** (`string`): 声音的唯一标识符

**languageCodes** (`string[]`): 此声音支持的语言代码列表

### `isUsingVertexAI()`

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

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

### `getProject()`

获取配置的 Google Cloud 项目 ID。

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

### `getLocation()`

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

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

## 身份验证

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

### 标准模式（API 密钥）

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

### Vertex AI 模式（服务账号）

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

**优势：**

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

**配置选项：**

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

#### 所需权限

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

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

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

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

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

## 重要说明

1. **身份验证**：需要 Google Cloud API 密钥（标准模式）或服务账号凭据（Vertex AI 模式）。

2. **环境变量**：

   - `GOOGLE_API_KEY` - 标准模式的 API 密钥
   - `GOOGLE_CLOUD_PROJECT` - Vertex AI 模式的项目 ID
   - `GOOGLE_CLOUD_LOCATION` - Vertex AI 模式的位置（默认为 'us-central1'）
   - `GOOGLE_APPLICATION_CREDENTIALS` - 服务账号密钥文件的路径

3. 默认声音设置为 `'en-US-Casual-K'`。

4. 文本转语音和语音转文本服务均使用 LINEAR16 作为默认音频编码。

5. `speak()` 方法通过 Google Cloud Text-to-Speech API 支持高级音频配置。

6. `listen()` 方法通过 Google Cloud Speech-to-Text API 支持多种识别配置。

7. `listen({ v2: true })` 需要服务账号凭据和 `GOOGLE_CLOUD_PROJECT`；如果只设置 API 密钥，则会因 `PERMISSION_DENIED` 而失败，此处的 API 密钥是 `GOOGLE_API_KEY`。`speak()` 和 v1 `listen()` 可仅凭 API 密钥运行。

8. 可使用 `getSpeakers()` 方法按语言代码筛选可用声音。

9. Vertex AI 模式提供 IAM 控制、审计日志和项目级结算等企业功能。