ThunderClap - Voice Command System

    ## Overview
    Full voice integration system for senbot with wake word, STT, TTS, and conversational AI.
    
    ## Hardware
    - **Speaker**: USB Speaker Bar (detected via ALSA/PulseAudio)
    - **Microphone**: USB Audio Interface
    - **Status**: ✅ Audio playback verified working (2026-03-01)
    
    ## Docker Containers
    
    ### STT (Speech-to-Text)
    - **Image**: `linuxserver/faster-whisper`
    - **Port**: 8001
    - **API**: HTTP REST
    - **Model**: whisper-base (default)
    - **Status**: ✅ Running
    
    ### TTS (Text-to-Speech)
    - **Image**: `rhasspy/wyoming-piper`
    - **Port**: 10200
    - **API**: Wyoming protocol (HTTP + UDP events)
    - **Voice**: en_US-lessac-medium.onnx
    - **Status**: ✅ Running
    
    ## Components
    
    ### Wake Word
    - **Engine**: Porcupine or Snowboy
    - **Wake Word**: "Hey Senbot" (configurable)
    
    ### Speech-to-Text (STT)
    - **Engine**: Faster Whisper (CTranslate2 optimized Whisper)
    - **Model**: whisper-base
    - **API Endpoint**: http://localhost:8001
    
    ### Text-to-Speech (TTS)
    - **Engine**: Piper TTS via Wyoming
    - **Voice**: en_US-lessac-medium.onnx
    - **API Endpoint**: http://localhost:10200
    
    ### NLP/Intent
    - **LLM**: Ollama (qwen3:14b, llama3:8b)
    - **Mode**: Conversational or command-based
    
    ## Architecture
    
    ```
    [USB Microphone] -> [STT Docker:8001] -> [Ollama LLM] -> [TTS Docker:10200] -> [USB Speaker]
    ```
    
    ## Configuration
    See `src/config.py`
    
    ## Model Upgrade Options (For Future Review)
    - **STT**: Distil-Whisper Large V3 (5-6x faster, ~5GB VRAM, MIT license)
    - **STT**: Canary Qwen 2.5B (best WER 5.63%, ~6GB VRAM)
    - **TTS**: Coqui TTS (alternative to Piper)
    
    ## Status
    - IN PROGRESS
    - Audio hardware working ✅
    - Docker containers running ✅
    - Python modules implemented ✅
    - End-to-end test pending
    # Senbot Voice System
    
    Full voice integration for senbot with wake word, speech-to-text, LLM processing, and text-to-speech.
    
    ## Features
    
    - **Wake Word Detection** - Always listening for "Senbot" or custom wake words
    - **Microphone Capture** - High-quality audio capture from system microphones
    - **Speech-to-Text** - Convert voice to text using Whisper (via Ollama)
    - **LLM Processing** - Process commands through Ollama (llama3, qwen, etc.)
    - **Text-to-Speech** - Speak responses using Piper TTS
    - **Conversational Mode** - Multi-turn dialogue without repeat wake word
    - **Recording Mode** - Save voice sessions to files
    
    ## Architecture
    
    ```
    ┌─────────────────────────────────────────────────────────────┐
    │                    VOICE SYSTEM                              │
    ├─────────────────────────────────────────────────────────────┤
    │  ┌──────────┐    ┌──────────┐    ┌──────────┐              │
    │  │ Wake Word│───▶│ Microphone│───▶│   STT    │              │
    │  │ Listener │    │  Capture  │    │ (Whisper)│              │
    │  └──────────┘    └──────────┘    └────┬─────┘              │
    │                                        │                    │
    │                                        ▼                    │
    │  ┌──────────┐    ┌──────────┐    ┌──────────┐             │
    │  │  Speaker │◀───│   TTS    │◀───│    LLM   │             │
    │  │  Output  │    │ (Piper)  │    │ (Ollama) │             │
    │  └──────────┘    └──────────┘    └──────────┘             │
    ├─────────────────────────────────────────────────────────────┤
    │  Modes: Wake | Listen | Speak | Record                      │
    └─────────────────────────────────────────────────────────────┘
    ```
    
    ## Installation
    
    ```bash
    # Install dependencies
    pip install pyaudio numpy pvporcupine requests
    
    # Install Piper TTS
    # See: https://github.com/rhasspy/piper
    
    # Start Ollama with whisper model
    ollama serve &
    ollama pull whisper
    ```
    
    ## Usage
    
    ### CLI
    
    ```bash
    # Start voice system
    python -m senbot.voice.cli start
    
    # Check status
    python -m senbot.voice.cli status
    
    # List audio devices
    python -m senbot.voice.cli devices
    
    # Test speak
    python -m senbot.voice.cli speak --text "Hello world"
    
    # Stop
    python -m senbot.voice.cli stop
    ```
    
    ### Python API
    
    ```python
    from senbot.voice import get_voice_processor
    
    # Get processor
    vp = get_voice_processor()
    
    # Start
    vp.start()
    
    # Status
    print(vp.get_status())
    
    # Speak something
    vp.speak("Hello! I am online.")
    
    # Stop
    vp.stop()
    ```
    
    ## Configuration
    
    Edit `config.yaml`:
    
    ```yaml
    voice:
      wake_words:
        - senbot
        - computer
      sample_rate: 16000
      command_timeout: 5
      conversational_mode: false
      
    ollama:
      url: http://localhost:11434
      model: llama3:8b
      
    tts:
      model: en_US-lessac-medium
    ```
    
    ## Requirements
    
    - Python 3.8+
    - PyAudio
    - Ollama running with:
      - whisper (STT)
      - llama3:8b or qwen3:14b (LLM)
    - Piper TTS (optional, for local TTS)
    
    ## Status
    
    🔄 IN PROGRESS - Core pipeline built, need to:
    - [ ] Test with actual audio hardware
    - [ ] Download whisper model to Ollama
    - [ ] Set up Piper TTS server
    - [ ] Add proper error handling
    - [ ] Add configuration file