> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/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 金鑰（並非 Azure OpenAI 金鑰）。如未提供，會改用 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 金鑰（並非 Azure OpenAI 金鑰）。如未提供，會改用 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`): 要轉換成語音的文字或文字串流。

**options** (`Options`): 設定選項。

**options.speaker** (`string`): 語音合成所用的語音 ID（例如 'en-US-JennyNeural'）。會覆寫預設語音。

傳回：`Promise<NodeJS.ReadableStream>` - WAV 格式的音訊串流

### `listen()`

使用 Azure 的語音轉文字服務轉錄音訊。

**audioStream** (`NodeJS.ReadableStream`): 要轉錄的音訊串流。必須是 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 訂閱金鑰（可在 Azure Portal 的「Speech Services」下取得）
- 兩者是獨立的 Azure 資源，使用不同的 API 金鑰及端點

### 環境變數

你可以透過建構函數選項或環境變數提供 API 金鑰及區域：

- `AZURE_API_KEY` - 你的 Azure Speech Services 訂閱金鑰
- `AZURE_REGION` - 你的 Azure 區域（例如 'eastus'、'westeurope'）

### 語音功能

- Azure 提供超過 200 種神經網絡語音，涵蓋超過 50 種語言
- 每個語音 ID 均採用以下格式：`{language}-{region}-{name}Neural`（例如 'en-US-JennyNeural'）
- 部分語音支援多種語言或提供高清音質版本
- 音訊輸出為 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)。