Payloads

What Is a Payload?

Command macro using one payload

A payload's function is to pass information to the command when it is executed. Both speech-triggered and event-triggered commands can include payloads.

Unlike regular voice command phrases -- which only trigger a command -- payloads are information that our command can actually use.

For example, if we want VC to play a particular song in our media player, we pass the song title as a payload to the command. Otherwise, it wouldn't know what song to play.

Payload Syntax

In the command macro, payload values are represented by placeholders.

• If we are passing one piece of information, the payload looks like {1}.
• If we need to pass 2 different pieces of information, the first piece is {1} and the second {2}.
• And so on.

These placeholders are then replaced in the command's macro by the values we provide when we issue our voice commands (or through event payloads).

For this reason, if you don't execute your voice command properly, your command won't work: it won't know what {1}, {2}, etc. stand for unless you pass it that information.

Once the speech engine figures out which command you are saying, the command will be executed and the payloads (if any) passed to the command macro. This macro is made up of the actions that are defined in the LCB (logical command builder).

Using Payloads

In the Command Tree Editor you can define any of four types of payloads depending on the kinds of values you want to pass:

1. payload list
2. payload range
3. payload dictation
4. payloadXML file

Select the desired payload type from the list of elements in the dropdown list of the Command Part menu option (NB: The command you are editing needs to be selected in the command tree for this menu option to be accessible).

The examples below describe a number of practical payload uses, but are not meant as detailed guides to building each of the commands in the Logical Command Builder.

Example 1. Payload from XML

The command phrase "Play Song" tells VoxCommando that you want to execute the macro that starts playing a song in whichever media program your command has specified (e.g. MediaMonkey, XBMC, iTunes, etc.).

{1} refers to the payload — in this case, a song title. In this example, we have a payloadXML file located in the mmPayloads folder of the VoxCommando directory which contains a list of all the songs available in our music library (see GenXML). When we say the title of a particular song in our command, VoxCommando consults this list of payload values and returns the best match based on the speech that it recognizes.

This value is then used within the command's macro. In this example, VoxCommando would initiate an SQL query of the MediaMonkey database to play the correct track.

The same payload value can be used more than once within the same command. For example, we could query the MediaMonkey database, and then add an action such as - OSD.ShowText > 'Playing song {1}' - to display a pop-up window on our screen.

In other words, the command phrase "Play song" is always the same. This phrase is required for VC to know what you want it to do. However, the payload value that you then provide can change based on a set of values you've defined in your payloadXML.

For a simple introductory example of a command that uses payloadXML, see the the thread "Open different news websites using payloadXML" on the XML Exchange board.

As well, most default configurations of VoxCommando come pre-packaged with commands that use payloadXML files (among other types of payloads). Take a closer look at these examples in your command tree to see how they work.

Example 2. Payload dictation

The command phrase "Search wikipedia for" tells VoxCommando that you want to execute the macro that performs a Wikipedia search in a web browser that you have specified.

The search term that you then say becomes the payload (e.g., "Search wikipedia for 'tree frog'").

This example uses the payload type called "payloadDictation: Regular". The payload dictation payload allows you to freely dictate the phrase that you want to look up, without relying on a predefined list of values. Note that it operates according the language you are using on your OS.

The downside of this type of payload is that VoxCommando won't have a finite set of phrases to listen for, therefore its ability to recognize what you have said may be impacted.

The process for building this simple command can be seen in the video, VoxCommando Fireside Chat 2 - Search Wikipedia.

You can also get the xml for this command on the XML Exchange board of the forum.

Reminder: Payload dictation is not available in the SP version of VoxCommando. This is a limitation of Microsoft's Speech Platform 11 and has nothing to do with VoxCommando.

Example 3. Using more than one payload

You are not limited to using just one payload in a given command.

The command below uses two different payload types:

1. A payload list.
2. A payload range.

A payload list is defined in the same way as command phrases, but the phrase you say will be passed on as data.

