voice-dictation 1.0.0
Voice-to-text dictation using ChatGPT transcription. Press hotkey to record, transcribed text pastes at cursor.
License: MIT
Requires Python: >=3.8
Keywords: voice, dictation, speech-to-text, transcription, whisper, chatgpt

# Voice Dictation

Cross-platform voice-to-text using ChatGPT transcription. Press **Ctrl+Shift+R** to start recording, press again to stop - simple toggle!

## How It Works

1. Run `dictate-hotkey-install` - Sets up the hotkey service
2. Press **Ctrl+Shift+R** - Starts recording (shows "[Recording...]")
3. Press **Ctrl+Shift+R** again - Stops, transcribes, types text at cursor

## Features

- **Simple toggle**: Same hotkey to start and stop
- **Cross-platform**: Windows, macOS, Linux (GNOME, KDE, XFCE)
- **Auto-type**: Transcribed text typed at cursor position
- **Background service**: Runs silently, always ready

---

## Quick Start

```bash
pip install .
chatgpt-auth           # One-time authorization
dictate-hotkey-install # Setup hotkey service
```

---

## Platform Setup

### Windows

```bash
pip install .
chatgpt-auth
dictate-hotkey-install
```

A lightweight hotkey service runs in the background and starts on login.

---

### macOS

```bash
pip3 install .
chatgpt-auth
dictate-hotkey-install
```

Creates an Automator Quick Action with keyboard shortcut.

**Required permissions:**
- System Settings > Privacy & Security > Accessibility
- System Settings > Privacy & Security > Microphone

---

### Linux

```bash
# Install dependencies
sudo apt install python3 python3-pip libportaudio2  # Debian/Ubuntu
sudo dnf install python3 python3-pip portaudio       # Fedora
sudo pacman -S python python-pip portaudio           # Arch

# Install & setup
pip3 install .
chatgpt-auth
dictate-hotkey-install
```

Auto-detects desktop environment:
- **GNOME**: Uses gsettings custom keybinding
- **KDE**: Uses kglobalshortcutsrc
- **XFCE**: Uses xfconf
- **Other**: Falls back to xbindkeys

---

## Authorization

```bash
chatgpt-auth
```

1. Opens https://chatgpt.com
2. Press `F12` > Console
3. Paste:
   ```javascript
   fetch('https://chatgpt.com/api/auth/session').then(r=>r.json()).then(d=>console.log(JSON.stringify({accessToken:d.accessToken,email:d.user?.email,expires:d.expires})))
   ```
4. Copy JSON output, paste in terminal

Tokens expire ~10 days. Run `chatgpt-auth` again when needed.

---

## Commands

| Command | Description |
|---------|-------------|
| `dictate-hotkey-install` | Setup hotkey service |
| `dictate-hotkey-uninstall` | Remove hotkey service |
| `dictate-hotkey-status` | Check if hotkey is configured |
| `chatgpt-auth` | Authorize with ChatGPT |
| `chatgpt-auth-status` | Check authorization status |
| `chatgpt-auth-delete` | Delete authorization / logout |

---

## Troubleshooting

| Issue | Solution |
|-------|----------|
| Hotkey not working (Windows) | Re-run `dictate-hotkey-install` |
| Hotkey not working (macOS) | Grant Accessibility permission |
| Hotkey not working (Linux) | `sudo usermod -aG input $USER`, re-login |
| "Authorization required" | Run `chatgpt-auth` |
| "Token expired" | Run `chatgpt-auth` again |

---

## Uninstall

```bash
dictate-hotkey-uninstall  # Remove hotkey service
chatgpt-auth-delete       # Remove authorization (optional)
pip uninstall voice-dictation
```

---

## Project Structure

```
voice-dictation/
├── pyproject.toml
├── requirements.txt
├── README.md
└── src/voice_dictation/
    ├── __init__.py
    ├── cli.py              # CLI entry points
    ├── core.py             # Dictation logic
    ├── config.py           # Configuration
    ├── hotkey_service.py   # Windows hotkey listener
    └── setup_autostart.py  # Platform setup
```

---

## License

MIT