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

# Google

Mastra 的 Google Voice 實作使用 Google Cloud 服務提供文字轉語音（TTS）及語音轉文字（STT）功能。它支援多種語音、語言、進階音訊設定選項，以及適用於企業部署的標準 API key 驗證和 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 key。未提供時會使用 GOOGLE\_API\_KEY 環境變數。vertexAI 為 true 時不會使用。

**speechModel.keyFilename** (`string`): 服務帳戶 JSON key 檔案的路徑。未提供時會使用 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 key。未提供時會使用 GOOGLE\_API\_KEY 環境變數。vertexAI 為 true 時不會使用。

**listeningModel.keyFilename** (`string`): 服務帳戶 JSON key 檔案的路徑。未提供時會使用 GOOGLE\_APPLICATION\_CREDENTIALS 環境變數。

**listeningModel.credentials** (`object`): 包含 client\_email 和 private\_key 屬性的記憶體內服務帳戶憑證物件。

**speaker** (`string`): 文字轉語音預設使用的語音 ID (Default: `'en-US-Casual-K'`)

**vertexAI** (`boolean`): 為企業部署啟用 Vertex AI 模式。使用以項目為基礎的驗證，而非 API key。必須設定 '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 key 的驗證。請在 `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: {},
  },
})
```

> **備註:** 如只設定 `GOOGLE_API_KEY`，`listen({ v2: true })` 會在 `speech.recognizers.recognize` 因 `PERMISSION_DENIED` 而失敗。API key 請求不帶 OAuth 身份，因此向使用者帳戶授予 `roles/speech.client` 並無作用——必須向請求所使用的服務帳戶授予此角色。無論 `vertexAI` 設定為何，這項要求都適用；`speak()` 及 v1 `listen()` 仍可只使用 API key 運作。

**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 key）

使用 Google Cloud API key 驗證。適用於 `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 key）
- 以 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 管理員（完整存取權限）
- `roles/texttospeech.editor` - Text-to-Speech 編輯者（建立及管理）
- `roles/texttospeech.viewer` - Text-to-Speech 檢視者（唯讀）

Speech-to-Text：

- `roles/speech.client` - Speech-to-Text 用戶端

請向請求所使用憑證對應的服務帳戶（透過 `keyFilename`、`credentials` 或 `GOOGLE_APPLICATION_CREDENTIALS`）授予 `roles/speech.client`。此角色是 `listen({ v2: true })` 的特定要求，並非只在 Vertex AI 模式下才需要。向使用者帳戶授予此角色不會影響只使用 API key 的請求，因為這類請求不帶可供授權的身份。

#### OAuth 範圍

同步 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 key（標準模式）或服務帳戶憑證（Vertex AI 模式）。

2. **環境變數**：

   - `GOOGLE_API_KEY` - 標準模式的 API key
   - `GOOGLE_CLOUD_PROJECT` - Vertex AI 模式的項目 ID
   - `GOOGLE_CLOUD_LOCATION` - Vertex AI 模式的位置（預設為 'us-central1'）
   - `GOOGLE_APPLICATION_CREDENTIALS` - 服務帳戶 key 檔案的路徑

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`；只設定 `GOOGLE_API_KEY` 時，會因 `PERMISSION_DENIED` 而失敗。`speak()` 及 v1 `listen()` 可只使用 API key 運作。

8. 可使用 `getSpeakers()` 方法按語言代碼篩選可用語音。

9. Vertex AI 模式提供企業功能，包括 IAM 控制、稽核記錄及項目層級帳單。