Mastra 集成 Mistral Voxtral 语音能力mastra/voice-mistral 的 TTS 与 STT 完整实战指南【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastramastra/voice-mistral是 Mastra 生态中基于 Mistral Voxtral 音频模型的语音 Provider为 AI 应用提供文本转语音TTS与语音转文本STT能力。本文将带你掌握该包的安装、配置、MistralVoice与CompositeVoice的组合使用、speak()/listen()/getSpeakers()三大核心 API 的参数细节并结合仓库源码剖析其底层实现与默认行为使你能够直接在自己的 Mastra 应用中落地多模态语音交互。包概览一个 Provider覆盖双向语音mastra/voice-mistral源码位于 voice/mistral/src/index.ts是对 Mistral Voxtral 系列音频模型的封装。它同时提供两条能力链路Text-to-SpeechTTS通过speak()将文本或文本流合成为语音支持一次性返回完整音频的缓冲模式以及边合成边返回的流式模式并支持 mp3、wav、pcm、flac、opus 五种输出格式与基于参考音频的一次性音色克隆Speech-to-TextSTT通过listen()对音频流进行批量转写支持说话人分离diarization、上下文偏置context biasing与时间戳粒度控制。根据 voice/mistral/CHANGELOG.md 中的 0.1.0 版本记录该 Provider 于该版本正式引入其底层依赖为 Mistral 官方 Node SDKvoice/mistral/package.json 中声明mistralai/mistralai^2.4.1要求 Node.js 版本不低于 22.13.0。安装在项目中使用 pnpm、npm 或 yarn 安装即可npm install mastra/voice-mistral安装后mastra/voice-mistral对外默认导出MistralVoice类它与核心包中mastra/core/voice导出的CompositeVoice、MastraVoice抽象基类配合使用构成 Mastra 语音体系的标准用法。配置API Key 与模型选型使用前必须配置 Mistral API 凭据。MistralVoice的构造逻辑见 voice/mistral/src/index.ts 的构造函数遵循以下优先级构造参数中显式传入的speechModel.apiKey/listeningModel.apiKey环境变量MISTRAL_API_KEY源码中通过process.env.MISTRAL_API_KEY读取若两者皆无构造函数会直接抛错提示设置MISTRAL_API_KEY或在参数中传入apiKey。构造参数支持以下配置参数类型默认值说明speechModel{ name?, apiKey? }{ name: voxtral-mini-tts-2603 }负责 TTS 的模型与独立 API KeylisteningModel{ name?, apiKey? }{ name: voxtral-mini-latest }负责 STT 的模型与独立 API Keyspeakerstringen_paul_neutral默认发音人 ID注意speechModel与listeningModel的 API Key 是独立解析的可以分别传入不同密钥例如语音与转写走不同账号各自缺失时会抛出针对性的错误信息。模型名也可以覆盖为其他 Voxtral 系列模型例如voxtral-mini-tts-2603之外的 TTS 模型源码类型MistralSpeechModel允许任意字符串扩展。最小初始化示例import { MistralVoice } from mastra/voice-mistral; // 依赖环境变量 MISTRAL_API_KEY const voice new MistralVoice(); // 显式指定模型与发音人 const voice new MistralVoice({ speechModel: { name: voxtral-mini-tts-2603, apiKey: process.env.MISTRAL_SPEECH_KEY }, listeningModel: { name: voxtral-mini-latest, apiKey: process.env.MISTRAL_LISTEN_KEY }, speaker: en_paul_neutral, });与 CompositeVoice 组合单向能力也可成对使用官方 README 推荐的用法是将输入STT与输出TTS组合到CompositeVoice中这样上层语音 Agent 无需关心具体 Provider 的分工import { CompositeVoice } from mastra/core/voice; import { MistralVoice } from mastra/voice-mistral; const voice new CompositeVoice({ input: new MistralVoice(), // Voxtral 负责 STT output: new MistralVoice(), // Voxtral 负责 TTS });从 packages/_internals/voice/src/voice/composite-voice.ts 的实现可以看到CompositeVoice的路由机制speak()委托给output内部名为speakProviderlisten()委托给input内部名为listenProvidergetSpeakers()走输出 ProvidergetListener()走输入 Provider当某一路 Provider 未配置时会抛出带错误码的MastraError如VOICE_COMPOSITE_NO_SPEAK_PROVIDER。因此你完全可以只配置单向能力例如仅把input设为MistralVoice做转写、把output留给其他 TTS Provider——CompositeVoice支持异构拼接。文本转语音speak() 全参数详解speak()接受字符串或 Node.js 可读流作为输入若传入流源码会先将其完整读取为文本并返回一个NodeJS.ReadableStream音频流。空文本输入会直接抛出Input text is empty错误。参数说明参数类型默认值说明speakerstring构造时的speaker指定发音人 ID覆盖构造默认值responseFormatpcm \| wav \| mp3 \| flac \| opus由服务端决定测试默认写出 mp3输出音频编码格式refAudiostring无参考音频数据用于一次性音色克隆model字符串voxtral-mini-tts-2603覆盖 TTS 模型streambooleanfalse是否启用流式合成其他任意键any无透传给 Mistral SDK 的扩展参数缓冲模式默认未开启stream时源码调用speechClient.audio.speech.complete({ stream: false })将返回的 base64 音频数据解码为 Buffer再通过PassThrough以流的形式返回。因此无论缓冲还是流式调用方拿到的都是统一的ReadableStream接口const audioStream await voice.speak(Hello from Mistral.); const chunks: Buffer[] []; for await (const chunk of audioStream) { chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)); } // chunks 即为完整音频二进制可写入文件或直接播放流式模式设置stream: true后底层会请求 Mistral 的流式接口源码在 voice/mistral/src/index.ts 的speakStreaming()中遍历事件流遇到speech.audio.delta事件即把其中的 base64 音频块解码后写入PassThrough实现“边合成边输出”适合低延迟交互场景如语音 Agent 的逐句播报const stream await voice.speak(Hello, { stream: true, responseFormat: pcm });流式场景下建议配合pcm等低延迟格式使用这也是 voice/mistral/CHANGELOG.md 中给出的示例组合。发音人查询与音色克隆在调用speak()前通常先通过getSpeakers()拉取 Mistral 预置发音人列表源码调用audio.voices.list({ type: preset, limit: 100 })返回数组元素包含voiceId、name、languages、gender字段const speakers await voice.getSpeakers(); console.log(speakers[0].voiceId, speakers[0].name, speakers[0].languages); // 使用查到的发音人合成 const audio await voice.speak(Hello with a preset voice., { speaker: speakers[0]!.voiceId, });若需要定制音色可传入refAudio参考音频实现一次性one-off音色克隆无需预先注册声音档案。语音转文本listen() 全参数详解listen()接收一个音频流源码会先将其完整读入 Buffer再以audio.{filetype ?? mp3}的文件形式调用audio.transcriptions.complete()返回转写后的文本字符串Promisestring。参数说明参数类型默认值说明languagestring无转写语言代码例如endiarizeboolean无是否开启说话人分离区分不同发言者contextBiasstring[]无上下文偏置词表提升专有名词/领域词汇识别率timestampGranularities(segment \| word)[]无时间戳粒度按片段或按单词filetypestringmp3音频文件扩展名决定 MIME 识别其他任意键any无透传给 Mistral SDK 的扩展参数// 先用 TTS 生成测试音频再转写回来 const audioStream await voice.speak(This is a transcription test.); const text await voice.listen(audioStream, { language: en }); console.log(text);getListener()用于向框架报告该 Provider 是否具备听写能力Mistral 实现固定返回{ enabled: true }表明可作为语音输入的接收端。源码级的支撑细节理解以下三点能帮助你更准确地使用与排查问题抽象基类契约MistralVoice继承自 packages/_internals/voice/src/voice/voice.ts 中的抽象类MastraVoice后者定义了speak/listen/getSpeakers/getListener/updateConfig等统一接口并持有speechModel、listeningModel、speaker配置字段。所有 Mastra 语音 Provider 都遵循这一契约因此可以在CompositeVoice中任意互换。观测安全基类的serializeForSpan()在生成追踪 Span 时会剥离apiKey只保留模型名与 speaker 等非敏感信息避免密钥随遥测数据泄露见 packages/core/src/voice/voice-serialize-for-span.test.ts 的对应测试。依赖与运行环境voice/mistral/package.json 声明engines.node 22.13.0peerDependency 为zod ^3.25.0 || ^4.0.0集成时需确保环境满足要求。如何验证集成是否可用仓库为MistralVoice提供了完整的集成测试voice/mistral/src/index.test.ts可作为自测脚本的参考骨架。测试覆盖初始化默认参数、getSpeakers()返回非空发音人列表、speak()的默认合成/指定 speaker/文本流输入/responseFormat: wav/stream: true五种路径、空文本抛错、listen()基础转写与language选项、getListener()返回{ enabled: true }以及未配置 API Key 时的抛错行为。你可以在本地运行# 在 voice/mistral 目录下 pnpm test运行前需确保环境变量MISTRAL_API_KEY已设置测试中的new MistralVoice()依赖它。测试通过后会生成test-outputs/mistral-speech.mp3音频文件可直接播放验证合成效果。小结mastra/voice-mistral用最少的配置把 Mistral Voxtral 的双向语音能力接入 Mastranew MistralVoice()即获得 TTS 与 STT配合CompositeVoice可与其他语音 Provider 灵活拼装speak()的流式模式与五种输出格式适合实时场景refAudio支持音色克隆listen()的diarize、contextBias、timestampGranularities则覆盖了会议转写、多说话人分析等进阶需求。结合 voice/mistral/src/index.ts 源码与 voice/mistral/src/index.test.ts 测试你可以快速完成从配置、合成、转写到验证的完整闭环。更多版本变更记录可查阅 voice/mistral/CHANGELOG.md。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考