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

# voice.getSpeakers()

`getSpeakers()` 方法从 Voice Provider 检索可用 Voice 选项（speaker）列表。应用可以向用户展示 Voice 选项，也可以根据不同情境以编程方式选择最合适的 Voice。

## 使用示例

```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`): 一个解析为 Voice 选项数组的 Promise；每个选项至少包含 voiceId 属性，还可能包含特定于 Provider 的其他元数据。

## 特定于 Provider 的元数据

不同 Voice Provider 会为其 Voice 返回不同的元数据：

**OpenAI**:

**voiceId** (`string`): Voice 的唯一标识符（例如 'alloy'、'echo'、'fable'、'onyx'、'nova'、'shimmer'）

**OpenAI Realtime**:

**voiceId** (`string`): Voice 的唯一标识符（例如 'alloy'、'echo'、'fable'、'onyx'、'nova'、'shimmer'）

**Deepgram**:

**voiceId** (`string`): Voice 的唯一标识符

**language** (`string`): 嵌入 Voice ID 的语言代码（例如 'en'）

**ElevenLabs**:

**voiceId** (`string`): Voice 的唯一标识符

**name** (`string`): Voice 的易读名称

**category** (`string`): Voice 类别（例如 'premade'、'cloned'）

**Google**:

**voiceId** (`string`): Voice 的唯一标识符

**languageCodes** (`string[]`): Voice 支持的语言代码数组（例如 \['en-US']）

**Azure**:

**voiceId** (`string`): Voice 的唯一标识符

**language** (`string`): 从 Voice ID 中提取的语言代码（例如 'en'）

**region** (`string`): 从 Voice ID 中提取的地区代码（例如 'US'）

**Murf**:

**voiceId** (`string`): Voice 的唯一标识符

**name** (`string`): Voice 名称（与 voiceId 相同）

**language** (`string`): 从 Voice ID 中提取的语言代码（例如 'en'）

**gender** (`string`): Voice 的性别（当前实现中始终为 'neutral'）

**PlayAI**:

**voiceId** (`string`): Voice 的唯一标识符（指向 manifest.json 的 S3 URL）

**name** (`string`): Voice 的易读名称（例如 'Angelo'、'Arsenio'）

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

**gender** (`string`): Voice 的性别（'M' 或 'F'）

**age** (`string`): Voice 的年龄类别（例如 'Young'、'Middle'）

**style** (`string`): Voice 的说话风格（例如 'Conversational'）

**Speechify**:

**voiceId** (`string`): Voice 的唯一标识符

**name** (`string`): Voice 的易读名称

**language** (`string`): Voice 的语言代码（例如 'en-US'）

**Sarvam**:

**voiceId** (`string`): Voice 的唯一标识符

**name** (`string`): Voice 的易读名称

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

**gender** (`string`): Voice 的性别（'male' 或 'female'）

## 注意事项

- 不同 Provider 提供的 Voice 差异很大
- 某些 Provider 可能需要身份验证才能检索完整的 Voice 列表
- 如果 Provider 不支持此方法，默认实现会返回空数组
- 如果需要频繁显示该列表，出于性能考虑，建议缓存结果
- 所有 Provider 都保证存在 `voiceId` 属性，但其他元数据会有所不同