Mode Settings

Mode settings files are found in the config\modes directory in the application directory. Each mode has its own settings file. To add a mode to your settings, simply create a mode YAML file and put it in this directory. You can name these files anything you like, but use a file suffix of .yaml. A mode has the following settings:

Setting	Type	Description
`name`	String	The name of the mode. Choose a name that is easy to recognize, so you can easily use the "activate", "deactivate", and "open help" commands.
`alternates`	List Collection	An optional list of additional string phrases that will match this mode name when using the "activate", "deactivate", and "open help" commands. This is helpful when a recognizer consistently fails to recognize a mode name.
`description`	String	A description of the mode. This text will appear in the content when you say "open help".
`initiallyActive`	Boolean	If `true`, this mode will be automatically active when the application starts.
`exclusive`	Boolean	If `true`, this mode is an exclusive mode.
`biases`	List Collection	You can use this optional setting to control recognition bias for certain phrases while the mode is active. See Bias.
`swaps`	List Collection	The optional list of swaps that are available when the mode is active. See Swaps.
`commands`	List Collection	The list of commands that are available when the mode is active. See Commands below.

Commands

Every mode has a list of commands. Each command has the following settings:

Setting	Type	Description
`name`	String	The spoken name for the command. This must be in lowercase and can contain at most 4 words.
`description`	String	The command description. This text will appear in the content when you say "open help". You can use basic HTML in this description for formatting the output.
`biasFactor`	Number	This optional setting is used to control recognition bias for this command name. If not supplied, the default value is 1.2. See Bias.
`pseudoCommand`	Boolean	This optional setting controls whether the command is identified as a true command when the commands-only interpreter state is active. If it is `false` (the default), the commands-only state will treat this as a true command. If it is `true`, the commands-only state will treat this as normal typing and ignore the command.
`alternates`	List Collection	A list of additional string phrases that will trigger this command. This is helpful when a recognizer consistently fails to recognize a command name.
`functions`	List Collection	This is a list of functions that should be called for this command. Functions define the actions that are taken for this command. See Functions.
`spaceLeft`	Boolean	Set this field to `true` if this command types text that normally has a space on the left side of it. For example, this is `true` for most words and `false` for ",". The default value of this field is `false`. Details: When the auto-spacing interpreter state is on, and this optional field is set to `true`, Utterly Voice will insert a space character on the left of any text typed by this command. This does not apply if the command is the first thing in the utterance.
`spaceRight`	Boolean	Set this field to `true` if this command types text that normally has a space on the right side of it. For example, this is `true` for most words and `false` for "$". The default value of this field is `false`. Details: This is similar to `spaceLeft`, except it adds space on the right side of the command output. If there is another command immediately after this command in the utterance, the `spaceLeft` value of the other command overrides this `spaceRight` value. If the auto-utterance-spacing interpreter state is on, and `spaceRight` is `true`, and this is the last command in the utterance, a space will be added after the content typed by the command. Otherwise, no space is added after the last command. In addition, auto-spacing never inserts two space characters between consecutive command outputs.

Example

The following is an example mode file with detailed comments explaining the fields.

---
# Mode name displayed in the interface and used as an argument to
# "activate" and "deactivate" commands.
name: "notepad"

# Mode description displayed in the help content.
description: >-
  Commands for the Windows Notepad application.

# Alternate matches for the mode name when using the
# "activate" and "deactivate" commands.
alternates:
  - "note pad"
  - "no pad"

# If this is true, this mode is automatically active when the application starts.
initiallyActive: false

# If this is true, this mode is in an exclusive mode.
# When an exclusive mode becomes active, all other modes are temporarily inactive.
# This is used for advanced modes.
exclusive: false

# List of commands that are active when this mode is active.
commands:

  # Command name. When the mode is active and you say this command,
  # the command is called.
  - name: "new file"
    # Command description displayed in the help content.
    description: >-
      Opens a new tab.
    # Ordered list of functions that are called for this command.
    # Many simple commands use a single function.
    functions:
      # The name of the function to call.
      - name: "keyPress"
        # Fixed arguments supplied to the function.
        # This issues to keyboard shortcut control+N.
        fixedArguments:
          - "control"
          - "n"
  - name: "open file"
    description: >-
      Open a file.
    functions:
      - name: "keyPress"
        fixedArguments:
          - "control"
          - "o"
  - name: "close file"
    description: >-
      Close the current file.
    # Alternate matches for the command name.
    alternates:
      - "clothes file"
      - "closed file"
    functions:
      - name: "keyPress"
        fixedArguments:
          - "control"
          - "w"
  - name: "save file"
    description: >-
      Save the current file.
    functions:
      - name: "keyPress"
        fixedArguments:
          - "control"
          - "s"
  - name: "save all files"
    description: >-
      Save all opened files.
    functions:
      - name: "keyPress"
        fixedArguments:
          - "control"
          - "alt"
          - "s"
  - name: "copy"
    description: >-
      Types control-c to copy content to clipboard.
    functions:
      - name: "keyPress"
        fixedArguments:
          - "control"
          - "c"
  - name: "cut"
    description: >-
      Types control-x to cut content to the clipboard.
    functions:
      - name: "keyPress"
        fixedArguments:
          - "control"
          - "x"
  - name: "paste"
    description: >-
      Types control-v to paste content.
    functions:
      - name: "keyPress"
        fixedArguments:
          - "control"
          - "v"
  - name: "go right file"
    description: >-
      Opens the next file tab.
      Accepts an optional number of times to execute the command.
    functions:
      - name: "keyRepeat"
        fixedArguments:
          - "control"
          - "tab"
        # Number of utterance arguments supplied to the function.
        # Utterance arguments are said after the command name.save buffer.
        # This argument controls how many times the keyboard shortcut is issued.
        utteranceArguments: 1
  - name: "go left file"
    description: >-
      Opens the previous file tab.
      Accepts an optional number of times to execute the command.
    functions:
      - name: "keyRepeat"
        fixedArguments:
          - "control"
          - "shift"
          - "tab"
        utteranceArguments: 1

Next ❯