voice.getSpeakers()

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

使用範例

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 屬性，但額外中繼資料各有不同