Before Submitting This PR

Please confirm you have done the following:

• I have searched existing issues and pull requests (including closed ones) to ensure this isn't a duplicate
  • There have been a couple attempts at this (1, 2), but this is a more readable/simpler implementation that covers more edge cases, both the signal handler + shortcut entrypoint.
• I have read CONTRIBUTING.md

Human Written Description

Part 1 - Race condition fix

This PR started by using an atomic state machine, but it still felt pretty brittle. I realized the correct way to approach this was just by using a "coordinator" (aka actor pattern) which gets simple "notifications" from the rest of the system, and handles the incoming commands sequentially, naturally brokering access to the transcription state.

Note: This fix doesn't rely on the 30ms debounce, the debounce is just a UX thing as described below.

Other attempts to fix this only used an AtomicBool, which seems good on the surface, but doesn't truly fix the race condition because it either 1) still causes a lockup in some edge cases (conservative lock) or 2) has multiple pipelines processing at the same time, potentially pasting text interleaved and whatnot. If you only guard the keypress, then you can have multiple push to talk / keypresses accidentally queue up multiple transcriptions.

Basically, there's a myriad of edge case race conditions that get categorically eliminated by using an actor here :)

Part 2 - Debounce for UX

Second, this PR adds a 30ms debounce which just helps avoid sound effect spam and needless repeated processing (but again, this is NOT necessary for the correctness guarantee)

Related Issues/Discussions

Fixes #64
Fixes #707
Fixes #462 (closed, but not truly fixed)

Related attempts:

• fix: prevent app lockup when toggle shortcut is pressed rapidly #820 *probably still be useful, dealing with audio race conditions and recovery
• Fix recorder start/stop failures and debounce toggle shortcuts #644

Previous related PR which attempted to mitigate this but caused the lock up accidentally:

• Fix race condition when toggling transcription via SIGUSR2 #560

Community Feedback

Issues linked above.

Testing

Tested on linux + wayland using SIGUSR2.

I have not tested this on macos, or using push to talk keybinds in the app. If someone else is able to test in those environments that'd be great, or we can merge and see how it works out. I don't think this would cause issues.

Screenshots/Videos (if applicable)

AI Assistance

• No AI was used in this PR
• AI was used (please describe below)

If AI was used:

• Tools used: Claude Code
• How extensively: I used Claude Code to explore the issue and verify the race condition, then instructed it on precisely how to fix the issue, and verified the fix. I stand by the fix.