Skip to content

cancel

This directory provides mechanisms to prevent unwanted voice commands from executing, either via manual cancellation or automatically when waking Talon.

It contains two primary files that work in tandem:

  • cancel.talon defines the voice commands used to trigger cancellation and ignore phrases.
  • cancel.py implements the logic that intercept phrases before they are executed, clearing them if a cancellation condition is met.

How It Works

The cancel system relies on a Talon "pre:phrase" event callback. By hooking into the speech system before a phrase is parsed and executed, the system can inspect the spoken words and dynamically abort execution by clearing the phrase's data.

The system handles two main scenarios:

1. Explicit Verbal Cancellation

If you realize mid-utterance that you have made a mistake or do not want Talon to execute what you just said, you can append a specific cancellation phrase (by default, "cancel cancel") to the end of your command.

  • In cancel.py, the pre_phrase function checks if the last words of the phrase match the cancel_phrase array (["cancel", "cancel"]).
  • If a match is found, the system displays an operating system notification and invokes cancel_entire_phrase(), which empties both the raw words (phrase["phrase"]) and any partially parsed sequences. This prevents any preceding commands in that same breath from being executed.
  • cancel.talon defines the corresponding cancel cancel$ rule to cleanly handle the end of the phrase with a skip() action.
  • Additionally, cancel.talon provides an ignore [<phrase>]$ command, which allows you to speak to a human or ignore background noise without running commands, notifying you that the speech was explicitly ignored.

2. Wake-up Protection (Stale Phrase Discarding)

When Talon is asleep, it may still buffer audio. If you wake Talon using a noise or a keypress, any speech uttered just prior to or during the wake-up transition could accidentally trigger commands.

To prevent this:

  • cancel.py overrides the default speech enable() action (which is called when Talon wakes).
  • Upon waking, it sets a timestamp threshold (ts_threshold) using time.perf_counter().
  • When the next phrase is processed, pre_phrase compares the phrase's start time against this threshold. If the phrase began before Talon was fully awake, the phrase is discarded, and a message is logged to the console.