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

# voice.getSpeakers()

`getSpeakers()` 方法會從語音 Provider 擷取可用的語音選項（講者）清單。應用程式可向用戶提供語音選擇，或以程式方式為不同情境選取最合適的語音。

## 使用範例

```typescript
import { OpenAIVoice } from '@mastra/voice-openai'
import { ElevenLabsVoice } from '@mastra/voice-elevenlabs'

// Initialize voice providers
const openaiVoice = new OpenAIVoice()
const elevenLabsVoice = new ElevenLabsVoice({
  apiKey: process.env.ELEVENLABS_API_KEY,
})

// Get available speakers from OpenAI
const openaiSpeakers = await openaiVoice.getSpeakers()
console.log('OpenAI voices:', openaiSpeakers)
// Example output: [{ voiceId: "alloy" }, { voiceId: "echo" }, { voiceId: "fable" }, ...]

// Get available speakers from ElevenLabs
const elevenLabsSpeakers = await elevenLabsVoice.getSpeakers()
console.log('ElevenLabs voices:', elevenLabsSpeakers)
// Example output: [{ voiceId: "21m00Tcm4TlvDq8ikWAM", name: "Rachel" }, ...]

// Use a specific voice for speech
const text = 'Hello, this is a test of different voices.'
await openaiVoice.speak(text, { speaker: openaiSpeakers[2].voiceId })
await elevenLabsVoice.speak(text, { speaker: elevenLabsSpeakers[0].voiceId })
```

## 參數

此方法不接受任何參數。

## 傳回值

**Promise\<Array<{ voiceId: string } & TSpeakerMetadata>>** (`Promise`): 解析為語音選項陣列的 Promise；每個選項最少包含 voiceId 屬性，亦可能包含 Provider 特定的額外中繼資料。

## Provider 特定的中繼資料

不同語音 Provider 會為其語音傳回不同的中繼資料：

**OpenAI**:

**voiceId** (`string`): 語音的唯一識別碼（例如 'alloy'、'echo'、'fable'、'onyx'、'nova'、'shimmer'）

**OpenAI Realtime**:

**voiceId** (`string`): 語音的唯一識別碼（例如 'alloy'、'echo'、'fable'、'onyx'、'nova'、'shimmer'）

**Deepgram**:

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

**language** (`string`): 嵌入語音 ID 的語言代碼（例如 'en'）

**ElevenLabs**:

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

**name** (`string`): 人類可讀的語音名稱

**category** (`string`): 語音類別（例如 'premade'、'cloned'）

**Google**:

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

**languageCodes** (`string[]`): 語音所支援的語言代碼陣列（例如 \['en-US']）

**Azure**:

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

**language** (`string`): 從語音 ID 擷取的語言代碼（例如 'en'）

**region** (`string`): 從語音 ID 擷取的地區代碼（例如 'US'）

**Murf**:

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

**name** (`string`): 語音名稱（與 voiceId 相同）

**language** (`string`): 從語音 ID 擷取的語言代碼（例如 'en'）

**gender** (`string`): 語音的性別（目前實作一律為 'neutral'）

**PlayAI**:

**voiceId** (`string`): 語音的唯一識別碼（指向 manifest.json 的 S3 URL）

**name** (`string`): 人類可讀的語音名稱（例如 'Angelo'、'Arsenio'）

**accent** (`string`): 語音的口音（例如 'US'、'Irish'、'US African American'）

**gender** (`string`): 語音的性別（'M' 或 'F'）

**age** (`string`): 語音的年齡類別（例如 'Young'、'Middle'）

**style** (`string`): 語音的說話風格（例如 'Conversational'）

**Speechify**:

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

**name** (`string`): 人類可讀的語音名稱

**language** (`string`): 語音的語言代碼（例如 'en-US'）

**Sarvam**:

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

**name** (`string`): 人類可讀的語音名稱

**language** (`string`): 語音的語言（例如 'english'、'hindi'）

**gender** (`string`): 語音的性別（'male' 或 'female'）

## 備註

- 不同 Provider 可用的語音差異很大
- 部分 Provider 可能需要驗證，才能擷取完整的語音清單
- 如 Provider 不支援此方法，預設實作會傳回空陣列
- 基於效能考慮，如需經常顯示清單，可考慮快取結果
- 所有 Provider 均保證包含 `voiceId` 屬性，但額外中繼資料各有不同