跳至主要內容

Inworld

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

如需即時全雙工語音對語音功能，同一個套件亦有匯出 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)

Constructor 參數
Constructor 參數 的直接連結

speechModel?:

InworldVoiceConfig
= { name: 'inworld-tts-2' }
文字轉語音功能的設定。
InworldVoiceConfig

name?:

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

apiKey?:

string
Inworld API key。未提供時會改用 INWORLD_API_KEY 環境變數。

listeningModel?:

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

name?:

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

apiKey?:

string
Inworld API key。未提供時會改用 INWORLD_API_KEY 環境變數。

speaker?:

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

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
語音合成的其他選項。
InworldSpeakOptions

speaker?:

string
在此請求中覆寫預設 speaker。

audioEncoding?:

AudioEncoding
覆寫預設音訊編碼。

sampleRateHertz?:

number
覆寫預設取樣率。

speakingRate?:

number
調整說話速度。

temperature?:

number
控制聲音變化程度。inworld-tts-1.5-* model 會採用此設定；inworld-tts-2 則會忽略。

deliveryMode?:

'STABLE' | 'BALANCED' | 'CREATIVE'
用於引導演繹風格的控制設定。只有 inworld-tts-2 會採用此設定。

language?:

string
此請求的 BCP-47 語言代碼。省略時會自動偵測。

傳回： Promise<NodeJS.ReadableStream>

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

使用 Inworld 的批次 STT endpoint 將語音轉換成文字。

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

input:

NodeJS.ReadableStream
要轉錄的音訊 stream。

options?:

InworldListenOptions
轉錄的其他選項。
InworldListenOptions

audioEncoding?:

'LINEAR16' | 'MP3' | 'OGG_OPUS' | 'FLAC' | 'AUTO_DETECT'
輸入 stream 的音訊編碼。

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 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 以較低的語音質素換取更短的延遲。
On this page