VoxMate

Your Intelligent Voice-Powered Companion

VoxMate is an advanced, open-source voice-activated virtual assistant that brings AI-powered automation to your fingertips. With natural language understanding and direct integration with popular services, VoxMate transforms how you interact with your computer.

Features • Quick Start • Documentation • Demo • Contributing

---

Table of Contents

• Overview
• Features
• Demo
• Quick Start
• Installation
• Configuration
• Usage
• Project Architecture
• API Integration
• Testing
• Troubleshooting
• Roadmap
• Contributing
• Security
• License
• Acknowledgments

---

What this project does

VoxMate is more than just a voice assistant—it's your personal AI companion designed to simplify daily tasks through natural voice interactions. Built with Python and powered by current speech recognition technology, VoxMate offers a modular, extensible architecture that's perfect for both personal use and further development.

Why VoxMate?

• Easy to Use - Just speak naturally, no complex commands
• Highly Customizable - Modify settings, add new features, or integrate your own APIs
• 100% Free & Open Source - No subscriptions, no hidden costs
• Privacy-Focused - Runs locally on your machine
• Minimal Dependencies - Lightweight and fast
• Modular Design - Easy to extend with new capabilities

---

What the project includes

Core Capabilities

Feature	Description	Status
Voice Recognition	Advanced speech-to-text using Google Speech Recognition API	Active
Natural Speech Output	Realistic text-to-speech with adjustable voice and speed	Active
Music Streaming	Play any song on YouTube with voice commands	Active
Live News	Get real-time top headlines from around the world	Active
Weather Updates	Current weather conditions for any city worldwide	Active
Entertainment	Random jokes and fascinating facts on demand	Active
Wikipedia Integration	Quick information lookup from Wikipedia	Active
⏰ Smart Greetings	Context-aware greetings based on time of day	Active
Secure Configuration	Environment-based API key management	Active

Advanced workflows

• Multi-Language Support (Coming Soon)
• Custom Voice Commands - Extensible command system
• Error Handling - Graceful fallbacks and user-friendly error messages
• Logging System - Track usage and debug issues
• Cross-Platform - Works on Windows, macOS, and Linux
• Offline Capabilities - Some features work without internet

---

Demo

Example Interaction

🤖 VoxMate: Hi sir. I am VoxMate, your virtual assistant. Good Morning.
🤖 VoxMate: Today is October 29th, 2025, and it's currently 09:30 AM.
🤖 VoxMate: The temperature in New York is 18°C with clear skies. How are you doing today?

👤 You: I'm doing great, thanks!

🤖 VoxMate: I'm glad to hear that! What can I do for you?

👤 You: Play some music

🤖 VoxMate: Sure! Which song would you like me to play?

👤 You: Play Bohemian Rhapsody

🤖 VoxMate: Playing Bohemian Rhapsody on YouTube.
[YouTube opens and starts playing]

🤖 VoxMate: Is there anything else I can help you with?

👤 You: Tell me a joke

🤖 VoxMate: Why do programmers prefer dark mode? 
            Because light attracts bugs! 😄

👤 You: What's the weather like?

🤖 VoxMate: The current temperature in New York is 18°C with clear skies.
            Wind speed is 5 km/h. Have a great day!

👤 You: Exit

🤖 VoxMate: Goodbye! Have a wonderful day!

---

Quick Start

Get VoxMate up and running in under 5 minutes!

Prerequisites

• Python 3.8+ (Download)
• Google Chrome (for music playback)
• Microphone (for voice input)
• Internet Connection (for most features)

One-Command Installation (Windows)

# Clone and setup in one go
git clone https://github.com/yourusername/VoxMate.git && cd VoxMate && python -m venv venv && .\venv\Scripts\activate && pip install -r requirements.txt

One-Command Installation (macOS/Linux)

# Clone and setup in one go
git clone https://github.com/yourusername/VoxMate.git && cd VoxMate && python3 -m venv venv && source venv/bin/activate && pip install -r requirements.txt

Quick Test

