Skip to content

safari

This directory provides the integration support for the Apple Safari browser (including Safari Technology Preview) within Talon on macOS. It enables cross-browser voice commands (such as tab management and browser navigation) to function properly in Safari by mapping generic browser action definitions to Safari-specific keyboard shortcuts, UI automation, and AppleScript fallbacks.

The integration is driven by two main files:

How It Works

Application Activation and Tags

The file safari.talon acts as the entry point when Safari is the active application. It associates the Safari context with standard Talon tags:

  • tag(): browser: Activates generic browser commands (like back, forward, and reloading).
  • tag(): user.tabs: Activates generic tab management commands (like closing, opening, or switching tabs).

Platform-Specific Action Overrides

The Python script safari.py defines the target bundle identifiers (com.apple.Safari and com.apple.SafariTechnologyPreview) under the safari application name on macOS.

It then overrides the abstract commands from the browser and user namespaces to map them to physical actions in Safari:

  • Keyboard Shortcuts: Functions like reload_hard (cmd-alt-r), show_downloads (cmd-alt-l), and browser_open_address_in_new_tab (cmd-enter) map directly to native Safari hotkeys.
  • Menu Navigation: Commands such as show_extensions are handled by programmatically pressing keystrokes to open Safari's preferences and navigate to the Extensions tab (cmd-, tab:8 space).
  • Dynamic URL Retrieval (address): To fetch the active tab's URL, the script employs a robust multi-tiered lookup:
    1. UI Automation (First Choice): It attempts to traverse Safari's accessibility hierarchy (AXRole="AXToolbar") to locate the address bar (AXIdentifier="WEB_BROWSER_ADDRESS_AND_SEARCH_FIELD") and read its value directly. This method is incredibly fast and operates entirely in memory.
    2. AppleScript Fallback (Second Choice): If UI automation fails (for instance, if the address bar is hidden or the UI hierarchy changes), it executes a brief AppleScript to query Safari for window 1's current tab's URL, wrapping the execution in a strict 0.1-second timeout to avoid UI freezing.