Speak continuously, ask one focused question, type with local suggestions, and interrupt an answer simply by talking. Speech recognition, language generation, speech synthesis, and voice activity detection run locally by default.
Download for Windows x64 · Installation details · Watch the demo
Local Voice Studio is a real-time conversational assistant built for privacy, low latency, and graceful failure. It combines a responsive PySide6 desktop interface with a bounded, cancellable audio pipeline. The app can keep a hands-free conversation going, answer a single recorded question, or accept typed prompts when speaking is inconvenient.
Click the preview to open the full MP4 walkthrough. This is a silent walkthrough rendered from the real PySide6 interface. It demonstrates modes, states, themes, devices, and typed suggestions; it is not presented as a physical microphone, speaker, echo, or voice-quality test.
The supported installer package is for 64-bit Windows 10/11 with at least 8 GB RAM, 8 GB free disk space, a microphone, a speaker/headset, and internet access during the first installation.
- Download LocalVoiceStudio-Windows-x64-v0.2.0.zip.
- Extract the ZIP completely.
- Double-click
INSTALL.bat. - Allow the one-time Python, runtime, and checksum-verified model downloads to finish.
- Start the app from the Local Voice Studio desktop or Start-menu shortcut.
After setup, normal VAD, speech recognition, response generation, and speech output run offline. The optional text-only online fallback remains disabled unless you configure and allow it. The bootstrap package is not yet commercially code-signed, so Windows SmartScreen may show a publisher warning; verify the release SHA-256 file before running it.
No installer can guarantee compatibility with literally every PC. ARM Windows, Windows versions older than 10, restricted corporate application-control policies, missing audio hardware, and unsupported drivers are outside this release target. Linux continues to use the source setup below.
- Two listening modes — continuous Conversation mode and controlled Ask once mode.
- Natural barge-in — speaking during an answer cancels generation, synthesis, and playback before listening to the follow-up.
- Noise-aware listening — local Silero neural VAD with adaptive energy detection as a portable fallback.
- Fully local core — whisper.cpp ASR, a quantized Qwen2.5 model, and Windows SAPI speech output.
- Selectable audio devices — choose the microphone and speaker while viewing live input level and latency.
- Private typing assistance — next-phrase suggestions inspect only the current text field and make no network request.
- Adaptive interface — responsive transcript/response layout with System, Light, and Dark themes.
- Honest fallbacks — missing models, unavailable devices, silence, and time limits produce explicit recoverable states.
- Optional text-only online fallback — disabled by default and activated only with explicit configuration and consent.
| Mode | Best for | How it works |
|---|---|---|
| Conversation | A hands-free back-and-forth | The microphone remains active, natural end-of-speech submits each turn, and speaking over an answer interrupts it automatically. |
| Ask once | A deliberate question or noisy room | Press Listen, speak the complete question, then press Answer. Interrupt cancels an answer and immediately opens a follow-up recording. |
Ask once retains the complete bounded recording, rejects silence, preserves short opening words with pre-roll, and warns when the question reaches its configured time limit.
flowchart LR
MIC["Microphone"] --> QUEUE["Bounded audio queue"]
QUEUE --> VAD["Silero / adaptive VAD"]
VAD --> ASR["whisper.cpp ASR"]
ASR --> VALIDATE["Transcript validation"]
VALIDATE --> LLM["Local Qwen LLM"]
LLM --> CHUNK["Sentence streaming"]
CHUNK --> TTS["Local TTS"]
TTS --> OUT["Selected speaker"]
MIC -. "speech during response" .-> CANCEL["Interruption manager"]
CANCEL --> LLM
CANCEL --> TTS
CANCEL --> OUT
HEALTH["Health, latency, and fallback services"] -.-> ASR
HEALTH -.-> LLM
HEALTH -.-> TTS
Audio callbacks never perform model inference. Bounded queues protect memory, heavy work runs outside the GUI thread, and request epochs prevent cancelled or stale responses from reaching the user. See the detailed architecture document.
- Windows 10/11 or a modern Linux desktop
- 64-bit Python 3.11 or newer
- 8 GB RAM minimum; 16 GB recommended
- A microphone and speaker or headset
- Approximately 8 GB of free disk space for environments, runtimes, and selected models
git clone https://github.com/Nikhi00718/offline-first-voice-assistant.git
cd offline-first-voice-assistant
Set-ExecutionPolicy -Scope Process Bypass
.\setup_windows.ps1
.\.venv\Scripts\python.exe scripts\download_models.py --yes
.\run_windows.batIf the direct llama.cpp wheel is unavailable, install Ollama and pull the configured local model; the application detects the localhost runtime as a fallback. A new terminal may be required after installing Ollama so ollama is available on PATH.
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[full,dev]"
python -m pip install llama-cpp-python --only-binary=:all: `
--extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu
python scripts\install_runtimes.py
python scripts\download_models.py --yes
python scripts\verify_models.py
python -m app.maingit clone https://github.com/Nikhi00718/offline-first-voice-assistant.git
cd offline-first-voice-assistant
chmod +x setup_linux.sh run_linux.sh
./setup_linux.sh
.venv/bin/python scripts/download_models.py --yes
./run_linux.shPortAudio and desktop audio permissions may be required on Linux. Model weights are downloaded separately, license-aware, checksum-verified where pinned, and never stored in Git.
- Launch the app and wait until the model status reports ready.
- Confirm the microphone and speaker in the device strip or choose alternatives in Settings.
- Select Conversation for hands-free listening or Ask once for push-to-record control.
- Speak, or type a prompt and press Enter. Local completion chips can finish common typed questions.
- Speak during an answer in Conversation mode, or press Interrupt in Ask once mode, to start a follow-up.
- Choose System, Light, or Dark appearance from Settings.
The user guide covers detector sensitivity, audio devices, themes, interruption, and fallback behavior.
The default path is offline:
- raw microphone audio is not stored;
- model weights and native runtimes remain on the machine;
- typed suggestions use no network service;
- conversation storage is opt-in;
- online fallback and transcript permission are both off.
An OpenAI-compatible text-only fallback can be enabled explicitly. ASR and TTS remain local, so microphone audio is not uploaded.
$env:RVA_ONLINE_PROVIDER = "openai-compatible"
$env:RVA_ONLINE_ENDPOINT = "https://provider.example/v1/chat/completions"
$env:RVA_ONLINE_MODEL = "provider-model-name"
$env:VOICE_ASSISTANT_API_KEY = "your-secret-key"
$env:RVA_ONLINE_ENABLED = "true"
$env:RVA_PRIVACY_ALLOW_ONLINE_TRANSCRIPTS = "true"
.\run_windows.batThe online provider is contacted only if the local language model fails before returning text. Never commit a populated .env file. Read privacy and security before enabling this option.
The checked-in release was validated with:
- 45 automated tests passed; one physical microphone/speaker test is intentionally marked manual;
- Ruff lint and formatting checks;
- Pyright with zero errors and zero warnings;
- health checks and privacy-safe release packaging;
- independent architecture, security, and submission reviews;
- SHA-256 verification of the generated submission package.
python -m pytest -q
python -m ruff check .
python -m ruff format --check .
pyright
python scripts\health_check.py
python scripts\run_full_evaluation.py
python scripts\build_release.pyPhysical room acoustics, echo cancellation behavior, microphone quality, and long-session comfort still require testing on the target hardware. Results are never presented as passed without an executed check.
app/ application, audio pipeline, model adapters, UI, and orchestration
config/ runtime defaults and checksum-aware model manifest
data/ seed and evaluation templates; private recordings are ignored
docs/ architecture, setup, privacy, testing, decisions, and reports
results/ reproducible benchmark and evaluation outputs
scripts/ diagnostics, downloads, training, evaluation, and release tooling
submission/ checksummed release package and documentation bundle
tests/ unit and cross-component integration tests
| Topic | Document |
|---|---|
| Installation | Installation guide |
| Daily operation | User guide |
| System design | Architecture |
| Models and trade-offs | Model selection |
| Privacy | Privacy and security |
| Testing | Testing guide |
| Benchmarks | Benchmark report |
| Troubleshooting | Troubleshooting |
| Current limitations | Limitations |
| Release readiness | Final completion report |
Contributions are welcome. Keep the core offline-first, do not block inside audio callbacks or the GUI thread, preserve bounded queues and cancellation semantics, and never commit credentials, recordings, databases, or model weights. See CONTRIBUTING.md for the development workflow.
The application source is released under the MIT License. Third-party runtimes and models retain their own licenses; see LICENSES.md and the license report.