speech2caret

Use your speech to write to the current caret position!

Goals

• ✅ Simple: A minimalist tool that does one thing well.
• ✅ Local: Runs entirely on your machine (uses Hugging Face models for speech recognition).
• ✅ Efficient: Optimised for low CPU and memory usage, thanks to an event-driven architecture that responds instantly to key presses without wasting resources.

Note: Tested only on Linux (Ubuntu). Other operating systems are currently unsupported.

Demo (turn volume on):

demo-jfk.mp4

Installation

1. System Dependencies

First, install the required system libraries:

sudo apt update
sudo apt install libportaudio2 ffmpeg

2. Grant Permissions

To read keyboard events and simulate key presses, evdev needs access to your keyboard input device. Add your user to the input group to grant the necessary permissions:

sudo usermod -aG input $USER
newgrp input  # or log out and back in 

3. Install and Run

You can install and run speech2caret using pip or uv:

# Install the package
uv add speech2caret  # or pip install speech2caret

# Run the application
speech2caret

Alternatively, you can run it directly without installation using uvx(the --index pytorch-cpu=... flag ensures only CPU packages are downloaded, avoiding GPU-related dependencies):

uvx --index pytorch-cpu=https://download.pytorch.org/whl/cpu --from speech2caret speech2caret

Configuration

The first time you run speech2caret, it creates a config file at ~/.config/speech2caret/config.ini.

You’ll need to manually edit it with the following values:

keyboard_device_path

This is the path to your keyboard input device. You can find the path either following this, or by running the command below and looking for an entry that ends with -event-kbd.

ls /dev/input/by-path/

start_stop_key and resume_pause_key

These are the keys you'll use to control the app.

To find the correct name for a key, you can use the provided Python script below. First, ensure you have your keyboard_device_path from the step above, then run this command:

uvx --from evdev python -c '
keyboard_device_path = "PASTE_YOUR_KEYBOARD_DEVICE_PATH_HERE"

from evdev import InputDevice, categorize, ecodes, KeyEvent
dev = InputDevice(keyboard_device_path)
print(f"Listening for key presses on {dev.name}...")
for event in dev.read_loop():
    if event.type == ecodes.EV_KEY:
        key_event = categorize(event)
        if key_event.keystate == KeyEvent.key_down:
            print(f" {key_event.keycode}")
'

Press the keys you wish to use, and their names will be printed to the terminal. For a full list of available key names, see here.

Additional (Optional) Configuration

You can configure audio cues to notify when recording has started, stopped, paused, or resumed. To do this, update the start_recording_audio_path, stop_recording_audio_path, resume_recording_audio_path, and pause_recording_audio_path config variables in ~/.config/speech2caret/config.ini with the absolute paths to your choice of audio files.

Word Replacement

You can define custom word or phrase replacements in the [word_replacement] section of ~/.config/speech2caret/config.ini file. This allows you to automatically substitute specific spoken words with desired text.

For example, to replace "new line" with a newline character or " underscore " with _, you can configure it as follows:

[word_replacement]
"new line" = "\n"
" underscore " = "_"

How to Use

1. Run the speech2caret command in your terminal.
2. Press your configured start_stop_key to begin recording.
3. Press the resume_pause_key to toggle between pausing and resuming.
4. When you are finished, press the start_stop_key again.
5. The recorded audio will be transcribed and typed at your current caret position.