Mastra Google Voice 集成指南用 mastra/voice-google 实现 TTS 语音合成与 STT 语音识别【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastramastra/voice-google是 Mastra 框架中对接 Google Cloud Text-to-Speech 与 Speech-to-Text 的官方语音集成包它把谷歌云端语音能力封装为统一的GoogleVoice类为 AI Agent 应用提供文字转语音与语音转文字的双向能力。本文将以 voice/google/README.md 为核心骨架结合仓库源码与测试用例完整讲解安装、鉴权、核心 API、SSML 高级合成、Speech-to-Text v1/v2 双通道识别以及 Vertex AI 企业部署模式读完即可在 Mastra Agent 中直接落地语音交互能力。一、包概览与安装mastra/voice-google是 Mastra 语音生态中的 Google 实现当前仓库版本为0.14.2见 voice/google/package.json。它的核心价值在于Text-to-SpeechTTS文本、SSML、多说话人标记等输入合成出可流式读取的音频流Speech-to-TextSTT接收音频流返回转写文本可配置语音speaker、语言languageCode、音频编码audioEncoding、流式输出均可自由定制多路鉴权API Key、服务账号密钥文件、内存凭据、Application Default CredentialsADC与 Vertex AI 项目级鉴权全部支持。安装命令与官方 README 完全一致npm install mastra/voice-google注意环境要求根据 voice/google/package.json 的engines字段需要Node.js 22.13.0同时该包将zod声明为 peer dependency^3.25.0 || ^4.0.0使用前请确保项目中已安装 zod。二、三种鉴权方式与优先级GoogleVoice的鉴权通过GoogleModelConfig配置定义于 voice/google/src/index.ts支持三个字段字段类型说明apiKeystringGoogle Cloud API Key可省略省略时回退到GOOGLE_API_KEY环境变量keyFilenamestring服务账号密钥文件JSON路径可省略省略时回退到GOOGLE_APPLICATION_CREDENTIALS环境变量credentials{ client_email?, private_key?, ... }内存中的服务账号凭据对象适合不能落地密钥文件的容器/Serverless 场景从源码resolveAuthConfig与buildAuthOptionsindex.ts可以看出实际解析顺序显式传入的speechModel/listeningModel配置优先未传则使用共享回退值环境变量GOOGLE_API_KEY、GOOGLE_APPLICATION_CREDENTIALS构造器级别的credentials是 speechModel 与 listeningModel 共用的兜底。因此最简洁的启动方式甚至可以完全不传任何密钥——只要设置了GOOGLE_API_KEY或GOOGLE_APPLICATION_CREDENTIALS环境变量即可。同时源码在super()调用中把解析后的 apiKey 同步给了基类MastraVoice保证语音模型信息在整个框架内一致可见。三、标准用法合成与转写的最小闭环官方 README 给出了一段完整的初始化 → 列出音色 → 合成 → 转写闭环代码这里结合源码逐行展开import { GoogleVoice } from mastra/voice-google; // 初始化speechModel 管 TTSlisteningModel 管 STT const voice new GoogleVoice({ speechModel: { apiKey: your-api-key, // 可选可依赖 GOOGLE_API_KEY 或 ADC keyFilename: /path/to/service-account.json, // 可选可依赖 GOOGLE_APPLICATION_CREDENTIALS }, listeningModel: { keyFilename: /path/to/service-account.json, // 可选可依赖 ADC }, speaker: en-US-Standard-F, // 默认音色 }); // 1. 列出可用音色默认语言 en-US可按 languageCode 过滤 const voices await voice.getSpeakers(); // 2. 合成语音返回 NodeJS.ReadableStream 音频流 const audioStream await voice.speak(Hello from Mastra!, { speaker: en-US-Standard-F, languageCode: en-US, }); // 3. 转写语音把音频流喂给 listen得到文本 const text await voice.listen(audioStream);几个值得注意的细节均有源码佐证getSpeakers()接受{ languageCode }参数默认en-US内部调用 Google TTS 的listVoices接口返回{ voiceId, languageCodes }[]结构index.ts。speak()的返回是一个PassThrough流默认音频编码为LINEAR16即 WAV/PCM可以直接pipe给文件流或播放器。测试用例 index.test.ts 展示了如何把音频流写入speech-test.wav文件。speak()的入参既可以是字符串也可以是NodeJS.ReadableStream——当传入文本流时内部会先完整读取再发给 Google APIindex.ts。未显式传speaker时源码使用默认音色en-US-Casual-KDEFAULT_VOICE见 index.ts这一点与 README 示例中显式指定的en-US-Standard-F不同两者都是合法用法一个走默认值、一个走显式覆盖。四、GoogleVoiceConfig 完整配置参考GoogleVoiceConfigindex.ts是构造器的全部配置入口含义如下配置项类型默认值说明speechModelGoogleModelConfig—TTS 鉴权配置apiKey / keyFilename / credentialslisteningModelGoogleModelConfig—STT 鉴权配置speakerstringen-US-Casual-K默认合成音色 IDvertexAIbooleanfalse是否启用 Vertex AI 项目级鉴权模式projectstringGOOGLE_CLOUD_PROJECTGoogle Cloud 项目 IDvertexAI: true时必填locationstringus-central1Vertex AI 区域可回退到GOOGLE_CLOUD_LOCATION环境变量初始化时还会做参数校验当vertexAI: true但既未传project、环境变量GOOGLE_CLOUD_PROJECT也不存在时构造器会直接抛出错误Google Cloud project ID is required when using Vertex AI...index.ts。这一点在单元测试 index.test.ts 中有明确断言。五、speak() 深度解析从纯文本到 SSML、多说话人与 Gemini TTSspeak()是 TTS 能力的核心方法签名如下speak(input: string | NodeJS.ReadableStream, options?: GoogleSpeakOptions): PromiseNodeJS.ReadableStreamGoogleSpeakOptionsindex.ts包含四类字段覆盖 Google Cloud TTS 请求的全部关键部分字段作用speaker本次调用的音色 ID覆盖构造器默认值languageCode语言代码不传时自动从音色 ID 推导如cmn-CN-Standard-A会推导为cmn-CNindex.tsinput透传给 Google 的SynthesizeSpeechRequest.input可携带text、ssml、markup、customPronunciations、multiSpeakerMarkup、prompt等字段voice透传voice对象可追加modelName如 Gemini TTS 模型与multiSpeakerVoiceConfigaudioConfig音频输出配置默认{ audioEncoding: LINEAR16 }可改为MP3、OGG_OPUS等5.1 SSML 与自定义发音医疗、法律等专业术语场景中普通文本合成的读音常常不准。通过input.ssml传入 SSML 即可精确控制发音例如 CHANGELOG.md 中官方给出的示例await voice.speak(Give Metacam to the patient., { input: { ssml: speakGive phoneme alphabetipa phmɛtəˈkæmMetacam/phoneme./speak, }, });测试用例 index.test.ts 验证了只要传入了ssml合成请求的input.ssml会原样透传且不会注入text字段。也可以只使用customPronunciations而不写完整 SSML。此时源码有个贴心逻辑如果options.input存在但其中没有text/ssml/markup/multiSpeakerMarkup会自动把位置参数input的文本填充为input.textindex.ts且不会修改调用方传入的对象有测试保证见 index.test.ts。5.2 多说话人标记multiSpeakerMarkup对话类内容如客服机器人角色扮演可用multiSpeakerMarkup一次性合成多角色音频await voice.speak(ignored, { input: { multiSpeakerMarkup: { turns: [{ speaker: R, text: Hi }] }, }, });源码对这类输入的处理原则是既然提供了结构化标记就不再注入text测试见 index.test.ts。5.3 Gemini TTS 模型选择options.voice.modelName允许切换到 Google 的新一代 Gemini 语音模型并配合input.prompt做风格引导await voice.speak(Hello!, { voice: { name: Kore, modelName: gemini-2.5-flash-preview-tts }, input: { prompt: Warm, calm tone. }, });源码在组装请求时采用默认值打底 调用方覆盖的合并策略voice.name和voice.languageCode先取默认再用...options?.voice展开覆盖因此modelName可以与其并存测试见 index.test.ts。六、listen() 深度解析Speech-to-Text v1 与 v2 双通道listen()接收音频流返回转写文本listen(audioStream: NodeJS.ReadableStream, options?: GoogleListenOptions): Promisestring6.1 v1 通道默认不传v2: true时走 Cloud Speech-to-Text v1 API请求默认配置为{ encoding: LINEAR16, languageCode: en-US, }音频以 base64 编码放入audio.contentindex.ts。可以通过options.config覆盖例如识别 FLAC 编码的法语音频await voice.listen(audioStream, { config: { encoding: FLAC, languageCode: fr-FR }, });6.2 v2 通道{ v2: true }v2 API 是 v1 的演进版本最大优势是支持更多音频编码格式包括 iOS Safari 常见的 AAC-in-MP4MP4_AAC其解码策略通过autoDecodingConfig或explicitDecodingConfig指定。启用方式await voice.listen(audioStream, { v2: true, // 显式指定解码格式若不指定默认自动注入 autoDecodingConfig: {} config: { explicitDecodingConfig: { encoding: MP4_AAC, sampleRateHertz: 44100, audioChannelCount: 1 }, }, // 可选指定 recognizer 路径默认 projects/{project}/locations/global/recognizers/_ recognizer: projects/my-project/locations/global/recognizers/my-recognizer, });v2 通道的默认值行为index.ts未指定任何解码配置时自动注入autoDecodingConfig: {}languageCodes默认[en-US]模型默认longrecognizer 默认使用构造器的projectVertex AI 模式或从 v2 客户端获取 projectId 拼装成projects/{project}/locations/global/recognizers/_。v2 客户端采用懒加载策略只有首次listen(..., { v2: true })时才实例化v2.SpeechClient测试见 index.test.ts不启用 v2 就不会产生额外开销。6.3 转写结果提取两条通道共用extractTranscription()index.ts按序取每个 result 的alternatives[0].transcript过滤空串后用空格拼接若没有任何有效转写则抛出No valid transcription found in results。七、Vertex AI 模式面向企业生产的项目级鉴权对于企业部署Google 官方推荐以项目project维度进行鉴权而不是使用 API Key。GoogleVoice为此提供了vertexAI开关该能力自 v0.12.0 起引入见 CHANGELOG.md// 方式一纯项目级鉴权依赖 ADC 或环境变量 const voice new GoogleVoice({ vertexAI: true, project: your-gcp-project, location: us-central1, speaker: en-US-Studio-O, }); // 方式二Vertex AI 服务账号密钥文件 const voice new GoogleVoice({ vertexAI: true, project: your-gcp-project, speechModel: { keyFilename: /path/to/service-account.json, }, }); // 方式三全部交给环境变量 // GOOGLE_CLOUD_PROJECTmy-project GOOGLE_CLOUD_LOCATIONeurope-west1 const voice new GoogleVoice({ vertexAI: true });关键行为均有测试覆盖见 index.test.ts开启vertexAI后源码在鉴权解析中优先注入 projectId并禁止使用 API Keyindex.ts符合项目级鉴权替代 API Key的企业安全诉求project构造器参数优先于GOOGLE_CLOUD_PROJECT环境变量location默认us-central1可用GOOGLE_CLOUD_LOCATION覆盖缺 project 时构造器抛错前述校验逻辑三个只读辅助方法可用于运行时探测isUsingVertexAI()、getProject()、getLocation()。八、源码结构、测试与已知坑位8.1 依赖与文件结构GoogleVoice继承自 Mastra 内部统一的语音基类MastraVoice位于 packages/_internals/voice/src/voice/voice.ts由 packages/_internals/voice/src/voice/index.ts 汇总导出。这意味着GoogleVoice天然兼容 Mastra 的 Agent 语音接口与其他语音提供方如 ElevenLabs、OpenAI 等的抽象契约。依赖方面voice/google/package.json 声明了google-cloud/speech^7.5.0STTgoogle-cloud/text-to-speech^6.4.1TTS8.2 值得注意的依赖陷阱google-cloud/speech必须 ≥ v7仓库专门为这个坑写了一个回归测试 speech-dependency.test.tsgoogle-cloud/speechv6 依赖的google-gaxv4 →gaxiosv6 在 Node 22 下会让 ADC 令牌交换以ERR_STREAM_PREMATURE_CLOSE失败导致GoogleVoice.listen()永远报错升级到 v7google-gaxv5 /gaxiosv7后问题解决对应 issue #19206修复记录见 CHANGELOG.md 的 0.14.1 条目。如果你遇到STT 在 Node 22 上一直失败的问题请优先检查锁文件里google-cloud/speech是否被降级到了 v6。8.3 测试即文档voice/google/src/index.test.ts 包含初始化、音色、speak、listen v1/v2 的完整单测并附带可连真实 Google Cloud 的集成测试生成 wav 文件后再转写验证合成 → 转写闭环测试还验证了不修改调用方入参对象的防御性设计v1 与 v2 通道均如此。九、常见问题速查问题排查方向listen()在 Node 22 上抛ERR_STREAM_PREMATURE_CLOSE确认google-cloud/speech版本 ≥ 7见上文 8.2 节报错缺少 project ID开了vertexAI: true但未设project/GOOGLE_CLOUD_PROJECT想换默认音色构造器传speaker或每次speak()时传options.speaker想输出 MP3 而非 WAVspeak(text, { audioConfig: { audioEncoding: MP3 } })识别 iOS Safari 录音AAC in MP4listen(stream, { v2: true, config: { explicitDecodingConfig: { encoding: MP4_AAC, ... } } })想查看某个语言的全部音色voice.getSpeakers({ languageCode: zh-CN })更多演进历史SSML 支持、v2 支持、Vertex AI 支持、依赖安全修复等可查看包的 voice/google/CHANGELOG.md官方详细文档入口见 voice/google/README.md。将本文的GoogleVoice实例接入 Mastra Agent 后即可在会话中同时获得朗读 Agent 回复与听懂用户语音输入的完整语音闭环能力。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Mastra Google Voice 集成指南：用 @mastra/voice-google 实现 TTS 语音合成与 STT 语音识别
Mastra Google Voice 集成指南用 mastra/voice-google 实现 TTS 语音合成与 STT 语音识别【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastramastra/voice-google是 Mastra 框架中对接 Google Cloud Text-to-Speech 与 Speech-to-Text 的官方语音集成包它把谷歌云端语音能力封装为统一的GoogleVoice类为 AI Agent 应用提供文字转语音与语音转文字的双向能力。本文将以 voice/google/README.md 为核心骨架结合仓库源码与测试用例完整讲解安装、鉴权、核心 API、SSML 高级合成、Speech-to-Text v1/v2 双通道识别以及 Vertex AI 企业部署模式读完即可在 Mastra Agent 中直接落地语音交互能力。一、包概览与安装mastra/voice-google是 Mastra 语音生态中的 Google 实现当前仓库版本为0.14.2见 voice/google/package.json。它的核心价值在于Text-to-SpeechTTS文本、SSML、多说话人标记等输入合成出可流式读取的音频流Speech-to-TextSTT接收音频流返回转写文本可配置语音speaker、语言languageCode、音频编码audioEncoding、流式输出均可自由定制多路鉴权API Key、服务账号密钥文件、内存凭据、Application Default CredentialsADC与 Vertex AI 项目级鉴权全部支持。安装命令与官方 README 完全一致npm install mastra/voice-google注意环境要求根据 voice/google/package.json 的engines字段需要Node.js 22.13.0同时该包将zod声明为 peer dependency^3.25.0 || ^4.0.0使用前请确保项目中已安装 zod。二、三种鉴权方式与优先级GoogleVoice的鉴权通过GoogleModelConfig配置定义于 voice/google/src/index.ts支持三个字段字段类型说明apiKeystringGoogle Cloud API Key可省略省略时回退到GOOGLE_API_KEY环境变量keyFilenamestring服务账号密钥文件JSON路径可省略省略时回退到GOOGLE_APPLICATION_CREDENTIALS环境变量credentials{ client_email?, private_key?, ... }内存中的服务账号凭据对象适合不能落地密钥文件的容器/Serverless 场景从源码resolveAuthConfig与buildAuthOptionsindex.ts可以看出实际解析顺序显式传入的speechModel/listeningModel配置优先未传则使用共享回退值环境变量GOOGLE_API_KEY、GOOGLE_APPLICATION_CREDENTIALS构造器级别的credentials是 speechModel 与 listeningModel 共用的兜底。因此最简洁的启动方式甚至可以完全不传任何密钥——只要设置了GOOGLE_API_KEY或GOOGLE_APPLICATION_CREDENTIALS环境变量即可。同时源码在super()调用中把解析后的 apiKey 同步给了基类MastraVoice保证语音模型信息在整个框架内一致可见。三、标准用法合成与转写的最小闭环官方 README 给出了一段完整的初始化 → 列出音色 → 合成 → 转写闭环代码这里结合源码逐行展开import { GoogleVoice } from mastra/voice-google; // 初始化speechModel 管 TTSlisteningModel 管 STT const voice new GoogleVoice({ speechModel: { apiKey: your-api-key, // 可选可依赖 GOOGLE_API_KEY 或 ADC keyFilename: /path/to/service-account.json, // 可选可依赖 GOOGLE_APPLICATION_CREDENTIALS }, listeningModel: { keyFilename: /path/to/service-account.json, // 可选可依赖 ADC }, speaker: en-US-Standard-F, // 默认音色 }); // 1. 列出可用音色默认语言 en-US可按 languageCode 过滤 const voices await voice.getSpeakers(); // 2. 合成语音返回 NodeJS.ReadableStream 音频流 const audioStream await voice.speak(Hello from Mastra!, { speaker: en-US-Standard-F, languageCode: en-US, }); // 3. 转写语音把音频流喂给 listen得到文本 const text await voice.listen(audioStream);几个值得注意的细节均有源码佐证getSpeakers()接受{ languageCode }参数默认en-US内部调用 Google TTS 的listVoices接口返回{ voiceId, languageCodes }[]结构index.ts。speak()的返回是一个PassThrough流默认音频编码为LINEAR16即 WAV/PCM可以直接pipe给文件流或播放器。测试用例 index.test.ts 展示了如何把音频流写入speech-test.wav文件。speak()的入参既可以是字符串也可以是NodeJS.ReadableStream——当传入文本流时内部会先完整读取再发给 Google APIindex.ts。未显式传speaker时源码使用默认音色en-US-Casual-KDEFAULT_VOICE见 index.ts这一点与 README 示例中显式指定的en-US-Standard-F不同两者都是合法用法一个走默认值、一个走显式覆盖。四、GoogleVoiceConfig 完整配置参考GoogleVoiceConfigindex.ts是构造器的全部配置入口含义如下配置项类型默认值说明speechModelGoogleModelConfig—TTS 鉴权配置apiKey / keyFilename / credentialslisteningModelGoogleModelConfig—STT 鉴权配置speakerstringen-US-Casual-K默认合成音色 IDvertexAIbooleanfalse是否启用 Vertex AI 项目级鉴权模式projectstringGOOGLE_CLOUD_PROJECTGoogle Cloud 项目 IDvertexAI: true时必填locationstringus-central1Vertex AI 区域可回退到GOOGLE_CLOUD_LOCATION环境变量初始化时还会做参数校验当vertexAI: true但既未传project、环境变量GOOGLE_CLOUD_PROJECT也不存在时构造器会直接抛出错误Google Cloud project ID is required when using Vertex AI...index.ts。这一点在单元测试 index.test.ts 中有明确断言。五、speak() 深度解析从纯文本到 SSML、多说话人与 Gemini TTSspeak()是 TTS 能力的核心方法签名如下speak(input: string | NodeJS.ReadableStream, options?: GoogleSpeakOptions): PromiseNodeJS.ReadableStreamGoogleSpeakOptionsindex.ts包含四类字段覆盖 Google Cloud TTS 请求的全部关键部分字段作用speaker本次调用的音色 ID覆盖构造器默认值languageCode语言代码不传时自动从音色 ID 推导如cmn-CN-Standard-A会推导为cmn-CNindex.tsinput透传给 Google 的SynthesizeSpeechRequest.input可携带text、ssml、markup、customPronunciations、multiSpeakerMarkup、prompt等字段voice透传voice对象可追加modelName如 Gemini TTS 模型与multiSpeakerVoiceConfigaudioConfig音频输出配置默认{ audioEncoding: LINEAR16 }可改为MP3、OGG_OPUS等5.1 SSML 与自定义发音医疗、法律等专业术语场景中普通文本合成的读音常常不准。通过input.ssml传入 SSML 即可精确控制发音例如 CHANGELOG.md 中官方给出的示例await voice.speak(Give Metacam to the patient., { input: { ssml: speakGive phoneme alphabetipa phmɛtəˈkæmMetacam/phoneme./speak, }, });测试用例 index.test.ts 验证了只要传入了ssml合成请求的input.ssml会原样透传且不会注入text字段。也可以只使用customPronunciations而不写完整 SSML。此时源码有个贴心逻辑如果options.input存在但其中没有text/ssml/markup/multiSpeakerMarkup会自动把位置参数input的文本填充为input.textindex.ts且不会修改调用方传入的对象有测试保证见 index.test.ts。5.2 多说话人标记multiSpeakerMarkup对话类内容如客服机器人角色扮演可用multiSpeakerMarkup一次性合成多角色音频await voice.speak(ignored, { input: { multiSpeakerMarkup: { turns: [{ speaker: R, text: Hi }] }, }, });源码对这类输入的处理原则是既然提供了结构化标记就不再注入text测试见 index.test.ts。5.3 Gemini TTS 模型选择options.voice.modelName允许切换到 Google 的新一代 Gemini 语音模型并配合input.prompt做风格引导await voice.speak(Hello!, { voice: { name: Kore, modelName: gemini-2.5-flash-preview-tts }, input: { prompt: Warm, calm tone. }, });源码在组装请求时采用默认值打底 调用方覆盖的合并策略voice.name和voice.languageCode先取默认再用...options?.voice展开覆盖因此modelName可以与其并存测试见 index.test.ts。六、listen() 深度解析Speech-to-Text v1 与 v2 双通道listen()接收音频流返回转写文本listen(audioStream: NodeJS.ReadableStream, options?: GoogleListenOptions): Promisestring6.1 v1 通道默认不传v2: true时走 Cloud Speech-to-Text v1 API请求默认配置为{ encoding: LINEAR16, languageCode: en-US, }音频以 base64 编码放入audio.contentindex.ts。可以通过options.config覆盖例如识别 FLAC 编码的法语音频await voice.listen(audioStream, { config: { encoding: FLAC, languageCode: fr-FR }, });6.2 v2 通道{ v2: true }v2 API 是 v1 的演进版本最大优势是支持更多音频编码格式包括 iOS Safari 常见的 AAC-in-MP4MP4_AAC其解码策略通过autoDecodingConfig或explicitDecodingConfig指定。启用方式await voice.listen(audioStream, { v2: true, // 显式指定解码格式若不指定默认自动注入 autoDecodingConfig: {} config: { explicitDecodingConfig: { encoding: MP4_AAC, sampleRateHertz: 44100, audioChannelCount: 1 }, }, // 可选指定 recognizer 路径默认 projects/{project}/locations/global/recognizers/_ recognizer: projects/my-project/locations/global/recognizers/my-recognizer, });v2 通道的默认值行为index.ts未指定任何解码配置时自动注入autoDecodingConfig: {}languageCodes默认[en-US]模型默认longrecognizer 默认使用构造器的projectVertex AI 模式或从 v2 客户端获取 projectId 拼装成projects/{project}/locations/global/recognizers/_。v2 客户端采用懒加载策略只有首次listen(..., { v2: true })时才实例化v2.SpeechClient测试见 index.test.ts不启用 v2 就不会产生额外开销。6.3 转写结果提取两条通道共用extractTranscription()index.ts按序取每个 result 的alternatives[0].transcript过滤空串后用空格拼接若没有任何有效转写则抛出No valid transcription found in results。七、Vertex AI 模式面向企业生产的项目级鉴权对于企业部署Google 官方推荐以项目project维度进行鉴权而不是使用 API Key。GoogleVoice为此提供了vertexAI开关该能力自 v0.12.0 起引入见 CHANGELOG.md// 方式一纯项目级鉴权依赖 ADC 或环境变量 const voice new GoogleVoice({ vertexAI: true, project: your-gcp-project, location: us-central1, speaker: en-US-Studio-O, }); // 方式二Vertex AI 服务账号密钥文件 const voice new GoogleVoice({ vertexAI: true, project: your-gcp-project, speechModel: { keyFilename: /path/to/service-account.json, }, }); // 方式三全部交给环境变量 // GOOGLE_CLOUD_PROJECTmy-project GOOGLE_CLOUD_LOCATIONeurope-west1 const voice new GoogleVoice({ vertexAI: true });关键行为均有测试覆盖见 index.test.ts开启vertexAI后源码在鉴权解析中优先注入 projectId并禁止使用 API Keyindex.ts符合项目级鉴权替代 API Key的企业安全诉求project构造器参数优先于GOOGLE_CLOUD_PROJECT环境变量location默认us-central1可用GOOGLE_CLOUD_LOCATION覆盖缺 project 时构造器抛错前述校验逻辑三个只读辅助方法可用于运行时探测isUsingVertexAI()、getProject()、getLocation()。八、源码结构、测试与已知坑位8.1 依赖与文件结构GoogleVoice继承自 Mastra 内部统一的语音基类MastraVoice位于 packages/_internals/voice/src/voice/voice.ts由 packages/_internals/voice/src/voice/index.ts 汇总导出。这意味着GoogleVoice天然兼容 Mastra 的 Agent 语音接口与其他语音提供方如 ElevenLabs、OpenAI 等的抽象契约。依赖方面voice/google/package.json 声明了google-cloud/speech^7.5.0STTgoogle-cloud/text-to-speech^6.4.1TTS8.2 值得注意的依赖陷阱google-cloud/speech必须 ≥ v7仓库专门为这个坑写了一个回归测试 speech-dependency.test.tsgoogle-cloud/speechv6 依赖的google-gaxv4 →gaxiosv6 在 Node 22 下会让 ADC 令牌交换以ERR_STREAM_PREMATURE_CLOSE失败导致GoogleVoice.listen()永远报错升级到 v7google-gaxv5 /gaxiosv7后问题解决对应 issue #19206修复记录见 CHANGELOG.md 的 0.14.1 条目。如果你遇到STT 在 Node 22 上一直失败的问题请优先检查锁文件里google-cloud/speech是否被降级到了 v6。8.3 测试即文档voice/google/src/index.test.ts 包含初始化、音色、speak、listen v1/v2 的完整单测并附带可连真实 Google Cloud 的集成测试生成 wav 文件后再转写验证合成 → 转写闭环测试还验证了不修改调用方入参对象的防御性设计v1 与 v2 通道均如此。九、常见问题速查问题排查方向listen()在 Node 22 上抛ERR_STREAM_PREMATURE_CLOSE确认google-cloud/speech版本 ≥ 7见上文 8.2 节报错缺少 project ID开了vertexAI: true但未设project/GOOGLE_CLOUD_PROJECT想换默认音色构造器传speaker或每次speak()时传options.speaker想输出 MP3 而非 WAVspeak(text, { audioConfig: { audioEncoding: MP3 } })识别 iOS Safari 录音AAC in MP4listen(stream, { v2: true, config: { explicitDecodingConfig: { encoding: MP4_AAC, ... } } })想查看某个语言的全部音色voice.getSpeakers({ languageCode: zh-CN })更多演进历史SSML 支持、v2 支持、Vertex AI 支持、依赖安全修复等可查看包的 voice/google/CHANGELOG.md官方详细文档入口见 voice/google/README.md。将本文的GoogleVoice实例接入 Mastra Agent 后即可在会话中同时获得朗读 Agent 回复与听懂用户语音输入的完整语音闭环能力。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考