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

# 하늘빛

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 음성 서비스와 Azure OpenAI

**⚠️ 중요:**&#xC774; 패키지는 **Azure OpenAI Services**와 다른 **Azure Speech Services**를 사용합니다.

- 이 패키지에 `AZURE_OPENAI_API_KEY`를 **사용하지 마세요**.
- Azure Speech Services 구독 키를 **사용하세요**(Azure Portal의 "음성 서비스"에서 받을 수 있음).
- 두 서비스는 API 키와 엔드포인트가 서로 다른 별도의 Azure 리소스입니다.

### 환경변수

API 키와 영역은 생성자 옵션이나 환경 변수를 통해 제공될 수 있습니다.

- `AZURE_API_KEY`- Azure Speech Services 구독 키
- `AZURE_REGION`- Azure 지역(예: 'eastus', 'westeurope')

### 음성 기능

- Azure는 50개 이상의 언어로 200개 이상의 신경 음성을 제공합니다.
- 각 음성 ID는 다음 형식을 따릅니다.`{language}-{region}-{name}Neural` (e.g., '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 documentation](https://learn.microsoft.com/en-us/azure/cognitive-services/speech-service/language-support?tabs=tts).