> Discover all available pages from the documentation index: https://mastra.zisheng.pro/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 key。未提供时使用 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`): 多语言支持所使用的 locale

**speaker** (`string`): 用于文本转语音的默认音色 ID (Default: `'en-UK-hazel'`)

## 方法

### `speak()`

使用 Murf API 将文本转换为语音。

**input** (`string | NodeJS.ReadableStream`): 要转换为语音的文本。如果提供流，会先将其转换为文本。

**options** (`object`): 语音合成选项

**options.speaker** (`string`): 为本次请求覆盖默认 speaker

**options.properties** (`object`): 为本次请求覆盖默认语音属性

返回： `Promise<NodeJS.ReadableStream>`

### `getSpeakers()`

返回可用音色选项数组，其中每个节点包含：

**voiceId** (`string`): 音色的唯一标识符

**name** (`string`): 音色的显示名称

**language** (`string`): 音色的语言代码

**gender** (`string`): 音色的性别

### `listen()`

Murf 不支持此方法，调用时会抛出错误。Murf 不提供语音转文本功能。

## 重要说明

1. 必须提供 Murf API key。请通过 `MURF_API_KEY` 环境变量设置，或在构造函数中传入。
2. 该服务默认使用 GEN2 模型版本。
3. 可以在构造函数层级设置语音属性，并在每次请求中覆盖。
4. 该服务可通过格式、采样率和声道类型等属性对音频进行广泛自定义。
5. 不支持语音转文本功能。