undertone

talk it. type it. ship it.

Voice typing for Linux that actually works.
Hold a key, speak, release -- your words appear wherever you're typing.

---

Demo

$ undertone

  ╭────────────────────────────────────────╮
  │  UNDERTONE                             │
  │  talk it. type it. ship it.            │
  ╰────────────────────────────────────────╯

  Status: vibing
  Hotkeys: Right Ctrl (hold) | F8 (toggle)

undertone> _

---

Quick Start

# Install
pipx install undertone

# Run (interactive setup on first launch)
undertone

# Upgrade to latest version
pipx upgrade undertone

That's it. 30 seconds to voice typing.

---

Features

	Feature	Description
Speed	< 1 second latency	Groq's Whisper API is blazing fast
Smart	App-aware cleanup	Auto styles for terminal, chat, docs, email, and code
Personal	Dictionary + snippets	Teach Undertone your words and trigger reusable expansions
Free	No credit card	Groq's free tier is generous
Offline	Local fallback	Works without internet via faster-whisper
Private	Privacy mode	Keep voice 100% on your machine
Auto	Runs on login	Always ready when you are

---

How It Works

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  Hold Key   │ -> │   Speak     │ -> │  Release    │ -> │ Text Appears│
│  (Right Ctrl)    │  naturally  │    │   key       │    │  at cursor  │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
                            |
                            v
                   ┌─────────────────┐
                   │  Groq Whisper   │
                   │ + LLM cleanup   │
                   └─────────────────┘

1. Press hotkey (Right Ctrl = hold, F8 = toggle)
2. Speak naturally
3. Release -- text appears in < 1 second

Works everywhere: browser, terminal, IDE, Slack, Discord, anywhere you type.

---

Commands

Run undertone to open the interactive CLI:

Command	Description
/setup	Configure API key & hotkeys
/start	Start voice typing
/stop	Take a break
/status	Check the vibe
/logs	View receipts
/config	Tweak settings
/dictionary	Add custom spoken -> written replacements
/snippets	Manage voice-triggered text expansions
/help	Get backup
/quit	Peace out

---

Requirements

• OS: Linux (X11, Wayland, or XWayland)
• Python: 3.10+
• API Key: Free from console.groq.com

System dependencies:

Audio (required):

sudo apt install libportaudio2

X11:

sudo apt install xclip xdotool

Wayland:

sudo apt install wl-clipboard wtype    # wlroots (Sway, Hyprland)
sudo apt install wl-clipboard ydotool  # GNOME, KDE, others

Undertone auto-detects your display server and uses the right tools.

---

Text Cleanup

Undertone uses a two-stage cleanup pipeline:

1. Light filler cleanup -- instantly strips obvious hesitation fillers like "um" and "uh"
2. LLM polish -- sends text to Groq's llama-3.1-8b-instant for punctuation and typo cleanup while preserving slang, tone, and casual wording (~160ms extra latency)

Toggle LLM cleanup on/off:

undertone> /config
# Select "LLM grammar fix on/off"

Adjust dictation style:

undertone> /config
# Select "Dictation style"

Teach Undertone your words or add snippets:

undertone> /dictionary
undertone> /snippets

When LLM is off or fails, regex cleanup runs as fallback.

---

Privacy Mode

By default, audio goes to Groq for fast transcription. Want to keep it local?

undertone> /config
# Select "Privacy mode" -> "local"

Local mode uses faster-whisper on your CPU. Slower (~3-5s) but your voice never leaves your machine.

---

Troubleshooting

No audio input detected

• Check your mic is connected
• Run arecord -l to list audio devices

Text not appearing

• X11: sudo apt install xclip xdotool
• Wayland (Sway/Hyprland): sudo apt install wl-clipboard wtype
• Wayland (GNOME/KDE): sudo apt install wl-clipboard ydotool
• Check logs with /logs to see which tools were detected

Service won't start

• Check logs: run undertone then /logs
• Verify API key at console.groq.com

---

Uninstall

# Stop service
undertone
# > /stop
# > /quit

# Remove package
pipx uninstall undertone

# Remove config (optional)
rm -rf ~/.config/undertone
rm ~/.config/systemd/user/undertone.service
systemctl --user daemon-reload

---

Tech Stack

• STT: Groq Whisper API / faster-whisper
• Cleanup: Regex filler removal + LLM grammar fix (Groq llama-3.1-8b-instant)
• Audio: sounddevice
• Hotkeys: pynput
• CLI: Rich

---

Contributing

PRs and issues welcome!

Report Bug

Request Feature

---

License

MIT - do whatever you want with it.

---

_{Built with caffeine and voice commands}