Editing the Base Vocabulary

The Getting Started Code article of this knowledge base provides an overview of querying, deleting and adding phrases to the base vocabulary. Those are the only interfaces needed to create a vocabulary from scratch.

This article builds on those concepts to create a more robust mechanism to edit the base vocabulary. Editing the base vocabulary allows you to leave some portion of it unchanged and add your own customization on top of it.

The advantage of editing the base vocabulary, rather than re-inventing it, is to maintain a consistent user experience between your app and other applications. This reduces confusion and training for end users. For example, it would be confusing for the user to say "move left" in all other applications, then say "to the left" in your application. So, in most instances, it is best to leave similar functionality unchanged from the base vocabulary.

The base vocabulary is set by the device operating system based on the active system language. The built-in commands may change from version to version. Therefore, commands like:

sc.deletePhrase("Voice Off");

are only guaranteed to work for customers running in English on the same OS version originally tested against. A future OS version may replace the "Voice Off" phrase with another similar phrase, rendering that code incorrect.

More robust interfaces were introduced in SDK v1.8 to allow applications to easily and reliably edit the base vocabulary. Using the new interfaces described below, the "voice off" example would instead be written:

for( String voiceOffPhrase : sc.getVoiceOffPhrases() ) {
	sc.deletePhrase(voiceOffPhrase);
}

Instead of hard-coding the voice off phrase, we query the engine for that information using getVoiceOffPhrases(). This example will behave identically in all languages, including ones to which your application is not translated; and will even work if the actual phrases are changed by future OS revisions.

Phrase Queries

The phrases in the active vocabulary can be queried based on functionality. Some actions have multiple phrases, so each query returns a List of phrases where each phrase is the exact spoken phrase in the current language. An empty list is returned if no phrases match the request.

These interfaces allow you to create detailed help pages describing the built-in phrases, and allow you to delete the phrases you do not want active.

Queries include:

• getPhrases() - returns all phrases

• getWakeWordPhrases() - returns the current wake words, such as "Hello Vuzix", that bring the speech command engine to the active triggered state where it listens for the full vocabulary.

• getVoiceOffPhrases() - returns the current phrases, such as "voice off", that take the speech command engine out of the active triggered state so it once again listens only for wake words.

• getStopPhrases() - returns the current phrases, such as "stop", that terminate previous scroll requests.

• getKeycodePhrases() - return phrases associated with a specific keycode, such as "go left" is associated with KEYCODE_DPAD_LEFT. This is described more below.

• getIntentPhrases() - returns phrases associated with any label you created with defineIntent(). This interface is not used in editing the base vocabulary.

• getBuiltInActionPhrases() - returns phrases associated with various pre-defined actions, such as "take a picture". This is described more below.

Querying Key Codes

The getKeycodePhrases() query for phrases associated with keycodes takes two parameters: keycode and keyFrequency.

The keycode can be any valid key defined in the KeyEvent class, such as KEYCODE_DPAD_LEFT.

The keyFrequency can limit the results to phrases associated with single-press or repeating (scroll) keys. The valid values are:

• KEY_FREQ_SINGLE_OR_REPEAT - match all phrases whether single-press or repeating (scrolling). Both "go left" and "scroll left" would match this.

• KEY_FREQ_SINGLE_PRESS - match only single-press actions. Only "go left" would match this, not "scroll left".

• KEY_FREQ_REPEATING - match only repeating actions. Only "scroll left" would match this, not "go left".

So the request for the "go left" phrase would be

List<String> leftPhrases = sc.getKeycodePhrases(KeyEvent.KEYCODE_DPAD_LEFT, VuzixSpeechClient.KEY_FREQ_SINGLE_PRESS);

It is possible to iterate over all valid key constants to determine if they have at least one valid phrase or you can query to identify keys that have at least one valid phrase associated using getMappedKeycodes(). This takes a single argument keyFrequency as described above, and returns a List of keycode values.

This example shows a query for every phrase associated to a key:

int selectedFrequency = VuzixSpeechClient.KEY_FREQ_SINGLE_OR_REPEAT;
for ( Integer keycode : sc.getMappedKeycodes(selectedFrequency) ) {
	for ( String eachKeyPhrase : sc.getKeycodePhrases(keycode, selectedFrequency) ) {
		// todo: Do something with keycode and eachKeyPhrase
	}
}

Query Built-In Actions

The operating system provides some special built-in actions which vary by device. You can query the associated phrases using getBuiltInActionPhrases(). This interface takes a single parameter to identify the action. The action may be one of:

• BUILT_IN_ACTION_SLEEP

• BUILT_IN_ACTION_COMMAND_LIST

• BUILT_IN_ACTION_SPEECH_SETTINGS

• BUILT_IN_ACTION_FLASHLIGHT_ON (M-Series only)

• BUILT_IN_ACTION_FLASHLIGHT_OFF (M-Series only)

• BUILT_IN_ACTION_VIEW_NOTIFICATIONS

• BUILT_IN_ACTION_CLEAR_NOTIFICATIONS (Blade only)

• BUILT_IN_ACTION_START_RECORDING

• BUILT_IN_ACTION_TAKE_PHOTO

• BUILT_IN_ACTION_ASSISTANT (Blade only)

• BUILT_IN_ACTION_ASSIST_ALEXA (Blade only)

• BUILT_IN_ACTION_ASSIST_GOOGLE (Blade only)

For example, to determine which phrase will turn the screen off, we could query:

List<String> sleepPhrases = sc.getBuiltInActionPhrases(VuzixSpeechClient.BUILT_IN_ACTION_SLEEP);

Deleting Items

Any phrase returned from any of the queries may be passed to deletePhrase() to remove the phrase from the vocabulary.

There is also a deleteAllPhrases() interface that removes all phrases to allow your application to insert clean entries.

When editing the base vocabulary it is often preferred to use the deleteAllPhrasesExcept() interface. This interface takes a List of phrases to keep, all others are deleted. This is useful when an application wants to keep basic navigation and delete all built-in actions. As the OS is updated more built-in actions may be added. So, rather than re-releasing your application with more and more delete commands, you can create a list of base phrases to keep and delete the others.

This example deletes all phrases except the wake word, voice off word, those mapped to key presses and the stop phrase.

VuzixSpeechClient sc = new VuzixSpeechClient(this); 
ArrayList<String>keepers = new ArrayList<>(); for ( Integer keycode : 
sc.getMappedKeycodes(VuzixSpeechClient.KEY_FREQ_SINGLE_OR_REPEAT) ) { 
	keepers.addAll(sc.getKeycodePhrases(keycode, 
	VuzixSpeechClient.KEY_FREQ_SINGLE_OR_REPEAT)); 
} 
keepers.addAll(sc.getWakeWordPhrases()); 
keepers.addAll(sc.getVoiceOffPhrases()); 
keepers.addAll(sc.getStopPhrases()); 
sc.deleteAllPhrasesExcept(keepers);