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

# voice.getSpeakers()

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

## 使用範例

```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 會 resolve 為語音選項陣列。每個選項至少包含 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` 屬性，但其他中繼資料會因 Provider 而異