Voice Keyboard

Instructions

Use {SKILL_DIR}/scripts/voice-keyboard.sh for all operations. Always check status first before starting or stopping.

Workflow

Execute steps based on what the user wants:

Check Status

{SKILL_DIR}/scripts/voice-keyboard.sh status

• STATUS: running (PID: ...) → voice keyboard is active
• STATUS: stopped → voice keyboard is not running

Install

Run when the user wants to install or first-time setup:

{SKILL_DIR}/scripts/voice-keyboard.sh install

This will:

1. Run uv sync inside {SKILL_DIR} to create .venv and install faster-whisper + evdev
2. Copy config.example.ini → ~/.config/voice-keyboard/config.ini (if not already present)
3. Warn if the user is not in the input group

If user is NOT in input group, inform them:

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

Start

{SKILL_DIR}/scripts/voice-keyboard.sh start

• Requires install to have been run first (.venv must exist)
• Starts dictate.py in background via nohup uv run python dictate.py
• If already running: reports PID, no action taken
• On success: reports PID and log location
• Usage: Hold AltGr to record → release to transcribe → text is typed into active field

Stop

{SKILL_DIR}/scripts/voice-keyboard.sh stop

Restart

Use after config changes:

{SKILL_DIR}/scripts/voice-keyboard.sh restart

View Logs

{SKILL_DIR}/scripts/voice-keyboard.sh logs

Or follow live:

tail -f /tmp/voice-keyboard.log

Configuration

Config file: ~/.config/voice-keyboard/config.ini

[whisper]
model = tiny.en       # tiny.en, base.en, small.en, medium.en, large-v3
device = cuda         # cpu or cuda
compute_type = float16

[hotkey]
key = alt_gr          # hold this key to record

[behavior]
auto_type = true
notifications = true
grab_keyboard = false

After editing, restart:

{SKILL_DIR}/scripts/voice-keyboard.sh restart

Cookbook

• IF: User says "start voice keyboard" or "enable dictation"

• THEN: Check status → if stopped, run start

• IF: User says "stop voice keyboard" or "disable dictation"

• THEN: Check status → if running, run stop

• IF: User says "install voice keyboard" or first-time setup

• THEN: Run install, report results and any warnings about input group

• IF: User says "restart voice keyboard" or "reload config"

• THEN: Run restart

• IF: User says "voice keyboard logs" or "why isn't it working"

• THEN: Run logs, report output