Skip to content

listening_timeout

This directory contains a utility plugin designed to automatically disable Talon's speech recognition after a specified period of inactivity (idle time). This is highly useful for saving CPU resources, preventing accidental voice commands when you step away from your computer, or ensuring privacy.

Core Functionality

The entire logic of this plugin is contained in listening_timeout.py.

How It Works

The plugin monitors speech activity and uses Talon's asynchronous cron system to schedule a shutdown timer:

  1. Activity Tracking: The script registers a callback function post_phrase with Talon's speech_system on the "post:phrase" event. Every time you speak a phrase, this callback updates last_phrase_time with the current high-resolution timestamp (time.perf_counter()) and restarts/refreshes the timeout job.
  2. Timeout Check: A background cron job runs at the end of the calculated timeout window. When it triggers, check_timeout() verifies if the elapsed time since the last phrase actually exceeds the timeout. If it does, the plugin triggers the timeout expiration routine.
  3. State Integration: The plugin overrides Talon's native speech.enable() and speech.disable() actions. Enabling speech automatically schedules a new timeout check, while disabling speech cancels any pending background timers.
  4. App Initialization: When Talon loads (on_ready), the script checks if speech recognition is already enabled. If so, it immediately starts the timeout timer to respect your configuration from the moment of launch.

Configurable Settings

The plugin exposes two configuration settings via Talon's standard setting system:

  • user.listening_timeout_minutes (integer): Specifies the idle threshold. After this many minutes of silence, speech recognition is disabled. A value of -1 (default) disables the automatic timeout completely.
  • user.listening_timeout_show_notification (boolean): If set to True (default), Talon displays an OS-level notification when the timeout expires and speech recognition is disabled.

Customizing Expiration Behavior

When the timeout expires, it calls the action user.listening_timeout_expired(). By default, this action disables speech and displays a notification. However, because this is defined as a standard Talon action, you can override its behavior in your personal user files to trigger additional events (such as playing a sound, changing an indicator light, or locking the screen).