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

```typescript
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

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

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

// Stop listening
await voice.stop();
```

### Event Handlers

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

```typescript
// 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

```typescript
// 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

```typescript
// 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


---
Source attribution: alsk1992
Original project: https://github.com/alsk1992/CloddsBot/blob/c930628c47a4a745f497e29035a3b64622f97cc7/src/skills/bundled/voice/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2026 alsk1992

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: alsk1992
Original project: https://github.com/alsk1992/CloddsBot/blob/c930628c47a4a745f497e29035a3b64622f97cc7/src/skills/bundled/voice/SKILL.md
Attribution basis: Source repository record

Fields of work: Product Management, Sales
Roles: Customer Success Manager, Product Manager, Sales Engineer
Specialties: API
Tools: ElevenLabs, Whisper
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 7c95c4f713dc182a393a11319dbf2d2639d76276ce66ca9a4d0157a208f406f4