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

# Inworld

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

如需即時全雙工語音對語音功能，同一個套件亦有匯出 [`InworldRealtimeVoice`](https://mastra.zisheng.pro/zh-HK/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)
```

## Constructor 參數

**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 key。未提供時會改用 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 key。未提供時會改用 INWORLD\_API\_KEY 環境變數。

**speaker** (`string`): 文字轉語音所使用的預設 voice 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 endpoint 將文字轉換成語音。它會傳回 readable stream，並在收到音訊分段時逐步輸出。

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

**input** (`string | NodeJS.ReadableStream`): 要轉換成語音的文字。如提供 stream，系統會先將其轉換成文字。

**options** (`InworldSpeakOptions`): 語音合成的其他選項。

**options.speaker** (`string`): 在此請求中覆寫預設 speaker。

**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 endpoint 將語音轉換成文字。

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

**input** (`NodeJS.ReadableStream`): 要轉錄的音訊 stream。

**options** (`InworldListenOptions`): 轉錄的其他選項。

**options.audioEncoding** (`'LINEAR16' | 'MP3' | 'OGG_OPUS' | 'FLAC' | 'AUTO_DETECT'`): 輸入 stream 的音訊編碼。

**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 endpoint 使用漸進式 NDJSON 串流，因此在收到完整回應前已可開始播放音訊。
- API key 可透過 `speechModel` 或 `listeningModel` 設定提供，亦可使用 `INWORLD_API_KEY` 環境變數。TTS 與 STT key 會分開解析：傳入不同的 `speechModel.apiKey` 與 `listeningModel.apiKey` 值，可讓各項服務使用各自的憑證。如只提供其中一個，系統會先將它重用於兩項服務，然後才以環境變數作為 fallback。
- `inworld-tts-2` 是預設的旗艦 model。可使用 `deliveryMode`（`STABLE` | `BALANCED` | `CREATIVE`）引導此 model 的演繹風格。`inworld-tts-2` 會忽略 `temperature` 選項。
- 相較於 `inworld-tts-1.5-max`，`inworld-tts-1.5-mini` model 以較低的語音質素換取更短的延遲。