version
Turn any Bluetooth speaker into an offline AI smart speaker.
CI License: MIT Python 3.11+ Tests Lint
Zero hardware engineering — pure software only.
Primary target: Sony SRS-XB100 · Works with any A2DP Bluetooth speaker.
🌐 Website · Installation · Documentation · Contributing · Roadmap
XBMind turns a Linux machine + Bluetooth speaker + USB microphone into a fully functional offline AI smart speaker — like Alexa or Google Home, but running entirely on your hardware with no cloud dependency.
Say "Hey Jarvis", ask a question, and hear the answer through your Bluetooth speaker. That's it.
| Feature | Description |
|---|---|
| 🔵 Bluetooth Auto-Pair | Discovers, pairs, and auto-reconnects with exponential backoff via D-Bus |
| 🎙️ Always-On Mic | Low-latency capture via sounddevice with USB mic auto-detection |
| 👂 Wake Word | openWakeWord (ONNX) in a dedicated OS thread — default: "Hey Jarvis" |
| 🗣️ Speech-to-Text | Offline via faster-whisper (CTranslate2) with optional Google Cloud fallback |
| 🧠 LLM Brain | Ollama (offline) with swappable providers: OpenAI, Claude, Gemini |
| 🔧 Built-in Tools | Weather, date/time, timers, Wikipedia, shell commands |
| 📢 Text-to-Speech | Piper TTS (offline) via subprocess pipe, optional ElevenLabs fallback |
| 💾 Memory | SQLite conversation history with auto-summarization |
| 🏥 Health Check | HTTP endpoint at localhost:7070/health with JSON component status |
| ⚙️ Systemd Ready | User service with auto-start, journald logging |
Mic → Wake Word → VAD → STT → LLM → TTS → Bluetooth Speaker
│ │
openWakeWord Ollama (local)
"Hey Jarvis" + tool calling
Detailed pipeline diagram
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Bluetooth │────▶│ Audio In │────▶│ Wake Word │
│ Manager │ │ (sounddev) │ │ (oww/onnx) │
└──────────────┘ └──────────────┘ └──────┬───────┘
│ wake!
┌──────▼───────┐
│ VAD │
│ (silero+buf) │
└──────┬───────┘
│ speech
┌──────▼───────┐
│ STT │
│ (whisper) │
└──────┬───────┘
│ text
┌──────▼───────┐
┌──────────────────────▶│ LLM │◀── Tools
│ conversation memory │ (ollama) │ (weather,
│ (SQLite) └──────┬───────┘ timer, ...)
│ │ response
│ ┌──────▼───────┐
│ │ TTS │
│ │ (piper) │
│ └──────┬───────┘
│ │ audio
│ ┌──────▼───────┐
└───────────────────────│ Audio Out │
│ (BT sink) │
└──────────────┘
- Linux — Arch, Ubuntu, Debian, Fedora, openSUSE, Void, or Alpine
- Python 3.11+ — tested up to 3.14
- Bluetooth adapter — built-in or USB dongle
- USB microphone — or built-in laptop mic
git clone https://github.com/nibir-ai/XBMind.git
cd XBMind
./scripts/install.shThe interactive installer handles everything:
| Phase | What it does |
|---|---|
| 1 | Detects your distro and package manager |
| 2 | Installs system dependencies (bluez, pipewire, portaudio) |
| 3 | Creates Python venv and installs all packages |
| 4 | Downloads AI models (Piper, Whisper, openWakeWord) |
| 5 | Installs and configures Ollama + pulls an LLM model |
| 6 | Configures Bluetooth auto-pairing |
| 7 | Sets up systemd user service |
| 8 | Creates local config with your speaker name |
Every step is optional — press n to skip.
# Activate venv (pick your shell): source .venv/bin/activate # bash / zsh source .venv/bin/activate.fish # fish # Launch: python -m xbmind.main # Or run directly without activating: .venv/bin/python -m xbmind.main # Or as a systemd service: systemctl --user enable --now xbmind
XBMind/
├── xbmind/ # Core Python package
│ ├── main.py # Orchestrator & entry point
│ ├── config.py # Pydantic v2 settings
│ ├── bluetooth/ # D-Bus BT management + audio sink
│ ├── audio/ # Mic capture, Silero VAD, playback
│ ├── wake_word/ # openWakeWord detector
│ ├── stt/ # Speech-to-text (Whisper, Google)
│ ├── llm/ # LLM providers + tool system + memory
│ ├── tts/ # Text-to-speech (Piper, ElevenLabs)
│ └── utils/ # Event bus, health server, logging
├── config/ # YAML configuration files
├── scripts/ # Interactive master installer
├── systemd/ # Systemd user service
├── tests/ # 69 pytest tests (all mocked, no hardware)
├── docs/ # Full documentation
└── .github/ # CI/CD workflows, issue templates
| Distribution | Package Manager | Status |
|---|---|---|
| Arch / Manjaro / EndeavourOS | pacman |
✅ Tested |
| Ubuntu / Debian / Pop!_OS | apt |
✅ Supported |
| Fedora / RHEL | dnf |
✅ Supported |
| openSUSE | zypper |
✅ Supported |
| Void Linux | xbps |
✅ Supported |
| Alpine Linux | apk |
| Guide | Description |
|---|---|
| Architecture | System design, async model, event bus, thread model |
| Installation | Step-by-step setup for all distros |
| Configuration | Every config.yaml key documented |
| Custom Wake Word | Train your own openWakeWord model |
| Custom TTS Voice | Use any Piper ONNX voice |
| Adding Tools | Write and register new LLM tools |
| Troubleshooting | 20+ real issues with fixes |
| Hardware Tested | Community-verified hardware list |
Contributions welcome! See CONTRIBUTING.md for guidelines and CODE_OF_CONDUCT.md for community standards.
MIT — see LICENSE.