TTS (Text-to-Speech) - Complete API Reference

/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

/voices                                     List available voices
/voices preview rachel                      Preview a voice
/voice set rachel                           Set default voice

/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)

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

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

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

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

// Preview a voice
await tts.preview('rachel', 'This is a preview of the Rachel voice.');

// 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 (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',
});

// Set output device
tts.setOutputDevice('Built-in Speakers');

// Get available devices
const devices = await tts.listOutputDevices();

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