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

# 합성음성

CompositeVoice 클래스를 사용하면 텍스트 음성 변환 및 음성 텍스트 변환 작업을 위해 다양한 음성 공급자를 결합할 수 있습니다. 이는 각 작업에 가장 적합한 공급자를 사용하려는 경우에 특히 유용합니다. 예를 들어 음성-텍스트에는 OpenAI를 사용하고 텍스트-음성에는 PlayAI를 사용합니다.

CompositeVoice는 Mastra 음성 제공자와 AI SDK Model 제공자를 모두 지원합니다.

## 생성자 매개변수

**config** (`object`): 복합 음성 서비스의 구성 객체

**config.input** (`MastraVoice | TranscriptionModel`): 음성 텍스트 변환 작업에 사용할 음성 Provider 또는 AI SDK 전사 Model입니다. AI SDK Model은 자동으로 래핑됩니다.

**config.output** (`MastraVoice | SpeechModel`): 텍스트 음성 변환 작업에 사용할 음성 Provider 또는 AI SDK 음성 Model입니다. AI SDK Model은 자동으로 래핑됩니다.

**config.realtime** (`MastraVoice`): 실시간 음성 대 음성 작업에 사용할 음성 Provider

## 행동 양식

### `speak()`

구성된 말하기 공급자를 사용하여 텍스트를 음성으로 변환합니다.

**input** (`string | NodeJS.ReadableStream`): 음성으로 변환할 텍스트

**options** (`object`): 음성 출력 Provider에 전달할 Provider별 옵션

참고:

- 말하는 제공자가 구성되지 않은 경우 이 메서드는 오류를 발생시킵니다.
- 옵션은 구성된 말하기 제공자에게 전달됩니다.
- 오디오 데이터 스트림을 반환합니다.

### `listen()`

구성된 청취 공급자를 사용하여 음성을 텍스트로 변환합니다.

**audioStream** (`NodeJS.ReadableStream`): 텍스트로 변환할 오디오 스트림

**options** (`object`): 음성 입력 Provider에 전달할 Provider별 옵션

참고:

- 수신 공급자가 구성되지 않은 경우 이 메서드는 오류를 발생시킵니다.
- 옵션은 구성된 청취 제공자에게 전달됩니다.
- 공급자에 따라 문자열 또는 전사된 텍스트 스트림을 반환합니다.

### `getSpeakers()`

말하기 제공자로부터 사용 가능한 음성 목록을 반환합니다. 각 노드에는 다음이 포함됩니다.

**voiceId** (`string`): 음성의 고유 식별자

**key** (`value`): Provider에 따라 달라지는 추가 음성 속성(예: 이름, 언어)

참고:

- 말하는 제공자의 음성만 반환합니다.
- 말하는 제공자가 구성되지 않은 경우 빈 배열을 반환합니다.
- 각 음성 객체에는 최소한 하나의 voiceId 속성이 있습니다.
- 추가 음성 속성은 말하는 제공자에 따라 다릅니다.

## 사용 예

### Mastra 음성 Provider 사용

```typescript
import { CompositeVoice } from '@mastra/core/voice'
import { OpenAIVoice } from '@mastra/voice-openai'
import { PlayAIVoice } from '@mastra/voice-playai'

// Create voice providers
const openai = new OpenAIVoice()
const playai = new PlayAIVoice()

// Use OpenAI for listening (speech-to-text) and PlayAI for speaking (text-to-speech)
const voice = new CompositeVoice({
  input: openai,
  output: playai,
})

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

// Convert text to speech using PlayAI
const audio = await voice.speak('Hello, world!')
```

### AI SDK Model 공급자 사용

AI SDK 전사 및 음성 Model을 CompositeVoice에 직접 전달할 수 있습니다.

```typescript
import { CompositeVoice } from '@mastra/core/voice'
import { openai } from '@ai-sdk/openai'
import { elevenlabs } from '@ai-sdk/elevenlabs'

// Use AI SDK models directly - they will be auto-wrapped
const voice = new CompositeVoice({
  input: openai.transcription('whisper-1'), // AI SDK transcription
  output: elevenlabs.speech('eleven_turbo_v2'), // AI SDK speech
})

// Works the same way as with Mastra providers
const text = await voice.listen(audioStream)
const audio = await voice.speak('Hello from AI SDK!')
```

### 믹스 앤 매치

Mastra 공급자를 AI SDK Model과 결합할 수 있습니다.

```typescript
import { CompositeVoice } from '@mastra/core/voice'
import { PlayAIVoice } from '@mastra/voice-playai'
import { groq } from '@ai-sdk/groq'

const voice = new CompositeVoice({
  input: groq.transcription('whisper-large-v3'), // AI SDK for STT
  output: new PlayAIVoice(), // Mastra for TTS
})
```