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

# Inworld

Mastra 中的 Inworld 语音实现使用 Inworld AI API 提供流式文本转语音（TTS）和批量语音转文本（STT）功能。它支持多种 TTS 和 STT 模型、可配置的音频编码以及渐进式音频流。

对于实时全双工语音到语音交互，同一软件包还导出了 [`InworldRealtimeVoice`](https://mastra.zisheng.pro/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 key。未提供时使用 INWORLD\_API\_KEY 环境变量。

**listeningModel** (`InworldListeningConfig`): 语音转文本功能的配置。 (Default: `{ name: 'groq/whisper-large-v3' }`)

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

**listeningModel.apiKey** (`string`): Inworld API key。未提供时使用 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`): 为本次请求覆盖默认 speaker。

**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 流，因此可以在收到完整响应前开始播放音频。
- 可以通过 `speechModel` 或 `listeningModel` 配置，或 `INWORLD_API_KEY` 环境变量提供 API key。TTS 和 STT 的 key 会独立解析：分别传入 `speechModel.apiKey` 和 `listeningModel.apiKey`，可让每项服务使用自己的凭据。如果只提供一个，则会先将其作为两项服务的备用 key，再回退到环境变量。
- `inworld-tts-2` 是默认旗舰模型。在此模型上可使用 `deliveryMode`（`STABLE` | `BALANCED` | `CREATIVE`）引导表达风格。不过，`temperature` 选项会被 `inworld-tts-2` 忽略。
- `inworld-tts-1.5-mini` 模型与 `inworld-tts-1.5-max` 相比，以较低的语音质量换取更低延迟。