Skip to main content
Version: 21 Aug 2024

Voice Intent Development Toolkit

Overview

The Voice Intent Development Toolkit (VIDTK) serves as an assistant for building application specific voice experiences. It assists the developer in the voice intent development lifecycle by offering insights into the anatomy of voice intents, specifically into their syntax and semantics.

The intuitive user interface guides the Voice Intent Developer from creation of the first voice intent to the creation of the asset (JSON file) that will, co-deployed with the application on the device, enable a customized voice experience. This facilitates a more efficient development lifecycle, creating a better overall voice experience for both the developer and the user.

We recommend using the VIDTK for any application-specific voice intent development.

Voice Design Guidelines

Voice Design Guidelines

For help understanding how to design your own app voice intents with the Magic Leap 2, see the Voice Intent Design Guidelines.

Supported Languages

The following languages are currently supported,

  • English (US)
  • Japanese
  • German
  • Modern Standard Arabic
  • French (France)
  • Spanish (Spain)
  • Italian
  • Portuguese (Portugal)

Naming Conventions

Since grammar files are the foundation of voice intents, it’s important to start with good naming conventions. Pick names that are descriptive and follow these rules. You can name your intent variables after their corresponding phrases. Only alphanumeric characters and underscores are supported.

  • Intents: Intents should be named in all-caps with snakecase. The naming convention “ML” is reserved for ML system intents and should not be used by application specific intents. Pick a short abbreviation for your app name followed by an underscore to differentiate your app intents.
    • Examples: APP_CAPTURE, APP_MENU, APP_YES, APP_NO
  • Slots: Slots should be named in CamelCase with the first letter in uppercase.
    • Examples: Color, MenuOption, VolumeLevel
  • Variables: Variables should be named using all lowercase snake_case with multiple words.
    • Examples: digit_single, degrees_rule

Samples

Simple (Intents only)

In the tabularized example below there are a total of five intents from which the first two, “APP_CONFIRM” and “APP_REJECT”, are app specific intents (App Intents) and the last three are system intents (System Intents). App specific intents allow you to associate one or more utterances with that specific intent. One can think about it as a group of different utterances that will trigger the intent.

FieldNameValue
app_intentsAPP_CONFIRM confirm | positive | affirm | agree
app_intentsAPP_REJECTdeny | reject
sys_intent_listML_SYSAUDIO_MUTE[empty]
sys_intent_listML_SYSAUDIO_UNMUTE[empty]
sys_intent_listML_SYSAUDIO_VOLUME_DOWN[empty]

Before validation we enter the above table values into the VIDTK UI using the following steps:

  1. Define App Intents

Define App Intents

  1. Define System Intents

Define System Intents

Before deploying the output with the Android application on the ML2 device, the “Validate” button enables the user to use the VIDTK for uncovering potential issues such as warnings and errors.

The “Validate” button enables the user to use the VIDTK for uncovering potential issues such as warnings and errors.

In our example, no issues were found and we can export our work to an ML2 compatible file (JSON) format using the “Export” button.

{
"language": "en-us",
"version": 1,
"_comment1": "[optional] list of slots shared by all app intents",
"app_slots": [],
"_comment2": "[optional] list of variables shared by all app intents",
"app_variables": [],
"_comment3": "[required] list of app intents",
"app_intents": [
{
"name": "APP_CONFIRM",
"value": "confirm | positive | affirm | agree",
"id": 0
},
{
"name": "APP_REJECT",
"value": "deny | reject",
"id": 1
}
],
"_comment4": "[optional] namelist of subscribed ML system intents",
"_comment5": "all default system intents are subscribed if this section doesn’t exist",
"_comment6": "NO system intents are subscribed if the value field for key “name” is empty",
"_comment7": "Partial system intents are subscribed if the value field contains some system intent names",
"sys_intent_list": {
"name": [
"ML_SYSAUDIO_MUTE",
"ML_SYSAUDIO_UNMUTE",
"ML_SYSAUDIO_VOLUME_DOWN"
]
}
}

To continue, use the Import button and continue designing and developing the desired Voice Intent experience.

Advanced

Grammar

In order to provide more flexibility in the formulation of intents, you can use a regular-expression-like syntax to formulate intents.

Allowed operators

OperatorDescription
| A pipe symbol separates alternative items.
()Parentheses enclose items that are grouped together.
?A question mark following a symbol denotes an optional item.
{}Braces implement slot-capturing semantic markup.
$A dollar sign precedes a variable which has a rule defined earlier in the grammar.
note

We are introducing two terms in this context: variable and slot.

Variables

A variable or non-terminal in terms of context-free grammars, serves purely as a grammatical tool to express variability. Instead of repeating an utterance with multiple shared substrings, you can use variables.

Example

Before:

FieldNameValue
app_intentsAPP_CONFIRM I hereby confirm | I hereby validate | I hereby acknowledge | I hereby verify | I hereby affirm

After (in variables notation):

FieldNameValue
app_variableconfirmation_variable confirm | validate | acknowledge | verify | affirm
app_intentsAPP_CONFIRM I hereby $confirmation_variable
note

In the grammar, before and after are equivalent.

Slots

Slots are similar to variables in that they express variability however {} notation serves as markup to be able to access those values specifically via Unity or the C-API.

Here is an example supporting the full grammar:

fieldnamevalue
app_slotsLoudnesshigh|medium|low
app_slotsVolumePercent1|2|3|4|5|6
app_variablesvolume_typesound | volume
app_variablestime_typeyear | month | day
app_intentsAPP_CONFIRMConfirm {Loudness}
app_intentsAPP_SET_VOL(set | change) the ? $volume_type (to | at) {VolumePercent} percent ?
sys_intent_listML_SYSAUDIO_MUTE[empty]
sys_intent_listML_SYSAUDIO_UNMUTE[empty]
sys_intent_listML_SYSAUDIO_VOLUME_DOWN[empty]

Following the analogous steps as in the previous example, you:

  1. Define App Intents

    Define System Intents

  2. Define App Variables

    Define System Intents

  3. Define App Slots

    Define System Intents

  4. Define System Intents

    Define System Intents

note

The definition order is commutative.

Using the Validate button yields:

Define System Intents

The lower left Validation successful indicates that you can export the file and then co-deploy it with an Android app.

Error and Warning Messages

This section provides examples of error and warning messages you might receive when creating and running your app intent.

Syntax Errors

  • Use of invalid symbols. This example shows use of the + operator, which Magic Leap doesn't support, resulting in the following error message.

Define System Intents

Define System Intents

  • Misspelled word. In this example, the value of the variable volume is misspelled as volumer, resulting in a warning.

Define System Intents

Define System Intents

  • Identical utterances. In this example, two intents share the utterance “Confirm {Loudness}”.

Define System Intents

Maximum Number Of Voice Intents

Magic Leap supports a maximum of 100 voice intents per configuration. If your configuration requires more than 100 voice intents, consider combining the values of related voice intents. For example, instead of creating Next Step and Continue as two different intents, combine them by setting the value of the intent to Next Step | Continue.

Installing VIDTK

You can install the VIDTK as an optional component when installing bundles in the Magic Leap Hub's Package Manager. If the VIDTK activity card is already present in the ML Hub, it indicates that VIDTK is installed. However, you may need to update the VIDTK package when you update the ML Hub. The app lets you know if this is required.

VIDTK Activity Card