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

# 음성.말하기()

그만큼`speak()`메소드는 텍스트를 음성으로 변환하는 모든 Mastra 음성 Provider에서 사용할 수 있는 핵심 기능입니다. 텍스트 입력을 받아 재생하거나 저장할 수 있는 오디오 스트림을 반환합니다.

## 매개변수

**input** (`string | NodeJS.ReadableStream`): 음성으로 변환할 텍스트입니다. 문자열이나 읽기 가능한 텍스트 스트림일 수 있습니다.

**options** (`object`): 음성 합성 옵션

**options.speaker** (`string`): 이 특정 요청에 사용할 음성 ID입니다. 생성자에 설정된 기본 speaker를 재정의합니다.

## 반환 값

다음 중 하나인 `Promise<NodeJS.ReadableStream | void>`를 반환합니다.

- `NodeJS.ReadableStream`: 재생하거나 저장할 수 있는 오디오 데이터 스트림
- `void`: 오디오를 직접 반환하지 않고 이벤트를 통해 오디오를 내보내는 실시간 음성 제공자를 사용하는 경우

## 공급자별 옵션

각 음성 Provider는 구현에 따른 추가 옵션을 지원할 수 있습니다. 다음은 몇 가지 예입니다.

### 오픈AI

**options** (`Options`): 구성 옵션입니다.

**options.speed** (`number`): 말하기 속도 배율입니다. 0.25에서 4.0 사이의 값을 지원합니다.

### 일레븐랩스

**options** (`Options`): 구성 옵션입니다.

**options.stability** (`number`): 음성 안정성입니다. 값이 높을수록 더 안정적이고 표현력이 낮은 음성이 생성됩니다.

**options.similarity\_boost** (`number`): 음성의 선명도와 원본 음성과의 유사도입니다.

### Google

**options** (`Options`): 구성 옵션입니다.

**options.languageCode** (`string`): 음성의 언어 코드(예: 'en-US')입니다.

**options.audioConfig** (`object`): Google Cloud Text-to-Speech API의 오디오 구성 옵션입니다.

### 머프

**options** (`Options`): 구성 옵션입니다.

**options.properties** (`object`): properties 구성입니다.

**options.properties.rate** (`number`): 말하기 속도 배율입니다.

**options.properties.pitch** (`number`): 음성 피치 조정값입니다.

**options.properties.format** (`'MP3' | 'WAV' | 'FLAC' | 'ALAW' | 'ULAW'`): 출력 오디오 형식입니다.

## 사용예

```typescript
import { OpenAIVoice } from '@mastra/voice-openai'
// Initialize a voice provider
const voice = new OpenAIVoice({
  speaker: 'alloy', // Default voice
})
// Basic usage with default settings
const audioStream = await voice.speak('Hello, world!')
// Using a different voice for this specific request
const audioStreamWithDifferentVoice = await voice.speak('Hello again!', {
  speaker: 'nova',
})
// Using provider-specific options
const audioStreamWithOptions = await voice.speak('Hello with options!', {
  speaker: 'echo',
  speed: 1.2, // OpenAI-specific option
})
// Using a text stream as input
import { Readable } from 'stream'
const textStream = Readable.from(['Hello', ' from', ' a', ' stream!'])
const audioStreamFromTextStream = await voice.speak(textStream)
```

## 함께 사용`CompositeVoice`

`CompositeVoice`를 사용하면 `speak()` 메서드가 구성된 말하기 Provider에 작업을 위임합니다.

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

const voice = new CompositeVoice({
  output: new PlayAIVoice(),
  input: new OpenAIVoice(),
})

// This will use the PlayAIVoice provider
const audioStream = 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 speech models
const voice = new CompositeVoice({
  output: elevenlabs.speech('eleven_turbo_v2'), // AI SDK model
  input: openai.transcription('whisper-1'), // AI SDK model
})

// Works the same way
const audioStream = await voice.speak('Hello from AI SDK!')

// Provider-specific options can be passed through
const audioWithOptions = await voice.speak('Hello with options!', {
  speaker: 'Rachel', // ElevenLabs voice
  providerOptions: {
    elevenlabs: {
      stability: 0.5,
      similarity_boost: 0.75,
    },
  },
})
```

AI SDK 통합에 관한 자세한 내용은 [CompositeVoice 참고 문서](https://mastra.zisheng.pro/ko/reference/voice/composite-voice)를 참조하세요.

## 실시간 음성 Provider

`OpenAIRealtimeVoice`와 같은 실시간 음성 Provider를 사용할 때 `speak()` 메서드는 다르게 동작합니다.

- 오디오 스트림을 반환하는 대신 오디오 데이터와 함께 '말하기' 이벤트를 발생시킵니다.
- 오디오 청크를 수신하려면 이벤트 리스너를 등록해야 합니다.

```typescript
import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
import Speaker from '@mastra/node-speaker'

const speaker = new Speaker({
  sampleRate: 24100, // Audio sample rate in Hz - standard for high-quality audio on MacBook Pro
  channels: 1, // Mono audio output (as opposed to stereo which would be 2)
  bitDepth: 16, // Bit depth for audio quality - CD quality standard (16-bit resolution)
})

const voice = new OpenAIRealtimeVoice()
await voice.connect()
// Register event listener for audio chunks
voice.on('speaker', stream => {
  // Handle audio chunk (e.g., play it or save it)
  stream.pipe(speaker)
})
// This will emit 'speaking' events instead of returning a stream
await voice.speak('Hello, this is realtime speech!')
```

## 메모

- `speak()`의 동작은 Provider마다 조금씩 다를 수 있지만 모든 구현은 동일한 기본 인터페이스를 따릅니다.
- 실시간 음성 Provider를 사용할 때 메서드는 오디오 스트림을 직접 반환하지 않고 대신 'speaking' 이벤트를 방출할 수 있습니다.
- 텍스트 스트림이 입력으로 제공되면 Provider는 일반적으로 처리하기 전에 이를 문자열로 변환합니다.
- 반환되는 스트림의 오디오 형식은 Provider마다 다릅니다. 일반적인 형식으로는 MP3, WAV, OGG가 있습니다.
- 최상의 성능을 위해 사용을 마치면 오디오 스트림을 닫거나 종료하는 것이 좋습니다.