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.

Related

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)
• French (France)*
• German
• Japanese
• Modern Standard Arabic*
• Spanish (Spain)*

note

*The VIDTK supports app intent development only. You can't use both system and app intents from within a voice-enabled application as it is not supported at this time.

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.

Field	Name	Value
app_intents	APP_CONFIRM	confirm | positive | affirm | agree
app_intents	APP_REJECT	deny | reject
sys_intent_list	ML_SYSAUDIO_MUTE	[empty]
sys_intent_list	ML_SYSAUDIO_UNMUTE	[empty]
sys_intent_list	ML_SYSAUDIO_VOLUME_DOWN	[empty]

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

1. Define App Intents

2. 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.

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.

Simple for Modern Standard Arabic, French, Spanish (Intents Only)

Field	Name	Value
app_intents	APP_CONFIRM	confirmer | affirmer | assurer
app_intents	APP_REJECT	refuser | rejeter
sys_intent_list	ML_SYSAUDIO_MUTE	Not Available
sys_intent_list	ML_SYSAUDIO_UNMUTE	Not Available
sys_intent_list	MY_SYSAUDIO_VOLUME_DOWN	Not Available

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

Operator	Description
|	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:

Field	Name	Value
app_intents	APP_CONFIRM	I hereby confirm | I hereby validate | I hereby acknowledge | I hereby verify | I hereby affirm

After (in variables notation):

Field	Name	Value
app_variable	confirmation_variable	confirm | validate | acknowledge | verify | affirm
app_intents	APP_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:

field	name	value
app_slots	Loudness	high|medium|low
app_slots	VolumePercent	1|2|3|4|5|6
app_variables	volume_type	sound | volume
app_variables	time_type	year | month | day
app_intents	APP_CONFIRM	Confirm {Loudness}
app_intents	APP_SET_VOL	(set | change) the ? $volume_type (to | at) {VolumePercent} percent ?
sys_intent_list	ML_SYSAUDIO_MUTE	[empty]
sys_intent_list	ML_SYSAUDIO_UNMUTE	[empty]
sys_intent_list	ML_SYSAUDIO_VOLUME_DOWN	[empty]

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

1. Define App Intents

   

2. Define App Variables

   

3. Define App Slots

   

4. Define System Intents

   

note

The definition order is commutative.

Using the Validate button yields:

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.

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

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

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.