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

# 텍스트 음성 변환(TTS)

Mastra의 TTS(텍스트 음성 변환)는 공급자를 사용하여 텍스트에서 음성 오디오를 합성하기 위한 통합 API를 제공합니다. TTS를 애플리케이션에 통합하면 자연스러운 음성 상호 작용으로 사용자 경험을 향상하고 시각 장애가 있는 사용자의 접근성을 향상할 수 있으며 더욱 매력적인 다중 모드 인터페이스를 만들 수 있습니다.

TTS는 모든 음성 애플리케이션의 핵심 구성 요소입니다. STT(Speech-to-Text)와 결합하여 음성 상호 작용 시스템의 기반을 이룹니다. 최신 Model은 실시간 상호 작용에 사용할 수 있지만 비용($)이 높은 STS([Speech-to-Speech](https://mastra.zisheng.pro/ko/guides/voice/speech-to-speech))를 지원합니다.

## 구성

Mastra에서 TTS를 사용하려면 음성 Provider를 초기화할 때 `speechModel`을 구성하세요. 여기에는 다음과 같은 매개변수가 포함됩니다.

- **`name`**: 사용할 특정 TTS Model입니다.
- **`apiKey`**: 인증을 위한 API 키입니다.
- **공급자별 옵션**: 특정 음성 Provider에서 요구하거나 지원할 수 있는 추가 옵션입니다.

**`speaker`** 옵션을 사용하면 음성 합성에 사용할 다양한 음성을 선택할 수 있습니다. 각 Provider는 **음성 다양성**, **품질**, **음성 개성**, **다국어 지원** 측면에서 서로 다른 특성을 지닌 음성 옵션을 제공합니다. **행동**: 이 매개변수는 모두 선택사항입니다. 사용 중인 특정 공급자에 따라 달라지는 음성 공급자가 제공하는 기본 설정을 사용할 수 있습니다.

```typescript
const voice = new OpenAIVoice({
  speechModel: {
    name: 'tts-1-hd',
    apiKey: process.env.OPENAI_API_KEY,
  },
  speaker: 'alloy',
})

// If using default settings the configuration can be simplified to:
const voice = new OpenAIVoice()
```

## 이용 가능한 Provider

Mastra는 각각 고유한 기능과 음성 옵션을 갖춘 여러 Text-to-Speech Provider를 지원합니다. 애플리케이션 요구 사항에 가장 적합한 Provider를 선택할 수 있습니다.

- [**OpenAI**](https://mastra.zisheng.pro/ko/reference/voice/openai): 자연스러운 억양과 표현력을 갖춘 고품질 음성
- [**Azure**](https://mastra.zisheng.pro/ko/reference/voice/azure): 다양한 음성과 언어를 지원하는 Microsoft의 음성 서비스
- [**ElevenLabs**](https://mastra.zisheng.pro/ko/reference/voice/elevenlabs): 감정 표현과 정교한 제어 기능을 갖춘 매우 사실적인 음성
- [**PlayAI**](https://mastra.zisheng.pro/ko/reference/voice/playai): 다양한 스타일의 자연스러운 음성에 특화
- [**Google**](https://mastra.zisheng.pro/ko/reference/voice/google): 다국어를 지원하는 Google의 음성 합성
- [**Cloudflare**](https://mastra.zisheng.pro/ko/reference/voice/cloudflare): 지연 시간이 짧은 애플리케이션을 위한 엣지 최적화 음성 합성
- [**Deepgram**](https://mastra.zisheng.pro/ko/reference/voice/deepgram): 정확도가 높은 AI 기반 음성 기술
- [**Speechify**](https://mastra.zisheng.pro/ko/reference/voice/speechify): 가독성과 접근성에 최적화된 Text-to-Speech
- [**Sarvam**](https://mastra.zisheng.pro/ko/reference/voice/sarvam): 인도 언어 및 억양에 특화
- [**Murf**](https://mastra.zisheng.pro/ko/reference/voice/murf): 사용자 지정 가능한 매개변수를 갖춘 스튜디오급 음성 해설 각 공급자는 필요에 따라 설치할 수 있는 별도의 패키지로 구현됩니다.

```bash
pnpm add @mastra/voice-openai@latest  # Example for OpenAI
```

## 말하기 방법 사용

TTS의 기본 메서드는 텍스트를 음성으로 변환하는 `speak()`입니다. 이 메서드는 화자 및 기타 Provider별 옵션을 지정할 수 있는 옵션을 받습니다. 사용 방법은 다음과 같습니다.

```typescript
import { Agent } from '@mastra/core/agent'
import { OpenAIVoice } from '@mastra/voice-openai'

const voice = new OpenAIVoice()

const agent = new Agent({
  id: 'voice-agent',
  name: 'Voice Agent',
  instructions: 'You are a voice assistant that can help users with their tasks.',
  model: 'openai/gpt-5.6-sol',
  voice,
})

const { text } = await agent.generate('What color is the sky?')

// Convert text to speech to an Audio Stream
const readableStream = await voice.speak(text, {
  speaker: 'default', // Optional: specify a speaker
  properties: {
    speed: 1.0, // Optional: adjust speech speed
    pitch: 'default', // Optional: specify pitch if supported
  },
})
```

## 음성 출력 저장

`speak()` 메서드는 오디오 스트림을 반환합니다. 생성된 음성을 나중에 재생하거나 처리하기 위해 저장해야 한다면 스트림을 파일로 파이프하세요.

```typescript
import { createWriteStream } from 'fs'
import path from 'path'

const audio = await agent.voice.speak('Hello, world!')
const filePath = path.join(process.cwd(), 'agent.mp3')
const writer = createWriteStream(filePath)

audio.pipe(writer)

await new Promise<void>((resolve, reject) => {
  writer.on('finish', () => resolve())
  writer.on('error', reject)
})
```

Agent의 음성 Provider에 관한 전반적인 개요는 [Mastra의 음성 기능](https://mastra.zisheng.pro/ko/guides/voice/overview)을 참조하세요.