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

# Azure

Mastra 中的 AzureVoice 类使用 Microsoft Azure Cognitive Services 提供文本转语音和语音转文本能力。

## 用法示例

这需要 Azure Speech Services 凭据，可通过环境变量提供，也可直接在配置中提供：

```typescript
import { AzureVoice } from '@mastra/voice-azure'

// Initialize with configuration
const voice = new AzureVoice({
  speechModel: {
    apiKey: 'your-azure-speech-api-key', // Or use AZURE_API_KEY env var
    region: 'eastus', // Or use AZURE_REGION env var
    voiceName: 'en-US-AriaNeural', // Optional: specific voice for TTS
  },
  listeningModel: {
    apiKey: 'your-azure-speech-api-key', // Or use AZURE_API_KEY env var
    region: 'eastus', // Or use AZURE_REGION env var
    language: 'en-US', // Optional: recognition language for STT
  },
  speaker: 'en-US-JennyNeural', // Optional: default voice
})

// Convert text to speech
const audioStream = await voice.speak('Hello, how can I help you?', {
  speaker: 'en-US-GuyNeural', // Optional: override default voice
})

// Convert speech to text
const text = await voice.listen(audioStream)
```

## 配置

### 构造函数选项

**speechModel** (`AzureSpeechConfig`): 文本转语音合成配置。

**speechModel.apiKey** (`string`): Azure Speech Services API key（不是 Azure OpenAI key）。未提供时回退到 AZURE\_API\_KEY 环境变量。

**speechModel.region** (`string`): Azure 区域（例如 'eastus'、'westeurope'）。未提供时回退到 AZURE\_REGION 环境变量。

**speechModel.voiceName** (`string`): 语音合成的语音 ID（例如 'en-US-AriaNeural'、'en-US-JennyNeural'）。仅用于 speechModel。请参阅下方语音列表。

**speechModel.language** (`string`): 识别语言代码（例如 'en-US'、'fr-FR'）。仅用于 listeningModel。

**listeningModel** (`AzureSpeechConfig`): 语音转文本识别配置。

**listeningModel.apiKey** (`string`): Azure Speech Services API key（不是 Azure OpenAI key）。未提供时回退到 AZURE\_API\_KEY 环境变量。

**listeningModel.region** (`string`): Azure 区域（例如 'eastus'、'westeurope'）。未提供时回退到 AZURE\_REGION 环境变量。

**listeningModel.voiceName** (`string`): 语音合成的语音 ID（例如 'en-US-AriaNeural'、'en-US-JennyNeural'）。仅用于 speechModel。请参阅下方语音列表。

**listeningModel.language** (`string`): 识别语言代码（例如 'en-US'、'fr-FR'）。仅用于 listeningModel。

**speaker** (`string`): 用于语音合成的默认语音 ID。

## 方法

### `speak()`

使用 Azure 的神经文本转语音服务将文本转换为语音。

**input** (`string | NodeJS.ReadableStream`): 要转换为语音的文本或文本 stream。

**options** (`Options`): 配置选项。

**options.speaker** (`string`): 用于语音合成的语音 ID（例如 'en-US-JennyNeural'）。会覆盖默认语音。

返回：`Promise<NodeJS.ReadableStream>` - WAV 格式的音频 stream

### `listen()`

使用 Azure 的语音转文本服务转录音频。

**audioStream** (`NodeJS.ReadableStream`): 要转录的音频 stream。必须采用 WAV 格式。

返回：`Promise<string>` - 从音频识别出的文本

语言和识别设置在初始化期间通过 `listeningModel` 配置，而不是作为选项传递给此方法。

### `getSpeakers()`

返回可用语音选项数组（200 多种语音），其中每个节点包含：

**voiceId** (`string`): 语音的唯一标识符（例如 'en-US-JennyNeural'、'fr-FR-DeniseNeural'）

**language** (`string`): 从语音 ID 中提取的语言代码（例如 'en'、'fr'）

**region** (`string`): 从语音 ID 中提取的区域代码（例如 'US'、'GB'、'FR'）

返回：`Promise<Array<{ voiceId: string; language: string; region: string; }>>`

## 重要说明

### Azure Speech Services 与 Azure OpenAI

\*\*⚠️ 重要：\*\*此包使用 **Azure Speech Services**，它与 **Azure OpenAI Services** 不同。

- **不要**为此包使用 `AZURE_OPENAI_API_KEY`
- **请使用** Azure Speech Services 订阅 key（可在 Azure Portal 的“Speech Services”下获取）
- 它们是不同的 Azure 资源，使用不同的 API key 和 endpoint

### 环境变量

可通过构造函数选项或环境变量提供 API key 和区域：

- `AZURE_API_KEY` - 你的 Azure Speech Services 订阅 key
- `AZURE_REGION` - 你的 Azure 区域（例如 'eastus'、'westeurope'）

### 语音能力

- Azure 提供覆盖 50 多种语言的 200 多种神经语音
- 每个语音 ID 都遵循 `{language}-{region}-{name}Neural` 格式（例如 'en-US-JennyNeural'）
- 部分语音支持多语言或提供 HD 高质量变体
- 音频输出采用 WAV 格式
- 用于识别的音频输入必须采用 WAV 格式

## 可用语音

Azure 提供覆盖多种语言的 200 多种神经语音。部分常用英语语音包括：

- **美国英语：**

  - `en-US-AriaNeural`（女性，默认）
  - `en-US-JennyNeural`（女性）
  - `en-US-GuyNeural`（男性）
  - `en-US-DavisNeural`（男性）
  - `en-US-AvaNeural`（女性）
  - `en-US-AndrewNeural`（男性）

- **英国英语：**

  - `en-GB-SoniaNeural`（女性）
  - `en-GB-RyanNeural`（男性）
  - `en-GB-LibbyNeural`（女性）

- **澳大利亚英语：**

  - `en-AU-NatashaNeural`（女性）
  - `en-AU-WilliamNeural`（男性）

要获取全部 200 多种语音的完整列表：

```typescript
const voices = await voice.getSpeakers()
console.log(voices) // Array of { voiceId, language, region }
```

有关更多信息，请参阅 [Azure Neural TTS 文档](https://learn.microsoft.com/en-us/azure/cognitive-services/speech-service/language-support?tabs=tts)。