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

# CompositeVoice

CompositeVoice 類別可讓您組合不同的 Voice Provider，以執行文字轉語音與語音轉文字作業。當您想為每項作業使用最合適的 Provider 時，這特別實用；例如使用 OpenAI 進行語音轉文字，並使用 PlayAI 進行文字轉語音。

CompositeVoice 同時支援 Mastra Voice Provider 與 AI SDK 模型 Provider

## 建構函式參數

**config** (`object`): 複合語音服務的設定物件

**config.input** (`MastraVoice | TranscriptionModel`): 用於語音轉文字作業的 Voice Provider 或 AI SDK 轉錄模型。AI SDK 模型會自動包裝。

**config.output** (`MastraVoice | SpeechModel`): 用於文字轉語音作業的 Voice Provider 或 AI SDK 語音模型。AI SDK 模型會自動包裝。

**config.realtime** (`MastraVoice`): 用於即時語音轉語音作業的 Voice Provider

## 方法

### `speak()`

使用已設定的語音輸出 Provider 將文字轉換為語音。

**input** (`string | NodeJS.ReadableStream`): 要轉換為語音的文字

**options** (`object`): 傳遞給語音輸出 Provider 的 Provider 專用選項

注意事項：

- 若未設定語音輸出 Provider，此方法會擲回錯誤
- 選項會直接傳遞給已設定的語音輸出 Provider
- 回傳音訊資料流

### `listen()`

使用已設定的聆聽 Provider 將語音轉換為文字。

**audioStream** (`NodeJS.ReadableStream`): 要轉換為文字的音訊資料流

**options** (`object`): 傳遞給聆聽 Provider 的 Provider 專用選項

注意事項：

- 若未設定聆聽 Provider，此方法會擲回錯誤
- 選項會直接傳遞給已設定的聆聽 Provider
- 視 Provider 而定，回傳字串或轉錄文字資料流

### `getSpeakers()`

回傳語音輸出 Provider 的可用語音清單，其中每個節點包含：

**voiceId** (`string`): 語音的唯一識別碼

**key** (`value`): 依 Provider 而異的其他語音屬性（例如名稱、語言）

注意事項：

- 僅回傳語音輸出 Provider 的語音
- 若未設定語音輸出 Provider，則回傳空陣列
- 每個語音物件至少會有一個 voiceId 屬性
- 其他語音屬性取決於語音輸出 Provider

## 使用範例

### 使用 Mastra Voice Provider

```typescript
import { CompositeVoice } from '@mastra/core/voice'
import { OpenAIVoice } from '@mastra/voice-openai'
import { PlayAIVoice } from '@mastra/voice-playai'

// Create voice providers
const openai = new OpenAIVoice()
const playai = new PlayAIVoice()

// Use OpenAI for listening (speech-to-text) and PlayAI for speaking (text-to-speech)
const voice = new CompositeVoice({
  input: openai,
  output: playai,
})

// Convert speech to text using OpenAI
const text = await voice.listen(audioStream)

// Convert text to speech using PlayAI
const audio = await voice.speak('Hello, world!')
```

### 使用 AI SDK 模型 Provider

您可以直接將 AI SDK 轉錄與語音模型傳入 CompositeVoice：

```typescript
import { CompositeVoice } from '@mastra/core/voice'
import { openai } from '@ai-sdk/openai'
import { elevenlabs } from '@ai-sdk/elevenlabs'

// Use AI SDK models directly - they will be auto-wrapped
const voice = new CompositeVoice({
  input: openai.transcription('whisper-1'), // AI SDK transcription
  output: elevenlabs.speech('eleven_turbo_v2'), // AI SDK speech
})

// Works the same way as with Mastra providers
const text = await voice.listen(audioStream)
const audio = await voice.speak('Hello from AI SDK!')
```

### 混合搭配

您可以組合 Mastra Provider 與 AI SDK 模型：

```typescript
import { CompositeVoice } from '@mastra/core/voice'
import { PlayAIVoice } from '@mastra/voice-playai'
import { groq } from '@ai-sdk/groq'

const voice = new CompositeVoice({
  input: groq.transcription('whisper-large-v3'), // AI SDK for STT
  output: new PlayAIVoice(), // Mastra for TTS
})
```