Swaps

Swaps allow you to modify the utterance transcript received from the recognizer before it is processed by the interpreter for possible command and text processing. Swaps are primarily used as an easy way to define jargon, and to force capitalization of certain words, but you can use them for other purposes.

Swaps Verus Commands

Whenever you want something specific typed when you say a certain phrase, you can achieve this using either swaps or commands. Here are the advantages and disadvantages of each:

Feature	Advantages	Disadvantages
Commands	Commands can accept arguments. You can control spacing on either side of the typed content.	Jargon commands are more difficult to use along with other commands, like "capital" or "title". For example, consider a command called "alternate bite" that simply types "byte". If you say "capital alternate bite", the application types "Alternate bite", because the target phrase is provided as an argument to the "capital" command. Commands require several fields.
Swaps	Easy to define. Works well with commands like "capital" and "title". A swap that replaces "alternate bite" with "byte" would type "Byte" when you say "capital alternate bite".	With command names, you can use the "escape" command to type the name of the command. This is not possible with swaps. Active swaps are always applied, regardless of what commands you use in an utterance. You can, however, enable and disable swaps by activating and deactivating the modes they belong to.

Swap Fields

You can define swaps in two places:

General settings file: The swaps in this file are always active. These primarily exist to ensure accurate command processing for all supported recognizers. In most cases, you will not need to change these swap settings.
Mode settings files: The swaps in this file are only active when the mode itself is active. You can see examples in the config\modes\example-jargon.yaml file. Each mode has an optional setting called swaps.

Whether swaps are defined in the general or mode settings, the swaps field is a list collection of individual swaps. Each swap has the following fields:

Setting	Type	Description
`from`	String	This can be either a phrase of one or more words or a regular expression. If this field contains words, and the utterance transcript contains these words, the words will be replaced. Matches against words are not case sensitive. Regular expressions are provided for advanced users who want more powerful control over matching. If this field contains a regular expression, and the utterance transcript is a match for the expression, the text will be replaced.
`to`	String	The replacement text. This text can optionally contain capitalized words, which is useful for uncommon proper nouns. If you are using regular expressions with capturing groups (with parentheses), you can use "$1", "$2", "$3", etc to output a specific group number.
`isExpression`	Boolean	Set this to `true` if the `from` field is a regular expression. This field defaults to `false`.

Auto Capitalization

If you are using the auto capitalization interpreter state and a recognizer that provides capitalization, the phrase that you want to swap may or may not contain capitalized words. This section provides some recommendations for reliable results with swaps when using auto capitalization.

To match a phrase that may or may not contain capitalized words, you can use a regular expression like "(?i)\bhello world\b" to match either "Hello world" or "hello world". As a reminder about regular expressions, "(?i)" declares that the match is not case sensitive and "\b" marks a word boundary.

As an alternative, you could define your swaps so that capitalized versions of matched text can trigger a similar capitalization of swapped text. For example, you could define the following two swaps:

"alternate bite" -> "byte"
"Alternate bite" -> "Byte"

Swap Order

Swapping happens after the recognizer produces a transcript and before the interpreter checks for commands and typing. The swapping process happens in the following order:

If auto capitalization is disabled (the default), the transcript is made entirely lowercase.
Swaps defined in the general settings file are applied in the order that they are defined.
The order of processing of mode settings files is not guaranteed, but swaps within a mode file are applied in the order that they are defined. This may impact how you define your swaps. For example, you should define a swap of "hello world" before a swap of "hello". If they were reversed, a swap of "hello world" would never occur.

❮ Mode Settings Functions ❯