Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/npateriya/LocalVoiceAI/llms.txt

Use this file to discover all available pages before exploring further.

LocalVoiceAI has a single configuration point: the push-to-talk keycode. By default, the binary listens for F10 (CGKeyboard keycode 109). If F10 conflicts with another application or system shortcut, you can override it at startup by setting the WHISPER_KEYCODE environment variable to any decimal keycode before starting the service.

​
Setting a Custom Keycode

Pass WHISPER_KEYCODE inline when calling make start: 
WHISPER_KEYCODE=101 make start   # use F9 instead of F10
The value is read once at startup by the localvoice binary. If the environment variable is absent, the binary silently falls back to the default of 109 (F10).

​
Keycode Reference

KeyKeycode
F8100
F9101
F10109 (default)
F11103
F12111
These are macOS CGEvent virtual keycodes for the function keys in decimal form. Pass the Code value directly as the WHISPER_KEYCODE value.

​
How the Default Is Applied

The localvoice binary initialises the push-to-talk keycode in two steps. First, the C-level event tap sets a module-level default: 
static int g_ptt_keycode = 109; // F10
Then, at Go main() startup, the binary reads the environment variable and validates it: 
keycode := int64(109)
if kcs := os.Getenv("WHISPER_KEYCODE"); kcs != "" {
    if n, err := fmt.Sscanf(kcs, "%d", &keycode); n != 1 || err != nil {
        fmt.Fprintln(os.Stderr, "[WARN] Invalid WHISPER_KEYCODE, using 109 (F10)")
        keycode = 109
    }
}
C.setPTTKeycode(C.int(keycode))
If you pass a value that cannot be parsed as a decimal integer (for example, WHISPER_KEYCODE=F9 instead of WHISPER_KEYCODE=101), the binary logs [WARN] Invalid WHISPER_KEYCODE, using 109 (F10) and continues with the built-in default. Always use the numeric keycode, not the key name.

​
Persisting the Keycode via the LaunchAgent Plist

Using WHISPER_KEYCODE=<value> make start only applies to that single invocation — if the agent is restarted by macOS (for example after a reboot), the variable will not be set. To make the override permanent, add it to the EnvironmentVariables dictionary in the LaunchAgent plist. The plist is located at: 
~/Library/LaunchAgents/com.localvoiceai.localvoice.plist
Open it in any text editor and find (or add) the EnvironmentVariables key. A PATH entry is already present from the install step; add WHISPER_KEYCODE alongside it: 
<key>EnvironmentVariables</key>
<dict>
    <key>PATH</key>
    <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
    <key>WHISPER_KEYCODE</key>
    <string>101</string>
</dict>
After saving the plist, apply the change by running: 
make reload
make reload unloads and reloads the LaunchAgent from the updated plist without replacing the binary, so no permission re-grant is required.

Build docs developers (and LLMs) love

Get started for freeTalk to us