# Desktop Voice Control

## Overview

OpenCode Desktop includes built-in microphone voice control for Windows (and other Electron platforms). Speak to fill the prompt, or issue short voice commands such as `send`, `clear`, and `stop`.

## Requirements

1. OpenCode Desktop app (Electron)
2. One cloud STT API key in the environment:
   - `DEEPGRAM_API_KEY` (recommended for streaming)
   - `GROQ_API_KEY`
   - `OPENAI_API_KEY`
3. Optional native recorder: SoX (`winget install sox`) or FFmpeg  
   If missing, the app automatically falls back to browser `getUserMedia` capture in the renderer.

## Usage

1. Open **Settings → Voice**
2. Choose provider, language, and hotkey (default `Alt+Space`)
3. Press the microphone button next to Send, or press the global hotkey
4. Speak
5. Press the hotkey / button again to stop
6. Review the inserted text, then send (or say `send` if commands are enabled)

## Voice commands

When **Voice commands** is enabled, short phrases are treated as commands instead of dictation:

| Phrase | Action |
| --- | --- |
| send / submit / go | Submit prompt |
| run / execute | Submit prompt |
| accept / approve / yes | Allow pending permission once |
| reject / deny / no | Deny pending permission |
| clear / reset / erase | Clear prompt |
| stop / cancel / abort | Stop generation |
| scroll up / scroll down | Scroll timeline |
| focus | Focus prompt |
| new line / line break | Insert newline |

Longer utterances are always treated as dictation text.

## Architecture

```
Hotkey / Mic button
  → Desktop main VoiceManager
  → Native SoX/FFmpeg capture OR renderer PCM stream
  → Cloud STT (Deepgram WS / Groq / OpenAI Whisper)
  → IPC transcription event
  → App VoiceProvider
  → Command parser OR prompt insert
```

### Packages

- `packages/desktop/src/main/voice/` — main-process capture, STT, IPC, hotkeys
- `packages/app/src/voice/` — UI, context, command parser, settings
- `packages/opencode/src/config/voice.ts` — Effect Schema for voice config

## Security

API keys are read only from environment variables. They are never written to `opencode.json` or electron-store.
