/voice

name: voice
description: "Voice recognition, wake words, and voice-controlled trading"
emoji: "🎤"
gates:
  envs:
    anyOf:
      - OPENAI_API_KEY
      - WHISPER_MODEL_PATH

Voice - Complete API Reference

Voice-controlled interface with wake word detection, speech-to-text, and text-to-speech.

---

Chat Commands

Voice Control

/voice start                                Start voice listening
/voice stop                                 Stop voice listening
/voice status                               Check voice status
/voice wake "hey clodds"                    Set wake word

Settings

/voice language en-US                       Set language
/voice sensitivity high                     Wake word sensitivity
/voice timeout 30                           Silence timeout (seconds)
/voice continuous on                        Enable continuous mode

---

TypeScript API Reference

Create Voice Assistant

import { createVoiceAssistant } from 'clodds/voice';

const voice = createVoiceAssistant({
  // Wake word
  wakeWord: 'hey clodds',
  wakeWordSensitivity: 0.5,  // 0-1

  // Speech-to-text
  stt: {
    provider: 'whisper',  // 'whisper' | 'vosk' | 'google'
    model: 'base',        // 'tiny' | 'base' | 'small' | 'medium' | 'large'
    language: 'en',
  },

  // Text-to-speech
  tts: {
    provider: 'elevenlabs',  // 'elevenlabs' | 'say' | 'espeak'
    voice: 'rachel',
    speed: 1.0,
  },

  // Timeouts
  silenceTimeoutMs: 3000,
  maxRecordingMs: 30000,
});

Start/Stop Listening

// Start listening for wake word
await voice.start();

// Check if listening
const isListening = voice.isListening();

// Stop listening
await voice.stop();

Event Handlers

// Wake word detected
voice.on('wake', () => {
  console.log('Wake word detected!');
});

// Speech recognized
voice.on('speech', (text: string) => {
  console.log(`User said: ${text}`);
});

// Transcription complete
voice.on('transcript', (result) => {
  console.log(`Final: ${result.text}`);
  console.log(`Confidence: ${result.confidence}`);
  console.log(`Duration: ${result.durationMs}ms`);
});

// Error handling
voice.on('error', (error) => {
  console.error('Voice error:', error);
});

// Silence detected
voice.on('silence', () => {
  console.log('User stopped speaking');
});

Speak (TTS)

// Speak text
await voice.speak('Your order has been placed');

// Speak with options
await voice.speak('Market is up 5%', {
  voice: 'josh',
  speed: 1.2,
  pitch: 1.0,
});

// Cancel speaking
voice.cancelSpeech();

Manual Transcription

// Transcribe audio buffer
const result = await voice.transcribe(audioBuffer, {
  language: 'en',
  prompt: 'Trading commands',  // Context hint
});

console.log(`Text: ${result.text}`);
console.log(`Language: ${result.language}`);

Voice Activity Detection

// Check if user is speaking
const vad = voice.getVAD();

vad.on('speechStart', () => {
  console.log('User started speaking');
});

vad.on('speechEnd', (audio) => {
  console.log('User stopped speaking');
  // audio contains the recorded speech
});

---

Wake Word Configuration

| Setting | Values | Description | |---------|--------|-------------| | `wakeWord` | Any phrase | Trigger phrase | | `sensitivity` | 0.0 - 1.0 | Detection threshold |

**Built-in wake words:**

• "hey clodds"
• "okay clodds"
• "clodds"

---

STT Providers

| Provider | Quality | Speed | Offline | |----------|---------|-------|---------| | **Whisper** | Excellent | Medium | Yes | | **Vosk** | Good | Fast | Yes | | **Google** | Excellent | Fast | No |

---

TTS Providers

| Provider | Quality | Voices | API Key | |----------|---------|--------|---------| | **ElevenLabs** | Premium | 30+ | Required | | **say** (macOS) | Good | System | None | | **espeak** | Basic | Many | None |

---

Voice Commands Examples

Once voice is active, speak naturally:

"Hey Clodds, what's my portfolio value?"
"Hey Clodds, buy 100 dollars of Trump YES"
"Hey Clodds, what are the top arbitrage opportunities?"
"Hey Clodds, set a price alert for Bitcoin at 100k"

---

Best Practices

1. **Quiet environment** — Background noise affects accuracy 2. **Clear speech** — Speak clearly for best recognition 3. **Short commands** — Keep voice commands concise 4. **Confirmation** — Enable confirmations for trades 5. **Fallback** — Text input always available