{"id":43932068,"url":"https://github.com/cliffmin/voxcore","last_synced_at":"2026-02-07T00:14:34.533Z","repository":{"id":314984240,"uuid":"1047642403","full_name":"cliffmin/voxcore","owner":"cliffmin","description":"Free, fast, offline voice dictation. Record anywhere, paste anywhere. Never lose a recording.","archived":false,"fork":false,"pushed_at":"2025-12-19T02:08:52.000Z","size":12360,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-19T09:32:10.711Z","etag":null,"topics":["accessibility","dictation","java","jnativehook","macos","openai","speech-to-text","whisper"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cliffmin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":null},"created_at":"2025-08-30T22:02:42.000Z","updated_at":"2025-12-17T03:09:11.000Z","dependencies_parsed_at":"2025-09-18T09:38:05.559Z","dependency_job_id":null,"html_url":"https://github.com/cliffmin/voxcore","commit_stats":null,"previous_names":["cliffmin/macos-ptt-dictation","cliffmin/voxcore"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/cliffmin/voxcore","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cliffmin%2Fvoxcore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cliffmin%2Fvoxcore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cliffmin%2Fvoxcore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cliffmin%2Fvoxcore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cliffmin","download_url":"https://codeload.github.com/cliffmin/voxcore/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cliffmin%2Fvoxcore/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29181289,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-06T23:15:33.022Z","status":"ssl_error","status_checked_at":"2026-02-06T23:15:09.128Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accessibility","dictation","java","jnativehook","macos","openai","speech-to-text","whisper"],"created_at":"2026-02-07T00:14:33.873Z","updated_at":"2026-02-07T00:14:34.516Z","avatar_url":"https://github.com/cliffmin.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# VoxCore\n\n[![CI](https://github.com/cliffmin/voxcore/actions/workflows/ci.yml/badge.svg)](https://github.com/cliffmin/voxcore/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/cliffmin/voxcore/branch/main/graph/badge.svg)](https://codecov.io/gh/cliffmin/voxcore) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) ![macOS](https://img.shields.io/badge/macOS-11%2B-blue) ![Java 17+](https://img.shields.io/badge/Java-17%2B-orange)\n\n**Universal voice-to-anything hotkey.** VoxCore captures once and pastes anywhere—ChatGPT, Claude, Cursor, Slack, email—while saving every recording so you never lose work. One hotkey. Zero tokens. Sub-second, on-device, private by default.\n\nBuilt for AI prompt workflows and cross-app dictation: fast local transcription, WAV backups for reliability, and optional VoxCompose plugin for adaptive refinement when you want LLM polish.\n\n---\n\n## See It In Action\n\n![VoxCore Demo](assets/demo.gif)\n\n*Hold ⌘+⌥+⌃+Space anywhere → speak → instant transcription at your cursor. Works in every app.*\n\n---\n\n## Why VoxCore?\n\n### ⚡ **Fast as Cloud (Or Faster)**\n- **Sub-second transcription** - 8-second recording: VoxCore \u003c1s, ChatGPT 4-5s\n- **No network latency** - Local processing, instant results\n- **Critical for AI workflows** - When prompting 20-50x/day, seconds add up\n- **Consistent performance** - No API overhead, no rate limiting, no cloud delays\n\n### 🛡️ **Never Lose Work Again**\n- **Always saves WAV** - Even if transcription fails, audio is saved\n- **Your recordings, forever** - No cloud dependency, no single point of failure\n- **Real story:** You spoke a 5-minute explanation. Cloud error. Recording lost forever. With VoxCore, the WAV is saved. Retry transcription or listen to the original audio.\n- **Reliability + Privacy** - Stored locally = private + reliable\n\n### 💰 **Free Forever**\n- **Zero tokens for transcription** - Save tokens for AI inference\n- **No subscriptions** - Open source, free forever\n- **No rate limits** - Transcribe 1000x/day if you want\n- **Real savings:** 1,500 transcriptions/month = $15/month saved (at $0.01/transcription)\n\n### 🧠 **Adapts to You**\n- **VoxCompose plugin** - LLM layer that learns your speech patterns\n- **More plugins coming** - Journal mode, email mode, meeting notes\n- **Extensible architecture** - Community plugins welcome\n- **Your choice:** Fast-only (VoxCore) or Fast + Smart (VoxCore + VoxCompose)\n\n### 🎯 **Maximizes AI Prompt Workflows**\n- **Works everywhere** - ChatGPT, Claude, Cursor, Slack, email, any app\n- **One universal hotkey** - Same workflow, every app, every time\n- **3-4x faster than typing** - Speak 150-200 words/min vs type 40-60 words/min\n- **Better AI results** - Verbal explanations include nuance and context\n\n### 🔒 **100% Private**\n- **Voice never uploaded** - All processing on-device\n- **HIPAA/GDPR compliant** - By design, not by policy\n- **Open source** - Audit the code, verify the claims\n- **Your data, your control** - No company has access\n\n### 🌐 **Works Everywhere**\n- **Universal paste** - Any app where you can type\n- **Offline capable** - Planes, trains, anywhere (no internet needed)\n- **Configurable** - Customize hotkey, behavior, output\n- **Simple by default** - Works out of the box, customize if you want\n\n---\n\n## Quick Start\n\n```bash\n# Install via Homebrew (recommended)\nbrew tap cliffmin/tap\nbrew install --cask hammerspoon\nbrew install voxcore\nvoxcore-install\n\n# Grant permissions, then reload Hammerspoon (⌘+⌥+⌃+R)\n```\n\n**Use anywhere:**\n- Hold `Cmd+Alt+Ctrl+Space` → Speak → Release\n- Text pastes at cursor in any app\n- Recording saved to `~/Documents/VoiceNotes/`\n\n\u003cdetails\u003e\n\u003csummary\u003eAlternative: Install from source\u003c/summary\u003e\n\n```bash\nbrew install --cask hammerspoon\nbrew install ffmpeg whisper-cpp openjdk@17\ngit clone https://github.com/cliffmin/voxcore.git\ncd voxcore \u0026\u0026 ./scripts/setup/install.sh\n```\n\u003c/details\u003e\n\n## Upgrading\n\n```bash\nbrew update\nbrew upgrade voxcore\nvoxcore-install  # Updates Hammerspoon integration\n```\n\nAfter upgrading, reload Hammerspoon (⌘+⌥+⌃+R). Your config and recordings are preserved.\n\n## The Problem VoxCore Solves\n\n**AI tools are exploding.** You're using 3-5 AI apps daily (ChatGPT, Claude, Cursor, Perplexity). Each has different or missing voice input. Some burn API tokens. Some require internet. None save your recordings.\n\n**You've lost recordings to cloud failures.** You spoke a 5-minute explanation. Cloud error. Recording gone forever. Under deadline. Can't recreate it.\n\n**You need voice input that:**\n- Works the same everywhere\n- Doesn't cost tokens\n- Works offline\n- **Never loses your recordings**\n- Keeps your voice private\n\n**VoxCore provides universal transcription infrastructure** - one hotkey that works everywhere, with your voice and recordings staying on your Mac.\n\n## Real-World Use Cases\n\n### AI Power Users: Save Tokens, Use Everywhere\n```\nDeveloper: Prompting ChatGPT, Claude, Cursor 50x/day\nProblem: \n- Cursor/Warp voice burns API tokens (monthly limit forces rationing)\n- Different voice input in each app (or missing entirely)\n- Can't use voice freely because it costs money\n\nVoxCore: \n- Same hotkey everywhere (ChatGPT, Claude, Cursor, any app)\n- Zero tokens for transcription (save tokens for AI inference)\n- 1,500 transcriptions/month = $15/month saved\n```\n\n### Never Lose Work: The Cloud Failure Problem\n```\nYou: Spoke 5-minute explanation to ChatGPT\nChatGPT: Sends to cloud → Error → Recording lost forever\nYou: Panic. Under deadline. Can't recreate it.\n\nWith VoxCore: WAV always saved. Retry transcription or listen to original audio.\nYour work is never lost, even if transcription fails.\n```\n\n### Privacy-Critical Work\n```\nHealthcare: Doctor dictating patient notes\nLegal: Lawyer recording case strategy  \nBusiness: Executive discussing confidential plans\n\nConcern: HIPAA/confidentiality/trade secrets\nVoxCore: Voice never uploaded, fully compliant\n```\n\n### Offline Productivity\n```\nPlane WiFi: Not working\nYou: Still need to prompt AI\nVoxCore: Transcribes locally, works perfectly\n```\n\n## How It Compares\n\n| Feature | VoxCore | ChatGPT Voice | Cursor | macOS Dictation |\n|---------|---------|---------------|--------|-----------------|\n| **Speed** | ✅ \u003c1s (4-5x faster) | ⚠️ 4-5s | ⚠️ 2-3s | ❌ 3-5s |\n| **Privacy** | ✅ Never uploaded | ❌ Cloud | ❌ API | ⚠️ Cloud |\n| **Works Everywhere** | ✅ Any app | ❌ ChatGPT only | ❌ Cursor only | ✅ Any app |\n| **Saves Recording** | ✅ WAV backup | ❌ Transient | ❌ Transient | ❌ No |\n| **Offline** | ✅ Yes | ❌ Cloud required | ❌ API required | ❌ Cloud required |\n| **Cost** | ✅ $0 | ⚠️ Subscription | ❌ Burns tokens | ✅ Free |\n| **Rate Limits** | ✅ None | ⚠️ Has limits | ❌ Token limits | ⚠️ Unknown |\n\n## Recent Improvements\n\n- **Better sentence boundaries** - No more \"the. Project. Vox. Core\"\n- **Improved proper noun handling** - CamelCase compounds preserved correctly\n- **~+2% accuracy** vs 0.4.3 with no added cost\n- **Sub-second performance** - End-to-end \u003c1s for short clips\n\n## Core Features\n\n### Universal Transcription\n- Works in every app where you can type\n- Same hotkey, same workflow, consistent results\n- Paste at cursor (ChatGPT, Slack, email, code, anywhere)\n\n### Privacy \u0026 Security\n- 100% on-device processing (verify with Little Snitch)\n- Voice never uploaded to any server\n- No telemetry or tracking\n- Open source - audit the code\n- HIPAA/GDPR-friendly by design\n\n### Reliability\n- WAV files always saved (`~/Documents/VoiceNotes/`)\n- Can retry transcription if it fails\n- Original audio preserved for quality verification\n- Never lose work to cloud errors\n\n### Performance\n- Sub-second transcription for typical prompts\n- Automatic model selection (speed/accuracy balance)\n- Smart post-processing (removes \"um\", \"uh\", fixes punctuation)\n- Often faster than cloud (no network latency)\n\n### Plugin Architecture\n- **VoxCore** - Fast, stateless, algorithmic core\n- **VoxCompose** - Optional LLM layer that adapts to you\n- **More plugins coming** - Journal mode, email mode, meeting notes\n- **Extensible** - Community plugins welcome\n\n### Cost\n- Zero API tokens consumed\n- No rate limits or usage caps\n- No subscriptions or hidden fees\n- Free, unlimited, forever\n\n## Where Your Data Lives\n\n```\n~/Documents/VoiceNotes/\n├── 2025-Nov-15_09.30.00_AM/\n│   ├── .version                      ← Version metadata\n│   ├── 2025-Nov-15_09.30.00_AM.wav  ← Your recording (yours forever)\n│   ├── 2025-Nov-15_09.30.00_AM.txt  ← Transcription\n│   └── 2025-Nov-15_09.30.00_AM.json ← Whisper metadata\n└── tx_logs/\n    └── tx-2025-11-15.jsonl           ← Performance tracking\n```\n\n**You own these files:**\n- No company has access\n- Move/delete/backup as you wish\n- Not dependent on any service\n- Standard formats (WAV, TXT, JSON)\n\n## Verify Privacy Yourself\n\n```bash\n# Install network monitor\nbrew install --cask little-snitch\n\n# Or use tcpdump\nsudo tcpdump -i any\n\n# Use VoxCore and verify: zero network traffic during transcription\n```\n\nIt's open source - audit the code, verify the claims.\n\n## Plugin Architecture\n\n**VoxCore is designed for extensibility.** The core stays lightweight, fast, and stateless. Advanced features come via opt-in plugins.\n\n### Official Plugin: VoxCompose\n\n[**VoxCompose**](https://github.com/cliffmin/voxcompose) is the official plugin for ML-based refinement (completely optional):\n\n- **Adaptive learning** - Learns from your corrections\n- **Context-aware casing** - Technical terms, proper nouns  \n- **LLM refinement** - Optional AI-powered cleanup (local Ollama)\n- **Stateful processing** - Builds user profile over time\n\n**Install or not?** Your choice. VoxCore works perfectly standalone.\n\n**See also:** [VoxCompose Integration Guide](https://github.com/cliffmin/voxcompose/blob/main/docs/voxcore-integration.md) for setup instructions.\n\n#### Vocabulary Learning (VoxCompose Only)\n\n**Note:** This feature is **completely optional** and only activates when VoxCompose is installed. VoxCore works perfectly standalone without any vocabulary file.\n\nIf you have VoxCompose installed, accuracy improves automatically through vocabulary sharing:\n\n1. **VoxCompose learns** - As you correct transcriptions, VoxCompose learns your technical terms, proper nouns, and speech patterns\n2. **Automatic export** - VoxCompose exports learned vocabulary to `~/.config/voxcompose/vocabulary.txt`\n3. **VoxCore detects** - VoxCore automatically detects and reads this file (no configuration needed)\n4. **Better accuracy** - Whisper transcribes technical terms more accurately with vocabulary hints\n\n**Example improvement (VoxCompose users only):**\n- Without vocabulary: \"vox core\" → \"box core\" or \"vox court\"\n- With vocabulary: \"vox core\" → \"VoxCore\" ✓\n\n**If vocabulary file is missing** (VoxCore standalone users): No problem! VoxCore gracefully falls back to default behavior.\n\n\u003cdetails\u003e\n\u003csummary\u003eAdvanced: Manual vocabulary export \u0026 configuration\u003c/summary\u003e\n\n**Export vocabulary manually:**\n```bash\nvoxcompose --export-vocabulary\n```\n\n**Customize vocabulary file location** (optional):\nEdit `~/.config/voxcore/config.json`:\n```json\n{\n  \"vocabulary_file\": \"~/custom/path/vocabulary.txt\",\n  \"enable_dynamic_vocab\": true\n}\n```\n\n**Disable vocabulary** (even if file exists):\n```json\n{\n  \"enable_dynamic_vocab\": false\n}\n```\n\u003c/details\u003e\n\n### Future: Community Extensions\n\nInspired by VS Code's extension marketplace, VoxCore is designed to support community-built plugins:\n\n- **Journal mode** - Transform speech into journal entries\n- **Meeting notes** - Structure as meeting minutes\n- **Code comments** - Format for inline documentation\n- **Custom workflows** - Build your own refinement logic\n\n**Coming soon:** Plugin API and extension marketplace. Stay tuned.\n\n## Ecosystem\n\nVoxCore is the hub of a multi-repo project for local voice-to-text on macOS.\n\n```mermaid\ngraph LR\n    VoxCore[\"VoxCore\u003cbr/\u003e\u003ci\u003eCore transcription engine\u003c/i\u003e\"]\n    VoxCompose[\"VoxCompose\u003cbr/\u003e\u003ci\u003eML transcript refinement\u003c/i\u003e\"]\n    Tap[\"homebrew-tap\u003cbr/\u003e\u003ci\u003eHomebrew distribution\u003c/i\u003e\"]\n    \n    VoxCore --\u003e|\"plugin interface\"| VoxCompose\n    Tap --\u003e|\"installs\"| VoxCore\n    Tap --\u003e|\"installs\"| VoxCompose\n```\n\n| Repository | Purpose | Status |\n|------------|---------|--------|\n| **[VoxCore](https://github.com/cliffmin/voxcore)** | Core push-to-talk transcription engine | v0.7.0 |\n| **[VoxCompose](https://github.com/cliffmin/voxcompose)** | Optional ML-based transcript refinement via local LLMs | v1.0.0 |\n| **[homebrew-tap](https://github.com/cliffmin/homebrew-tap)** | Homebrew formulae for easy installation | Active |\n\n**Architecture:** VoxCore handles recording, transcription (whisper-cpp), and post-processing (Java pipeline). VoxCompose is an optional plugin that adds self-learning corrections and LLM refinement via local Ollama. They communicate through a stdin/stdout plugin protocol, keeping concerns cleanly separated.\n\n## Documentation\n\n- **[Setup Guide](docs/setup/)** - Installation and configuration\n- **[Usage Guide](docs/usage/)** - How to use VoxCore\n- **[Performance](docs/performance.md)** - Benchmarks and speed improvements\n- **[Configuration](docs/setup/configuration.md)** - Customize behavior\n- **[Troubleshooting](docs/setup/troubleshooting.md)** - Common issues\n- **[Contributing](CONTRIBUTING.md)** - Development guidelines\n- **[Architecture](docs/development/architecture.md)** - System design\n- **[Versioning](docs/development/versioning.md)** - Releases and version management\n- **[Release Guide](docs/development/release.md)** - Complete release process\n\n## FAQ\n\n**Q: Is my voice really never uploaded?**  \nA: Correct. All processing is local. Verify with Little Snitch or tcpdump.\n\n**Q: How's the accuracy?**  \nA: Whisper-level (~95%+) with smart post-processing for cleanup.\n\n**Q: Does it work offline?**  \nA: Yes, 100%. Perfect for planes, trains, anywhere without internet.\n\n**Q: What if transcription fails?**  \nA: The WAV file is saved. Retry transcription or listen to the original audio.\n\n**Q: Does it cost anything?**  \nA: No. Zero tokens, zero subscriptions. MIT licensed, free forever.\n\n**Q: Will it burn my API tokens?**  \nA: No. VoxCore transcribes locally. Save tokens for actual AI inference.\n\n**Q: What about HIPAA/GDPR?**  \nA: Compliant by design (voice never leaves your device), but consult your legal team.\n\n**Q: Can I customize the hotkey?**  \nA: Yes. Edit `~/.hammerspoon/ptt_config.lua`.\n\n## Roadmap\n\n**Current (v0.7.0):**\n- [x] Fast offline transcription (whisper-cpp)\n- [x] Universal paste (works everywhere)\n- [x] 100% private (never uploads)\n- [x] WAV backup (always saved)\n- [x] Smart post-processing (Java pipeline)\n- [x] Dynamic model selection (base.en for speed, medium.en for accuracy)\n- [x] VoxCompose vocabulary integration (auto-refresh)\n- [x] Robust audio device detection (name-based, handles macOS Continuity)\n- [x] Standalone CLI (`voxcore transcribe`)\n- [x] Plugin architecture (VoxCompose integration)\n\n**Next (v0.8.0):**\n- [ ] Streaming transcription (real-time feedback)\n- [ ] Integration testing (E2E)\n- [ ] Log rotation and observability improvements\n\n**Future:**\n- [ ] Multi-mode plugins (journal, email, meeting modes)\n- [ ] Quick-switch keybinds for different contexts\n- [ ] Multi-language optimization\n- [ ] Linux support (currently macOS only)\n- [ ] Plugin marketplace\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n\n---\n\n**Fast. Private. Secure. Yours.**\n\nYour voice never leaves your Mac. Your recordings are yours forever.\n\nBuilt for people who value speed, privacy, and control.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcliffmin%2Fvoxcore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcliffmin%2Fvoxcore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcliffmin%2Fvoxcore/lists"}