TTS (Text-to-Speech) - Complete API Reference
Convert text to natural-sounding speech using ElevenLabs, macOS say, or espeak.
Chat Commands
Synthesize Speech
/speak "Your order has been filled" Speak text aloud /speak "Market alert" --voice rachel Use specific voice /speak "Portfolio up 5%" --speed 1.2 Adjust speed
Voice Management
/voices List available voices /voices preview rachel Preview a voice /voice set rachel Set default voice
Settings
/tts status Check TTS status /tts provider elevenlabs Set provider /tts speed 1.0 Set default speed /tts volume 0.8 Set volume (0-1)
TypeScript API Reference
Create TTS Service
import { createTTSService } from 'clodds/tts';
const tts = createTTSService({ provider: 'elevenlabs', apiKey: process.env.ELEVENLABS_API_KEY,
// Defaults defaultVoice: 'rachel', defaultSpeed: 1.0, defaultPitch: 1.0, });
Synthesize Speech
// Basic synthesis const audio = await tts.synthesize('Hello, your trade was executed.');
// Play immediately await tts.speak('Portfolio value is $10,000');
// With options await tts.speak('Market alert: BTC crossed $100k', { voice: 'josh', speed: 1.2, pitch: 1.0, volume: 0.8, });
Streaming Synthesis
// Stream for long text (lower latency) const stream = await tts.streamSynthesize(longText, { voice: 'rachel', });
stream.on('data', (chunk) => { // Play audio chunks as they arrive audioPlayer.write(chunk); });
stream.on('end', () => { console.log('Synthesis complete'); });
List Voices
// Get available voices const voices = await tts.listVoices();
for (const voice of voices) {
console.log(${voice.id}: ${voice.name});
console.log( Gender: ${voice.gender});
console.log( Accent: ${voice.accent});
console.log( Use case: ${voice.useCase});
}
Voice Preview
// Preview a voice await tts.preview('rachel', 'This is a preview of the Rachel voice.');
Queue Management
// Queue multiple messages tts.queue('First message'); tts.queue('Second message'); tts.queue('Third message');
// Messages play in order
// Clear queue tts.clearQueue();
// Skip current tts.skip();
ElevenLabs Voices
Voice ID Name Gender Accent Best For
rachel
Rachel F American Narration
domi
Domi F American Conversational
bella
Bella F American Soft, gentle
antoni
Antoni M American Narration
josh
Josh M American Deep, authoritative
arnold
Arnold M American Gruff, character
adam
Adam M American Deep, narration
sam
Sam M American Raspy, character
Providers
Provider Quality Latency Cost Setup
ElevenLabs Premium ~500ms $5/100k chars API key
say (macOS) Good ~100ms Free Built-in
espeak Basic ~50ms Free Install
Provider Configuration
// ElevenLabs (best quality) const tts = createTTSService({ provider: 'elevenlabs', apiKey: process.env.ELEVENLABS_API_KEY, });
// macOS say (free, local) const tts = createTTSService({ provider: 'say', defaultVoice: 'Samantha', // macOS voice });
// espeak (cross-platform, free) const tts = createTTSService({ provider: 'espeak', defaultVoice: 'en-us', });
Audio Output
// Set output device tts.setOutputDevice('Built-in Speakers');
// Get available devices const devices = await tts.listOutputDevices();
SSML Support (ElevenLabs)
// Use SSML for advanced control
await tts.speak( <speak> <prosody rate="slow">Important alert:</prosody> <break time="500ms"/> Your stop loss was triggered. </speak>, { ssml: true });
Best Practices
-
Use streaming — For long text, reduces time to first audio
-
Cache common phrases — "Order filled", "Alert triggered"
-
Adjust speed — Faster for alerts, slower for details
-
Queue management — Don't overlap important messages
-
Fallback provider — Use say/espeak if ElevenLabs unavailable