Markdown Documentation (docs/AHK_SCRIPTS.md)

AutoHotkey Infrastructure for SL5-Aura-Service

Because Windows handles file locks and system hotkeys differently than Linux, this project uses a set of AutoHotkey (v2) scripts to bridge the gap between the Python STT engine and the Windows User Interface.

Overview of Scripts

1. trigger-hotkeys.ahk

  • Purpose: The main user interface for controlling the service.

  • Key Features:

    • Intercepts F10 and F11 to start/stop dictation.

    • Uses a Keyboard Hook to override default Windows system behavior (e.g., F10 activating the menu bar).

    • Deployment: Designed to be registered via the Windows Task Scheduler with “Highest Privileges” so it can capture hotkeys even when the user is working in an Administrator-level application.

2. type_watcher.ahk

  • Purpose: Acts as the “Consumer” in the STT pipeline.

  • Key Features:

    • Watches a temporary directory for incoming .txt files generated by the Python engine.

    • State Machine (Zombie Map): Implements a memory-based map to ensure each file is typed exactly once. This prevents “double-typing” caused by redundant Windows file-system events (Added/Modified).

    • Safe Typing: Uses SendText to ensure special characters are handled correctly in any active editor.

    • Reliable Cleanup: Manages file deletion with a retry-logic to handle Windows file-access locks.

3. scripts/ahk/sync_editor.ahk

  • Purpose: Ensures seamless synchronization between the disk and the text editor (e.g., Notepad++).

  • Key Features:

    • Save-on-Demand: Can be triggered by Python to force a Ctrl+S in the editor before the engine reads the file.

    • Dialog Automator: Automatically detects and confirms “File modified by another program” reload dialogs, creating a fluid real-time update experience.

    • Visual Feedback: Provides short-lived notification boxes to inform the user that corrections are being applied.

4. scripts/notification_watcher.ahk

  • Purpose: Provides UI feedback for background processes.

  • Key Features:

    • Monitors specific status files or events to display notifications to the user.

    • Decouples the logic of “calculating” a message (Python) from “displaying” it (AHK), ensuring the main STT engine isn’t blocked by UI interactions.

Non-Admin Fallback

If the application is run without Administrator privileges:

  • Functionality: The service remains fully functional.

  • Hotkey Limitations: System-reserved keys like F10 may still trigger the Windows menu. In this case, it is recommended to change the hotkeys to non-system keys (e.g., F9 or Insert).

  • Task Scheduler: If the “AuraDictation_Hotkeys” task was created during an Admin-install, the script will run with high privileges even for a standard user. If not, the start_dictation.bat will launch a local user-level instance silently.

3. Warum “nervige Meldungen” erscheinen und wie man sie im AHK-Code stoppt

Um sicherzustellen, dass das Skript selbst niemals den Nutzer mit Popups stört, füge diese “Silent-Flags” oben in deine .ahk Dateien ein:

#Requires AutoHotkey v2.0
#SingleInstance Force   ; Ersetzt alte Instanzen ohne zu fragen
#NoTrayIcon            ; (Optional) Wenn du kein Icon im Tray willst
ListLines(False)       ; Erhöht Performance und verbirgt Debug-Logs

4. Strategie für die Hotkeys (F10 Alternative)

Da F10 ohne Admin-Rechte unter Windows fast unmöglich sauber abzufangen ist, könntest du im trigger-hotkeys.ahk eine Weiche einbauen:

if !A_IsAdmin {
    ; Wenn kein Admin, warne den Entwickler im Log
    ; Log("Running without Admin - F10 might be unreliable")
}

; Nutze Wildcards, um die Chance zu erhöhen, dass es auch ohne Admin klappt
*$f10::
{
    ; ... Logik
}

Zusammenfassung der Verbesserungen:

  1. Batch-Datei: Nutzt start "" /b, um das schwarze Fenster zu vermeiden, und prüft vorher, ob der Admin-Task schon läuft.

  2. Transparenz: Die Doku erklärt nun offen: “Kein Admin? Kein Problem, nimm einfach eine andere Taste als F10”.

  3. AHK-Skript: Nutzt #SingleInstance Force, um den “An older instance is running”-Dialog zu unterdrücken.

Damit wirkt die Software viel professioneller (“Smooth”), da sie im Hintergrund startet, ohne dass der Nutzer mit technischen Details oder Bestätigungsfenstern konfrontiert wird.

Why this Documentation is important:

By documenting the “Zombie Map” and the “Task Scheduler/Admin” requirement, you explain to other developers (and your future self) why the code is more complex than a simple Linux script. It turns “weird workarounds” into “engineered solutions for Windows limitations.”

(s,29.1.’26 11:02 Thu)