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

# Inworld

Mastra 的 Inworld 語音實作使用 Inworld AI 的 API，提供串流文字轉語音 (TTS) 與批次語音轉文字 (STT) 功能。它支援多種 TTS 和 STT 模型、可設定的音訊編碼，以及漸進式音訊串流。

若要進行即時、全雙工的語音對語音互動，同一套件也會匯出 [`InworldRealtimeVoice`](https://mastra.zisheng.pro/zh-TW/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 模型。

**speechModel.apiKey** (`string`): Inworld API 金鑰。未提供時會改用 INWORLD\_API\_KEY 環境變數。

**listeningModel** (`InworldListeningConfig`): 語音轉文字功能的設定。 (Default: `{ name: 'groq/whisper-large-v3' }`)

**listeningModel.name** (`'groq/whisper-large-v3'`): 要使用的 Inworld STT 模型。

**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-\* 模型會採用此設定；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` 是預設的旗艦模型。可使用 `deliveryMode` (`STABLE` | `BALANCED` | `CREATIVE`) 引導此模型的表達風格。`inworld-tts-2` 會忽略 `temperature` 選項。
- 相較於 `inworld-tts-1.5-max`，`inworld-tts-1.5-mini` 模型以較低的語音品質換取更低的延遲。