Mastra voice-azure 架构解析Azure 语音 TTS/STT 双向能力的实现原理与实战配置【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本文以 Mastra 仓库中mastra/voice-azure包的架构文档为核心深入讲解该类如何封装 Microsoft Azure Cognitive Services Speech SDK实现文本转语音TTS与语音转文本STT的双向能力。读完后你将掌握AzureVoice的完整配置方式speechModel/listeningModel/speaker、211 个内置声音的选择机制、speak()/listen()的底层数据流与错误处理策略以及如何将其接入 Mastra 语音生态。包概览与文件组织mastra/voice-azure是 Mastra 框架的 Azure 语音集成包基于microsoft-cognitiveservices-speech-sdk当前 package.json 中声明为^1.48.0提供标准化的语音交互接口。它继承自 Mastra 的基类MastraVoice定义在 voice 基类源码使 Azure 语音能力可以无缝接入 Mastra 的 Agent、Workflow 等上层组件。顶层组件结构如下AzureVoice (主类) ├── 继承 MastraVoice (mastra/core / internal/voice) ├── 依赖 │ ├── microsoft-cognitiveservices-speech-sdk │ └── Node.js stream API ├── 配置 │ ├── speechModel (TTS 配置) │ └── listeningModel (STT 配置) └── 静态数据 └── AZURE_VOICES (211 个声音定义)仓库中的文件组织非常清晰见 voice/azure 目录/src ├── index.ts # AzureVoice 主类实现TTS STT ├── voices.ts # 静态声音定义211 个声音 ID └── index.test.ts # 集成测试套件需真实 Azure 凭据安装与基本入口npm install mastra/voice-azureimport { AzureVoice } from mastra/voice-azure;AzureVoice 类结构与构造函数配置AzureVoice在 src/index.ts 中定义继承自MastraVoice。类内部维护四个私有属性分别对应 TTS 与 STT 两侧的 SDK 实例speechConfig?: Azure.SpeechConfig—— TTS 操作的配置listeningConfig?: Azure.SpeechConfig—— STT 操作的配置speechSynthesizer?: Azure.SpeechSynthesizer—— TTS 合成器实例speechRecognizer?: Azure.SpeechRecognizer—— STT 识别器实例构造参数完整说明构造函数接受一个可选配置对象src/index.ts#L28-L36{ speechModel?: { apiKey?: string // Azure Speech Services API key region?: string // Azure 区域如 eastus voiceName?: string // 默认声音如 en-US-AriaNeural language?: string // TTS 不使用该字段 }, listeningModel?: { apiKey?: string // Azure Speech Services API key region?: string // Azure 区域 language?: string // 识别语言如 en-US voiceName?: string // STT 不使用该字段 }, speaker?: VoiceId // 默认说话声音 ID受 VoiceId 类型约束 }参数适用侧说明默认值/回退speechModel.apiKeyTTSAzure Speech 订阅密钥回退到环境变量AZURE_API_KEYspeechModel.regionTTSAzure 区域如eastus回退到环境变量AZURE_REGIONspeechModel.voiceNameTTS合成声音名称默认en-US-AriaNeurallisteningModel.apiKeySTTAzure Speech 订阅密钥回退到AZURE_API_KEYlisteningModel.regionSTTAzure 区域回退到AZURE_REGIONlisteningModel.languageSTT识别语言写入speechRecognitionLanguage未设置时使用 SDK 默认speakerTTS默认声音VoiceId类型未指定时默认en-US-AriaNeural配置初始化流程构造函数的初始化逻辑src/index.ts#L49-L78遵循五个步骤环境变量回退apiKey与region均支持回退到AZURE_API_KEY/AZURE_REGION环境变量校验任一模型配置了但缺少凭据时构造函数立即抛出No Azure API key provided for .../No region provided for ...双配置独立TTS 与 STT 分别创建各自的Azure.SpeechConfig.fromSubscription(apiKey, region)互不干扰默认声音TTS 侧的声音按speechModel.voiceName || speaker || en-US-AriaNeural的优先级解析写入speechSynthesisVoiceNameSDK 实例化构造时即创建SpeechSynthesizer与SpeechRecognizer基础实例但每次请求会再创建新的合成器见下文。值得注意的是构造函数首先将speechModel.name、listeningModel.name、apiKey、speaker传给基类MastraVoice的super()。对照基类实现voice.ts#L103-L112基类会把它们存入listeningModel/speechModel/speaker属性并在serializeForSpan()中输出不含 apiKey的观测数据——也就是说凭据只存在于 Azure SDK 侧不会泄漏到 Mastra 的 tracing span 中。公开 API 详解AzureVoice实现了IMastraVoice契约中的四个核心方法其余如connect()、send()、answer()等实时双工方法保留基类的默认空实现从源码结构看Azure 侧仅做单请求式合成/识别不支持 WebSocket/RTC 实时流。getSpeakers()列出可用声音async getSpeakers(): PromiseArray{ voiceId: string; language: string; region: string; }实现src/index.ts#L86-L92是对静态数组AZURE_VOICES做映射从声音 ID 中解析出语言与区域return AZURE_VOICES.map(voice ({ voiceId: voice, language: voice.split(-)[0], region: voice.split(-)[1], }));这是一个同步操作包装成 Promise仅为了与接口签名保持一致。测试套件中对返回结构做了断言长度大于 0且每项包含voiceId、language、region三个字段index.test.ts#L28-L36。speak()文本转语音TTS签名async speak( input: string | NodeJS.ReadableStream, options?: { speaker?: string; [key: string]: any } ): PromiseNodeJS.ReadableStream // WAV 格式音频流数据流输入文本/流 ↓ [流转换]若输入是 ReadableStream累积为 UTF-8 字符串 ↓ [文本校验]trim 后为空则抛出 Input text is empty ↓ [声音配置]若 options.speaker 存在更新 speechSynthesisVoiceName ↓ [Azure 合成]speakTextAsync ↓ [结果校验]检查 ResultReason SynthesizingAudioCompleted ↓ [Buffer 包装]Readable.from([Buffer.from(result.audioData)]) ↓ 输出音频流源码级要点src/index.ts#L103-L166每次请求创建新的合成器const synthesizer new Azure.SpeechSynthesizer(this.speechConfig)不复用构造时的实例5 秒超时保护用Promise.race将合成 Promise 与一个 5000ms 的setTimeoutreject Promise 竞速超时抛出Speech synthesis timed out。从源码结构看长文本合成可能需要调大该值否则会误超时空输入校验!input?.trim()时抛出Input text is empty对应测试 index.test.ts#L150-L152流输入处理非字符串输入通过for await逐块读取并Buffer.concat读取失败时包装为Failed to read input stream: ...资源清理finally语义上用synthesizer.close()成功与失败路径都会关闭合成器音频格式由 Azure SDK 默认决定通常为 16kHz、16-bit、单声道 PCM WAV。listen()语音转文本STT签名async listen(audioStream: NodeJS.ReadableStream): Promisestring // 音频输入必须是 WAV 格式数据流音频流输入 ↓ [Buffer 累积]全部 chunk 读入内存并拼接 ↓ [Push Stream 创建]Azure.AudioInputStream.createPushStream() ↓ [音频配置]Azure.AudioConfig.fromStreamInput(pushStream) ↓ [识别器创建]new SpeechRecognizer(listeningConfig, audioConfig) ↓ [分块写入]按 4096 字节块 write 到 push stream ↓ [识别执行]recognizeOnceAsync单次语音识别 ↓ [结果校验]仅 ResultReason.RecognizedSpeech 才 resolve ↓ 输出文本源码级要点src/index.ts#L183-L231全量内存累积先把整个音频流读进Buffer.concat(chunks)大文件会带来内存压力文档中也明确建议生产环境评估流式替代方案4096 字节分块for (let i 0; i audioData.length; i 4096)逐块写入 Azure 的 push stream最后pushStream.close()表示音频结束单次识别使用recognizeOnceAsyncutterance 级非连续识别模式结果校验非RecognizedSpeech的结果会 reject错误信息中带上Azure.ResultReason[result.reason]的可读原因码与errorDetails资源清理finally块中recognizer.close()防止资源泄漏。getListener()监听能力探测async getListener(): Promise{ enabled: boolean } // 恒返回 { enabled: true }这是 Mastra 框架用来判断 STT 是否可用的能力查询。注意一个从源码可观察到的细节该方法不检查listeningModel是否真正配置恒返回enabled: true真正的未配置错误会在调用listen()时以Listening model (Azure) not configured抛出。基类的默认实现返回{ enabled: false }voice.ts#L266-L270Azure 侧覆盖该行为。声音定义与 VoiceId 类型声音目录集中在 src/voices.ts共211 个声音定义对文件中*Neural条目统计确认以as const数组导出覆盖 50 语言阿拉伯语、英语、德语、西班牙语、中文等与多个区域变体en-US、en-GB、en-AU 等。声音类型包括标准 Neural 声音如en-US-AriaNeural、af-ZA-AdriNeural多语言声音Multilingual后缀如de-DE-SeraphinaMultilingualNeuralHD 声音:DragonHDLatestNeural后缀如en-US-Andrew:DragonHDLatestNeural见 voices.ts#L201-L210AI 生成声音如AIGenerate1NeuralTurbo 多语言声音如AlloyTurboMultilingualNeural声音 ID 的标准格式为{language}-{region}-{name}NeuralgetSpeakers()正是利用这一格式解析language第 1 段与region第 2 段。类型层面VoiceId通过 const 断言导出voices.ts#L213-L215export const AZURE_VOICES [ /* ...211 个声音 ID... */ ] as const; export type VoiceId (typeof AZURE_VOICES)[number];这使得speaker构造参数与getSpeakers()的返回值都获得字面量级类型安全写错声音名在编译期即可发现。与 Mastra 框架的集成契约从 packages/_internals/voice/src/voice/voice.ts 的IMastraVoice接口可以确认AzureVoice履约的完整契约speak(input, options?)—— TTS返回PromiseNodeJS.ReadableStream | voidlisten(audioStream, options?)—— STT返回Promisestring | NodeJS.ReadableStream | voidgetSpeakers()—— 返回Array{ voiceId: string } 元数据getListener()—— 返回{ enabled: boolean }另有connect()/send()/answer()/close()/on()/off()/addInstructions()/addTools()等实时与工具扩展点Azure 侧均继承基类默认空实现构造函数通过super()把speechModel.name、apiKey、listeningModel.name、apiKey与speaker传给基类使 Mastra 框架能够追踪当前配置了哪些模型同时基类的serializeForSpan()会把apiKey排除在可观测性序列化之外voice.ts#L120-L129这一点对凭据安全是重要保障。错误处理策略与资源管理配置期错误构造函数立即抛出缺少 API key →No Azure API key provided for speech model/... for listening model缺少 region →No region provided for speech model/... for listening model对应的测试用例见 index.test.ts#L154-L165先删除AZURE_API_KEY环境变量验证只传region时构造函数按预期抛出运行期错误未配置对应模型却调用方法 →Speech model (Azure) not configured/Listening model (Azure) not configured空输入文本 →Input text is empty流读取失败 → 包装为Failed to read input stream: ...合成/识别失败 → 带 Azure 原因码与errorDetails的详细错误信息合成超时 → 5 秒Promise.race超时保护资源清理全部采用 try/catch/finally 模式speak()在成功与失败路径都调用synthesizer.close()listen()在finally中调用recognizer.close()避免 SDK 内部资源泄漏。构建与分发构建配置见 tsdown.config.ts注意当前仓库已从 tsup 迁移到 tsdownexport default defineConfig({ entry: [src/index.ts], format: [esm, cjs], // 双格式输出 nodeProtocol: strip, treeshake: true, sourcemap: true, deps: { alwaysBundle: [internal/voice] }, // 基类打入产物 onSuccess: async () { await generateTypes(process.cwd(), new Set([internal/voice])); // 生成 .d.ts }, });即ESM 与 CommonJS 双格式输出、生成 source map、基类internal/voice被 bundle 进产物、类型定义由internal/types-builder在构建成功后生成。package.json 的 exports 同时声明了import./dist/index.js与require./dist/index.cjs条件两类消费者均可使用运行环境要求node 22.13.0。测试策略集成测试套件 src/index.test.ts 使用真实 Azure API读取AZURE_API_KEY/AZURE_REGION环境变量覆盖五个维度初始化默认参数初始化new AzureVoice()后getSpeakers()应返回非空数组、环境变量回退getSpeakers()声音列表结构校验、voiceId/language/region元数据完整性speak()默认参数合成、指定speakeren-US-AriaNeural/en-US-JennyNeural、文本流输入Readablepush 字符串断言音频 Buffer 非空并把产物写入test-outputs/目录供人工检查listen()默认参数转写、文件流转写createReadStream读取上一步生成的 WAV、流转写并做round-trip 校验——例如合成 Listening test with defaults 后转写断言文本包含listening test错误处理空文本拒绝、缺失 API key 时构造函数抛出。测试还会创建test-outputs目录保存合成音频index.test.ts#L10-L26便于本地调试时直接听 WAV 文件验证效果。性能与安全考量内存listen()全量累积音频流于内存大音频文件可能带来内存压力文档建议生产环境考虑流式替代方案。超时speak()的 5 秒超时可防止 Azure API 故障导致请求挂起但对长文本合成偏紧按需调整。资源管理每个请求新建 synthesizer/recognizer 实例无实例池化与复用——简单正确优先吞吐优化留待后续如连接池、实例复用。凭据管理优先使用环境变量AZURE_API_KEY/AZURE_REGION直连配置需自行保管密钥凭据不会进入 tracing 序列化输出见基类serializeForSpan。输入校验文本仅做非空校验未提供 SSML 注入防护错误信息中可能携带 Azure 内部细节生产环境建议对错误做脱敏。实战使用示例以下示例综合了架构文档与 README 的用法均可直接复制运行需有效的 Azure Speech 订阅。基础 TTSconst voice new AzureVoice({ speechModel: { apiKey: key, region: eastus }, }); const audioStream await voice.speak(Hello World);基础 STTconst voice new AzureVoice({ listeningModel: { apiKey: key, region: eastus }, }); const text await voice.listen(audioStream); // audioStream 为 WAV 音频流完整双向合成 转写 round-tripconst voice new AzureVoice({ speechModel: { apiKey: key, region: eastus }, listeningModel: { apiKey: key, region: eastus }, speaker: en-US-JennyNeural, }); const audio await voice.speak(Test message); const transcription await voice.listen(audio);按次覆盖声音const audio await voice.speak(Bonjour, { speaker: fr-FR-DeniseNeural, });完全依赖环境变量// 仅设置 AZURE_API_KEY 与 AZURE_REGION 后 const voice new AzureVoice({ speechModel: {}, listeningModel: { language: en-US }, });列出全部声音const voices await voice.getSpeakers(); // [{ voiceId: af-ZA-AdriNeural, language: af, region: ZA }, ...] 共 211 项小结mastra/voice-azure是对 Azure Cognitive Services Speech SDK 的 TypeScript 原生封装通过继承MastraVoice接入 Mastra 统一的语音提供方接口以 TTS/STT 双配置模型独立管理两侧凭据与区域提供 211 个类型安全的声音选项并具备环境变量回退、超时保护与完整的资源清理。架构上它优先保证简单与正确——单请求式合成/识别、每请求新建 SDK 实例、无池化——这使其适合 Mastra 生态内的基础语音合成与识别场景文档同时列出了清晰的演进方向listen()的流式增量处理、显式 SSML 支持、实例缓存复用、音频格式选择与连续识别模式、以及 metrics/telemetry 可观测性。深入阅读可参考 主实现、声音目录、集成测试 与 基类契约。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考