{"id":48380750,"url":"https://github.com/jstarfilms/koe","last_synced_at":"2026-06-06T06:03:16.357Z","repository":{"id":342087579,"uuid":"1169232246","full_name":"JStaRFilms/Koe","owner":"JStaRFilms","description":"Lightning-fast, privacy-focused voice dictation for desktop and mobile. Electron + Expo, powered by Groq.","archived":false,"fork":false,"pushed_at":"2026-03-19T20:03:37.000Z","size":8089,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-20T11:15:15.128Z","etag":null,"topics":["android","desktop-app","electron","expo","expo-router","groq","ios","mobile-app","offline-vad","onnxruntime","react","react-native","speech-to-text","vibecoding","voice-dictation","whisper"],"latest_commit_sha":null,"homepage":"https://koe-pink.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JStaRFilms.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":"audit_report.js","citation":null,"codeowners":null,"security":null,"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}},"created_at":"2026-02-28T11:23:13.000Z","updated_at":"2026-03-14T03:51:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/JStaRFilms/Koe","commit_stats":null,"previous_names":["jstarfilms/koe"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/JStaRFilms/Koe","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JStaRFilms%2FKoe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JStaRFilms%2FKoe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JStaRFilms%2FKoe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JStaRFilms%2FKoe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JStaRFilms","download_url":"https://codeload.github.com/JStaRFilms/Koe/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JStaRFilms%2FKoe/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31448216,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T15:22:31.103Z","status":"ssl_error","status_checked_at":"2026-04-05T15:22:00.205Z","response_time":75,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["android","desktop-app","electron","expo","expo-router","groq","ios","mobile-app","offline-vad","onnxruntime","react","react-native","speech-to-text","vibecoding","voice-dictation","whisper"],"created_at":"2026-04-05T20:01:07.083Z","updated_at":"2026-04-05T20:01:07.909Z","avatar_url":"https://github.com/JStaRFilms.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"src/assets/icons/logo.svg\" width=\"120\" alt=\"Koe Logo\"\u003e\n  \u003ch1\u003eKoe (声)\u003c/h1\u003e\n  \u003cp\u003e\u003cstrong\u003eLightning-Fast, Privacy-First Voice Dictation for Windows, iOS, and Android\u003c/strong\u003e\u003c/p\u003e\n\n  [![Release](https://img.shields.io/github/v/release/JStaRFilms/Koe)](https://github.com/JStaRFilms/Koe/releases)\n  [![License](https://img.shields.io/badge/license-ISC-green.svg)](LICENSE)\n  [![Electron](https://img.shields.io/badge/Electron-40.6.1-47848F?logo=electron)](https://electronjs.org/)\n  [![Groq](https://img.shields.io/badge/Powered%20by-Groq-orange)](https://groq.com/)\n\u003c/div\u003e\n\n---\n\n## What is Koe?\n\n**Koe** (声, Japanese for \"voice\") is a free, open-source alternative to subscription-based voice dictation tools. Press a hotkey (Desktop) or a button (Mobile), speak naturally, and get polished AI text typed at your cursor or copied to your clipboard.\n\nUnlike cloud-based solutions that charge monthly fees, Koe uses your own [Groq API key](https://console.groq.com/keys) and stays free for up to 8 hours of transcription a day on Groq's free tier.\n\n### Why Koe?\n\n| Feature | WhisperFlow ($8+/mo) | Built-in OS Dictation | **Koe (Free)** |\n|---------|---------------------|----------------------|----------------|\n| Cost | Subscription | Free | **Free (BYOK)** |\n| Accuracy | High | Poor | **High (Whisper)** |\n| AI Enhancement | Yes | No | **Yes** |\n| Privacy | Cloud audio | Local | **Local VAD + BYOK** |\n| Global Hotkey | Yes | Limited | **Yes** |\n| Auto-Paste | Yes | No | **Yes** |\n\n---\n\n- **Cross-Platform** — Native performance on Windows (Desktop) and iOS/Android (Mobile)\n- **Global Hotkey (Desktop)** — Press `Ctrl + Shift + Space` anywhere to start or stop dictation\n- **Clipboard-First (Mobile)** — High-fidelity audio capture with instant polished results copied to your clipboard\n- **Pause Naturally** — Koe keeps listening through short pauses instead of treating every breath like the end of a recording\n- **Rolling Segments** — Long recordings are processed in the background as ordered chunks, so performance stays fast even on longer sessions\n- **Instant Transcription** — Groq Whisper handles speech-to-text at high speed\n- **AI Text Enhancement** — Each segment is refined before it is committed, so only polished text is returned\n- **Auto-Type (Desktop)** — Refined text is typed progressively into the focused text field while you are still talking\n- **Minimalist UI** — A premium, high-contrast interface designed for focus and speed\n- **Transcription History** — One-click copy and retry for saved transcripts\n- **Usage Dashboard** — Track daily audio seconds, request pressure, and queue activity\n\n---\n\n### Desktop (Windows)\n\n1. Download the latest `.exe` from [Releases](https://github.com/JStaRFilms/Koe/releases).\n2. Install and launch. Koe will live in your system tray.\n\n### Mobile (iOS \u0026 Android)\n\n1. Clone the repo and navigate to `apps/mobile`.\n2. Install [Expo Go](https://expo.dev/go) on your device.\n3. Run `pnpm dev:mobile` and scan the QR code.\n*Note: Native builds (.ipa/.apk) can be generated via EAS.*\n\n### Build Everything from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/JStaRFilms/Koe.git\ncd Koe\n\n# Install all dependencies (Monorepo)\npnpm install\n\n# Run Desktop\npnpm dev\n\n# Build for production\npnpm build\n\n# Run Mobile\npnpm dev:mobile\n```\n\nIf `pnpm dev` fails with `Electron failed to install correctly`, pnpm likely skipped Electron's install script during dependency setup. This repo now allowlists the required build/install scripts for pnpm 10+, and an existing checkout can be repaired with:\n\n```bash\npnpm rebuild electron esbuild protobufjs electron-winstaller\n```\n\n### Release Builds\n\n- Real release artifacts should be built on GitHub Actions, not locally\n- Push a matching version tag such as `v1.1.3` after updating `package.json`\n- The release workflow will build Windows and macOS and attach artifacts to that GitHub Release\n- See [docs/release-process.md](docs/release-process.md)\n\n### Vercel Deployment\n\n- The marketing website is the Next.js app in `koe-website/`\n- In Vercel Project Settings -\u003e Build and Deployment -\u003e Root Directory, set the root to `koe-website`\n- Leave the framework as Next.js for that project\n- A root-level `vercel.json` is also included as a fallback so root builds target `koe-website`\n\n### Requirements\n\n- Windows 10/11 (for Desktop) or iOS/Android (for Mobile)\n- [Groq API Key](https://console.groq.com/keys) (free tier available)\n- Microphone access\n\n---\n\n## Quick Start\n\n1. **Launch** Koe — it minimizes to your system tray\n2. **Configure** — Right-click the tray icon → **Settings** → Enter your Groq API key\n3. **Dictate** — Click any text field and press `Ctrl + Shift + Space`\n4. **Speak** — The pill UI appears. Talk naturally, including pauses\n5. **Done** — Press the hotkey again when you're finished. Koe finalizes the session, copies the full refined transcript, and keeps it in history\n\n---\n\n## Usage Guide\n\n### Global Hotkeys\n\n| Action | Shortcut |\n|--------|----------|\n| Start / Stop Recording | `Ctrl + Shift + Space` |\n| Retry Last Failed / Latest Transcript | `Ctrl + Shift + ,` |\n| Open Settings | Tray menu |\n\n### How Recording Works\n\n- Koe records one continuous session until you stop it\n- Internally, it breaks longer recordings into ordered segments\n- Segments are transcribed and refined in the background\n- Refined text is typed in order as it becomes ready\n- When the session ends, Koe keeps one full final transcript in clipboard and history\n\n### The Pill UI\n\nThe floating pill is designed to stay out of the way while still telling you what matters:\n\n- **Idle** — Waiting for the next dictation\n- **Listening** — Live voice levels and active recording state\n- **Warning** — Mic fallback or chunk failure without immediately killing the session\n- **Processing** — Finalizing remaining work after you stop\n- **Complete** — Brief success state before hiding\n\n### Settings\n\nConfigure via the settings window (right-click the tray icon):\n\n| Setting | Description | Default |\n|---------|-------------|---------|\n| Groq API Key | Your API key from [console.groq.com](https://console.groq.com/keys) | — |\n| Language | Transcription language (`auto` for detection) | `auto` |\n| Prompt Style | How Koe refines the transcript | `Clean` |\n| Auto-Paste | Automatically type into the focused window | `enabled` |\n| Theme | Dark / Light mode | `dark` |\n\n---\n\nKoe uses a shared core architecture to ensure consistency across Desktop and Mobile. Business logic lives in `@koe/core`, while platform-specific drivers handle audio and output.\n\nSee the [Detailed Architecture Guide](docs/Architecture.md) for more info.\n\n### Platform Specifics\n\n| Feature | Desktop (Windows) | Mobile (iOS/Android) |\n|---------|-------------------|----------------------|\n| **Trigger** | Global Hotkey | Capture Button |\n| **Output** | Auto-Paste / Type | Clipboard-First |\n| **Storage** | `electron-store` | `SecureStore` |\n| **Capture Logic** | Local VAD + ordered segments | Metering-driven chunk rotation + ordered segments |\n\n### Privacy-First Design\n\n1. **Desktop speech detection** runs locally using ONNX WebAssembly\n2. **Mobile recording control** stays on-device until a chunk is ready to transcribe\n3. **Retry audio** is stored only for failed or unresolved segments\n4. **Your API key** is stored locally on each platform and only used for transcription/refinement requests\n\n---\n\n## Tech Stack\n\n| Layer | Technology |\n|-------|------------|\n| **Framework** | Electron + Vite |\n| **Frontend** | Vanilla JavaScript, Custom CSS |\n| **Audio Capture** | Web Audio API |\n| **Voice Detection** | `@ricky0123/vad-web` (Silero VAD) |\n| **Transcription** | Groq Whisper API (`whisper-large-v3-turbo`) |\n| **Text Enhancement** | Groq chat refinement pipeline |\n| **Storage** | `electron-store` + temp retry files |\n| **Packaging** | `electron-builder` |\n\n---\n\n## Groq API Limits\n\nKoe is designed to stay inside Groq's free-tier limits:\n\n| Metric | Limit | Approximate Usage |\n|--------|-------|-------------------|\n| Requests per minute | 20 | ~6 transcribed segments/minute with paced refinement |\n| Requests per day | 2,000 | ~8 hours of normal dictation |\n| Audio per day | 28,800 sec | 8 hours |\n\nThe built-in scheduler tracks request pressure and keeps the app responsive while staying inside the cap.\n\n---\n\n## Roadmap\n\n### Completed\n- [x] Global hotkey toggle (Desktop)\n- [x] Local VAD speech detection\n- [x] Groq Whisper transcription\n- [x] AI transcript refinement\n- [x] Auto-paste to focused window (Desktop)\n- [x] Transcription history \u0026 Usage dashboard\n- [x] Mobile App (iOS/Android V1)\n- [x] Shared Core Extraction\n\n### Planned\n- [x] Custom AI prompts\n- [x] Keyboard shortcut customization\n- [ ] Export history as `.txt` / `.md`\n- [x] Native macOS support (Electron)\n- [ ] Android IME (Custom Keyboard) implementation\n\n### Future\n- [ ] Snippet library with voice shortcuts\n- [ ] App-specific tone profiles\n- [ ] Cloud sync across devices\n- [ ] Team collaboration features\n\nSee [Feature Requests](docs/issues/) for the full backlog.\n\n---\n\n## Contributing\n\nContributions are welcome. Please see the repo docs and existing code patterns before opening a PR.\n\n### Development Setup\n\n```bash\n# Fork and clone\ngit clone https://github.com/your-username/Koe.git\ncd Koe\n\n# Install dependencies\npnpm install\n\n# Start development\npnpm dev\n```\n\n### Monorepo Structure\n\nKoe is transitioning to a monorepo to support multiple platforms:\n\n- **Root**: Legacy Electron Desktop app and shared workspace configuration\n- **`apps/mobile`**: Expo-based mobile client (iOS/Android)\n- **`packages/koe-core`**: Shared business logic, types, and API services\n\n### Development Commands\n\n| Target | Command | Description |\n|--------|---------|-------------|\n| **Desktop** | `pnpm dev` | Start the Electron app in dev mode |\n| **Mobile** | `pnpm dev:mobile` | Start the Expo development server |\n| **Core** | `pnpm build:core` | Build the shared logic package |\n| **All** | `pnpm type-check` | Run type-checking across all packages |\n\n### Project Structure\n\n```text\nKoe/\n├── apps/               # Application projects\n│   └── mobile/        # Expo mobile app\n├── packages/           # Shared logic\n│   └── koe-core/      # Core services (Whisper, Sessions)\n├── src/                # Legacy Desktop source\n│   ├── main/           # Electron main process\n│   └── renderer/       # UI code\n├── docs/               # Documentation \u0026 Tasks\n├── pnpm-workspace.yaml # Workspace config\n└── package.json        # Root manifest \u0026 scripts\n```\n\n---\n\n## Troubleshooting\n\n### \"No audio detected\"\n- Ensure microphone permissions are granted in Windows Settings\n- Check that your default recording device is selected\n- If another app is holding the mic, Koe will try another available input and warn you in the pill UI\n\n### \"API rate limit exceeded\"\n- Wait for the per-minute window to clear\n- Check the usage dashboard for queue pressure\n- Very long continuous dictation can still pile up requests on the free tier\n\n### \"Auto-paste not working\"\n- Some applications block simulated keystrokes\n- Disable auto-paste in Settings and use `Ctrl + V` manually\n- Run Koe as administrator if the issue persists\n\n### App won't launch\n- Ensure you're on Windows 10/11 64-bit\n- Check that [Visual C++ Redistributables](https://aka.ms/vs/17/release/vc_redist.x64.exe) are installed\n- Check Windows Event Viewer for crash details\n\n---\n\n## Acknowledgments\n\n- **Groq** — For the fast Whisper and chat APIs\n- **Silero** — For the VAD model\n- **@ricky0123** — For the `vad-web` library\n- **WhisperFlow** — For helping prove the category exists\n\n---\n\n## License\n\nKoe is licensed under the ISC License. See the [LICENSE](LICENSE) file for details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \u003cp\u003eBuilt with ❤️ by \u003ca href=\"https://github.com/JStaRFilms\"\u003eJ StaR Films Studios\u003c/a\u003e\u003c/p\u003e\n  \u003cp\u003e\u003csub\u003eStar us on GitHub if you find Koe useful.\u003c/sub\u003e\u003c/p\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjstarfilms%2Fkoe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjstarfilms%2Fkoe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjstarfilms%2Fkoe/lists"}