Language: HTML | XAML

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

Applies to Windows Phone only

Learn how to update the list of supported phrases (PhraseList elements) in a Voice Command Definition (VCD) file 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 movie-viewer app for a relatively small set of movies, and you want users to be able to start a movie simply by saying the app name followed by "Play <movie name>". You don't need to create a separate ListenFor element for each possible movie. Instead, you can dynamically populate PhraseList at run time with the movie options. In the ListenFor element itself, you could specify something like: <ListenFor> Play {movies} </ListenFor>, where "movies" is the value of the Label attribute for the PhraseList.

See the Voice command elements and attributes reference for more info about PhraseList and other VCD elements.

What you need to know



This topic builds on Quickstart: Voice commands.

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


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.

function buttonSpeechRecognizerSRGSConstraintCheckCommandSetClick() {
    var installedCommandSets =
    if (installedCommandSets.hasKey("examplevcd")) {
        var commandSet = installedCommandSets.lookup("examplevcd");
        var messageDialog;
        messageDialog =
          new Windows.UI.Popups.MessageDialog(
, "Command set name");

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's an example of a VCD file that defines four command options for a demo app that implements the various types of speech recognition.

This particular example has a command prefix ("Recognize"), an optional word ("Show"), a topic list for identifying the different types of speech recognition implemented by the app, and a PhraseTopic, which allows the user to dictate a free-form message in-line with the voice command.

<VoiceCommands xmlns="">

  <CommandSet xml:lang="en-us" Name="examplevcd">
    <Example>Show default speech recognition</Example>

  <Command Name="showRecognition">
      <Example>Show default recognition</Example>
      <ListenFor>[Show] {options} {person}</ListenFor>
      <Feedback>Showing {options} {person}</Feedback>

    <PhraseList Label="options">
      <Item>default recognition</Item>
      <Item>web search</Item>
      <Item>list constraint</Item>
      <Item>file constraint</Item>
    <PhraseTopic Label="person" Scenario="Search">
      <Subject>Person Names</Subject>

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


Here's how to update the phrase list shown in the previous example.

function buttonSpeechRecognizerSRGSConstraintUpdateClick() {
    var installedCommandSets =
    if (installedCommandSets.hasKey("examplevcd")) {
        var commandSet = installedCommandSets.lookup("examplevcd");
            "options", ['test1', 'test2', 'test3', 'test4']).done(
              // Success function.
            function (result) {
                var messageDialog;
                messageDialog =
                  new Windows.UI.Popups.MessageDialog(
                  "Phrase list updated", "Success");
        // Error function.
        function (err) {
            WinJS.log && WinJS.log("Update phrase list failed.");


Add a Subject element to the PhraseTopic element to refine the relevance of speech-recognition results and improve scalability.

In our example, we have a PhraseTopic with a "Short Message" scenario, further refined by a "Person Names" Subject.

    <PhraseTopic Label="person" Scenario="Search">
      <Subject>Person Names</Subject>

Use the Properties dictionary of a SpeechRecognitionSemanticInterpretation object to find out the content spoken in the subset of a ListenFor element represented by a PhraseTopic. The dictionary key is the Label attribute value of the PhraseTopic element.

Related topics

Responding to speech interactions
Quickstart: Voice commands
Voice command elements and attributes
Speech design guidelines for Windows Phone



© 2014 Microsoft