Mastra の Google Voice 実装は、Google Cloud サービスを使用した Text-to-Speech（TTS）および Speech-to-Text（STT）機能を提供します。複数の Voice と言語、高度な音声設定オプションに加え、標準の 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?:
apiKey?:
keyFilename?:
credentials?:
listeningModel?:
apiKey?:
keyFilename?:
credentials?:
speaker?:
vertexAI?:
project?:
location?:
メソッドメソッドへの直接リンク
speak()speakへの直接リンク
Google Cloud Text-to-Speech サービスを使用してテキストを音声に変換します。
input:
options?:
speaker?:
languageCode?:
input?:
ssml、markup、prompt（Gemini-TTS 形式の制御）、customPronunciations、multiSpeakerMarkup をサポートします。text、ssml、markup、multiSpeakerMarkup なしで指定すると、位置引数の input が自動的に text フィールドとして使用されます。voice?:
name と languageCode）に統合される Voice 設定。modelName（例：'gemini-2.5-flash-preview-tts'）と multiSpeakerVoiceConfig をサポートします。audioConfig?:
戻り値：Promise<NodeJS.ReadableStream>
listen()listenへの直接リンク
Google Cloud Speech-to-Text サービスを使用して音声をテキストに変換します。v1（デフォルト）と v2 の両 API をサポートします。v2 API では、自動デコードによって AAC-in-MP4 音声（iOS Safari）もサポートします。
v1（デフォルト）v1（デフォルト）への直接リンク
audioStream:
options?:
config?:
v2v2への直接リンク
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 を設定してください。
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:
options:
v2:
config?:
languageCodes: ['en-US'] と model: 'long' を使用する自動デコードです。音声形式を自動検出するには autoDecodingConfig: {} を設定します。MP4_AAC、M4A_AAC、MOV_AAC などのエンコーディングを指定するには explicitDecodingConfig を使用します。recognizer?:
projects/{project}/locations/global/recognizers/_ です。{project} はコンストラクターの project オプション、GOOGLE_CLOUD_PROJECT、またはクライアントのデフォルトプロジェクトから解決されます。戻り値：Promise<string>
getSpeakers()getspeakersへの直接リンク
使用可能な Voice オプションの配列を返します。各要素には次の値が含まれます。
voiceId:
languageCodes:
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 は2つの認証方法をサポートします。
標準モード（API キー）標準モード（API キー）への直接リンク
認証に Google Cloud API キーを使用します。speak() と v1 の listen() に対応します。IAM で認可され、サービスアカウント認証情報が必要な listen({ v2: true }) には対応しません（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 管理者（フルアクセス）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 スコープOAuth スコープへの直接リンク
同期 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 モードのプロジェクト IDGOOGLE_CLOUD_LOCATION- Vertex AI モードのロケーション（デフォルト：'us-central1'）GOOGLE_APPLICATION_CREDENTIALS- サービスアカウントキーファイルへのパス
- デフォルトの Voice は
'en-US-Casual-K'です。 - Text-to-Speech と Speech-to-Text の両サービスは、デフォルトの音声エンコーディングとして LINEAR16 を使用します。
speak()メソッドは、Google Cloud Text-to-Speech API による高度な音声設定をサポートします。listen()メソッドは、Google Cloud Speech-to-Text API によるさまざまな認識設定をサポートします。listen({ v2: true })にはサービスアカウント認証情報とGOOGLE_CLOUD_PROJECTが必要です。GOOGLE_API_KEYだけを設定した場合はPERMISSION_DENIEDになります。speak()と v1 のlisten()は API キーだけで動作します。- 使用可能な Voice は、
getSpeakers()メソッドで言語コードにより絞り込めます。 - Vertex AI モードは、IAM 制御、監査ログ、プロジェクト単位の請求などのエンタープライズ機能を提供します。