文字轉語音（TTS）

Mastra 的文字轉語音（TTS）提供統一 API，可透過 Provider 將文字合成為語音音訊。 在應用程式中加入 TTS，可透過自然的語音互動改善使用者體驗及視障使用者的無障礙體驗，亦可建立更具吸引力的多模態介面。

TTS 是所有語音應用程式的核心元件。配合 STT（語音轉文字），即可構成語音互動系統的基礎。較新的模型支援可用於即時互動的 STS（語音轉語音），但成本較高（$）。

設定

要在 Mastra 使用 TTS，初始化語音 Provider 時需提供 speechModel，當中包括以下參數：

• name：要使用的特定 TTS 模型。
• apiKey：用於驗證身分的 API 金鑰。
• Provider 專用選項：特定語音 Provider 可能要求或支援的其他選項。

speaker 選項讓你選擇不同聲線來合成語音。每個 Provider 提供的聲線選項在聲線多樣性、質素、聲線個性及多語言支援方面各有特色。

行為：以上參數全部均為選填。你可以使用語音 Provider 提供的預設設定，實際設定視乎所用 Provider。

const voice = new OpenAIVoice({
  speechModel: {
    name: 'tts-1-hd',
    apiKey: process.env.OPENAI_API_KEY,
  },
  speaker: 'alloy',
})

// If using default settings the configuration can be simplified to:
const voice = new OpenAIVoice()

可用的 Provider

Mastra 支援多個文字轉語音 Provider，各有獨特功能及聲線選項。你可選擇最符合應用程式需要的 Provider：

• OpenAI：提供具自然語調及表達力的高質素聲線
• Azure：Microsoft 的多聲線及多語言語音服務
• ElevenLabs：極為逼真的情感聲線及精細控制
• PlayAI：專門提供多種風格的自然聲線
• Google：Google 支援多語言的語音合成服務
• Cloudflare：針對低延遲應用程式最佳化的邊緣語音合成
• Deepgram：由 AI 驅動的高準確度語音技術
• Speechify：針對可讀性及無障礙體驗最佳化的文字轉語音
• Sarvam：專門處理印度語言及口音
• Murf：具可自訂參數的錄音室級旁白

每個 Provider 均以獨立套件實作，你可按需要安裝：

pnpm add @mastra/voice-openai@latest  # Example for OpenAI

使用 speak 方法

TTS 的主要方法是 speak()，用於把文字轉換成語音。此方法接受選項，讓你指定聲線及其他 Provider 專用設定。用法如下：

import { Agent } from '@mastra/core/agent'
import { OpenAIVoice } from '@mastra/voice-openai'

const voice = new OpenAIVoice()

const agent = new Agent({
  id: 'voice-agent',
  name: 'Voice Agent',
  instructions: 'You are a voice assistant that can help users with their tasks.',
  model: 'openai/gpt-5.6-sol',
  voice,
})

const { text } = await agent.generate('What color is the sky?')

// Convert text to speech to an Audio Stream
const readableStream = await voice.speak(text, {
  speaker: 'default', // Optional: specify a speaker
  properties: {
    speed: 1.0, // Optional: adjust speech speed
    pitch: 'default', // Optional: specify pitch if supported
  },
})

儲存語音輸出

speak() 方法會傳回音訊串流。如需儲存產生的語音以供稍後播放或處理，請把串流 pipe 至檔案：

import { createWriteStream } from 'fs'
import path from 'path'

const audio = await agent.voice.speak('Hello, world!')
const filePath = path.join(process.cwd(), 'agent.mp3')
const writer = createWriteStream(filePath)

audio.pipe(writer)

await new Promise<void>((resolve, reject) => {
  writer.on('finish', () => resolve())
  writer.on('error', reject)
})

如需 Agent 語音 Provider 的完整概覽，請參閱 Mastra 中的 Voice。