/tap2talk-py

Voice transcription desktop app - Double-tap Ctrl to start/stop recording

Primary LanguagePythonMIT LicenseMIT

Tap2Talk

Voice transcription desktop app for macOS - Double-tap Ctrl to start/stop recording, get instant transcription.

Created by unclecode - Author of Crawl4AI (50K+ stars)

Features

  • Simple Controls: Double-tap Ctrl to start/stop recording
  • Instant Transcription: Powered by Groq's Whisper API for fast, accurate transcription
  • Smart Text Insertion: Automatically inserts transcribed text at your cursor position
  • Beautiful Overlay: Native macOS overlay window shows recording status
  • Abort Recording: Double-tap Esc to cancel recording
  • Retry on Failure: Built-in retry mechanism for failed transcriptions
  • Menu Bar App: Runs quietly in your menu bar without cluttering your Dock

Installation

Quick Install

pip install tap2talk

Install from Source

git clone https://github.com/unclecode/tap2talk.git
cd tap2talk
pip install -e .

Setup

  1. Get your Groq API Key:

    • Visit Groq Console
    • Create a free account and generate an API key
    • Keys start with gsk_

  2. Run Tap2Talk:

    tap2talk

  3. First Run Setup:

    • You'll be prompted to enter your Groq API key
    • The key is saved securely in ~/.tap2talk/config.yaml

Usage

Quick Start

# Install
pip install tap2talk

# Run (will ask how you want to run it)
tap2talk

# Or start directly as background service
tap2talk start

Service Commands

tap2talk              # Interactive mode (asks service or terminal)
tap2talk start        # Start as background service
tap2talk stop         # Stop background service  
tap2talk status       # Check if running
tap2talk restart      # Restart service
tap2talk logs         # View recent logs

Using Tap2Talk

  1. Grant Permissions: macOS will ask for:

    • Accessibility permission (for keyboard monitoring)
    • Microphone permission (for recording)

  2. Use Hotkeys:

    • Double-tap Ctrl: Start/stop recording
    • Double-tap Esc: Abort recording

  3. Watch the Overlay: A beautiful overlay shows:

    • Recording (red mic icon)
    • Processing (gear icon)
    • Done (checkmark)
    • Aborted (X mark)
    • Error (warning icon)

macOS Permissions

Tap2Talk requires these permissions to function:

  1. Accessibility: System Preferences > Security & Privacy > Privacy > Accessibility
  2. Microphone: System Preferences > Security & Privacy > Privacy > Microphone

Add your Terminal app (Terminal, iTerm2, etc.) to both permission lists.

Configuration

Configuration is stored in ~/.tap2talk/config.yaml:

groq_api_key: "your_api_key_here"
log_level: "info"
auto_paste: true
recording_timeout: 30
model: "whisper-large-v3-turbo"
double_press_threshold_ms: 400
overlay_position: "top-right"
overlay_hide_delay_ms: 2000

Troubleshooting

Permissions Issues

Make sure your terminal has both Accessibility and Microphone permissions in System Preferences.

API Key Issues

  • Groq API keys start with gsk_
  • Get a free key at console.groq.com/keys
  • Check your key is saved in ~/.tap2talk/config.yaml

Recording Not Starting

  • Check the menu bar for the Tap2Talk icon
  • Ensure you're double-tapping Ctrl quickly (within 400ms)
  • Try adjusting double_press_threshold_ms in config

Development

# Clone the repository
git clone https://github.com/unclecode/tap2talk.git
cd tap2talk

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install in development mode
pip install -e .

# Run tests
python -m pytest

Building

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Build package
uv build

# Install locally
uv pip install dist/tap2talk-*.whl

License

MIT License - see LICENSE file for details.

Author

Created by unclecode

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

  • Powered by Groq for lightning-fast transcription
  • Built with rumps for macOS menu bar integration
  • Uses PyObjC for native macOS features