<bevocal:enroll>

Extension. Create and modify enrolled grammars.

Syntax

 <bevocal:enroll
     name="string"
     expr="js_expression"
     cond="js_expression"
     grammarname="string"
     speakeridexpr="js_expression"
     phraseidexpr="js_expression"
     minconsistencies="integer"
     maxtries="integer"
     type="MIME_type"
 />

Description

To use this tag, the containing <vxml> tag must declare the XML namespace bevocal by including the following attribute:

 xmlns:bevocal="http://www.bevocal.com/"

Attribute Description

name
Name of the input variable that will hold the enrollment result. The variable name may not be a JavaScript reserved keyword.

The input variable has dialog (form) scope; its name must be unique among all VoiceXML and JavaScript variables within the form's scope.

expr
JavaScript expression that assigns the initial value of the input variable for this enrollment. Optional (default is undefined).

If you set the input variable to a value other than undefined, you'll need to clear it before the enrollment can execute.

cond
JavaScript boolean expression that also must evaluate to true for the enrollment to execute. Optional (default is true).

If not specified, the value of the input variable alone determines whether or not the field can execute.

grammarname
The name of the enrollment grammar to which the new phrase will be added. If the grammar does not exist, it will be created.

speakerid
Deprecated; use speakeridexpr instead.

speakeridexpr
JavaScript expression that evaluates to the ID of the current speaker. Because enrolled grammars are speaker-dependent, recognition against the grammar only works with the same speaker (and same value for speakeridexpr).

phraseidexpr
A unique ID for the phrase being enrolled in the grammar. When the grammar is matched during speech recognition, the phrase ID for the enrolled phrase that was recognized is returned.

For example, in an address book application, each name should be enrolled with a different phrase ID. The associated telephone numbers should be stored in a database that maps from phrase ID to telephone number. When a name from the grammar is recognized, the phrase ID can be used to look up the telephone number.

minconsistencies
The minimum number of consistent utterances that must be provided by the user for the enrollment to succeed.

minconsistencies must be less than or equal to maxtries or a parse-time error.badfetch will be thrown. The default and minimum value for minconsistencies is 2.

maxtries
The maximum number of enrollment attempts the interpreter will make. If it has not collected minconsistencies consistent utterances in maxtries attempts, an error.enrollment.max_tries event will be thrown. The developer should catch the event and may decide to clear the enroll item and force the FIA to visit it again.

maxtries must be greater than or equal to minconsistencies or a parse-time error.badfetch will be thrown. The default value for maxtries is 5.

type
The MIME type for the recorded utterance. Allowed types are:

• audio/wav (RIFF format)

• audio/basic (m-law encoded)

The default type is audio/wav.

keyexpr
Deprecated. Use the bevocal.security.key property instead.

Properties of the Input Variable

Once enrollment succeeds, the input variable is filled with the audio from one of the user's consistent utterances. Applications can send the audio to their back-end server using <submit> or <data>.

Properties of the Shadow Variable

Corresponding to the <bevocal:enroll> input variable name is a shadow variable name$. After the input variable is filled, some additional information is available in the following properties of this shadow variable:

Property Description

clash
The number of clashes that occurred during enrollment

clashedPhraseIds
The existing phrase IDs that clashed with the enroll utterance.

enrollAudio
The audio data from one of the consistent utterances. This is the same audio data that is stored in the input variable.

numConsistentUtterances
The number of consistent utterances collected for this enrollment

For a field whose name is name, you access the property propName of the shadow variable with the syntax:

 name$.propName

For example, you access the clash property for a field named en1 field as:

 en1$.clash

Usage Model

The <bevocal:enroll> tag must collect several utterances until it has a consistent statistical model of the phrase the user is trying to enroll. The first time a <bevocal:enroll> item is visited, it will collect one utterance and then return control to the FIA. Since the minimum value of minconsistencies is 2, the FIA's next iteration will select the same <bevocal:enroll> item, which will then collect a second utterance. This behavior will continue until a consistent enrollment is achieved, maxtries is reached, or an error occurs.

When an enroll utterance clashes with an existing phrase in the enrolled grammar, an error.enrollment.clash event is thrown. You can use the shadow variables, name$.clash and name$.clashedPhraseIds to get information about the number of clashes and which phrase IDs the enroll utterance clashed with.

Security Considerations

The bevocal.security.key property controls access to enrollment grammars. In this situation, a key can be thought of as a namespace that qualifies the grammarname attribute of <bevocal:enroll>. Applications using one security key are totally prevented from accessing enrollment grammars created by an application using a second key, because their grammars live in separate namespaces. When you develop applications for one of BeVocal's commercial hosting services such as Enterprise Hosting, you will need a security key in order to use enrollment.

When you develop on Café, you can use enrollment without a key; however there are limitations. First, there will be an implied key derived from your Café account number. This means that even if you use the same enrollment grammar name from two different Café accounts, you will not be able to access the same enrolled phrases. Attempting to enroll more than ten phrases will cause an error.noauthorization event to be thrown.

Tip:

•	If a JavaScript expression contains any of the characters "`<`", "`>`", or "`&`", that character must be replaced with the corresponding escape sequence "`<`", "`>`", or "`&`". For more information, see JavaScript Quick Reference.

Usage

Parents Children

<form> <audio> <catch> <enumerate> <error> <filled> <grammar> <help> <link> <noinput> <nomatch> <option> <prompt> <property> <value>

Exceptions

Exception Description

error.enrollment.retries
The system collected maxtries utterances and still could not achieve a consistent model of the phrase being enrolled.

error.enrollment.clash
The utterances that were collected clash with those for another phrase already enrolled in this model.

