在 Mastra 中接入 Mistral Voxtral 语音能力mastra/voice-mistral 全面实战指南【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastramastra/voice-mistral是 Mastra 官方提供的 Mistral 语音供应商集成包基于 Mistral 的 Voxtral 音频模型为 TypeScript 的 AI 应用补齐了文本转语音TTS与语音转文本STT能力。读完本文你将掌握MistralVoice的安装配置、缓冲式与流式 TTS、基于参考音频的一次性音色克隆、带说话人分离diarization的批量转写以及如何通过CompositeVoice与mastra/core组合出可用的语音输入输出管线。一、什么是mastra/voice-mistralmastra/voice-mistral是 Mastra 的 Mistral 语音供应商实现当前版本 0.1.1在仓库中位于 voice/mistral 目录。根据 CHANGELOG.md 与 README.md 的说明它提供三个核心能力Text-to-speech通过speak()支持缓冲式与流式两种输出可输出 mp3、wav、pcm、flac、opus 五种音频格式并支持通过参考音频进行一次性音色克隆Speech-to-text通过listen()支持批量转写附带说话人分离speaker diarization、上下文偏置context biasing与时间戳粒度timestamp granularity控制Voice discovery通过getSpeakers()从 Mistral Voices API 拉取可用预设音色。其类型与运行时实现位于 voice/mistral/src/index.tsMistralVoice继承自 Mastra 内部的抽象语音基类MastraVoice见 packages/_internals/voice/src/voice/voice.ts因此天然具备speak/listen/getSpeakers/getListener等统一接口契约可与 Mastra 的其他语音供应商互换使用。二、安装与环境变量在任意 Node.js 22.13.0见 voice/mistral/package.json的 TypeScript 项目中安装npm install mastra/voice-mistral包的依赖仅有一个运行时依赖mistralai/mistralai^2.4.1见 voice/mistral/package.json体积轻量。同时它声明了zod作为 peer dependency^3.25.0 || ^4.0.0与 Mastra 生态兼容。API Key 有两种提供方式源码见 voice/mistral/src/index.ts环境变量MISTRAL_API_KEY推荐构造时不传任何参数也会自动读取构造函数中通过speechModel.apiKey/listeningModel.apiKey显式传入优先级高于环境变量。若两个途径都没有提供 KeyMistralVoice会在构造阶段直接抛出错误测试 voice/mistral/src/index.test.ts 专门验证了这一行为删除环境变量后new MistralVoice()会 throw。三、快速上手一段代码打通 TTS 与 STT官方文档与 CHANGELOG 给出的最小可用示例见 docs/src/content/en/integrations/voice/mistral.mdximport { MistralVoice } from mastra/voice-mistral; const voice new MistralVoice(); // 文本转语音缓冲式默认返回完整音频流 const audioStream await voice.speak(Hello, how can I help you?, { responseFormat: mp3, }); // 语音转文本 const text await voice.listen(audioStream, { language: en, }); // 列出可用预设音色 const speakers await voice.getSpeakers();注意speak()返回的是PromiseNodeJS.ReadableStream而listen()直接接受该流作为输入因此 TTS 输出可以无缝喂给 STT形成文本 → 语音 → 文本的回环链路。listen()返回的response.text即转写结果见 voice/mistral/src/index.ts。四、构造函数参数详解MistralVoice的构造函数签名见 voice/mistral/src/index.tsnew MistralVoice({ speechModel?: MistralModelConfig, listeningModel?: MistralModelConfig, speaker?: string, })参数类型默认值说明speechModelMistralModelConfig{ name: voxtral-mini-tts-2603 }TTS 合成模型配置name为模型 IDapiKey缺省回退到MISTRAL_API_KEYlisteningModelMistralModelConfig{ name: voxtral-mini-latest }STT 转写模型配置如需固定版本可指定voxtral-mini-2507speakerstringen_paul_neutral默认音色 ID可通过getSpeakers()获取可选 ID源码中定义了类型约束MistralSpeechModel当前为voxtral-mini-tts-2603类型上允许扩展MistralOutputFormat为pcm | wav | mp3 | flac | opus见 voice/mistral/src/index.ts。带完整配置的初始化示例见 docs/src/content/en/integrations/voice/mistral.mdxconst voice new MistralVoice({ speechModel: { name: voxtral-mini-tts-2603, apiKey: your-mistral-api-key, }, listeningModel: { name: voxtral-mini-latest, apiKey: your-mistral-api-key, }, speaker: en_paul_neutral, });值得说明的是构造函数会为 TTS 与 STT 分别创建独立的Mistral客户端实例speechClient与listeningClient见 voice/mistral/src/index.ts因此两路能力可以独立配置不同模型与密钥。五、speak()缓冲式与流式文本转语音5.1 输入与输出约定speak(input, options?)的input既可以是普通字符串也可以是NodeJS.ReadableStream文本流源码会先调用streamToString把流读成字符串见 voice/mistral/src/index.ts。如果输入为空文本trim 后长度为 0会抛出Input text is empty错误——测试 voice/mistral/src/index.test.ts 覆盖了该分支。5.2 选项说明选项类型默认值说明speakerstring构造函数默认值本次调用使用的音色 ID覆盖构造时的默认设置responseFormatpcm \| wav \| mp3 \| flac \| opus未指定由 API 决定输出音频格式流式场景推荐pcm以获得最低延迟refAudiostring无Base64 编码的参考音频用于一次性音色克隆参考音频至少 2-3 秒modelstringvoxtral-mini-tts-2603覆盖本次调用的语音合成模型streambooleanfalse开启流式输出音频块边到边写5.3 缓冲式 TTS 的底层实现当stream为 false默认时源码调用speechClient.audio.speech.complete({ ..., stream: false })将返回的 Base64 音频数据一次性解码为 Buffer再通过PassThrough流推送出去见 voice/mistral/src/index.ts。这种模式适合先完整合成、再消费整段音频的场景例如生成后可落盘保存。5.4 流式 TTS 的底层实现当stream: true时走speakStreaming()私有方法见 voice/mistral/src/index.ts以stream: true调用同一个complete端点拿到事件流随后在异步循环中监听speech.audio.delta事件把每块 Base64 音频增量解码后写入PassThrough供下游即时消费一旦出错则passThrough.destroy(error)传递错误。这种边合成边输出的模式适合实时对话与低延迟播报// 流式 TTS来自 CHANGELOG 示例 const stream await voice.speak(Hello, { stream: true, responseFormat: pcm, // pcm 格式延迟最低 }); // 消费音频块 for await (const chunk of stream) { // 将 chunk 写入播放器、WebSocket 或下行链路 }测试 voice/mistral/src/index.test.ts 验证了流式模式下能持续收集到非空音频块。5.5 一次性音色克隆通过refAudio传入一段 Base64 编码的参考音频建议 2-3 秒以上即可在不注册专属音色的前提下让本次合成克隆参考音频的音色特征const stream await voice.speak(这段语音使用了参考音色, { refAudio: base64AudioString, // 参考音频的 Base64 编码 responseFormat: mp3, });从源码看refAudio与voiceId会同时透传给 Mistral 的audio.speech.complete接口见 voice/mistral/src/index.ts由服务端完成音色合成。六、listen()批量语音转写listen(audioStream, options?)接受任意NodeJS.ReadableStream音频流内部先streamToBuffer完整读出音频字节再调用audio.transcriptions.complete进行批量转写见 voice/mistral/src/index.ts。由于是先收齐再转写的批量模式它适合会议记录、呼叫质检等离线或近实时场景。6.1 选项说明选项类型默认值说明languagestring未指定语言代码如en显式指定可提升准确率diarizebooleanfalse开启说话人分离区分不同说话人contextBiasstring[]未指定词汇引导context biasing用于纠正专有名词、领域术语timestampGranularities(segment \| word)[]未指定时间戳粒度支持按段segment或按词wordfiletypestringmp3输入音频的文件扩展名提示用于组装上传文件名const text await voice.listen(audioStream, { language: en, diarize: true, contextBias: [Mastra, Voxtral, Neural], timestampGranularities: [word], filetype: wav, });测试 voice/mistral/src/index.test.ts 覆盖了默认转写与指定language: en两种调用路径并断言返回文本非空。七、getSpeakers()与getListener()7.1 音色发现getSpeakers()调用 Mistral 的audio.voices.list({ type: preset, limit: 100 })返回最多 100 个预设音色见 voice/mistral/src/index.ts。每个音色对象包含字段类型说明voiceIdstring音色唯一标识UUIDnamestring音色显示名languagesstring[]该音色支持的语言genderstring \| null音色性别测试 voice/mistral/src/index.test.ts 断言返回数组非空且每条记录至少包含voiceId与name。一个值得注意的细节getSpeakers()返回的是 UUID 形式的预设音色 ID而默认音色en_paul_neutral是一个命名字符串别名——TTS 端点接受它但它并不出现在预设列表里见 docs/src/content/en/integrations/voice/mistral.mdx。7.2 监听能力上报getListener()固定返回{ enabled: true }向框架声明该供应商具备 STT 能力见 voice/mistral/src/index.ts。在基类MastraVoice中该方法默认返回{ enabled: false }由各供应商按自身能力覆写见 packages/_internals/voice/src/voice/voice.ts。八、与CompositeVoice组合使用在实际的 Agent 应用中通常需要同时具备听得懂和说得出的能力。README见 voice/mistral/README.md展示了通过CompositeVoice将 STT 与 TTS 组装在一起的标准姿势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 });这样上层只需面向一个voice对象分别调用listen输入与speak输出底层再根据需求替换为不同的供应商实现如 OpenAI、ElevenLabs 等实现供应商级别的可插拔。九、能力边界与注意事项结合官方文档 docs/src/content/en/integrations/voice/mistral.mdx 的 Notes 部分使用时有几点限制需要留意API Key可通过构造函数传入也可直接依赖MISTRAL_API_KEY环境变量两者取其一即可TTS 语言支持9 种——英语、法语、西班牙语、葡萄牙语、意大利语、荷兰语、德语、印地语、阿拉伯语STT 语言支持13 种——英语、中文、印地语、西班牙语、阿拉伯语、法语、葡萄牙语、俄语、德语、日语、韩语、意大利语、荷兰语TTS 输入长度单次请求建议控制在 300 词以内以获得最佳合成效果STT 音频时长单次请求最长支持 3 小时音频音色克隆refAudio参考音频最短需 2-3 秒默认音色别名en_paul_neutral是命名字符串别名不在getSpeakers()返回的 UUID 列表中属预期行为。十、延伸阅读供应商入口与完整类型定义voice/mistral/src/index.ts官方集成文档docs/src/content/en/integrations/voice/mistral.mdx使用说明与安装指南voice/mistral/README.md集成测试覆盖 speak/listen/getSpeakers/错误处理voice/mistral/src/index.test.ts包元信息依赖、Node 版本要求、导出结构voice/mistral/package.json语音供应商抽象基类与接口契约packages/_internals/voice/src/voice/voice.ts【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考