跳至主要內容

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 金鑰。未提供時會改用 INWORLD_API_KEY 環境變數。

listeningModel?:

InworldListeningConfig
= { name: 'groq/whisper-large-v3' }
語音轉文字功能的設定。
InworldListeningConfig

name?:

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

apiKey?:

string
Inworld API 金鑰。未提供時會改用 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
覆寫此請求的預設說話者。

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 串流，因此可在收到完整回應前開始播放音訊。
  • 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 模型以較低的語音品質換取更低的延遲。
On this page