Google

Mastra 的 Google Voice 實作使用 Google Cloud 服務提供文字轉語音（TTS）及語音轉文字（STT）功能。它支援多種語音、語言、進階音訊設定選項，以及適用於企業部署的標準 API key 驗證和 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?:

GoogleModelConfig

= { apiKey: process.env.GOOGLE_API_KEY }

文字轉語音功能的設定

GoogleModelConfig

apiKey?:

string

Google Cloud API key。未提供時會使用 GOOGLE_API_KEY 環境變數。vertexAI 為 true 時不會使用。

keyFilename?:

string

服務帳戶 JSON key 檔案的路徑。未提供時會使用 GOOGLE_APPLICATION_CREDENTIALS 環境變數。

credentials?:

object

包含 client_email 和 private_key 屬性的記憶體內服務帳戶憑證物件。

listeningModel?:

GoogleModelConfig

= { apiKey: process.env.GOOGLE_API_KEY }

語音轉文字功能的設定

GoogleModelConfig

apiKey?:

string

Google Cloud API key。未提供時會使用 GOOGLE_API_KEY 環境變數。vertexAI 為 true 時不會使用。

keyFilename?:

string

服務帳戶 JSON key 檔案的路徑。未提供時會使用 GOOGLE_APPLICATION_CREDENTIALS 環境變數。

credentials?:

object

包含 client_email 和 private_key 屬性的記憶體內服務帳戶憑證物件。

speaker?:

string

= 'en-US-Casual-K'

文字轉語音預設使用的語音 ID

vertexAI?:

boolean

= false

為企業部署啟用 Vertex AI 模式。使用以項目為基礎的驗證，而非 API key。必須設定 'project'。

project?:

string

Google Cloud 項目 ID（vertexAI 為 true 時必須提供）。未提供時會使用 GOOGLE_CLOUD_PROJECT 環境變數。

location?:

string

= 'us-central1'

Vertex AI 的 Google Cloud 區域。未提供時會使用 GOOGLE_CLOUD_LOCATION 環境變數。

方法
方法的直接連結

`speak()`
speak 的直接連結

使用 Google Cloud Text-to-Speech 服務將文字轉換成語音。

input:

string | NodeJS.ReadableStream

要轉換成語音的文字。如提供串流，會先將其轉換成文字。

options?:

object

語音合成選項

GoogleSpeakOptions

speaker?:

string

此請求使用的語音 ID。

languageCode?:

string

語音的語言代碼（例如 'en-US'）。預設使用從 speaker ID 得出的語言代碼，否則為 'en-US'。

input?:

ISynthesizeSpeechRequest['input']

直接傳送至 Google Cloud TTS API 的進階輸入物件。支援 ssml、markup、prompt（Gemini-TTS 風格引導）、customPronunciations 及 multiSpeakerMarkup。如提供的物件不含 text、ssml、markup 或 multiSpeakerMarkup，位置 input 引數會自動用作 text 欄位。

voice?:

ISynthesizeSpeechRequest['voice']

合併至預設值（name 和 languageCode）之上的語音設定。支援 modelName（例如 'gemini-2.5-flash-preview-tts'）及 multiSpeakerVoiceConfig。

audioConfig?:

ISynthesizeSpeechRequest['audioConfig']

Google Cloud Text-to-Speech API 的音訊設定選項。

傳回：Promise<NodeJS.ReadableStream>

`listen()`
listen 的直接連結

使用 Google Cloud Speech-to-Text 服務將語音轉換成文字。支援 v1（預設）和 v2 API。v2 API 透過自動解碼，額外支援 AAC-in-MP4 音訊（iOS Safari）。

v1（預設）
v1（預設）的直接連結

audioStream:

NodeJS.ReadableStream

要轉錄的音訊串流

options?:

GoogleListenOptionsV1

v1 辨識選項

GoogleListenOptionsV1

config?:

IRecognitionConfig

Google Cloud Speech-to-Text API 的 v1 辨識設定

v2
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 亦是如此。

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 辨識選項

GoogleListenOptionsV2

v2:

true

啟用 v2 API 路徑

config?:

v2.IRecognitionConfig

