Turn any Android phone with a SIM card into an autonomous, ultra-low-latency AI Voice Agent powered by Google Gemini, Edge-TTS, and ADB.
✨ Key Features • 🏗️ Architecture • ⚡ Quick Start • 🎧 Audio Setup • 🖥️ Desktop GUI • ⚙️ Configuration • 🤖 AI Personas
Most AI phone calling systems require costly cloud telephony services (Twilio, Vonage, Plivo, SIP trunks) with per-minute fees, regulatory caller-ID verification hurdles, and carrier restrictions.
CallVox AI bypasses all VoIP aggregators entirely. It bridges your PC directly to an Android Smartphone using hardware audio channels and ADB (Android Debug Bridge). Your AI agent answers and places real cellular phone calls directly through your standard mobile SIM plan with zero carrier fees!
╔══════════════════════════════════════════════════════════════════╗
║ NO TWILIO. NO VOIP FEES. ║
║ Real SIM Calls • Real Phone Numbers • Sub-second Voice ║
╚══════════════════════════════════════════════════════════════════╝
| Feature | Description | Highlight |
|---|---|---|
| 📞 Direct Cellular Calls | Inbound auto-answering and autonomous outbound dialer directly over your Android carrier. | Zero VoIP Costs |
| 🧠 Gemini LLM Brain | Powered by high-speed Google Gemini models for conversational reasoning and intent analysis. | Sub-Second Latency |
| 🗣️ Ultra-Realistic Neural TTS | Microsoft Edge Neural Voice synthesis with human-like breathing, cadence, pitch, and speed. | 100+ Natural Voices |
| 🎛️ Modern Desktop GUI | Sleek Cyberpunk/Glassmorphic dashboard with live audio visualizers, call logs, & transcripts. | Native pywebview App |
| 🔄 Live Call Summaries & CRM | Real-time audio transcription, caller intent classification, and structured SQLite history logs. | Full CRM Export |
| 📶 USB & Wireless ADB | Works over standard USB-C cable or Wi-Fi 5GHz for seamless wireless untethered calling. | Flexible Connectivity |
| 🎙️ Dual Audio Architecture | Supports Bluetooth Hands-Free Profile (HFP), 3.5mm TRRS Splitters, or Virtual Audio Cables. | Zero Echo & Lag |
| 🎭 Dynamic AI Personas | Configurable prompts for customer support, appointment booking, medical reception, or sales outreach. | Instant Customization |
flowchart LR
subgraph Mobile["📱 Android Device (Cellular Network)"]
A[📞 Carrier Incoming / Outgoing Call] --> B[ADB Telephony Controller]
A <--> C[🔊 Mic / Speaker / Bluetooth Audio]
end
subgraph HardwareBridge["⚡ Audio & Control Bridge"]
C <== "Bluetooth HFP / 3.5mm AUX / USB Audio" ==> D[🎧 SoundDevice Audio Router]
B <== "USB / Wi-Fi ADB Commands" ==> E[📱 Phone Controller]
end
subgraph PC["💻 Desktop AI Core & Desktop GUI"]
D <--> F["🎙️ STT & Voice Activity Detector (VAD)"]
F --> G["🧠 Google Gemini LLM Engine"]
G --> H["🗣️ Edge-TTS Neural Voice Synthesizer"]
H --> D
E <--> I["🖥️ Native Dashboard UI (pywebview)"]
G --> J[("🗄️ SQLite Database (Transcripts & CRM)")]
I <--> J
end
style Mobile fill:#111927,stroke:#00f2fe,stroke-width:2px,color:#fff
style HardwareBridge fill:#1a1429,stroke:#9d4edd,stroke-width:2px,color:#fff
style PC fill:#0b0f17,stroke:#4caf50,stroke-width:2px,color:#fff
To conduct bidirectional phone conversations, audio is bridged between the Android phone and your PC:
┌──────────────────────────────────────────────────┐
│ TWO-WAY AUDIO PATH │
└──────────────────────────────────────────────────┘
[Caller's Voice] ──> [Phone Audio Out] ──> [PC Audio In (STT)] ──> [Gemini LLM]
│
[Caller Hears] <── [Phone Mic In] <── [PC Audio Out (TTS)] <────────┘
| Setup Method | Connection Type | Latency | Complexity | Recommended For |
|---|---|---|---|---|
| 🔵 Bluetooth HFP | Wireless (Hands-Free Profile) | ~120ms | ⭐ Easy | Everyday convenience, completely wireless |
| 🔌 3.5mm AUX + TRRS Splitter | Wired analog audio cables | <10ms | ⭐⭐ Medium | Studio quality, zero interference |
| 🎚️ Virtual Audio Cable | Software routing (VB-Cable / VoiceMeeter) | ~30ms | ⭐⭐⭐ Advanced | Power users & custom microphone setups |
- Python 3.10+ installed
- Android Phone (Android 9.0+) with Developer Options enabled
- Google Gemini API Key (Get free key here)
- ADB (Bundled in
scrcpy-win64or system-wide)
# Clone the repository
git clone https://github.com/YOUR_USERNAME/CallVox-AI.git
cd CallVox-AI
# Create virtual environment
python -m venv venv
# Windows:
.\venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate
# Install dependencies
pip install -r requirements.txtCopy the example configuration file:
# Windows
copy .env.example .env
# Linux / macOS
cp .env.example .envOpen .env and fill in your Gemini API Key:
GEMINI_API_KEY=AIzaSyYourGeminiApiKeyHere
AI_VOICE=en-US-JennyNeural
SYSTEM_PROMPT=You are an expert AI receptionist for Apex Solutions. Be polite, concise, and helpful.- Enable USB Debugging in
Settings > Developer Options. - Connect your phone via USB cable and tap Allow Debugging.
- Verify connection:
python main.py --check-adb
# Pair device (Only once)
python main.py --pair-wireless <PHONE_IP> <PAIR_PORT> <6_DIGIT_CODE>
# Connect wirelessly
python main.py --connect-wireless <PHONE_IP>:5555python app.py# 1. Check Version & Environment
python main.py --version
# 2. Check Device & Telephony Connection
python main.py --check-adb
# 3. Start Auto-Answer Inbound Call Daemon
python main.py --monitor
# 4. Place an Autonomous Outbound Call
python main.py --outbound "+1234567890"
# 5. View Live Call History & CRM Summaries
python main.py --history
# 6. List Available Audio Devices
python main.py --list-audioThe built-in desktop control panel offers full real-time telemetry and control:
┌─────────────────────────────────────────────────────────────────────────────┐
│ ⚡ CALLVOX AI │ Device: [● Pixel 8 Pro - Connected] │ Status: [IDLE] │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ [ 📞 DIALER ] [ 🎙️ AUDIO VISUALIZER ] [ 📜 LIVE TRANSCRIPT]│
│ ┌─────────────┐ ┌─────────────────────────┐ ┌───────────────────┐│
│ │ +1 (555) 01 │ │ ▂ ▃ ▅ ▆ █ ▇ ▅ ▃ ▂ │ │ Caller: Hello? ││
│ │ [ CALL ] │ │ Sampling Rate: 16kHz │ │ AI: Hi, how can I ││
│ └─────────────┘ └─────────────────────────┘ │ help you today? ││
│ └───────────────────┘│
│ [ 📊 RECENT CALLS ] │
│ • +1-202-555-0199 │ Duration: 02:14 │ Intent: Support Inquiry │
│ • +1-415-555-0142 │ Duration: 01:05 │ Intent: Appointment Scheduled │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
- 🎚️ Live Audio Waveforms: Visual inspection of voice activity and microphone input gating.
- 📱 One-Click Dialing: Type or paste any number to launch an outbound AI conversation.
- 📝 Live Transcript Stream: Real-time multi-turn conversation display.
- 🔋 Battery & Signal Telemetry: Real-time status sync via ADB.
- 🗃️ Searchable CRM Database: Filter, review, replay, and export call records.
| Key | Description | Default |
|---|---|---|
GEMINI_API_KEY |
Google Gemini API Key | (Required) |
AI_VOICE |
Microsoft Edge TTS voice model identifier | en-US-JennyNeural |
AI_LANGUAGE |
Default speech recognition and response language | en-US |
AUDIO_INPUT_DEVICE |
Sound device index/name for Phone Audio Input | default |
AUDIO_OUTPUT_DEVICE |
Sound device index/name for AI Voice Output | default |
AUTO_ANSWER_DELAY |
Seconds to wait before answering an incoming call | 2.0 |
RECORD_CALLS |
Save high-definition audio recordings of calls | true |
ADB_MODE |
Connection mode (USB or WIRELESS) |
USB |
Change your AI's identity instantly by updating SYSTEM_PROMPT in .env or in the desktop dashboard:
🏢 Corporate Receptionist & Secretary
You are Sarah, the executive virtual assistant for Nexus Tech.
Your goal is to warmly welcome callers, inquire about their needs, answer general business questions, and take clear messages or schedule appointments. Keep answers polite, helpful, and concise.
🏥 Dental / Medical Clinic Scheduler
You are Alex, the appointment receptionist at BrightSmile Dental Clinic.
Help callers schedule, reschedule, or cancel dental checkups. Confirm their full name, preferred date, and contact number. Keep a reassuring, professional tone.
🍕 Restaurant Order & Reservation Bot
You are Mario, the digital concierge at Bella Italia Bistro.
Take table reservations (asking for party size, date, and time), answer menu and dietary questions, and provide opening hours. Keep answers energetic, concise, and friendly.
- Core Runtime: Python 3.10+
- Large Language Model: Google Gemini Pro / Flash
- Voice Synthesis: Edge-TTS (Neural Microsoft Voices)
- Speech Recognition: SpeechRecognition / Google STT / Whisper VAD
- Audio I/O: SoundDevice, PyDub, NumPy
- Hardware Controller: Android Debug Bridge (ADB) & scrcpy
- Desktop UI: pywebview, HTML5, Modern Glassmorphism CSS, Vanilla JS
- Database: SQLite3 with automated indexing
Important
This software is designed for legitimate automation, personal productivity, customer service, and accessibility use cases.
- Call recording and automated telephony laws vary across states and countries (One-Party vs Two-Party Consent).
- Always ensure you comply with local regulations (such as TCPA in the US, GDPR in the EU, or equivalent local telecommunications acts) and inform callers when calls are recorded or powered by AI.
Contributions make the open-source community an amazing place to learn, inspire, and create!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the MIT License. See LICENSE for more information.
Made with ❤️ by AI Enthusiasts • Star ⭐ this repository if you find it helpful!