error.noauthorization
Maximum number of phrases enrolled into the grammar. For a Café developer, the enrolled grammar is limited to 10 phrases.

noinput
No speech was heard before the time specified by the timeout attribute on the last queued prompt (or by the timeout property) elapsed.

See Also

•	See Chapter 9, Voice Enrollment Grammars in the Grammar Reference, especially for the description of how to refer to an enrolled grammar.
•	The JavaScript function `bevocal.enroll.removeEnrolledPhrase`

Examples

A form that adds items to an enrolled grammar.

 <?xml version="1.0" ?>
 <!DOCTYPE vxml PUBLIC "-//BeVocal Inc//VoiceXML 2.0//EN"
  "http://cafe.bevocal.com/libraries/dtd/vxml2-0-bevocal.dtd">
 <vxml version="2.0" xmlns="http://www.w3.org/2001/vxml">
 
 <form id="enroll_names">
   <block>
     Welcome to the address book demo. 
     Let's add some names to the address book.
   </block> 
 
   <!-- This event is thrown when there is a clash with one -->
   <!-- of the existing phrases in the enrolled grammar.    --> 
   <catch event="error.enrollment.clash">
     Oops! There was a clash for the enrollment sample.
     <exit/>
   </catch>
 
   <!-- This event is thrown when then minimum number of        -->
   <!-- consistent utterances are not obtained within maxtries. -->
   <catch event="error.enrollment.max_tries">
     Maximum tries reached. Please try again.
     <exit/>
   </catch>
 
   <catch event="error.noauthorization">
     Maximum phrases enrolled.
     <exit/>
   </catch>
 
   <catch event="noinput">
     <prompt> In the noinput handler </prompt>
     <reprompt/>
   </catch>
 
   <!-- Prompts for a phrase to be enrolled.                          -->
   <!-- Executes this item at least twice to get 2 consistent         -->
   <!-- samples for the phrase; that value is controlled by.          -->
   <!-- minconsistencies. The grammarname and speakeridexpr uniquely  -->
   <!-- identify an enrollment grammar. The phraseidexpr uniquely     -->
   <!-- identifies a phrase in enrolled grammar and is returned       -->
   <!-- when recognized against the enrollment grammar.               -->
 
   <bevocal:enroll name="en1" 
       minconsistencies="2" maxtries="4"
       grammarname="ADDRESSBOOK" speakeridexpr="'speaker10'"
       phraseidexpr="'tom'" type="audio/wav">
     <prompt count="1"> Say a name </prompt>
     <prompt count="2"> Say the name again. </prompt>
     <prompt count="3"> Please say the name again. </prompt>
 
     <filled>
       The enrolled phrase is <value expr="en1"/>
     </filled>
   </bevocal:enroll>
 
   <bevocal:enroll name="en2"
       minconsistencies="2" maxtries="4"
       grammarname="ADDRESSBOOK" speakeridexpr="'speaker10'"
       phraseidexpr="'jackson'" type="audio/wav">
     <prompt count="1"> Say a name </prompt>
     <prompt count="2"> Say the name again. </prompt>
     <prompt count="3"> Please say the name again. </prompt>
 
     <filled>
       The enrolled phrase is <value expr="en2$.enrollAudio"/>
     </filled>
   </bevocal:enroll>
 
 </form>
 </vxml>

And a form that uses that enrolled grammar.

 <?xml version="1.0" ?>
 <!DOCTYPE vxml PUBLIC "-//BeVocal Inc//VoiceXML 2.0//EN"
 "http://cafe.bevocal.com/libraries/dtd/vxml-bevocal.dtd">
 
 <vxml version="2.0" xmlns:bevocal="http://www.bevocal.com/">
 
 <link next="addressbook.vxml">
   <grammar>
     #ABNF 1.0;
     root $abook;
     $abook = address book;
   </grammar>
 </link>
 
 <form id="recognize_names">
 
 <field name="f1">
   Let's recognize the enrolled names. 
   Say one of the enrolled names
   <grammar>
     <![CDATA[
       #ABNF 1.0;
       root $call;
       $call= [call] $<enrolled:/ADDRESSBOOK?speaker=speaker10>
       [on|at] [his|her|its|else] [home|work|cell] [phone];
     ]]>
   </grammar>
   <filled> 
     Calling <value expr="f1"/>
     Thanks for using address book. Good Bye.
   </filled>
 </field>
 
 </form>
 </vxml>

[Show Frames] [FIRST] [PREVIOUS] [NEXT]

Property	Description
`clash`	The number of clashes that occurred during enrollment
`clashedPhraseIds`	The existing phrase IDs that clashed with the enroll utterance.
`enrollAudio`	The audio data from one of the consistent utterances. This is the same audio data that is stored in the input variable.
`numConsistentUtterances`	The number of consistent utterances collected for this enrollment

Parents	Children
`<form>`	`<audio>` `<catch>` `<enumerate>` `<error>` `<filled>` `<grammar>` `<help>` `<link>` `<noinput>` `<nomatch>` `<option>` `<prompt>` `<property>` `<value>`

Exception	Description
`error.enrollment.retries`	The system collected `maxtries` utterances and still could not achieve a consistent model of the phrase being enrolled.
`error.enrollment.clash`	The utterances that were collected clash with those for another phrase already enrolled in this model.
`error.noauthorization`	Maximum number of phrases enrolled into the grammar. For a Café developer, the enrolled grammar is limited to 10 phrases.
`noinput`	No speech was heard before the time specified by the `timeout` attribute on the last queued prompt (or by the timeout property) elapsed.