LUMA Voice Assistant - Technical Documentation

Detailed Setup Guide

System Requirements

Operating System: Windows, macOS, or Linux
Python 3.8 or higher
RAM: 4GB minimum (8GB recommended)
Storage: 500MB free space
Hardware:
- Working microphone (USB or integrated)
- Speakers or headphones
- Stable internet connection

Dependencies Overview

sounddevice           # Audio I/O handling
numpy                 # Audio processing
torch                 # Neural network backend
silero-vad            # Voice activity detection
moonshine-onnx        # Speech recognition
groq                  # LLM API client
pyttsx3               # Text-to-speech
python-dotenv         # Environment management

Step-by-Step Installation

Python Installation
- Download Python from python.org
- During installation, check "Add Python to PATH"
- Verify installation: python --version

Virtual Environment Setup

# Windows
python -m venv venv
venv\Scripts\activate

# Linux/MacOS
python3 -m venv venv
source venv/bin/activate

Dependencies Installation
```
pip install -r requirements.txt
```
Groq API Setup
1. Sign up at console.groq.com
2. Generate an API key
3. Add the API key in .env
4. Format : GROQ_API_KEY=your_api_key_here

Configuration Details

Audio Settings

SAMPLING_RATE = 16000    # Audio sampling frequency
CHUNK_SIZE = 512         # Audio buffer size
MAX_SPEECH_SECS = 30     # Maximum speech duration
VAD_THRESHOLD = 0.3      # Voice detection sensitivity
VAD_MIN_SILENCE = 3000   # Minimum silence duration (ms)

Model Configuration

Speech Recognition: Moonshine ASR (base model)
LLM: Groq LLaMA 3.1-8B
VAD: Silero VAD (ONNX)

Troubleshooting Guide

Common Issues

Error: "GROQ_API_KEY not found"
Solution:

Check if .env file exists in root directory
Verify API key format
Restart application after adding key

Error: "Audio input status error"
Solution:

Check microphone connections
Verify microphone permissions
Try different USB ports
Update audio drivers

Error: "VAD processing error"
Solution:

Restart application
Check CPU usage
Verify PyTorch installation
Update CUDA drivers (if using GPU)

Performance Optimization

Adjust CHUNK_SIZE for better latency
Modify VAD_THRESHOLD for different environments
Use GPU acceleration if available
Close background applications

Development Guidelines

Code Structure

├── main.py           # Main application entry
├── terminal_style.py # Terminal UI utilities
├── requirements.txt  # Dependencies
└── .env             # Configuration

Contributing

Fork the repository
Create a feature branch
Follow PEP-8 style guide
Add tests for new features
Submit a pull request