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

# 인월드

Mastra의 Inworld 음성 구현은 Inworld AI의 API를 사용하여 스트리밍 TTS(텍스트 음성 변환) 및 일괄 음성 텍스트 변환(STT) 기능을 제공합니다. 여러 TTS 및 STT Model, 구성 가능한 오디오 인코딩 및 프로그레시브 오디오 스트리밍을 지원합니다.

실시간 전이중 음성 대 음성의 경우 동일한 패키지를 내보냅니다.[`InworldRealtimeVoice`](https://mastra.zisheng.pro/ko/reference/voice/inworld-realtime).

## 사용예

```typescript
import { InworldVoice } from '@mastra/voice-inworld'

// Initialize with default configuration (uses INWORLD_API_KEY environment variable)
const voice = new InworldVoice()

// Initialize with custom configuration
const voice = new InworldVoice({
  speechModel: {
    name: 'inworld-tts-2',
    apiKey: 'your-api-key',
  },
  listeningModel: {
    name: 'groq/whisper-large-v3',
    apiKey: 'your-api-key',
  },
  speaker: 'Dennis',
})

// Text-to-Speech (streaming)
const audioStream = await voice.speak('Hello, world!')

// Speech-to-Text
const transcript = await voice.listen(audioStream)
```

## 생성자 매개변수

**speechModel** (`InworldVoiceConfig`): 텍스트 음성 변환 기능의 구성입니다. (Default: `{ name: 'inworld-tts-2' }`)

**speechModel.name** (`'inworld-tts-2' | 'inworld-tts-1.5-max' | 'inworld-tts-1.5-mini'`): 사용할 Inworld TTS Model입니다.

**speechModel.apiKey** (`string`): Inworld API 키입니다. 지정하지 않으면 INWORLD\_API\_KEY 환경 변수를 사용합니다.

**listeningModel** (`InworldListeningConfig`): 음성을 텍스트로 변환하는 기능의 구성입니다. (Default: `{ name: 'groq/whisper-large-v3' }`)

**listeningModel.name** (`'groq/whisper-large-v3'`): 사용할 Inworld STT Model입니다.

**listeningModel.apiKey** (`string`): Inworld API 키입니다. 지정하지 않으면 INWORLD\_API\_KEY 환경 변수를 사용합니다.

**speaker** (`string`): 텍스트 음성 변환에 사용할 기본 음성 ID입니다. (Default: `'Dennis'`)

**audioEncoding** (`'LINEAR16' | 'MP3' | 'OGG_OPUS' | 'ALAW' | 'MULAW' | 'FLAC' | 'PCM' | 'WAV'`): TTS 출력의 기본 오디오 인코딩입니다. (Default: `'MP3'`)

**sampleRateHertz** (`number`): TTS 출력의 기본 샘플 레이트입니다. (Default: `48000`)

**language** (`string`): STT의 기본 BCP-47 언어 코드입니다. (Default: `'en-US'`)

## 행동 양식

### `speak(input, options?)`

Inworld의 스트리밍 TTS 엔드포인트를 사용하여 텍스트를 음성으로 변환합니다. 오디오 청크가 도착하면 점진적으로 내보내는 읽기 가능한 스트림을 반환합니다.

```typescript
const audioStream = await voice.speak('Hello, world!', {
  speaker: 'Olivia',
  audioEncoding: 'WAV',
  sampleRateHertz: 24000,
  speakingRate: 1.2,
  temperature: 0.8,
})
```

**input** (`string | NodeJS.ReadableStream`): 음성으로 변환할 텍스트입니다. 스트림을 제공하면 먼저 텍스트로 변환합니다.

**options** (`InworldSpeakOptions`): 음성 합성을 위한 추가 옵션입니다.

**options.speaker** (`string`): 이 요청에서 기본 화자를 재정의합니다.

**options.audioEncoding** (`AudioEncoding`): 기본 오디오 인코딩을 재정의합니다.

**options.sampleRateHertz** (`number`): 기본 샘플 레이트를 재정의합니다.

**options.speakingRate** (`number`): 말하기 속도를 조정합니다.

**options.temperature** (`number`): 음성의 변동성을 제어합니다. inworld-tts-1.5-\* Model에서는 적용되며 inworld-tts-2에서는 무시됩니다.

**options.deliveryMode** (`'STABLE' | 'BALANCED' | 'CREATIVE'`): 전달 스타일을 조정하는 제어 옵션입니다. inworld-tts-2에서만 적용됩니다.

**options.language** (`string`): 이 요청의 BCP-47 언어 코드입니다. 생략하면 자동으로 감지됩니다.

**보고:** `Promise<NodeJS.ReadableStream>`

### `listen(input, options?)`

Inworld의 일괄 STT 엔드포인트를 사용하여 음성을 텍스트로 변환합니다.

```typescript
const transcript = await voice.listen(audioStream, {
  audioEncoding: 'MP3',
  sampleRateHertz: 44100,
  language: 'ja-JP',
})
```

**input** (`NodeJS.ReadableStream`): 텍스트로 변환할 오디오 스트림입니다.

**options** (`InworldListenOptions`): 음성 인식을 위한 추가 옵션입니다.

**options.audioEncoding** (`'LINEAR16' | 'MP3' | 'OGG_OPUS' | 'FLAC' | 'AUTO_DETECT'`): 입력 스트림의 오디오 인코딩입니다.

**options.sampleRateHertz** (`number`): 입력 오디오의 샘플 레이트입니다.

**options.language** (`string`): 음성 인식에 사용할 BCP-47 언어 코드입니다.

**options.numberOfChannels** (`number`): 입력의 오디오 채널 수입니다.

**보고:** `Promise<string>`

### `getSpeakers()`

Inworld API에서 사용 가능한 음성 목록을 반환합니다.

```typescript
const speakers = await voice.getSpeakers()
// [{ voiceId: 'Dennis', name: 'Dennis', language: 'en', description: '...', tags: ['friendly'], source: 'SYSTEM' }, ...]
```

**보고:** `Promise<Array<{ voiceId: string; name: string; language: string; description: string; tags: string[]; source: string }>>`

## 메모

- TTS 엔드포인트는 점진적 NDJSON 스트리밍을 사용하므로 전체 응답을 수신하기 전에 오디오 재생을 시작할 수 있습니다.
- API 키는 `speechModel` 또는 `listeningModel` 구성이나 `INWORLD_API_KEY` 환경 변수를 통해 제공할 수 있습니다. TTS와 STT 키는 독립적으로 결정됩니다. 서로 다른 `speechModel.apiKey` 및 `listeningModel.apiKey` 값을 전달하면 각 서비스에서 자체 자격 증명을 사용할 수 있습니다. 하나만 제공하면 환경 변수를 사용하기 전에 두 서비스 모두에서 대체 값으로 재사용합니다.
- `inworld-tts-2`는 기본 플래그십 Model입니다. 이 Model에서 전달 스타일을 조정하려면 `deliveryMode` (`STABLE` | `BALANCED` | `CREATIVE`)를 사용하세요. `inworld-tts-2`에서는 `temperature` 옵션이 무시됩니다.
- `inworld-tts-1.5-mini` Model은 `inworld-tts-1.5-max`보다 음성 품질이 낮은 대신 지연 시간이 더 짧습니다.