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

# Murf

Mastra 的 Murf 語音實作使用 Murf 的 AI 語音服務提供文字轉語音（TTS）功能，並支援多種語言的多款語音。

## 使用範例

```typescript
import { MurfVoice } from '@mastra/voice-murf'

// Initialize with default configuration (uses MURF_API_KEY environment variable)
const voice = new MurfVoice()

// Initialize with custom configuration
const voice = new MurfVoice({
  speechModel: {
    name: 'GEN2',
    apiKey: 'your-api-key',
    properties: {
      format: 'MP3',
      rate: 1.0,
      pitch: 1.0,
      sampleRate: 48000,
      channelType: 'STEREO',
    },
  },
  speaker: 'en-US-cooper',
})

// Text-to-Speech with default settings
const audioStream = await voice.speak('Hello, world!')

// Text-to-Speech with custom properties
const audioStream = await voice.speak('Hello, world!', {
  speaker: 'en-UK-hazel',
  properties: {
    format: 'WAV',
    rate: 1.2,
    style: 'casual',
  },
})

// Get available voices
const voices = await voice.getSpeakers()
```

## 建構函式參數

**speechModel** (`MurfConfig`): 文字轉語音功能的設定 (Default: `{ name: 'GEN2' }`)

**speechModel.name** (`'GEN1' | 'GEN2'`): 要使用的 Murf 模型世代

**speechModel.apiKey** (`string`): Murf API 金鑰。若未提供，則使用 MURF\_API\_KEY 環境變數

**speechModel.properties** (`object`): 所有語音合成請求的預設屬性

**speechModel.properties.style** (`string`): 語音的說話風格

**speechModel.properties.rate** (`number`): 語速倍數

**speechModel.properties.pitch** (`number`): 語音音高調整

**speechModel.properties.sampleRate** (`8000 | 24000 | 44100 | 48000`): 音訊取樣率（Hz）

**speechModel.properties.format** (`'MP3' | 'WAV' | 'FLAC' | 'ALAW' | 'ULAW'`): 輸出音訊格式

**speechModel.properties.channelType** (`'STEREO' | 'MONO'`): 音訊聲道設定

**speechModel.properties.pronunciationDictionary** (`Record<string, string>`): 自訂發音對應

**speechModel.properties.encodeAsBase64** (`boolean`): 是否將音訊編碼為 base64

**speechModel.properties.variation** (`number`): 語音變化參數

**speechModel.properties.audioDuration** (`number`): 目標音訊長度（秒）

**speechModel.properties.multiNativeLocale** (`string`): 多語言支援的地區設定

**speaker** (`string`): 文字轉語音所使用的預設語音 ID (Default: `'en-UK-hazel'`)

## 方法

### `speak()`

使用 Murf API 將文字轉換為語音。

**input** (`string | NodeJS.ReadableStream`): 要轉換為語音的文字。如提供串流，會先將其轉換為文字。

**options** (`object`): 語音合成選項

**options.speaker** (`string`): 為此請求覆寫預設說話者

**options.properties** (`object`): 為此請求覆寫預設語音屬性

傳回：`Promise<NodeJS.ReadableStream>`

### `getSpeakers()`

傳回可用語音選項的陣列，每個節點包含：

**voiceId** (`string`): 語音的唯一識別碼

**name** (`string`): 語音的顯示名稱

**language** (`string`): 語音的語言代碼

**gender** (`string`): 語音的性別

### `listen()`

Murf 不支援此方法，呼叫時會擲回錯誤。Murf 不提供語音轉文字功能。

## 重要事項

1. 必須提供 Murf API 金鑰。請透過 `MURF_API_KEY` 環境變數設定，或在建構函式中傳入。
2. 此服務預設使用 GEN2 模型版本。
3. 語音屬性可在建構函式層級設定，亦可按個別請求覆寫。
4. 此服務可透過格式、取樣率及聲道類型等屬性，廣泛自訂音訊。
5. 不支援語音轉文字功能。