# Activate virtual environment
.\venv\Scripts\activate  # Windows
source venv/bin/activate  # macOS/Linux

# Run VoxMate
python main.py

---

Installation

Step-by-Step Installation

1. Clone the Repository

git clone https://github.com/yourusername/VoxMate.git
cd VoxMate

2. Create Virtual Environment

Windows:

python -m venv venv
.\venv\Scripts\activate

macOS/Linux:

python3 -m venv venv
source venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

Alternative: Install as a package:

pip install -e .

This enables you to run VoxMate from anywhere using:

virtual-assistant

4. Setup API Keys (Optional but Recommended)

VoxMate works without API keys, but Weather and News features require them.

Step 1: Copy the example environment file:

# Windows
copy env.example .env

# macOS/Linux
cp env.example .env

Step 2: Get your FREE API keys:

Service	URL	Free Tier	Features
NewsAPI	newsapi.org	100 requests/day	News headlines
OpenWeatherMap	openweathermap.org	1000 requests/day	Weather data

Step 3: Edit .env file and add your keys:

# API Keys
NEWS_API_KEY=your_newsapi_key_here
WEATHER_API_KEY=your_openweathermap_key_here

# Location Settings
CITY=YourCity
COUNTRY=us

# Voice Settings (Optional)
SPEECH_RATE=190

5. Verify Installation

Run the test suite to ensure everything works:

python test_assistant.py

Expected output:

✅ Testing Configuration... PASS
✅ Testing Text-to-Speech... PASS
✅ Testing Joke Service... PASS
✅ Testing Music Player... PASS
⚠️  Testing Weather Service... REQUIRES API KEY
⚠️  Testing News Service... REQUIRES API KEY
✅ Testing Wikipedia Search... PASS

Overall: 5/7 tests passed (71%)

---

Configuration

Environment Variables

VoxMate uses a .env file for configuration. Here's a complete reference:

# =============================================
# API KEYS
# =============================================
# News API Key (Get from: https://newsapi.org/)
NEWS_API_KEY=your_key_here

# Weather API Key (Get from: https://openweathermap.org/api)
WEATHER_API_KEY=your_key_here

# =============================================
# LOCATION SETTINGS
# =============================================
# Your city name (e.g., "New York", "London", "Tokyo")
CITY=New York

# Country code (e.g., "us", "uk", "in", "jp")
# See: https://www.iso.org/iso-3166-country-codes.html
COUNTRY=us

# =============================================
# VOICE SETTINGS
# =============================================
# Speech rate in words per minute (150-200 recommended)
SPEECH_RATE=190

# Voice index (0 = male voice, 1 = female voice)
# Note: Available voices depend on your system
VOICE_INDEX=1

Advanced Configuration

Edit src/virtual_assistant/config.py for more control:

# Speech Settings
SPEECH_RATE = 190          # Words per minute (150-250)
VOICE_INDEX = 1            # 0 = Male, 1 = Female

# News Settings
NEWS_COUNT = 3             # Number of headlines to read (1-10)
NEWS_CATEGORY = "general"  # general, business, technology, etc.

# Timeout Settings
LISTEN_TIMEOUT = 10        # Seconds to wait for voice input
PHRASE_LIMIT = 10          # Max seconds for a single phrase

# Browser Settings
HEADLESS_BROWSER = False   # True = No browser window for music

---

Usage

Running VoxMate

Option 1: Direct Execution

python main.py

Option 2: As a Module

python -m virtual_assistant

Option 3: As an Installed Package (if installed with pip install -e .)

virtual-assistant

Voice Commands Reference

Music & Entertainment

Say This	VoxMate Will
"Play Imagine Dragons"	Search and play on YouTube
"Play song Despacito"	Search and play on YouTube
"Tell me a joke"	Tell a random joke
"Tell me a fact"	Share an interesting fact

Information & News

Say This	VoxMate Will
"What's the news?"	Read top 3 headlines
"Tell me the weather"	Give current weather
"Information about Python"	Search Wikipedia
"What is artificial intelligence?"	Search Wikipedia

