AI Voice Desktop Assistant

Open-source voice-first AI assistant for Windows with Whisper, GPT, and ElevenLabs.

Created by Enterprise DNA -- a leading data and AI education company.

What is it? • Built with AI • Features • Tech Stack • Quick Start • Architecture • Dev with AI • Contributing • License

---

What is AI Voice Desktop Assistant?

AI Voice Desktop Assistant is an open-source Windows desktop app that turns your voice into text anywhere you can type. Press a global hotkey (Ctrl+Space), speak, and the app records your microphone, streams the audio to OpenAI's Whisper transcription model, and types the result into whatever window you are focused on -- a Slack thread, a VS Code editor, a Google Doc, an email draft.

It is a small, focused, always-on-top utility built with PyQt6. The window has a single record button and a live audio-level bar so you know when the mic is hot. Everything else stays out of the way.

This is the open-source mirror of Echo Assist, originally released by Omni Intelligence.

Why another voice typer?

• Bring your own keys -- no subscription, no middleman, just your own OpenAI (and optionally ElevenLabs) API key in a local .env file
• Global hotkey -- works from any focused application; you never need to alt-tab to the assistant window
• Frameless, always on top -- the window is draggable, tiny, and stays visible so you can monitor recording state at a glance
• Audio-level visualisation -- a live bar tells you the mic is actually capturing, which is the bug most voice tools hide from you
• Configurable input device -- the settings panel lists every input device PyAudio can enumerate; pick whichever you like
• Open and hackable -- ~300 lines of Python per module, MIT licensed

---

Built with AI

This project was developed and open-sourced with AI-assisted development tools. Enterprise DNA believes in the future of AI-augmented software development, and this repo is a reference for what is possible. The audio pipeline, PyQt6 UI, and open-source release pipeline were all iterated with AI coding agents.

AI Development Tools Used

Tool	Role
Claude Code by Anthropic	Primary AI coding agent used to audit, clean, and prepare the open-source release.
Cursor	AI-powered IDE for inline edits and refactors across the Python modules.
GitHub Copilot	Pair-programming assistant for code completion and pattern matching.

Enterprise DNA is committed to demonstrating that AI tools are not just productivity boosters -- they are a new way to build software.

---

Features

Voice-to-Text (Whisper)

• Global Ctrl+Space hotkey toggles recording from anywhere on the system
• Microphone capture via PyAudio at 16 kHz mono, 16-bit PCM
• Background QThread streams audio frames without blocking the UI
• On stop, the captured WAV is sent to OpenAI's gpt-4o-mini-transcribe model and transcribed to text
• The transcribed text is typed into the currently focused window via the keyboard library
• Temporary voice_record.wav is deleted after successful transcription

Live Audio Visualisation

• A PyQt6 frame grows and shrinks with your microphone level in real time
• Useful for verifying mic permissions, input gain, and the right device is selected before you start speaking

Microphone Settings Panel

• A settings gear lists every input device PyAudio reports
• Optional PREFERRED_MIC_NAME environment variable auto-selects the first device whose name matches a substring (for example, blue yeti)
• Switching the microphone while recording restarts the capture stream cleanly

Minimalist Frameless UI

• Always-on-top, draggable, borderless window
• Dark theme driven by a small ThemeConfig stylesheet
• Ctrl+Q hotkey closes the app, Ctrl+Space toggles recording
• Custom window icon

---

Tech Stack

Layer	Technology
Language	Python 3.8+
UI Framework	PyQt6 (Qt 6)
Audio Capture	PyAudio (PortAudio bindings)
Audio Math	NumPy
Transcription	OpenAI Whisper / gpt-4o-mini-transcribe
Chat / LLM	OpenAI GPT (optional, via openai SDK)
Text-to-Speech	ElevenLabs (optional)
Global Hotkey	keyboard (Win32 hook)
Config Loader	python-dotenv
OS	Windows 10 / 11

---

Quick Start

Prerequisites

• Python 3.8+ (3.11 or 3.12 recommended)
• Windows 10 or 11 (the keyboard library uses Win32 hooks, so the app is Windows-only)
• A working microphone
• An OpenAI API key
• An ElevenLabs API key (optional, only for text-to-speech features)

Step 1: Clone the Repo

git clone https://github.com/Enterprise-DNA-OS/ai-voice-desktop-assistant.git
cd ai-voice-desktop-assistant

Step 2: Create a Virtual Environment

python -m venv .venv
.venv\Scripts\activate

Step 3: Install Dependencies

pip install -r requirements.txt

PyAudio note. PyAudio depends on PortAudio. If pip install fails on Windows, use:

pip install pipwin
pipwin install pyaudio

Step 4: Configure Environment Variables

copy .env.example .env

Open .env and fill in your keys:

OPENAI_API_KEY=your-openai-api-key
ELEVENLABS_API_KEY=your-elevenlabs-api-key
AGENT_ID=your-agent-id
KMP_DUPLICATE_LIB_OK=TRUE

