keys

This directory serves as the foundation for keyboard-based input and navigation within the Talon voice control system. It translates spoken commands (such as letters, numbers, symbols, modifiers, and navigation keys) into physical key events. By abstracting keyboard definitions into lists and system-specific overlays, it ensures a uniform user experience across different operating systems.

Core Component Breakdown

The keyboard input system is composed of four main elements: platform-neutral lists, symbol configurations, platform-specific overrides, and orchestration logic.

1. Platform-Neutral Layout Lists

These .talon-list files define the baseline spoken vocabulary for standard keyboard keys that behave consistently across physical platforms:

• letter.talon-list: Defines the phonetic alphabet used to trigger standard letter keys. For example, speaking "air" types the character a, and "bat" types b.
• number_key.talon-list: Maps spoken digits (e.g., "zero" through "nine") to their respective numeric characters.
• arrow_key.talon-list: Maps directional vocabulary ("up", "down", "left", "right") to directional arrow keycodes.
• function_key.talon-list: Binds verbal shortcuts (e.g., "f one" through "f twenty") to standard function keys.
• keypad_key.talon-list: Maps numeric keypad operations (like "key pad point" or "key pad enter") to dedicated numpad keycodes.

2. Symbol Definitions

Symbols and punctuation require robust matching because they are used both inside command sequences and during natural language dictation.

• symbols.py uses a custom Python structure, the Symbol class, to house this logic. This file coordinates the translation of symbols (like $, *, [) and provides multiple phonetic aliases (e.g., mapping both "down score" and "underscore" to _). It splits these aliases into command-only contexts or combined command/dictation configurations, while additionally catering to engine-specific behaviors such as Dragon Speech.

3. Platform-Specific Overrides

Keyboard modifiers and special keys (like delete and navigation boundaries) behave differently depending on the host OS. This system isolates platform-specific nuances inside subdirectories:

• mac: Focuses on macOS configurations. It overrides the standard modifier key list to prioritize keys like command (super) and option (alt) and handles macOS-specific deletion behaviors (such as mapping "forward delete" to standard PC-style delete).
• win: Serves Windows and Linux. It exposes standard PC modifier mappings while retaining cross-platform fallback aliases—mapping macOS terminology like "command" and "option" to Windows equivalents to minimize muscle memory disruption for multi-platform developers.

4. Logic, Captures, and Grammar Execution

The engine uses Python rules to aggregate these lists and .talon files to bind them to physical speech triggers:

• keys.py: Defines the Talon Module and registers all lists and semantic captures. It defines nested captures like <self.unmodified_key> and combinations like <self.key>+ (e.g., combining a list of zero-to-many modifiers with an unmodified alphanumeric/special key). It also instantiates the fallback dictionaries loaded from symbols.py.
• keys.talon: Declares the voice commands that users speak to generate inputs. It links the captures registered in keys.py to physical keystroke commands. For instance, speaking <user.modifiers> <user.unmodified_key> sends the composite key sequence to the host system. It also supports formatting macros (e.g., speaking "ship air bat" produces "AB").

---

Processing Pipeline

The system processes a spoken command such as "control shift option left" on a Mac through the following pipeline:

  [ Spoken Command: "control shift option left" ]
                        │
                        ▼
            [ Grammar: keys.talon ]
  Matches: <user.modifiers> <user.unmodified_key>
                        │
                        ▼
             [ Orchestrator: keys.py ]
  Identifies modifiers list and matches direction key
                        │
                        ▼
           [ OS Specific / List Lookups ]
  1. Resolves modifiers "control", "shift", and "option" 
     using the mac/modifier_key.talon-list
  2. Resolves directional key "left" 
     using the arrow_key.talon-list
                        │
                        ▼
          [ Action Dispatch: keys.py ]
  Compiles and dispatches keystroke event: "ctrl-shift-alt-left"

This decoupled architecture allows you to easily edit vocabulary aliases inside the flat .talon-list files without breaking the underlying pattern-matching rules written in Python.