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