A payload range is a list of numbers defined as Low#, High#

For example, a payload range of 4,12 would allow you to say any number from 4 to 12 inclusive. In the example above, VoxCommando will expect a value of 1 to 60.

Why, in this case, would we use a payload list rather than a series of ordinary phrases?

By using a payload list, the command macro can actually make use of the phrase. It is storing the value that we give it, rather than just using it as a trigger to initiate a command. In this example, VoxCommando can then use the payload value when issuing the reminder. It can remind us that we wanted to "walk the dog" at the appropriate time.

Several different methods for making reminder commands have been posted to the forum. Here's one, but there are many others, some of which are too complex for new users with no background in programming. Try searching the forum for "reminders", "walk the dog", "timers", "schedules" etc.

More on Payload XML

A payloadXML can be set up so that an action will use one of the contained phrases as the payload, or it may be used to map phrases to corresponding values (e.g., you might have a list of directional phrases, "up," "down, "right," "left" that are mapped to keyboard values).

You can choose between these two types of payloadXML under the Command Parts menu option of the Command Tree Editor.

Any time you need to create, view, or edit a payloadXML file, you should use the payload XML editor. You can access the payload editor window one of two ways:

1. Within the Command Tree Editor, double-click on any command's payloadXML element to edit that payloadXML. Existing payloadXML files can be edited by double-clicking on the corresponding payloadXML element of a command in the command tree. This will open the PayloadXML Properties window, from which you can choose to edit an existing payloadXML or create a new one.
2. Go to File >> Payload XML Editor. Create a new file, or browse to the correct file in your VC folder if it already exists.

NOTE: To reliably test a command that uses a value-phrase payloadXML file, you will need to save the command, exit the LCB and issue the appropriate voice command. The "test payloads" fields in the bottom right-hand corner of the LCB expect payload values, not phrases. These fields are not associated with your payloadXML file, and VoxCommando will not access values stored there if you try to enter a payload phrase.

Syntax

Payload Editor. Double-click on a payload XML element in the command tree editor to access the payload editor window. The payload editor can also be accessed from the File menu.

When building command actions in the Logical Command Builder, the syntax {1} refers to the value of payload 1.

Example of friendly payloads

If you are using a payloadXML that contains phrases mapped to values, you can use the syntax {PF.1} in your action as an alternative to {1}. {PF.1} will be replaced with the "friendly" version of payload 1, or in other words, the phrase of the payload instead of the value.

Suppose you have an "Open website x" command that uses payloadXML, where website names are associated with their URLs. Then the friendly payload {PF.1} is the actual website name and {1} is the URL (the value that VC needs in order to load the correct webpage).

If you then want to have VoxCommando announce which site it is going to open, you could use the action: TTS.Speak "Now opening the site: {PF.1}."

Customizing your payload xml file

Whenever you create a payloadXML file, you have the option of checking the SubMatch box. This is what allows you to ask VC to "Play artist Marley" when what you would actually like to hear is artist Bob Marley and the Wailers. If this box is not checked, VoxCommando will expect the complete phrase: "Bob Marley and the Wailers".

Note that there is an advanced option in the main Options menu that you may wish to adjust for defining the maximum and minimum sub-phrase lengths that you want VC to recognize.

Payloads vs. Parameters

It is easy to confuse "payloads" with "parameters".

Each action in a command usually does just one thing; actions will usually expect parameters. Some parameters are required for the action to work, and some are optional (e.g., the action Launch.OpenURL requires the desired URL as a parameter).

In the LCB you can specify parameters that are simply static (unchanging) values that always do the same thing, or you can use payloads to make them more dynamic. For example, you could provide the Launch.OpenURL action with a static parameter such as "www.voxcommando.com", which would result in the command always opening the VoxCommando site:

Alternatively, you could insert payload {1} as the parameter and create a payload list or payloadXML file containing different website URLs. This would then give you the flexibility to open different sites using the same command: