> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/llms.txt

# 文字轉語音（TTS）

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

TTS 是所有語音應用程式的核心元件。搭配 STT（語音轉文字）後，兩者會構成語音互動系統的基礎。較新的模型支援可用於即時互動的 STS（[語音轉語音](https://mastra.zisheng.pro/zh-TW/guides/voice/speech-to-speech)），但成本較高（$）。

## 設定

若要在 Mastra 中使用 TTS，初始化 Voice Provider 時必須提供 `speechModel`，其中可包含以下參數：

- **`name`**：要使用的特定 TTS 模型。
- **`apiKey`**：用於身分驗證的 API 金鑰。
- **Provider 特有選項**：特定 Voice Provider 可能需要或支援的其他選項。

**`speaker`** 選項可讓你選擇不同聲音來合成語音。每個 Provider 都提供具有不同**聲音多樣性**、**品質**、**聲音個性**及**多語言支援**特性的聲音選項

**行為**：這些參數均為選填。你可以使用 Voice Provider 提供的預設設定；實際預設值取決於所使用的 Provider。

```typescript
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**](https://mastra.zisheng.pro/zh-TW/reference/voice/openai)：具備自然語調與表情的高品質聲音
- [**Azure**](https://mastra.zisheng.pro/zh-TW/reference/voice/azure)：Microsoft 的語音服務，提供多種聲音與語言
- [**ElevenLabs**](https://mastra.zisheng.pro/zh-TW/reference/voice/elevenlabs)：具有情緒與精細控制的高度擬真聲音
- [**PlayAI**](https://mastra.zisheng.pro/zh-TW/reference/voice/playai)：專精於提供各種風格的自然聲音
- [**Google**](https://mastra.zisheng.pro/zh-TW/reference/voice/google)：Google 的語音合成，支援多種語言
- [**Cloudflare**](https://mastra.zisheng.pro/zh-TW/reference/voice/cloudflare)：針對低延遲應用程式進行邊緣最佳化的語音合成
- [**Deepgram**](https://mastra.zisheng.pro/zh-TW/reference/voice/deepgram)：具備高準確度的 AI 驅動語音技術
- [**Speechify**](https://mastra.zisheng.pro/zh-TW/reference/voice/speechify)：針對可讀性與無障礙體驗最佳化的文字轉語音
- [**Sarvam**](https://mastra.zisheng.pro/zh-TW/reference/voice/sarvam)：專精於印度語言與口音
- [**Murf**](https://mastra.zisheng.pro/zh-TW/reference/voice/murf)：提供可自訂參數的錄音室品質配音

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

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

## 使用 speak 方法

TTS 的主要方法是 `speak()`，可將文字轉換成語音。此方法接受選項，讓你指定 speaker 與其他 Provider 特有選項。用法如下：

```typescript
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()` 方法會傳回音訊串流。若要儲存產生的語音供日後播放或處理，請將串流導向檔案：

```typescript
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 上 Voice Provider 的整體概覽，請參閱 [Mastra 中的 Voice](https://mastra.zisheng.pro/zh-TW/guides/voice/overview)。