How to dynamically modify Voice Command Definition (VCD) phrase lists (HTML)

Learn how to access and update the list of supported phrases (PhraseList elements) in a Voice Command Definition (VCD) file using the speech recognition result at run time.

Dynamically modifying a phrase list at run time can be useful if the voice command is specific to a task involving some kind of user-defined favorites or transient app data.

For example, let's say you have a travel app where users can enter destinations, and you want users to be able to start the app by saying the app name followed by "Show trip to <destination>". You don't need to create a separate ListenFor element for each possible destination. Instead, you can dynamically populate PhraseList at run time with the destinations created by the user. In the ListenFor element itself, you could specify something like: <ListenFor> Show trip to {destination} </ListenFor>, where "destination" is the value of the Label attribute for the PhraseList.

See the VCD elements and attributes v1.2 reference for more info about PhraseList and other VCD elements.

Prerequisites

This topic builds on Quickstart: Voice commands with Cortana. We continue here to demonstrate features with a trip planning and management app named Adventure Works.

To complete this tutorial, have a look through these topics to get familiar with the technologies discussed here:

• Install Microsoft Visual Studio.
• Get a developer license. For instructions, see Develop using Visual Studio 2013.
• Create your first app using JavaScript.
• Roadmap for Windows Store apps using JavaScript
• Learn about events with Quickstart: adding HTML controls and handling events
• See Cortana design guidelines for how to integrate your app with Cortana and Speech design guidelines for helpful tips on designing a useful and engaging speech-enabled app.

Instructions

Step 1: Identify the command

To update a PhraseList element in the VCD file, get the CommandSet element that contains the phrase list. Use the Name attribute of that CommandSet element (Name must be unique in the VCD file) as a key to access the VoiceCommandManager.installedCommandSets property and get the voiceCommandSet reference.

Step 2: Replace the phrase list

After you've identified the command set, get a reference to the phrase list that you want to modify and call the setPhraseListAsync method; use the Label attribute of the PhraseList element and an array of strings as the new content of the phrase list.

Note  If you modify a phrase list, the entire phrase list is replaced. If you want to insert new items into a phrase list, you must specify both the existing items and the new items in the call to setPhraseListAsync.

Here, the VCD file defines a Command"showTripToDestination" with a PhraseList that defines three options for selecting a destination in our Adventure Works travel app. As the user saves and deletes destinations in the app, the app updates the options in the PhraseList.

<?xml version="1.0" encoding="utf-8"?>
<VoiceCommands xmlns="https://schemas.microsoft.com/voicecommands/1.1">
  <CommandSet xml:lang="en-us" Name="AdventureWorksCommandSet_en-us">
    <CommandPrefix> Adventure Works, </CommandPrefix>
    <Example> Show trip to London </Example>

    <Command Name="showTripToDestination">
      <Example> show trip to London  </Example>
      <ListenFor> show trip to {destination} </ListenFor>
      <Feedback> Showing trip to {destination} </Feedback>
      <Navigate/>
    </Command>

    <PhraseList Label="destination">
      <Item> London </Item>
      <Item> Dallas </Item>
      <Item> New York </Item>
    </PhraseList>

  </CommandSet>

<!-- Other CommandSets for other languages -->

</VoiceCommands>

Here's how to update the PhraseList shown in the previous example with an additional destination to Phoenix.

N/A

Remarks

Using a PhraseList to constrain the recognition is appropriate for a relatively small set or words. When the set of words is too large (hundreds of words, for example), or shouldn’t be constrained at all, use the PhraseTopic element and a Subject element to refine the relevance of speech-recognition results to improve scalability.

In our example, we have a PhraseTopic with a Scenario of "Search", further refined by a Subject of "City\State".

<?xml version="1.0" encoding="utf-8"?>
<VoiceCommands xmlns="https://schemas.microsoft.com/voicecommands/1.1">
  <CommandSet xml:lang="en-us" Name="AdventureWorksCommandSet_en-us">
    <CommandPrefix> Adventure Works, </CommandPrefix>
    <Example> Show trip to London </Example>

    <Command Name="showTripToDestination">
      <Example> show trip to London  </Example>
      <ListenFor> show trip to {destination} </ListenFor>
      <Feedback> Showing trip to {destination} </Feedback>
      <Navigate/>
    </Command>

    <PhraseList Label="destination">
      <Item> London </Item>
      <Item> Dallas </Item>
      <Item> New York </Item>
    </PhraseList>

    <PhraseTopic Label="destination" Scenario="Search">
      <Subject>City/State</Subject>
    </PhraseTopic>

  </CommandSet>

Related topics

Cortana interactions

Launch a foreground app with voice commands in Cortana

Launch a background app with voice commands in Cortana

VCD elements and attributes v1.2

Designers

Cortana design guidelines