Skip to content

mode_indicator

This directory contains the Mode Indicator plugin, a lightweight, highly customizable graphical utility for Talon. It displays a colored bubble on your screen to visually represent Talon’s current active state (such as command, dictation, mixed, or sleep mode) and microphone status.

How it Works

The mode indicator uses a canvas overlay rendered directly on the screen. It monitors system events and context changes to adjust its color and text dynamically, giving you real-time visual feedback on whether Talon is listening, asleep, muted, or in a specific input mode.

The plugin consists of three primary files:

  • mode_indicator.py: The core Python implementation. It registers Talon settings, tracks state changes, and handles the low-level rendering.
  • mode_indicator.talon: The configuration file where you declare default settings (size, positions, colors) and map voice commands to toggle the indicator.
  • README.md: Documentation featuring a demo video and preview screenshots of the indicator's states.

Technical Details

State Monitoring and Lifecycle

mode_indicator.py coordinates several event listeners and background processes to keep the UI in sync with Talon:

  • Talon Context Updates: It registers a callback via registry.register("update_contexts", ...) to capture active mode changes (e.g., transitioning between sleep, dictation, command, or custom tags like user.deep_sleep).
  • Active Polling: A background cron job runs every 500 milliseconds via cron.interval to poll for two things:
  • Settings Changes: It detects when you live-edit configuration values inside your .talon files and immediately updates the indicator.
  • Active Microphone: Since Talon does not currently offer a reactive callback for audio device changes, the script polls actions.sound.active_microphone(). If the active microphone is set to "None", the indicator switches to its muted styling.
  • Screen Transformations: It registers with ui.register("screen_change", ...) to automatically reposition and scale the indicator if monitor geometry or resolution changes.

Drawing and Canvas Rendering

The indicator is drawn using Talon's built-in skia library inside a high-performance transparent canvas overlay:

  • Positioning: The position is calculated dynamically as a percentage of your primary monitor's dimensions, adhering to user-configured horizontal and vertical anchors (e.g., top-center).
  • Styling: The canvas applies a radial gradient based on the active mode's primary color and a darkened variant of that color (controlled by a gradient factor). A subtle drop shadow is appended using ImageFilter.drop_shadow.
  • Microphone Name Overlay: If enabled, the engine calculates the boundaries of the text and overlays the first two letters of the active microphone name directly in the center of the indicator.

Configuration and Commands

You can configure the behavior and styling of the indicator inside mode_indicator.talon by editing the declared settings.

Default State Colors

  • Muted Microphone: Black (000000)
  • Sleep Mode: Grey (808080)
  • Deep Sleep Mode: Red (FF0000)
  • Dictation Mode: Gold (ffd700)
  • Mixed Mode: Medium Sea Green (3cb371)
  • Command Mode: Cornflower Blue (6495ed)
  • Other Modes: Ghost White (f8f8ff)

Voice Commands

The plugin exposes the following voice commands to quickly toggle the visibility of the widget on the fly:

  • "mode indicator show": Displays the canvas on screen.
  • "mode indicator hide": Closes and unregisters the canvas.