voice.getSpeakers()

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

使用範例

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 而異