> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/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 提供涵蓋 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)。