Skip to main content

Speechify

The Speechify voice implementation in Mastra provides text-to-speech capabilities using Speechify's API.

Usage example
Direct link to Usage example

import { SpeechifyVoice } from '@mastra/voice-speechify'

// Initialize with default configuration (uses SPEECHIFY_API_KEY environment variable)
const voice = new SpeechifyVoice()

// Initialize with custom configuration
const voice = new SpeechifyVoice({
  speechModel: {
    name: 'simba-3.5',
    apiKey: 'your-api-key',
  },
  speaker: 'harper_32', // Default voice
})

// Convert text to speech
const audioStream = await voice.speak('Hello, world!', {
  speaker: 'imogen_32', // Override default voice
})

// Any voice speaks any of simba-3.5's 48 languages
const portuguese = await voice.speak('Olá, mundo!', { language: 'pt-BR' })

Constructor parameters
Direct link to Constructor parameters

speechModel?:

SpeechifyConfig
= { name: 'simba-3.5' }
Configuration for text-to-speech functionality
SpeechifyConfig

name?:

SpeechifyModel
The Speechify model to use ('simba-3.5', 'simba-3.2', 'simba-3.0', or the legacy 'simba-english' and 'simba-multilingual')

apiKey?:

string
Speechify API key. Falls back to SPEECHIFY_API_KEY environment variable

speaker?:

SpeechifyVoiceId
= 'harper_32' for the Simba 3 models, otherwise 'george'
Default voice ID to use for speech synthesis. Any id from Speechify's catalog; every catalog voice works on simba-3.5. simba-3.2 accepts English voices only

Methods
Direct link to Methods

speak()
Direct link to 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?:

Options
Configuration options.
Options

speaker?:

string
Override the default speaker for this request

model?:

SpeechifyModel
Override the default model for this request

language?:

string
Locale of the text, such as 'pt-BR'. On simba-3.5 any voice speaks it

audioFormat?:

'mp3' | 'ogg' | 'aac' | 'pcm'
Container of the audio stream

outputFormat?:

string
Sample rate and bitrate, such as 'mp3_24000_128' or 'pcm_16000'

options?:

object
Synthesis switches such as { loudness_normalization: true }

Returns: Promise<NodeJS.ReadableStream>

getSpeakers()
Direct link to getspeakers

Returns every voice the API key can use, read live from Speechify's catalog. Each entry 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

models:

string[]
Models that render this voice

listen()
Direct link to listen

This method isn't supported by Speechify and will throw an error. Speechify doesn't provide speech-to-text functionality.

Notes
Direct link to Notes

  • Speechify requires an API key for authentication
  • The default model is 'simba-3.5', Speechify's recommended model: 48 languages on one id, and every catalog voice speaks all of them
  • 'simba-3.2' is English only; a non-English voice returns an error
  • 'simba-3.0' covers English, German, Spanish, French, Italian and Portuguese
  • 'simba-english' and 'simba-multilingual' are legacy ids. New workspaces get a 'model_retired' error, and from 2026-11-21 they are served by 'simba-3.2' and 'simba-3.5'
  • The default speaker follows the configured model: 'harper_32' for the Simba 3 models, otherwise 'george'
  • Speech-to-text functionality isn't supported
  • Additional audio stream options can be passed through the speak() method's options parameter
On this page