> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/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'）。預設使用從語音 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`，讓系統可解析辨識器路徑；即使未啟用 `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 金鑰請求不帶 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 辨識器資源路徑。預設為 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 管理員（完整存取權）
- `roles/texttospeech.editor` — Text-to-Speech 編輯者（建立及管理）
- `roles/texttospeech.viewer` — Text-to-Speech 檢視者（唯讀）

Speech-to-Text：

- `roles/speech.client` — Speech-to-Text 使用者端

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

#### 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 金鑰（標準模式）或服務帳戶認證資訊（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`；只設定 `GOOGLE_API_KEY` 時會因 `PERMISSION_DENIED` 而失敗。`speak()` 與 v1 `listen()` 可只使用 API 金鑰執行。

8. 可使用 `getSpeakers()` 方法依語言程式碼篩選可用語音。

9. Vertex AI 模式提供 IAM 控制、稽核記錄與專案層級計費等企業功能。