System Commands

Say This	VoxMate Will
"Exit" or "Goodbye"	Close the assistant
"Thank you"	Acknowledge and continue

Tips for Best Results

Do:

• Speak clearly and at a normal pace
• Wait for the " Listening..." prompt
• Use natural language (no need for robot-speak)
• Ensure minimal background noise

Don't:

• Shout or whisper
• Speak while VoxMate is talking
• Use extremely long sentences
• Cover your microphone

---

Project Architecture

Directory Structure

VoxMate/
│
├── 📁 src/
│   └── 📁 virtual_assistant/        # Main package
│       ├── 📄 __init__.py           # Package initialization
│       ├── 📄 __main__.py           # Module entry point
│       ├── 📄 assistant.py          # Core assistant logic
│       ├── 📄 config.py             # Configuration management
│       └── 📁 services/             # Feature modules
│           ├── 📄 __init__.py
│           ├── 📄 jokes.py          # Joke service (Official Joke API)
│           ├── 📄 music.py          # YouTube music player (Selenium)
│           ├── 📄 news.py           # News service (NewsAPI)
│           ├── 📄 weather.py        # Weather service (OpenWeatherMap)
│           └── 📄 wikipedia.py      # Wikipedia search (Selenium)
│
├── 📁 venv/                         # Virtual environment
│
├── 📄 main.py                       # Primary entry point
├── 📄 requirements.txt              # Python dependencies
├── 📄 setup.py                      # Package installation script
├── 📄 env.example                   # Environment template
├── 📄 .env                          # Your API keys (gitignored)
├── 📄 .gitignore                    # Git ignore rules
├── 📄 LICENSE                       # MIT License
└── 📄 README.md                     # This file

Tools and libraries

Core Technologies

Technology	Purpose	Version
Python	Core language	3.8+
pyttsx3	Text-to-speech engine	2.99
SpeechRecognition	Voice recognition	3.14+
PyAudio	Audio I/O	0.2.14
Selenium	Web automation	4.37+

APIs & Services

Service	Purpose	Documentation
Google Speech Recognition	Speech-to-text conversion	Docs
NewsAPI	News headlines	Docs
OpenWeatherMap	Weather data	Docs
Official Joke API	Random jokes	Docs
Randfacts	Random facts	PyPI

Dependencies

pyttsx3==2.99          # Text-to-speech
SpeechRecognition      # Voice recognition
pyaudio                # Audio handling
selenium               # Web automation
requests               # HTTP requests
python-dotenv          # Environment variables
randfacts              # Random facts
pywin32                # Windows-specific (Windows only)

System Architecture

┌─────────────────────────────────────────────────────┐
│                    USER INPUT                       │
│              (Voice via Microphone)                 │
└───────────────────┬─────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────┐
│           Speech Recognition Engine                 │
│         (Google Speech Recognition API)             │
└───────────────────┬─────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────┐
│          Natural Language Processing                │
│            (Command Parser in assistant.py)         │
└───────────────────┬─────────────────────────────────┘
                    │
        ┌───────────┴───────────┐
        ▼                       ▼
┌──────────────┐      ┌──────────────────┐
│   Services   │      │   Direct Actions │
│   Module     │      │   (greetings,    │
│   Dispatcher │      │    time, etc.)   │
└──────┬───────┘      └──────────────────┘
       │
       ├─► News Service (NewsAPI)
       ├─► Weather Service (OpenWeatherMap)
       ├─► Music Service (YouTube/Selenium)
       ├─► Joke Service (Official Joke API)
       ├─► Fact Service (Randfacts)
       └─► Wikipedia Service (Web Scraping)
                    │
                    ▼
┌─────────────────────────────────────────────────────┐
│           Text-to-Speech Engine                     │
│                  (pyttsx3)                          │
└───────────────────┬─────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────┐
│                  AUDIO OUTPUT                       │
│                  (Speakers)                         │
└─────────────────────────────────────────────────────┘

---

API Integration

Adding Your Own APIs

VoxMate is designed to be easily extensible. Here's how to add new features:

1. Create a New Service Module

Create a new file in src/virtual_assistant/services/:

# src/virtual_assistant/services/my_service.py

import requests

def my_custom_feature(query):
    """
    Your custom feature implementation.
    
    Args:
        query (str): User's query or command
        
    Returns:
        str: Response to be spoken
    """
    try:
        # Your API call here
        response = requests.get(f"https://api.example.com?q={query}")
        data = response.json()
        
        return f"Here's your result: {data['result']}"
    
    except Exception as e:
        return f"Sorry, I encountered an error: {str(e)}"

2. Register in Assistant

Edit src/virtual_assistant/assistant.py to add your command:

# Import your service
from virtual_assistant.services.my_service import my_custom_feature

# In the run() method, add your command handler
elif 'your trigger word' in command:
    result = my_custom_feature(command)
    speak(result)

3. Add Configuration (if needed)

Add any API keys or settings to .env:

MY_SERVICE_API_KEY=your_key_here

And load them in config.py:

import os
from dotenv import load_dotenv

load_dotenv()
MY_SERVICE_API_KEY = os.getenv('MY_SERVICE_API_KEY')

---

Testing

Automated Testing

VoxMate includes a comprehensive test suite:

# Run all tests
python test_assistant.py

Test Coverage

Component	Test Type	Status
Configuration Loading	Unit
Text-to-Speech	Integration
Voice Recognition	Integration	Manual
News Service	API
Weather Service	API
Joke Service	API
Music Player	E2E
Wikipedia Search	E2E

Manual Testing Checklist

• Microphone detection works
• Voice commands are recognized accurately
• Speech output is clear and understandable
• All services respond correctly
• Error messages are user-friendly
• Browser automation works (music/Wikipedia)

---

Troubleshooting

Common Issues & Solutions

Issue: "Could not understand audio"

Symptoms: VoxMate can't recognize your voice

Solutions:

1. Check microphone permissions in system settings
2. Reduce background noise
3. Speak more clearly and closer to the microphone
4. Test your microphone in other applications
5. Check internet connection (Google Speech Recognition needs internet)

# Test your microphone
python -c "import speech_recognition as sr; r = sr.Recognizer(); print(sr.Microphone.list_microphone_names())"

---

Issue: "No module named 'pyaudio'"

Symptoms: Import error when running VoxMate

Solutions:

Windows:

pip install pipwin
pipwin install pyaudio

macOS:

brew install portaudio
pip install pyaudio

Linux (Ubuntu/Debian):

sudo apt-get install python3-pyaudio
pip install pyaudio

---

Issue: "Weather/News not working"

Symptoms: Weather and news features return errors

Solutions:

1. Verify API keys are correct in .env file
2. Check if API keys are activated (can take a few minutes)
3. Verify you haven't exceeded free tier limits
4. Test API keys directly:

# Test NewsAPI
curl "https://newsapi.org/v2/top-headlines?country=us&apiKey=YOUR_KEY"

# Test OpenWeatherMap
curl "http://api.openweathermap.org/data/2.5/weather?q=London&appid=YOUR_KEY"

---

Issue: "Selenium WebDriver error"

Symptoms: Music playback or Wikipedia search fails

Solutions:

1. Ensure Google Chrome is installed and up to date
2. Check internet connection
3. Clear browser cache
4. Update Selenium:

pip install --upgrade selenium

---

Issue: "Text-to-Speech not working"

Symptoms: No audio output from VoxMate

Solutions:

1. Check speaker volume and connections
2. Test system audio with other applications
3. Try different voice settings in config.py:

VOICE_INDEX = 0  # Try 0, 1, or 2
SPEECH_RATE = 150  # Lower rate

4. List available voices:

import pyttsx3
engine = pyttsx3.init()
voices = engine.getProperty('voices')
for voice in voices:
    print(voice.name)

---

Issue: "Permission denied" errors

Symptoms: Can't write to .env or other files

Solutions:

1. Run terminal as administrator (Windows) or use sudo (macOS/Linux)
2. Check file permissions:

# Windows
icacls .env

# macOS/Linux
ls -la .env
chmod 644 .env

---

Performance Optimization

Slow Response Time

Causes & Fixes:

• Slow internet: Check connection speed
• Too many browser tabs: Close unnecessary tabs
• System resources: Close other applications
• API response time: Normal; external APIs vary in speed

High CPU Usage

Causes & Fixes:

• Browser automation: Normal when playing music
• Multiple instances: Ensure only one VoxMate is running
• Background processes: Check Task Manager/Activity Monitor

---

Getting Help

If you're still experiencing issues:

1. Check the logs: Look for error messages in the console
2. Run diagnostics:

   python test_assistant.py
   

3. Search existing issues: GitHub Issues
4. Ask for help: Open a new issue
5. Community: Join our Discussions

---

Roadmap

Version 2.0 (Upcoming)

• Multi-Language Support - Commands and responses in multiple languages
• Conversation Memory - Context-aware conversations
• Offline Mode - Core features without internet
• Custom Wake Word - "Hey VoxMate" activation
• Plugin System - Easy third-party extensions

Version 2.1

• GUI Dashboard - Visual interface for settings and stats
• Spotify Integration - Native music playback
• Email Capabilities - Send/read emails via voice
• Calendar Integration - Manage appointments and reminders
• Smart Home Control - IoT device integration

Version 3.0 (Future)

• Mobile App - iOS/Android companion app
• Cloud Sync - Settings and preferences across devices
• Voice Profiles - Multi-user support
• AI Learning - Personalized responses based on usage
• Docker Support - Containerized deployment

Community Requests

Vote for features you'd like to see: Feature Requests

---

Contributing

We love contributions! VoxMate is built by the community, for the community.

How to Contribute

1. Fork the repository

   # Click "Fork" on GitHub, then:
   git clone https://github.com/YOUR_USERNAME/VoxMate.git
   

2. Create a feature branch

   git checkout -b feature/amazing-feature
   

3. Make your changes

   • Write clean, documented code
   • Follow PEP 8 style guidelines
   • Add tests for new features

4. Format your code

   pip install black
   black .
   

5. Test your changes

   python test_assistant.py
   

6. Commit and push

   git commit -m "Add amazing feature"
   git push origin feature/amazing-feature
   

7. Open a Pull Request

   • Go to your fork on GitHub
   • Click "New Pull Request"
   • Describe your changes

Contribution Ideas

• Bug Fixes - Fix issues listed in Issues
• New Features - Add new services or capabilities
• Documentation - Improve README, add tutorials
• Translations - Add multi-language support
• UI/UX - Create a graphical interface
• Testing - Improve test coverage

Code Style

We use Black for code formatting:

# Good
def greet_user(name: str) -> str:
    """Greet the user with their name."""
    return f"Hello, {name}!"

# Not ideal
def greet_user(name):
    return "Hello, " + name + "!"

Commit Message Guidelines

• Use present tense ("Add feature" not "Added feature")
• Be descriptive but concise
• Reference issues when applicable

Examples:

✅ Add Spotify integration #42
✅ Fix microphone detection bug #38
✅ Update README with troubleshooting section
❌ fixed stuff
❌ updates

---

Security

Reporting Security Issues

Please do not report security vulnerabilities through public GitHub issues.

Instead, email: security@voxmate.dev

Include:

• Description of the vulnerability
• Steps to reproduce
• Potential impact
• Suggested fix (if any)

We'll respond within 48 hours.

Security Best Practices

1. API Keys: Never commit .env files to version control
2. Updates: Keep dependencies updated regularly
3. Permissions: Run VoxMate with minimal necessary permissions
4. Network: Be cautious when using on public networks
5. Code Review: Review any custom services you add

Supported Versions

Version	Supported
1.0.x

Show Your Support

If VoxMate helped you, please consider:

⭐ Starring this repository
Sharing on social media
Contributing to the project

---

Made with and Python

VoxMate • Your Voice, Your Assistant, Your Way

⬆ Back to Top