YAML Tutorial

All Utterly Voice settings files use a format known as YAML. This is a popular text file format used by many applications to organize settings data. You only need to know the basics of this format, which this page teaches you. If you are already familiar with YAML, you can skip this page.

YAML was chosen by Utterly Voice due to its simple and concise text format for settings data. Once you are familiar with the format, you will find that editing text settings data by voice is easier than using a mouse-driven user interface. This is because you can more easily copy, paste, and modify content.

It helps to look at the settings files as examples while reading this page. Open the application directory, then open the config and config\modes directories there. You will find many example settings files in these directories. When creating new commands or modes, you don't have to start typing settings from scratch. Most often you can find a command or mode that is similar to what you want, then copy, paste, and modify as needed.

Document Start

YAML files begin with the document start marker ---. You will see this as the first line on every settings file.

Key-Value Pairs

The YAML format is fundamentally a collection of many key-value pairs. The keys are the names of specific settings, and the values are the values for those settings.

A key and value are separated by :, with the key on the left and the value on the right. For example, the following microphoneThreshold setting is found in the config\settings.yaml file, and it has a value of 100.

microphoneThreshold: 100

Each value has a specific type, which can be one of the following:

• Number
• Boolean (true or false)
• String (text)
• Map Collection (related keys and values)
• List Collection (list of values)

The sections below describe each of these types.

Number Values

Some settings have a value that is a number. The microphoneThreshold setting described above has a number value. A number value can be either integer (example: 100) or decimal (example: 1.5).

Boolean Values

Some settings have a value that is a boolean value that is either true or false. For example, the darkTheme setting in the config\settings.yaml file has a boolean value.

darkTheme: false

String Values

A string value is used to provide text as a value. There are several ways to represent strings with YAML, but this documentation explains three methods that are most useful in Utterly Voice settings.

• For most settings, you should use double quotes " to wrap a string value.
• In some less common scenarios described later, you might want to use single quotes ' to wrap a string value.
• For long strings, you can use >-, then a newline, then one or more lines of indented text. This is called block style for a string.

The following snippet from the config\modes\basic.yaml file shows the three ways to provide a string value. The name value uses double quotes, the description value uses a block style string that is two lines long, and the expression value uses single quotes.

---
name: "basic"
description: >-
  The basic mode is active by default
  and is used for basic dictation commands common to most programs and activities.
biases:
  - expression: '\bgo up the \w'
    factor: 0.5

Map Collections

A map collection is a collection of related keys and values. When a setting has a value that is a map collection, the map collection value starts on the next line and is indented. For example, see the following initiallyActiveStates map collection setting found in the config\settings.yaml file. This map collection contains four keys, each of which have boolean values.

initiallyActiveStates:
  autoCapitalization: false
  autoSpacing: true
  autoUtteranceSpacing: false
  commandsOnly: false

List Collections

A list collection is a list of values. When a setting has a value that is a list collection, the list collection values start on the next line and are indented. Each list collection value starts with - . For example, see the following snippet from the titleSkip list collection setting found in the config\settings.yaml file. This list collection contains a list of string values.

titleSkip:
  - "a"
  - "an"
  - "and"

Comments and Empty Lines

You can include comments in the file using #. Everything after # on a line in the file is a comment. Comments are not processed by the application; they only help to explain the data in the file for anyone who is reading it. You will see examples of comments below.

You can also include empty lines in a file to improve formatting. Empty lines are not processed by the application.

Nested Settings Data

Each value in a list or map collection can be a number, boolean, string, or another collection. When collections contain other collections, this creates nested data, which defines parent-child relationships for the data. A parent owns all of the data within its children, grandchildren, etc.

For example, a snippet of the commands list collection found in the config\modes\mouse.yaml file is shown below. These settings are shown twice: first without any comments, then with many detailed comments explaining each field. You do not need to understand what each of these fields means yet; you just need to understand how the data is organized.

This may seem confusing at first, but YAML is very good at representing nested data in a clear and concise way. Here are some important things to notice:

• Indentation is used to define the parent-child relationships. When looking at indentation, ignore the hyphen (-) and colon (:) characters, and just look at the actual data. When the indentation increases on a line, it means that this data is owned by the parent at the previous line. When the indentation decreases on a line, it means that the previous line completed child data.
• Wherever you see a hyphen (-), it marks the beginning of a list collection item.
• Wherever you see a colon (:), a map collection key is on the left of the colon, and the value associated with that key is either on the right of the colon, or on one or more indented lines immediately after the colon.

Example settings data without comments:

