DocsReferenceVoiceElevenLabs

ElevenLabs

The ElevenLabs voice implementation in Mastra provides high-quality text-to-speech (TTS) and speech-to-text (STT) capabilities using the ElevenLabs API.

Usage Example

import { ElevenLabsVoice } from "@mastra/voice-elevenlabs";
 
// Initialize with default configuration (uses ELEVENLABS_API_KEY environment variable)
const voice = new ElevenLabsVoice();
 
// Initialize with custom configuration
const voice = new ElevenLabsVoice({
  speechModel: {
    name: 'eleven_multilingual_v2',
    apiKey: 'your-api-key',
  },
  speaker: 'custom-speaker-id',
});
 
// Text-to-Speech
const audioStream = await voice.speak("Hello, world!");
 
// Get available speakers
const speakers = await voice.getSpeakers();

Constructor Parameters

speechModel?:

ElevenLabsVoiceConfig
= { name: 'eleven_multilingual_v2' }
Configuration for text-to-speech functionality.

speaker?:

string
= '9BWtsMINqrJLrRacOk9x' (Aria voice)
ID of the speaker to use for text-to-speech

ElevenLabsVoiceConfig

name?:

ElevenLabsModel
= 'eleven_multilingual_v2'
The ElevenLabs model to use

apiKey?:

string
ElevenLabs API key. Falls back to ELEVENLABS_API_KEY environment variable

Methods

speak()

Converts text to speech using the configured speech model and voice.

input:

string | NodeJS.ReadableStream
Text to convert to speech. If a stream is provided, it will be converted to text first.

options?:

object
Additional options for speech synthesis

options.speaker?:

string
Override the default speaker ID for this request

Returns: Promise<NodeJS.ReadableStream>

getSpeakers()

Returns an array of available voice options, where each node contains:

voiceId:

string
Unique identifier for the voice

name:

string
Display name of the voice

language:

string
Language code for the voice

gender:

string
Gender of the voice

listen()

Converts audio input to text using ElevenLabs Speech-to-Text API.

input:

NodeJS.ReadableStream
A readable stream containing the audio data to transcribe

options?:

object
Configuration options for the transcription

The options object supports the following properties:

language_code?:

string
ISO language code (e.g., 'en', 'fr', 'es')

tag_audio_events?:

boolean
Whether to tag audio events like [MUSIC], [LAUGHTER], etc.

num_speakers?:

number
Number of speakers to detect in the audio

filetype?:

string
Audio file format (e.g., 'mp3', 'wav', 'ogg')

timeoutInSeconds?:

number
Request timeout in seconds

maxRetries?:

number
Maximum number of retry attempts

abortSignal?:

AbortSignal
Signal to abort the request

Returns: Promise<string> - A Promise that resolves to the transcribed text

Important Notes

  1. An ElevenLabs API key is required. Set it via the ELEVENLABS_API_KEY environment variable or pass it in the constructor.
  2. The default speaker is set to Aria (ID: ‘9BWtsMINqrJLrRacOk9x’).
  3. Speech-to-text functionality is not supported by ElevenLabs.
  4. Available speakers can be retrieved using the getSpeakers() method, which returns detailed information about each voice including language and gender.
DeepgramGoogle