Skip to content

command_history

The Command History plugin provides a visual on-screen overlay that displays a log of your recently recognized voice commands. This is highly useful for debugging voice recognition accuracy, tracking down misbehaved commands, or simply keeping a visual log of your spoken inputs.

This plugin consists of two main files:

  • command_history.py – Manages the background logic, registers speech listeners, tracks command state, and defines the IMGUI (Immediate Mode GUI) interface.
  • command_history.talon – Defines the voice commands that control the visibility and size of the history display.

How It Works

The plugin hooks directly into Talon's speech system to intercept and display spoken phrases.

1. Capturing Spoken Phrases

The core speech processing occurs inside command_history.py:

  • Speech Listener: The module registers a phrase listener with speech_system.register("phrase", on_phrase).
  • Filtering & Formatting:
    • When you speak, on_phrase captures the utterance. It utilizes skip_phrase (imported from the subtitles module) to ignore unwanted phrases.
    • It then passes the raw phrase list to actions.user.history_transform_phrase_text(). By default, this action joins the words into a single string. It can be overridden in other user files to customize how text is formatted before being logged.
  • History Buffer: The processed string is appended to a global Python list (history). This list is automatically sliced to maintain a maximum capacity defined by the user.command_history_size setting (defaulting to 50 entries).

2. Rendering the Overlay

The visual component is rendered using Talon's built-in imgui library:

  • The @imgui.open(y=0) decorator defines a GUI window at the top of the screen.
  • Depending on the state of the toggle hist_more, the GUI will either render a small snippet of your history—configured by the user.command_history_display setting (defaulting to 10 entries)—or the entire stored history buffer up to the configured max size.
  • The GUI also features a simple interactive button allowing you to close the history window with your mouse.

Voice Commands

The command_history.talon file provides voice controls to manage the UI state:

  • "command history": Toggles the display window open or closed.
  • "command history close": Force-closes the display window.
  • "command history clear": Empties the command history list.
  • "command history more": Expands the window to show the maximum number of recorded items.
  • "command history less": Collapses the window to show only the default limited display count.

Configuration & Customization

You can customize the size of the history and display behavior by adding these settings to your personal Talon configuration files:

settings():
    # Keep up to 100 commands in memory
    user.command_history_size = 100
    # Show 15 commands in the default collapsed view
    user.command_history_display = 15