# Tap2Talk
Voice transcription desktop app for macOS - Double-tap Ctrl to start/stop recording, get instant transcription.
Created by [unclecode](https://github.com/unclecode) - Author of [Crawl4AI](https://github.com/unclecode/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
```bash
pip install tap2talk
```
### Install from Source
```bash
git clone https://github.com/unclecode/tap2talk.git
cd tap2talk
pip install -e .
```
## Setup
1. **Get your Groq API Key**:
- Visit [Groq Console](https://console.groq.com/keys)
- Create a free account and generate an API key
- Keys start with `gsk_`
2. **Run Tap2Talk**:
```bash
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
```bash
# Install
pip install tap2talk
# Run (will ask how you want to run it)
tap2talk
# Or start directly as background service
tap2talk start
```
### Service Commands
```bash
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`:
```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](https://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
```bash
# 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
```bash
# 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**
- GitHub: [@unclecode](https://github.com/unclecode)
- X/Twitter: [@unclecode](https://x.com/unclecode)
- Check out [Crawl4AI](https://github.com/unclecode/crawl4ai) - #1 open source library for web crawling with 50K+ stars
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Acknowledgments
- Powered by [Groq](https://groq.com) for lightning-fast transcription
- Built with [rumps](https://github.com/jaredks/rumps) for macOS menu bar integration
- Uses [PyObjC](https://github.com/ronaldoussoren/pyobjc) for native macOS features
Raw data
{
"_id": null,
"home_page": null,
"name": "tap2talk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "voice, transcription, macos, desktop, groq, whisper",
"author": "Tap2Talk",
"author_email": "unclecode <unclecode@kidocode.com>",
"download_url": "https://files.pythonhosted.org/packages/e7/d5/08a9f93d7a4ae90a5927bde4e741a52036ec5aa6ed2378cdb7f5fd6381b3/tap2talk-0.2.0.tar.gz",
"platform": null,
"description": "# Tap2Talk\n\nVoice transcription desktop app for macOS - Double-tap Ctrl to start/stop recording, get instant transcription.\n\nCreated by [unclecode](https://github.com/unclecode) - Author of [Crawl4AI](https://github.com/unclecode/crawl4ai) (50K+ stars)\n\n## Features\n\n- **Simple Controls**: Double-tap Ctrl to start/stop recording\n- **Instant Transcription**: Powered by Groq's Whisper API for fast, accurate transcription\n- **Smart Text Insertion**: Automatically inserts transcribed text at your cursor position\n- **Beautiful Overlay**: Native macOS overlay window shows recording status\n- **Abort Recording**: Double-tap Esc to cancel recording\n- **Retry on Failure**: Built-in retry mechanism for failed transcriptions\n- **Menu Bar App**: Runs quietly in your menu bar without cluttering your Dock\n\n## Installation\n\n### Quick Install\n\n```bash\npip install tap2talk\n```\n\n### Install from Source\n\n```bash\ngit clone https://github.com/unclecode/tap2talk.git\ncd tap2talk\npip install -e .\n```\n\n## Setup\n\n1. **Get your Groq API Key**:\n - Visit [Groq Console](https://console.groq.com/keys)\n - Create a free account and generate an API key\n - Keys start with `gsk_`\n\n2. **Run Tap2Talk**:\n ```bash\n tap2talk\n ```\n\n3. **First Run Setup**:\n - You'll be prompted to enter your Groq API key\n - The key is saved securely in `~/.tap2talk/config.yaml`\n\n## Usage\n\n### Quick Start\n```bash\n# Install\npip install tap2talk\n\n# Run (will ask how you want to run it)\ntap2talk\n\n# Or start directly as background service\ntap2talk start\n```\n\n### Service Commands\n```bash\ntap2talk # Interactive mode (asks service or terminal)\ntap2talk start # Start as background service\ntap2talk stop # Stop background service \ntap2talk status # Check if running\ntap2talk restart # Restart service\ntap2talk logs # View recent logs\n```\n\n### Using Tap2Talk\n\n1. **Grant Permissions**: macOS will ask for:\n - Accessibility permission (for keyboard monitoring)\n - Microphone permission (for recording)\n\n2. **Use Hotkeys**:\n - **Double-tap Ctrl**: Start/stop recording\n - **Double-tap Esc**: Abort recording\n\n3. **Watch the Overlay**: A beautiful overlay shows:\n - Recording (red mic icon)\n - Processing (gear icon)\n - Done (checkmark)\n - Aborted (X mark)\n - Error (warning icon)\n\n## macOS Permissions\n\nTap2Talk requires these permissions to function:\n\n1. **Accessibility**: System Preferences > Security & Privacy > Privacy > Accessibility\n2. **Microphone**: System Preferences > Security & Privacy > Privacy > Microphone\n\nAdd your Terminal app (Terminal, iTerm2, etc.) to both permission lists.\n\n## Configuration\n\nConfiguration is stored in `~/.tap2talk/config.yaml`:\n\n```yaml\ngroq_api_key: \"your_api_key_here\"\nlog_level: \"info\"\nauto_paste: true\nrecording_timeout: 30\nmodel: \"whisper-large-v3-turbo\"\ndouble_press_threshold_ms: 400\noverlay_position: \"top-right\"\noverlay_hide_delay_ms: 2000\n```\n\n## Troubleshooting\n\n### Permissions Issues\nMake sure your terminal has both Accessibility and Microphone permissions in System Preferences.\n\n### API Key Issues\n- Groq API keys start with `gsk_`\n- Get a free key at [console.groq.com/keys](https://console.groq.com/keys)\n- Check your key is saved in `~/.tap2talk/config.yaml`\n\n### Recording Not Starting\n- Check the menu bar for the Tap2Talk icon\n- Ensure you're double-tapping Ctrl quickly (within 400ms)\n- Try adjusting `double_press_threshold_ms` in config\n\n## Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/unclecode/tap2talk.git\ncd tap2talk\n\n# Create virtual environment\npython -m venv .venv\nsource .venv/bin/activate\n\n# Install in development mode\npip install -e .\n\n# Run tests\npython -m pytest\n```\n\n## Building\n\n```bash\n# Install uv\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Build package\nuv build\n\n# Install locally\nuv pip install dist/tap2talk-*.whl\n```\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Author\n\nCreated by **unclecode**\n- GitHub: [@unclecode](https://github.com/unclecode)\n- X/Twitter: [@unclecode](https://x.com/unclecode)\n- Check out [Crawl4AI](https://github.com/unclecode/crawl4ai) - #1 open source library for web crawling with 50K+ stars\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Acknowledgments\n\n- Powered by [Groq](https://groq.com) for lightning-fast transcription\n- Built with [rumps](https://github.com/jaredks/rumps) for macOS menu bar integration\n- Uses [PyObjC](https://github.com/ronaldoussoren/pyobjc) for native macOS features\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Voice transcription desktop app - Double-tap Ctrl to start/stop recording",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/unclecode/tap2talk",
"Issues": "https://github.com/unclecode/tap2talk/issues",
"Repository": "https://github.com/unclecode/tap2talk"
},
"split_keywords": [
"voice",
" transcription",
" macos",
" desktop",
" groq",
" whisper"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b57d80c47ef198bf6bfa0d12bd6df166633c880dfb0c4677e445dff732bb6222",
"md5": "c595d8a95266f1fa8fd267467d165662",
"sha256": "480c9a70f7c51d3fc2aa2816304c4aa77f5e6d0b005996430f5f9f334f4c6a36"
},
"downloads": -1,
"filename": "tap2talk-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c595d8a95266f1fa8fd267467d165662",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 37916,
"upload_time": "2025-08-09T13:35:40",
"upload_time_iso_8601": "2025-08-09T13:35:40.279045Z",
"url": "https://files.pythonhosted.org/packages/b5/7d/80c47ef198bf6bfa0d12bd6df166633c880dfb0c4677e445dff732bb6222/tap2talk-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e7d508a9f93d7a4ae90a5927bde4e741a52036ec5aa6ed2378cdb7f5fd6381b3",
"md5": "c212e3e33bd344e648e301d5fe9ed450",
"sha256": "a88d8d104eff195305022388d181f393307189e8a992546809adf8c8b97f08e2"
},
"downloads": -1,
"filename": "tap2talk-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "c212e3e33bd344e648e301d5fe9ed450",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 37801,
"upload_time": "2025-08-09T13:35:41",
"upload_time_iso_8601": "2025-08-09T13:35:41.423730Z",
"url": "https://files.pythonhosted.org/packages/e7/d5/08a9f93d7a4ae90a5927bde4e741a52036ec5aa6ed2378cdb7f5fd6381b3/tap2talk-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-09 13:35:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "unclecode",
"github_project": "tap2talk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "groq",
"specs": [
[
">=",
"0.11.0"
]
]
},
{
"name": "sounddevice",
"specs": [
[
">=",
"0.5.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.24.0"
]
]
},
{
"name": "PyYAML",
"specs": [
[
">=",
"6.0"
]
]
},
{
"name": "pystray",
"specs": [
[
">=",
"0.19.0"
]
]
},
{
"name": "Pillow",
"specs": [
[
">=",
"10.0.0"
]
]
},
{
"name": "pyperclip",
"specs": [
[
">=",
"1.8.0"
]
]
},
{
"name": "pynput",
"specs": [
[
">=",
"1.7.0"
]
]
},
{
"name": "pyobjc-framework-Quartz",
"specs": [
[
">=",
"10.0"
]
]
},
{
"name": "pyobjc-framework-ApplicationServices",
"specs": [
[
">=",
"10.0"
]
]
},
{
"name": "pywin32",
"specs": [
[
">=",
"305"
]
]
},
{
"name": "keyboard",
"specs": [
[
">=",
"0.13.5"
]
]
},
{
"name": "resampy",
"specs": [
[
">=",
"0.4.0"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"7.0.0"
]
]
},
{
"name": "black",
"specs": [
[
">=",
"23.0.0"
]
]
},
{
"name": "flake8",
"specs": [
[
">=",
"6.0.0"
]
]
}
],
"lcname": "tap2talk"
}
JSON
