Skip to main content

voice.getSpeakers()

The getSpeakers() method retrieves a list of available voice options (speakers) from the voice provider. This allows applications to present users with voice choices or programmatically select the most appropriate voice for different contexts.

Usage ExampleDirect link to Usage Example

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 });

ParametersDirect link to Parameters

This method does not accept any parameters.

Return ValueDirect link to Return Value

Promise<Array<{ voiceId: string } & TSpeakerMetadata>>:

Promise
A promise that resolves to an array of voice options, where each option contains at least a voiceId property and may include additional provider-specific metadata.

Provider-Specific MetadataDirect link to Provider-Specific Metadata

Different voice providers return different metadata for their voices:

voiceId:

string
Unique identifier for the voice (e.g., 'alloy', 'echo', 'fable', 'onyx', 'nova', 'shimmer')

NotesDirect link to Notes

  • The available voices vary significantly between providers
  • Some providers may require authentication to retrieve the full list of voices
  • The default implementation returns an empty array if the provider doesn't support this method
  • For performance reasons, consider caching the results if you need to display the list frequently
  • The voiceId property is guaranteed to be present for all providers, but additional metadata varies

On this page