Voice Assistant

What is Voice Assistant?

Voice Assistant is a Python-based application that integrates voice interaction (speech-to-text, text-to-speech, and voice activity detection) with a Multi-Content Processor (MCP) to enable WhatsApp messaging. It runs locally on Linux, macOS, or Windows (Python ≥3.13, using uv) and connects to LiveKit’s real-time audio platform. It is built for developers who want to create a voice‑controlled assistant that can send and receive WhatsApp messages via an MCP server.

How to use Voice Assistant?

1. Clone the repository, create a virtual environment with uv venv, and activate it.
2. Run uv sync to install dependencies.
3. Set the required environment variables (LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET, CARTESIA_API_KEY, OPENAI_API_KEY) in a .env file.
4. Configure the WhatsApp MCP server path in mcp_config.json (replace placeholders with absolute paths to uv and the whatsapp-mcp-server directory).
5. Start the assistant with uv run voice-assistant-cli.
6. Open LiveKit Agents Playground in a browser and connect to your local agent.

Key features of Voice Assistant

• Voice‑activated assistant using Silero Voice Activity Detection (VAD)
• Real‑time speech‑to‑text via OpenAI Whisper (via LiveKit)
• Text‑to‑speech using Cartesia AI
• WhatsApp message handling through a Multi‑Content Processor (MCP)
• Runs locally with Python and uv for easy dependency management
• Connects to LiveKit Agents Playground for testing and debugging

Use cases of Voice Assistant

• Build a voice‑controlled assistant that reads and sends WhatsApp messages hands‑free
• Prototype a multi‑modal agent that combines voice input with external service integration
• Create a personal assistant that responds to spoken queries and acts on WhatsApp contacts or groups

FAQ from Voice Assistant

What prerequisites are needed?

Python ≥3.13 and uv (Python packager and virtual environment manager) must be installed on your system. You also need accounts/API keys for LiveKit, Cartesia, and OpenAI.

How do I configure the WhatsApp MCP?

Edit the mcp_config.json file with the absolute path to your uv binary and the full path to the whatsapp-mcp-server directory. The server must be running separately and configured according to its own documentation.

How do I run the assistant?

After completing the setup steps, run uv run voice-assistant-cli from the project root. The assistant will start and connect to LiveKit; you can then interact with it via the LiveKit Agents Playground.

What services are used for speech and AI?

Silero for voice activity detection, OpenAI for speech‑to‑text and language model responses, and Cartesia for text‑to‑speech. Real‑time audio handling is managed by LiveKit.

Is there any built‑in model download required?

No manual download is needed inside the script. The LiveKit plugins (including Silero) handle their own model setup when the assistant starts.