commands:
  - name: "show"
    description: >-
      Activates the "screen analyzer" exclusive mode to control the mouse.
      Once a label has been selected, a left click is performed at the label.
    functions:
      - name: "toggleMode"
        fixedArguments:
          - "on"
          - "screen analyzer"
      - name: "openMouseGuide"
        fixedArguments:
          - "screen"
          - "left"
  - name: "show multi"
    description: >-
      Activates the "screen analyzer" exclusive mode to control the mouse.
      Once a label has been selected, a left click is performed at the label,
      and after a brief pause, the labels appear again.
      The process continues until you say "cancel".
    functions:
      - name: "toggleMode"
        fixedArguments:
          - "on"
          - "screen analyzer multi"
      - name: "openMouseGuide"
        fixedArguments:
          - "screen"
          - "left"

Example settings data with comments highlighted in green:

# The commands before the colon is the key of a map collection. All data after
# this is owned by commands, which is a list of commands.
commands:
  # The first hyphen at this indentation indicates this is the first item of
  # the commands list collection. This item is a map collection with keys:
  # name, description, and functions. This is the first command in the list
  # of commands. The name key has a value of "show", which is the name of the
  # command.
  - name: "show"
    # This is the description of the "show" command, which is a string value
    # provided in block style.
    description: >-
      Activates the "screen analyzer" exclusive mode to control the mouse.
      Once a label has been selected, a left click is performed at the label.
    # This is the list of functions that are associated with the "show" command.
    functions:
      # This is the first function of the functions in the "show" command.
      # This item is a map collection with keys: name and fixedArguments.
      # The name key has a string value. This is the name of the function.
      - name: "toggleMode"
        # The fixedArguments key has a list collection value. Each item is a
        # string value.
        fixedArguments:
          # The first fixed argument for the "toggleMode" function.
          - "on"
          # The second fixed argument for the "toggleMode" function.
          - "screen analyzer"
      # The second hyphen at this indentation indicates the second item of the
      # functions list collection. This item is similar to the previous item,
      # but with different values.
      - name: "openMouseGuide"
        fixedArguments:
          - "screen"
          - "left"
  # The second hyphen at this indentation indicates the second command in the
  # commands list collection. This is the next command in the list of commands.
  # This command is similar to the previous command, but with different values.
  - name: "show multi"
    description: >-
      Activates the "screen analyzer" exclusive mode to control the mouse.
      Once a label has been selected, a left click is performed at the label,
      and after a brief pause, the labels appear again.
      The process continues until you say "cancel".
    functions:
      - name: "toggleMode"
        fixedArguments:
          - "on"
          - "screen analyzer multi"
      - name: "openMouseGuide"
        fixedArguments:
          - "screen"
          - "left"

String Escape Sequences

If a string value needs to contain a double quote ", a single quote ', a backslash character \, a newline character, or a tab character, you need to consider how escape sequences work.

Consider this string value:

"Type ", then continue"

This string will not work as expected. When the first open quote is encountered by the application reading the file, the application will look for the next open quote to decide where the string ends. This happens just before the comma. A similar problem happens when you include a single quote in a string that is wrapped in single quotes.

To fix this problem, you use an escape sequence. Escape sequences are special sequences of two characters that get translated as the character you actually want when the application reads the data. These escape sequences are used to solve the quoting issues described above and to insert special characters.

Most escape sequences only apply to double quoted strings. Single quoted strings only have one sequence. Block style strings do not support any escape sequences. The following table describes the escape sequences:

From the table above, notice that only one escape sequence is relevant for single quoted strings. This is the only sequence recognized by this type of string. This makes single quoted strings useful when you want to use the backslash \ character in the string, because you do not need an escape sequence for it. This is why it is used in the example above for the expression value.

For block style strings that use >-, no escape sequences are supported. This means that you cannot insert a newline character in the string. If you need to do this, just use a double quoted string.

The following example shows how to use escape sequences in double and single quoted strings. Both examples produce the same string value.

key1: "Enter \", then ', then finish."
key2: 'Enter ", then '', then finish.'

YAML supports many ways to provide strings and escape sequences. The options described in this page should be everything you need for Utterly Voice settings. If you would like to try other more advanced options, see this post for an excellent overview of all of the options.

YAML Errors

If you edit a settings file, and Utterly Voice displays an error about the file at startup, you probably entered invalid YAML. The easiest way to find the problem in your file, is to use an online YAML validation tool. These tools will show you exactly where the problem is. There are many tools that perform this. One recommended tool is YAML Lint.