Skip to content

macro

This directory contains a voice macro engine that enables users to record sequences of spoken commands, play them back, save them under named identifiers, and export them as reusable Talon scripting code.

The implementation consists of two main components:

  • macro.talon defines the voice commands used to control the recording, playback, and export operations.
  • macro.py manages the internal recording state, intercepts spoken phrases, executes playback, handles persistence, and provides a graphical list of saved macros.

How It Works

The macro engine records sequences of voice commands by intercepting speech input and replaying it using Talon's mimicry system.

1. Intercepting Speech

In macro.py, the plugin registers a listener with Talon's speech system:

speech_system.register("pre:phrase", fn)

The callback function intercepts every spoken phrase before it executes. If recording is active, it extracts the unmapped words of the phrase (d["parsed"]._unmapped) and appends them to the current macro list via the macro_append_command action.

2. Recording & Playback Control

Voice commands in macro.talon manage the state of the recorder:

  • macro record: Sets the recording state to True and clears any previous unsaved macro.
  • macro stop: Disables recording and discards the final spoken phrase (which is typically the "macro stop" command itself) to prevent recursive loops.
  • macro play [{user.saved_macros}]: Iterates through the list of recorded commands and executes them sequentially using actions.mimic(words). If a named macro is provided, it plays that specific saved macro; otherwise, it plays the last unsaved recording.

3. Macro Organization and UI

Users can store and list macros for long-term use within their current session:

  • Saving: The macro save as <user.text> command calls macro_save(), which registers the macro in a Python dictionary and dynamically updates the user.saved_macros list. This update immediately makes the saved macro name available as an optional voice argument for playback and copy commands.
  • Listing: The macro list command triggers an imgui (Immediate Mode GUI) panel defined in macro.py. This GUI displays all active named macros on screen and provides an on-screen button to close itself.

4. Exporting to Clipboard

The system also serves as a code generation utility for scripting. Spoken commands like macro copy [{user.saved_macros}] or macro copy as <user.text> format the macro's actions into structured Talon script format. For example, a macro named my_macro that presses a series of keys would be copied to the clipboard as:

my_macro:
    mimic("command one")
    mimic("command two")

This allows developers and users to easily write repetitive voice workflows on the fly and paste them directly into their .talon files.