跳到主要内容

Inworld

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

对于实时全双工语音到语音交互，同一软件包还导出了 InworldRealtimeVoice。

使用示例
使用示例的直接链接

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
= { name: 'inworld-tts-2' }
文本转语音功能的配置。
InworldVoiceConfig

name?:

'inworld-tts-2' | 'inworld-tts-1.5-max' | 'inworld-tts-1.5-mini'
要使用的 Inworld TTS 模型。

apiKey?:

string
Inworld API key。未提供时使用 INWORLD_API_KEY 环境变量。

listeningModel?:

InworldListeningConfig
= { name: 'groq/whisper-large-v3' }
语音转文本功能的配置。
InworldListeningConfig

name?:

'groq/whisper-large-v3'
要使用的 Inworld STT 模型。

apiKey?:

string
Inworld API key。未提供时使用 INWORLD_API_KEY 环境变量。

speaker?:

string
= 'Dennis'
用于文本转语音的默认音色 ID。

audioEncoding?:

'LINEAR16' | 'MP3' | 'OGG_OPUS' | 'ALAW' | 'MULAW' | 'FLAC' | 'PCM' | 'WAV'
= 'MP3'
TTS 输出的默认音频编码。

sampleRateHertz?:

number
= 48000
TTS 输出的默认采样率。

language?:

string
= 'en-US'
STT 的默认 BCP-47 语言代码。

方法
方法的直接链接

speak(input, options?)
speakinput-options的直接链接

使用 Inworld 的流式 TTS 端点将文本转换为语音。返回一个可读流，在音频分块到达时逐步发出。

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
语音合成的其他选项。
InworldSpeakOptions

speaker?:

string
为本次请求覆盖默认 speaker。

audioEncoding?:

AudioEncoding
覆盖默认音频编码。

sampleRateHertz?:

number
覆盖默认采样率。

speakingRate?:

number
调整语速。

temperature?:

number
控制音色变化程度。inworld-tts-1.5-* 模型会采用此设置，inworld-tts-2 则会忽略。

deliveryMode?:

'STABLE' | 'BALANCED' | 'CREATIVE'
用于控制表达风格的引导设置。仅 inworld-tts-2 会采用。

language?:

string
本次请求的 BCP-47 语言代码。省略时会自动检测。

返回： Promise<NodeJS.ReadableStream>

listen(input, options?)
listeninput-options的直接链接

使用 Inworld 的批量 STT 端点将语音转换为文本。

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

input:

NodeJS.ReadableStream
要转写的音频流。

options?:

InworldListenOptions
转写的其他选项。
InworldListenOptions

audioEncoding?:

'LINEAR16' | 'MP3' | 'OGG_OPUS' | 'FLAC' | 'AUTO_DETECT'
输入流的音频编码。

sampleRateHertz?:

number
输入音频的采样率。

language?:

string
转写所使用的 BCP-47 语言代码。

numberOfChannels?:

number
输入音频的声道数。

返回： Promise<string>

getSpeakers()
getspeakers的直接链接

返回 Inworld API 提供的可用音色列表。

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 相比，以较低的语音质量换取更低延迟。
On this page