vaani-assistant 1.0.0

Enterprise-grade, low-latency Gemini Live voice assistant for Linux desktop.

Vaani (वाणी) 🎙️✨

Real-time bidirectional AI voice assistant built on the Google Gemini Live API with a transparent glassmorphic GTK4 desktop HUD.

   _  _   _____   _____   _   _   _ 
  | | | | /  _  \ /  _  \ | \ | | | |
  | | | | | |_| | | |_| | |  \| | | |
  | | | | |  _  | |  _  | | . ` | | |
  \ \_/ / | | | | | | | | | |\  | | |
   \___/  \_| |_/ \_| |_/ \_| \_/ \_/

◌ Standby ➔ ▂▅▇ Listening ➔ ◈ Thinking ➔ ▇▅▃ Speaking

---

Overview

Vaani is a desktop voice assistant that speaks and listens using a low-latency, bidirectional audio stream connected directly to Google's Gemini Live model over WebSockets. Designed specifically for Linux desktop environments (optimized for GNOME on Ubuntu/Debian), it completely bypasses traditional wake-word latency and intermediate speech-to-text transcription. Audio flows in and out of Gemini natively, providing a natural, sub-second response loop.

A glassmorphic top-center Head-Up Display (HUD) overlay reflects assistant states using real-time Cairo waveform visualization, state-aware accent colors, and status indicators.

---

Core Capabilities

• Bidirectional Audio Stream: Constant 16 kHz microphone input stream and 24 kHz speaker output stream via persistent WebSockets.
• Glassmorphic HUD Overlay: Transparent panel pinned to the top-center of the monitor displaying real-time engine states with a 30 FPS hardware-accelerated visualizer.
• Native Tool Calling: Executes desktop automation tools (launch GNOME Terminal, open websites, capture compositor-aware screenshots, manage notes, access memory) silently in the background.
• Bilingual Personality: Standardized on a friendly, conversational feminine voice with custom Hinglish grammar safeguards.
• Mute-First Privacy: Instant manual and system-level mute transitions with an optimized interruption pipeline.
• Interactive Onboarding Wizard: A self-guided CLI setup that safely stores your configurations in user-space directory.

---

Installation

The Recommended Install (Native Debian Package)

You can download and install the official native Debian package system-wide in one go (resolves PipeWire and system GObject dependencies automatically):

curl -LO https://github.com/yashthakare93/vaani/releases/download/v1.0.0/vaani_1.0.0_amd64.deb && sudo apt install ./vaani_1.0.0_amd64.deb

Once installed, simply run the onboarding setup wizard once to configure your Gemini API key:

vaani --setup

And launch the assistant:

vaani

---

Developer Installation (Run from Source)

Ideal for development, customizing tools, or modifying the GTK4 overlay interface.

1. Install System Dependencies (Ubuntu 24.04 / Linux Mint)

sudo apt-get update
sudo apt-get install -y \
  python3 python3-pip python3-venv python3-gi python3-gi-cairo \
  gir1.2-gtk-4.0 libportaudio2 portaudio19-dev libsndfile1 ffmpeg \
  pipewire pipewire-pulse pulseaudio-utils xdg-utils

2. Clone the Repository

git clone https://github.com/yashthakare93/vaani.git
cd vaani

3. Set Up Python Virtual Environment

python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -e .

4. Run the Setup & Onboarding

# Set your Gemini API key and profile details
python3 -m vaani_assistant --setup

5. Launch the Assistant

python3 -m vaani_assistant

---

Command Line Interface (CLI) Reference

Once installed, the vaani command is available system-wide:

vaani              # Launches the voice assistant and GTK HUD
vaani --setup      # Launches the interactive onboarding setup wizard
vaani --version    # Prints the installed package version
vaani --help       # Displays available options and flags

---

Real-Time HUD States

The transparent overlay dynamically changes colors and symbols to represent Vaani's cognitive state:

State	Accent Color	Visualizer Behavior	Symbol	Description
Standby	Grey	Static flat line	◌	Waiting for user conversation to begin
Listening	Accent Blue	Active real-time microphone RMS waves	(waves)	Audio stream actively processing your voice
Thinking	Purple Accent	Subtle pulsing diamond	◈	Gemini processing query / running tool calls
Speaking	Green Accent	Active real-time assistant speaker waves	(waves)	Native audio playback active
Muted	Crimson Red	Static flat line	⊘	Microphone input disabled (Privacy Mode)
Offline	Grey / Red	Static flat line	✕	Network disconnected / connection retry loop

---

systemd User Service (Autostart)

If you installed via the .deb package (Option A), you can configure Vaani to start automatically when you log into your desktop environment:

# Enable the user service
systemctl --user enable vaani

# Start the service immediately
systemctl --user start vaani

# Stop the service
systemctl --user stop vaani

# View real-time logs
journalctl --user -u vaani -f

---

Developer Diagnostics

Before modifying code or reporting issues, use the diagnostics utility to verify your current environment state:

python3 scripts/diagnostics.py

This utility performs tests on the following subsystems:

• API Key Validity: Tests connection to Google Gemini developer endpoints.
• Audio Pipeline: Validates sounddevice sample rate and system output.
• Socket Connectivity: Verifies PulseAudio/PipeWire sockets.
• GTK Libraries: Verifies GObject introspections and CSS rendering.
• Data Integrity: Checks JSON databases in data/.

---

Directory Mappings

• Global Config File: ~/.config/vaani/.env (Stores your secure GEMINI_API_KEY)
• Venv Workspace: ~/.local/share/vaani/venv/
• Application Databases: ~/.local/share/vaani/data/ (Contains user facts, notes, memory maps)
• Shared Docs: /usr/share/doc/vaani/

---

License & Support

Standard MIT License. Created by Yash Thakare, 2026. For any issues, please run system diagnostics first and reference the results in your inquiry.