A cross-platform voice-to-text assistant. The desktop app captures speech on a global hotkey, transcribes it through ChatGPT, and pastes the result into whatever app is focused. An Android keyboard lives in voxa-kotlin/.
Current version: 0.2.4
- System-wide hotkey — Start and stop recording from any app (default:
F9to start on Windows/Linux,Option+Spaceon macOS — F9 collides with Mission Control on many Mac keyboards;Escapeto stop everywhere) - Recording overlay — Small floating widget with a live timer
- ChatGPT transcription — Uses ChatGPT's backend Whisper API for speech-to-text
- Auto-paste — Transcript is copied to the clipboard and pasted into the focused field (Windows:
Ctrl+Vvia SendKeys; macOS:Cmd+Vvia System Events, requires Accessibility permission; Linux: clipboard fallback) - Hub UI — Home, History, Microphone, Shortcuts, and Settings in one window
- Dictation history — Browse past transcripts with source app labels, word counts, and pagination
- Audio retention — Replay saved recordings; configurable retention and disk limits
- Retry — Re-transcribe failed dictations from stored audio
- Unlimited recording — No hard cap on session length (configurable max duration in Settings)
- Background operation — Runs in the system tray with optional launch at login
The voxa-kotlin/ tree contains a HeliBoard-based IME with an in-keyboard mic for voice input on Android. See voxa-kotlin/CLAUDE.md for build notes.
- Clone this repository:
git clone https://github.com/blackscythe123/voxa.git cd voxa - Install dependencies:
npm install
npm startThe app opens the Hub window and adds a system tray icon. You can close the window and keep dictating from the tray.
-
Sign in to ChatGPT
- Open Settings in the Hub (or right-click the tray icon → Login to ChatGPT)
- A browser window opens for ChatGPT login (2FA, CAPTCHA, etc.)
- Once signed in, your session is saved locally and the browser closes
-
Configure hotkeys and audio (optional)
- Shortcuts — Set start/stop hotkeys and overlay position
- Microphone — Choose input device
- Settings — Retention limits, privacy mode, launch at login, and recording duration
- Click into any text field (VS Code, Google Docs, Word, Slack, etc.)
- Press your start hotkey (
F9by default on Windows/Linux,Option+Spaceon macOS) - The recording overlay appears with a timer
- Speak naturally
- Press the stop hotkey or click Stop
- Wait a few seconds for transcription
- The transcript is pasted into the focused field (or left on the clipboard if paste fails)
Open History in the Hub to review, replay audio, copy text, or retry failed dictations.
npm run build:win # Windows NSIS installer
npm run build:mac # macOS DMG + zip
npm run build:linux # Linux AppImage + deb
npm run build:all # All platformsOutput lands in dist/.
src/
├── main.js # Electron main process (hotkeys, tray, IPC, dictation pipeline)
├── preload.js # Secure preload bridge
├── services/
│ ├── chatgptAuth.js # ChatGPT login + transcription API
│ ├── configStore.js # Local preferences (electron-store)
│ ├── historyStore.js # Dictation history (JSON on disk)
│ ├── audioStore.js # Saved recording files
│ ├── retentionWorker.js # Audio/history cleanup by retention policy
│ ├── sourceApp.js # Foreground app detection for history labels
│ └── textInserter.js # Clipboard + paste into focused window
└── renderer/
├── index.html # Hub shell (sidebar + routed views)
├── overlay.html # Recording overlay
├── renderer.js # Hub router, audio capture, history UI
└── styles/ # tokens, hub, history, views
- Electron — Desktop app framework
- electron-store — Local preference persistence
Dictation history and audio are stored under the app's user data directory (history.json and an audio/ folder).
- ChatGPT session cookies are stored in the app's local user data folder
- Audio is sent to ChatGPT's servers for transcription
- Privacy mode (Settings) skips writing history and audio to disk
- Automatic paste is implemented on Windows and macOS (macOS requires Accessibility permission — Voxa will prompt on first launch); Linux relies on clipboard + manual paste
- macOS builds are unsigned and not notarized — Gatekeeper will flag the app as from an "unidentified developer" on first launch (see Troubleshooting below)
- Password fields are excluded from paste targets where possible
- ChatGPT's internal API endpoints may change; updates may be required
Hotkey not working?
- Check for conflicts with system hotkeys or other apps
- Try a different hotkey in Shortcuts
Recording but no transcription?
- Sign in again via Settings or the tray menu
- Check your internet connection
- ChatGPT may be rate-limited or temporarily unavailable
Microphone not working?
- Grant microphone permission when prompted
- Pick the correct device under Microphone
- Confirm the mic works in another app
Text not inserting?
- Click the target field before dictating
- On macOS, grant Accessibility permission (System Settings → Privacy & Security → Accessibility) — without it, auto-paste silently falls back to clipboard-only
- On Linux, paste manually from the clipboard (
Ctrl+V) - Some secure fields block programmatic paste
macOS says the app is from an "unidentified developer"?
- The app isn't notarized (no Apple Developer account). Right-click the app in Finder and choose Open, or run
xattr -cr /Applications/Voxa.appin Terminal, then launch normally.
History or audio missing?
- History requires a successful
npm installwith no errors loading history services - Check retention settings in Settings (success audio defaults to kept indefinitely, bounded by disk cap)
- Edit files in
src/ - Restart the app (
npm start) - Main-process changes require a full restart
Regenerate tray/app icons after asset changes:
npm run iconsMIT — see LICENSE.
For issues or feature requests, open an issue on GitHub.