v2 辨識設定。預設使用自動解碼，並設有 languageCodes: ['en-US'] 和 model: 'long'。設定 autoDecodingConfig: {} 可自動偵測音訊格式，或使用 explicitDecodingConfig 指定 MP4_AAC、M4A_AAC 或 MOV_AAC 等編碼。

recognizer?:

string

v2 recognizer 資源路徑。預設為 projects/{project}/locations/global/recognizers/_，當中的 {project} 會從建構函數的 project 選項、GOOGLE_CLOUD_PROJECT 或用戶端的預設項目解析。

傳回：Promise<string>

`getSpeakers()`
getspeakers 的直接連結

傳回可用語音選項的陣列，其中每個節點包含：

voiceId:

string

語音的唯一識別碼

languageCodes:

string[]

此語音支援的語言代碼清單

`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 支援兩種驗證方式：

標準模式（API key）
標準模式（API key）的直接連結

使用 Google Cloud API key 驗證。適用於 speak() 及 v1 listen()，但不適用於 listen({ v2: true })；後者透過 IAM 授權，並需要服務帳戶憑證（請參閱 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 key）
以 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。此角色是 listen({ v2: true }) 的特定要求，並非只在 Vertex AI 模式下才需要。向使用者帳戶授予此角色不會影響只使用 API key 的請求，因為這類請求不帶可供授權的身份。

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 key（標準模式）或服務帳戶憑證（Vertex AI 模式）。
環境變數：
- GOOGLE_API_KEY - 標準模式的 API key
- GOOGLE_CLOUD_PROJECT - Vertex AI 模式的項目 ID
- GOOGLE_CLOUD_LOCATION - Vertex AI 模式的位置（預設為 'us-central1'）
- GOOGLE_APPLICATION_CREDENTIALS - 服務帳戶 key 檔案的路徑
預設語音設為 'en-US-Casual-K'。
文字轉語音及語音轉文字服務均使用 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 key 運作。
可使用 getSpeakers() 方法按語言代碼篩選可用語音。
Vertex AI 模式提供企業功能，包括 IAM 控制、稽核記錄及項目層級帳單。

使用範例使用範例 的直接連結

建構函數參數建構函數參數 的直接連結

speechModel?:

apiKey?:

keyFilename?:

credentials?:

listeningModel?:

apiKey?:

keyFilename?:

credentials?:

speaker?:

vertexAI?:

project?:

location?:

方法方法 的直接連結

speak()speak 的直接連結

input:

options?:

speaker?:

languageCode?:

input?:

voice?:

audioConfig?:

listen()listen 的直接連結

v1（預設）v1（預設） 的直接連結

audioStream:

options?:

config?:

v2v2 的直接連結

audioStream:

options:

v2:

config?:

recognizer?:

getSpeakers()getspeakers 的直接連結

voiceId:

languageCodes:

isUsingVertexAI()isusingvertexai 的直接連結

getProject()getproject 的直接連結

getLocation()getlocation 的直接連結

驗證驗證 的直接連結

標準模式（API key）標準模式（API key） 的直接連結

Vertex AI 模式（服務帳戶）Vertex AI 模式（服務帳戶） 的直接連結

所需權限所需權限 的直接連結

IAM 角色IAM 角色 的直接連結

OAuth 範圍OAuth 範圍 的直接連結

重要事項重要事項 的直接連結

使用範例
使用範例的直接連結

建構函數參數
建構函數參數的直接連結

方法
方法的直接連結

`speak()`
speak 的直接連結

`listen()`
listen 的直接連結

v1（預設）
v1（預設）的直接連結

v2
v2 的直接連結

`getSpeakers()`
getspeakers 的直接連結

`isUsingVertexAI()`
isusingvertexai 的直接連結

`getProject()`
getproject 的直接連結

`getLocation()`
getlocation 的直接連結

驗證
驗證的直接連結

標準模式（API key）
標準模式（API key）的直接連結

Vertex AI 模式（服務帳戶）
Vertex AI 模式（服務帳戶）的直接連結

所需權限
所需權限的直接連結

IAM 角色
IAM 角色的直接連結

OAuth 範圍
OAuth 範圍的直接連結

重要事項
重要事項的直接連結