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

# Google

Mastra の Google Voice 実装は、Google Cloud サービスを使用した Text-to-Speech（TTS）および Speech-to-Text（STT）機能を提供します。複数の Voice と言語、高度な音声設定オプションに加え、標準の 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`): Text-to-Speech 機能の設定 (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`): Speech-to-Text 機能の設定 (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`): Text-to-Speech に使用するデフォルトの Voice 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`): このリクエストに使用する Voice ID。

**options.languageCode** (`string`): Voice の言語コード（例：'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）に統合される Voice 設定。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

AAC-in-MP4（iOS Safari）などの追加音声形式をサポートする Cloud Speech-to-Text v2 API を使用するには、`v2: true` を渡します。

v2 の `recognize` 呼び出しは IAM で認可され、API キーだけの認証は受け付けません。`vertexAI` を有効にしていない場合でも、`listeningModel` にサービスアカウント認証情報を設定（または `GOOGLE_APPLICATION_CREDENTIALS` を設定）し、Recognizer のパスを解決できるように `GOOGLE_CLOUD_PROJECT` を設定してください。

```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 ID がないため、ユーザーアカウントに `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: {} を設定します。MP4\_AAC、M4A\_AAC、MOV\_AAC などのエンコーディングを指定するには explicitDecodingConfig を使用します。

**options.recognizer** (`string`): v2 Recognizer のリソースパス。デフォルトは projects/{project}/locations/global/recognizers/\_ です。{project} はコンストラクターの project オプション、GOOGLE\_CLOUD\_PROJECT、またはクライアントのデフォルトプロジェクトから解決されます。

戻り値：`Promise<string>`

### `getSpeakers()`

使用可能な Voice オプションの配列を返します。各要素には次の値が含まれます。

**voiceId** (`string`): Voice の一意な識別子

**languageCodes** (`string[]`): この Voice がサポートする言語コードの一覧

### `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 は2つの認証方法をサポートします。

### 標準モード（API キー）

認証に Google Cloud API キーを使用します。`speak()` と v1 の `listen()` に対応します。IAM で認可され、サービスアカウント認証情報が必要な `listen({ v2: true })` には対応しません（[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 クライアント

リクエストで認証情報を提示するサービスアカウント（`keyFilename`、`credentials`、`GOOGLE_APPLICATION_CREDENTIALS` のいずれかを使用）に `roles/speech.client` を付与します。このロールは Vertex AI モードだけでなく、特に `listen({ v2: true })` に必要です。API キーだけのリクエストには認可対象の ID がないため、ユーザーアカウントに付与しても効果はありません。

#### 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. デフォルトの Voice は `'en-US-Casual-K'` です。

4. Text-to-Speech と Speech-to-Text の両サービスは、デフォルトの音声エンコーディングとして 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. 使用可能な Voice は、`getSpeakers()` メソッドで言語コードにより絞り込めます。

9. Vertex AI モードは、IAM 制御、監査ログ、プロジェクト単位の請求などのエンタープライズ機能を提供します。