Skip to content

homophones

This directory contains a robust, interactive system for correcting homophones (words that sound the same but have different spellings, such as by, buy, and bye). It provides voice commands to trigger homophone selections, automatically manages text formatting, handles plural forms naively, and displays an on-screen graphical user interface (GUI) to choose alternative spellings.

Core Architecture and File Interactions

The homophones system relies on three interconnected components: a database file, a Python backend that manages data structures and the UI state, and Talon voice command files that activate based on the state of the GUI.

1. The Word Database

The dataset is stored in homophones.csv. Each line contains a comma-separated list of homophones. * This file is actively watched by the Python file-system observer (fs.watch), meaning any manual additions or corrections to the CSV will be automatically reloaded by Talon without requiring a restart.

2. Backend Logic and UI State

The backend coordination is managed by homophones.py. It serves several critical roles: * Database Parsing & Indexing: It parses homophones.csv and populates a fast lookup dictionary all_homophones mapping each word (in lowercase) to its set of homophones. * Intelligent Word Normalization: If a direct match is not found but the queried word ends with "s", the script naively strips the "s" to check if the singular form has defined homophones. If found, it appends "s" to the matches (e.g., converting "claws" to "clauses"). * Capitalization Matching: It detects whether the user's original text is capitalized or in uppercase, ensuring that the suggested homophones preserve this formatting. * Contextual Overlays: It implements an interactive IMGUI (imgui.open) that displays the available homophone options on-screen. When this menu opens, the Python script dynamically assigns the user.homophones_open tag to the context, which enables context-specific voice commands. * Quick Replacement: If a word has only one alternative homophone, and quick_replace is enabled, the system instantly replaces the word in-place without showing the GUI menu, reducing cognitive load.

3. Command Interfaces

The voice interactions are divided into two distinct files depending on whether the selection menu is open:

  • homophones.talon: This file contains global commands to summon the homophones interface. You can search for a specific word, examine the currently selected text ("phones that"), or dynamically select and inspect words to the left or right of the cursor.
  • homophones_open.talon: This file is scoped strictly to the user.homophones_open tag. Once the GUI menu is displayed, it overrides standard input behaviors to allow users to format and select a homophone option in a single phrase (for example, "choose upper three" to select the third option and capitalize it).

Execution Flow Example

  1. Trigger: The user selects the word "write" in their document and says "phones that".
  2. Lookup: homophones.talon intercepts this phrase and calls the action user.homophones_show_auto().
  3. Backend Processing: Inside homophones.py, raise_homophones retrieves the selection "write", searches the parsed map, and finds the matching group ["right", "write", "rite"]. It reorders the list so that the original word is at the end, minimizing search distraction.
  4. UI Activation: The script activates the user.homophones_open context tag and renders the IMGUI overlay next to the screen coordinates showing:
    • 1. right
    • 2. rite
    • 3. write
  5. Selection: The user says "choose one" or "choose upper one".
  6. Resolution: homophones_open.talon (or the active context fallback inside the Python script) catches the number, retrieves "right", formats it if requested, inserts it back into the active text editor, and calls user.homophones_hide() to dismiss the UI and clear the context tag.