Only OPENAI_API_KEY is required for voice typing. ELEVENLABS_API_KEY and AGENT_ID are optional and only consumed by future TTS features.

Step 5: Run the App

python productivity_app.py

Or double-click run.bat to launch with no console window (productivity_app.pyw).

Press Ctrl+Space from any focused window to start recording. Press it again to stop. The transcribed text is typed into whichever window has focus.

---

Architecture

Project Structure

ai-voice-desktop-assistant/
  productivity_app.py       Entry point (console build)
  productivity_app.pyw      Entry point (windowed / no-console build)
  config.py                 Window size, audio device, AGENT_ID config
  run.bat                   Windows launcher (uses pythonw)
  requirements.txt          Python dependencies
  .env.example              Sample environment variables
  echo_assist.ico           App icon
  modules/
    voice_typer.py          Audio capture, Whisper call, UI widget
    style_config.py         PyQt6 theme / stylesheet tokens

Runtime Flow

User presses Ctrl+Space (global hook via `keyboard`)
  -> VoiceTyperWidget.toggle_recording
    -> VoiceTyperThread (QThread) starts
      -> PyAudio opens input stream at 16 kHz mono
      -> loop: read 512 frames, emit audio_level, append to buffer
      -> until stop_event is set
    -> stream.close, write buffer to voice_record.wav
    -> OpenAI client.audio.transcriptions.create(
         model="gpt-4o-mini-transcribe", file=...)
    -> emit text_ready(transcript)
  -> VoiceTyperWidget.handle_text
    -> keyboard.write(transcript) into the focused window

All long-running work happens on a QThread. The UI thread only reacts to signals: audio_level, transcribing_status, text_ready, and error_occurred.

Key Design Decisions

• One thread per recording session. Each press of the record button spawns a fresh VoiceTyperThread. When the user stops, the thread writes the WAV, calls Whisper, emits the text, and exits. No global worker pool.
• Hotkeys registered once per widget instance. setup_global_hotkey runs in __init__ and cleanup removes them. This avoids double-fire bugs when the widget is reloaded.
• Frameless, always-on-top window. The main window is borderless and draggable via mouse events on the window itself, not a custom title bar.
• No audio is streamed to OpenAI during recording. The entire capture is buffered locally and sent as one request after the user stops. This keeps latency predictable and avoids partial-transcript glitches.
• Temporary files live next to the script. voice_record.wav is written to the current working directory and deleted after a successful transcription.

Configuration

config.py is the single source of truth for runtime tunables. Every value can be overridden via environment variables:

Setting	Env var	Default
Default input device index	DEFAULT_INPUT_DEVICE_INDEX	0
Preferred mic name (substring match)	PREFERRED_MIC_NAME	empty
ElevenLabs agent id	AGENT_ID	empty
Window size	(hardcoded)	300 x 300

---

Developing with AI Tools

This project is designed to work well with AI development tools. Two files make this explicit:

• CLAUDE.md -- Project-wide instructions, conventions, and architecture overview. Claude Code reads this automatically.
• AGENTS.md -- Defines specialist agents with clear ownership boundaries.

Using Claude Code

Open the project folder in Claude Code. The agent will pick up CLAUDE.md and AGENTS.md automatically and follow the conventions.

Using Cursor

Open the project in Cursor. The CLAUDE.md file serves as context for Cursor's AI features. Use inline edit (Cmd+K / Ctrl+K) for quick changes and the chat panel for larger refactors.

Using GitHub Copilot

Copilot picks up patterns from the existing modules (PyQt6 signal / slot, thread lifecycle, hotkey registration). The consistent conventions in CLAUDE.md make Copilot suggestions more accurate.

Contributing with AI Tools

We encourage contributors to use AI tools. If you submit a PR:

1. Mention which AI tools you used -- we see it as a positive
2. Follow the conventions in CLAUDE.md
3. Use the specialist agent boundaries in AGENTS.md
4. Run python -m py_compile on every file you touched before submitting

---

Contributing

See CONTRIBUTING.md for detailed guidelines.

TL;DR:

1. Fork the repo
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes (AI tools welcome)
4. Run python -m py_compile productivity_app.py modules/voice_typer.py to verify every file still parses
5. Commit with a descriptive message
6. Push to your fork and open a PR

---

License

MIT -- use it however you want.

---

Acknowledgments

• Originally released as Echo Assist by Omni Intelligence
• Built with Claude Code by Anthropic
• Developed in Cursor -- the AI-powered IDE
• AI pair programming by GitHub Copilot
• Speech-to-text and chat models by OpenAI
• Voice synthesis by ElevenLabs
• UI framework from the Qt Project and the PyQt6 maintainers
• Audio capture powered by PortAudio and PyAudio
• Global hotkey hook via keyboard

---

Built with pride by Enterprise DNA
Powered by AI-assisted development with Claude Code, Cursor, and GitHub Copilot