Motorola VoxML 1.0 user guide

VoxML 1.0 Language Reference

Revision 1.0

Motorola, Inc.

Consumer Applications and Services Division 55 Shuman Blvd, Suite 600 Naperville, IL 60563 USA

Contents

1. An Introduction to VoxML 1.0

Overview..............................................................................................1

What is VoxML.............................................................................1

Purpose of this Document..............................................................1

Structure of a VoxML Document..........................................................2

DIALOGs and STEPs....................................................................2

The Basic Elements .......................................................................3

Other Reference Documentation...........................................................4

VoxML 1.0 Application Development Guide .................................4

2. VoxML 1.0 Element Reference

ACK Element.......................................................................................5

AUDIO Element...................................................................................7

BREAK Element..................................................................................8

CANCEL Element................................................................................9

CASE Element.....................................................................................11

CLASS Element...................................................................................12

DIALOG Element ................................................................................14

EMP Element.......................................................................................15

ERROR Element..................................................................................16

HELP Element .....................................................................................18

INPUT Element....................................................................................20

INPUT Element : Type DATE.......................................................21

INPUT Element : Type DIGITS.....................................................22

INPUT Element : Type GRAMMAR .............................................23

INPUT Element : Type HIDDEN...................................................24

INPUT Element : Type MONEY ...................................................25

INPUT Element : Type NONE.......................................................26

INPUT Element : Type NUMBER.................................................27

INPUT Element : Type OPTIONLIST ...........................................28

INPUT Element : Type PHONE.....................................................29

INPUT Element : Type PROFILE..................................................30

INPUT Element : Type RECORD..................................................31

INPUT Element : Type TIME........................................................33

October 1998 VoxML 1.0 Language Reference i

INPUT Element : Type YORN.......................................................34

OPTION Element.................................................................................35

OPTIONS Element...............................................................................37

OR Element..........................................................................................38

PROMPT Element................................................................................39

PROS Element .....................................................................................40

RENAME Element...............................................................................41

RESPONSE Element............................................................................42

STEP Element......................................................................................44

SWITCH Element ................................................................................45

VALUE Element..................................................................................46

3. Appendices

Appendix A - VoxML 1.0 Document Type Definition...........................47

Appendix B - Vcard Profile Names and Subtypes..................................49

October 1998 VoxML 1.0 Language Reference ii

Overview

An Introduction to VoxML 1.0

Overview

1. An Introduction to VoxML 1.0

Part of the reason that the World Wide Web has been so popular is the relative ease with which authors can create content using HTML. For all its faults, HTML has served its purpose as a vehicle for the presentation of rich text as well as images, hypertext links, and simple GUI input controls.

VoxML offers the same ease of production to voice applications. In one sense, VoxML offers the same building blocks as HTML: text (which is read via textto-speech), recorded sound samples (analogous to images), navigational controls, and input controls.

However, writing a voice application is very different from writing a GUI application, and thus the structure of VoxML is very different from HTML. Here are some examples of the differences:

• HTML specifies a two-dimensional layout, whereas VoxML specifies a

“layout” in the time dimension only.

• HTML is designed and displayed in whole-page units, while VoxML is

designed and delivered in whole-dialog units, but presented in much smaller units, called steps.

• A single HTML page often presents the user with dozens of options, which

would overwhelm the user of a voice application. In general, voice applications should limit the number of options available at a given step in the dialog to ease the burden on the user’s short-term memory and to improve the performance of the speech recognition.

What is VoxML

VoxML is based on XML. As such, VoxML follows all of the syntactic rules of XML, with semantics that support the creation of interactive speech applications. For more information on the exact structure of the language with respect to XML, see the VoxML 1.0 DTD (Document Type Definition) which is available in Appendix A.

Purpose of this Document

This document serves as the official language reference for VoxML 1.0. It contains information on the syntax of the elements and their attributes, example usage, the structure of VoxML documents (or DIALOGs), and pointers to other reference documentation that may be helpful when developing applications using VoxML.

This document is intended for VoxML application developers.

October 1998 VoxML 1.0 Language Reference 1

Structure of a VoxML Document

VoxML documents have a hierarchical structure, in which every element (except the DIALOG element) is contained by another element. In contrast to HTML, there is a strict containment relationship enforced by the language, so there can be no ambiguity as to which element contains which.

DIALOGs and STEPs

The two most fundamental elements in VoxML are the DIALOG element and the STEP element. These elements provide the basic structure of a VoxML application.

The DIALOG element defines the scope of a VoxML document. All other VoxML elements are contained by the DIALOG element. In normal cases, one can equate a DIALOG to a file, in much the same way that there is one HTML element per file when developing HTML-based applications.

The STEP element defines a state within a DIALOG, or to say it another way, the STEP element defines an application state.

An Introduction to VoxML 1.0

Structure of a VoxML Document

Together the DIALOG element and the associated STEP elements define a state machine that represents an interactive dialogue between the application and a user. When the VoxML voice browser interprets the VoxML document, it will navigate through the DIALOG to different STEPs as a result of the user’s responses.

Here is a simple VoxML example, which has 1 DIALOG and 2 STEPs.

1 <?xml version="1.0"?> 2 <DIALOG> 3 <STEP NAME="init"> 4 <PROMPT> Please select a soft drink. </PROMPT> 5 <HELP> Your choices are coke, pepsi, 7 up, 6 or root beer. </HELP> 7 <INPUT TYPE="optionlist" NAME="drink"> 8 <OPTION NEXT="#confirm"> coke </OPTION> 9 <OPTION NEXT="#confirm"> pepsi </OPTION> 10 <OPTION NEXT="#confirm"> 7 up </OPTION> 11 <OPTION NEXT="#confirm"> root beer </OPTION> 12 </INPUT> 13 </STEP> 14 <STEP NAME="confirm"> 15 <PROMPT> You ordered a <VALUE NAME="drink"/>. 16 </PROMPT> 17 </STEP> 18 </DIALOG>

When this VoxML document is interpreted, the voice browser will begin by executing the STEP called “init”. The user will hear the text contained by the PROMPT element. If the user were to ask for “help” before making a selection, the user would hear the text contained with the HELP element. After the user makes a selection, the voice browser will execute the STEP named “confirm”, which will simply read back the user’s selection and then exit the application.

October 1998 VoxML 1.0 Language Reference 2

An Introduction to VoxML 1.0

Structure of a VoxML Document

There are a few important points to be made after looking at this first code example. First, you will notice that line 1 of the source code contains the XML declaration string, which is required to be the first line of all VoxML documents.

Also, STEPs in a VoxML application are executed based on the user’s responses not on the order of the STEPs within the source file. Although the definition of the “init” STEP appears on line 3 and the definition of the “confirm” STEP appears on line 14, the order in which they are defined has no impact on the order in which the voice browser navigates through them.

Lastly, the line numbers shown in the example listing are not part of the source code. They are shown only to make referencing the code simpler.

The Basic Elements

VoxML contains a lot of elements, which provides the application developer with a lot of flexibility and power in the language. Section 2 of this document describes these elements in detail.

There are, however, a few elements that are used in almost every DIALOG that you will write. These basic elements are found in the example on the previous page. They are DIALOG, STEP, PROMPT, HELP, and INPUT. If you are new to VoxML, you should familiarize yourself with these basic elements before progressing to the other, less frequently used elements.

October 1998 VoxML 1.0 Language Reference 3

Other Reference Documentation

October 1998 VoxML 1.0 Language Reference 4

ACK Element

VoxML 1.0 Element Reference

ACK Element

2. VoxML 1.0 Element Reference

This section describes the VoxML elements, their attributes, and their syntax. Examples are provided to help show common usage of each element.

The ACK element is used to acknowledge the transition between STEPs, usually as a result of a user response. While an application developer could create additional STEPs that were used to acknowledge the user’s response, the ACK element provides an easier way to specify the common sorts of acknowledgements.

An ACK element can be contained within a STEP or a CLASS element.

Syntax

Attributes

Attribute Name Allowed Values

CONFIRM YORN *

BACKGROUND Y

N *

REPROMPT Y

N *

October 1998 VoxML 1.0 Language Reference 5

VoxML 1.0 Element Reference

ACK Element

Examples

1 <STEP NAME="card_type"> 2 <PROMPT> 3 What type of credit card do you have? 4 </PROMPT> 5 <INPUT NAME="type" TYPE="optionlist"> 6 <OPTION NEXT="#exp"> visa </OPTION> 7 <OPTION NEXT="#exp"> mastercard </OPTION> 8 <OPTION NEXT="#exp"> discover </OPTION> 9 </INPUT> 10 <ACK CONFIRM="YORN" REPROMPT="Y"> 11 I thought you said <VALUE NAME="type"/> 12 <BREAK/> Is that correct? 13 </ACK> 14 </STEP>

In this rather complex example, the ACK element is used to confirm the user's choice of credit card. When this code is interpreted by the VoxML voice browser, it will speak the text of the PROMPT element using text-to-speech technology, wait until the user responds with “visa”, “mastercard”, or “discover”, and then ask the user to confirm the type of card was recognized correctly.

If the user answers “yes” to the ACK, the browser will proceed to the STEP named “exp”. If the user answers “no” to the ACK, the text of the PROMPT will be read again, and the user will be allowed to make his or her choice again — the browser re-enters the STEP as if for the first time.

October 1998 VoxML 1.0 Language Reference 6

AUDIO Element

VoxML 1.0 Element Reference

AUDIO Element

The AUDIO element specifies an audio file that should be played. AUDIO elements can be used as an alternative anywhere that you would read text to the user.

An AUDIO element can be contained within a PROMPT, EMP, PROS, HELP, ERROR, CANCEL, or ACK element.

Syntax

Attributes

Attribute Name Allowed Values

SRC audio file URL

Examples

1 <PROMPT> 2 At the tone, the time will be 11:59 p m 3 <AUDIO SRC="http://localhost/sounds/beep.wav"/> 4 </PROMPT>

The above code is a simple example of an audio sample included in a PROMPT element. When interpreted by the VoxML Voice Browser, this code will speak the text from line 2 using text-to-speech technology, and then play the WAV file “beep.wav” as specified by the AUDIO element on line 3.

For a description of the audio formats supported by the voice browser, see the release notes for the VoxML SDK.

October 1998 VoxML 1.0 Language Reference 7

BREAK Element

VoxML 1.0 Element Reference

BREAK Element

The BREAK element is used to insert a pause into content to be presented to the user. BREAK elements can be used anywhere that you would read text to or play audio samples for the user.

The BREAK element can be contained within a PROMPT, EMP, PROS, HELP, ERROR, CANCEL, or ACK element.

Syntax

Attributes

Attribute Name Allowed Values

MSECS milliseconds (integer)

SIZE NONE

SMALL MEDIUM * LARGE

Examples

1 <PROMPT> 2 Welcome to Earth. <BREAK MSECS="250"/> 3 How may I help you? 4 </PROMPT>

The code shown above illustrates the use of the BREAK element with the MSECS attribute, inside a PROMPT. When interpreted by the VoxML voice browser, this code would speak the text “Welcome to Myosphere.”, pause for 250 milliseconds, and then speak the text “How may I help you?”.

1 <PROMPT> 2 Welcome to Earth. <BREAK SIZE="medium"/> 3 How may I help you? 4 </PROMPT>

As an alternative to specifying an exact number of milliseconds, an application developer can use the SIZE attribute of the BREAK element to control the duration of the pause.

The actual duration of “small”, “medium”, and “large” are system defined, and may change. Use the MSECS attribute if a specific duration is required.

October 1998 VoxML 1.0 Language Reference 8

CANCEL Element

The CANCEL element enables the application developer to define the behavior of the VoxML application in response to a user’s request to cancel the current PROMPT. If the application developer does not define the behavior of CANCEL for a given STEP, the system default behavior will be used.

The default behavior for the CANCEL element is to stop the PROMPT, and then process any interactive INPUTs.

The CANCEL element, like the HELP element, can be invoked through a variety of phrases. The user may say only the word “cancel”, or the user may say “I would like to cancel, please.” In either case, the CANCEL element will be interpreted.

The CANCEL element can be contained within a STEP or a CLASS element.

Syntax

VoxML 1.0 Element Reference

CANCEL Element

Attributes

Attribute Name Allowed Values

NEXT next step URL

NEXTMETHOD GET *

POST

October 1998 VoxML 1.0 Language Reference 9

VoxML 1.0 Element Reference

CANCEL Element

Examples

1 <STEP NAME="report"> 2 <CANCEL NEXT="#traffic_menu"/> 3 <PROMPT> Traffic conditions for Chicago, 4 Illinois, Monday, May 18. Heavy 5 congestion on ... </PROMPT> 7 <INPUT TYPE="optionlist"> 8 <OPTION NEXT="#report"> repeat </OPTION> 9 <OPTION NEXT="#choose"> new city </OPTION> 10 </INPUT> 11 </STEP>

The code on line 2 illustrates the use of the CANCEL element to specify that when the user says “cancel”, the browser should proceed to the STEP named “traffic_menu”, instead of the default behavior, which would be to simply stop the PROMPT from playing and wait for a user response. Users can also interrupt the PROMPT by speaking valid OPTION. In this example, the user could interrupt the PROMPT and get the traffic conditions for a different city by saying “new city”.

October 1998 VoxML 1.0 Language Reference 10

CASE Element

VoxML 1.0 Element Reference

CASE Element

The CASE element is used to define the flow of control of the application, based on the values of internal VoxML variables.

The CASE element can be contained by a SWITCH element, or by an INPUT element, when using an INPUT type that collects a single value (i.e. DATE, DIGITS, MONEY, PHONE, TIME, YORN).

Syntax

Attributes

Attribute Name Allowed Values

VALUE literal value

NEXT next step URL

NEXTMETHOD GET *

POST

Examples

1 <SWITCH FIELD="pizza"> 2 <CASE VALUE="pepperoni" NEXT="#p_pizza"/> 3 <CASE VALUE="sausage" NEXT="#s_pizza"/> 4 <CASE VALUE="veggie" NEXT="#v_pizza"/> 5 </SWITCH>

The code on lines 2-4 shows the use of the CASE element within the SWITCH element. In this example, the CASE elements are used to direct the browser to different URLs based on the value of the VoxML variable “pizza”.

October 1998 VoxML 1.0 Language Reference 11

CLASS Element

VoxML 1.0 Element Reference

CLASS Element

The CLASS element defines a set of elements that are to be reused within the context of a DIALOG. The definitions of a given CLASS may be inherited by STEPs or other CLASSs. The CLASS element allows the application developer to define a set of elements once, and then use them several times. The CLASS element is often used to define the default behavior of ERROR, HELP, and CANCEL, within a given DIALOG.

The CLASS element can be contained by a DIALOG element only.

Syntax

<CLASS NAME="value" [PARENT=" value "] [BARGEIN=" value "] [COST="value"] > VoxML </CLASS>

Attributes

Attribute Name Allowed Values

NAME identifier

PARENT identifier

BARGEIN Y *

COST integer

The COST attribute is a platform-dependent feature. A given browser implementation may or may not

support each platform-dependent feature. October 1998 VoxML 1.0 Language Reference 12

VoxML 1.0 Element Reference

CLASS Element

Examples

1 <CLASS NAME="simple"> 2 <HELP> Your choices are <OPTIONS/> </HELP> 3 <ERROR> I did not understand what you said. 4 Valid responses are <OPTIONS/> </ERROR> 5 </CLASS> 6 7 <STEP NAME="beverage" PARENT="simple"> 8 <PROMPT> Please choose a drink. </PROMPT> 9 <INPUT NAME="drink" TYPE="optionlist"> 10 <OPTION NEXT="#food"> coke </OPTION> 11 <OPTION NEXT="#food"> pepsi </OPTION> 12 </INPUT> 13 </STEP> 14 15 <STEP NAME="food" PARENT="simple"> 16 <PROMPT> Please choose a meal. </PROMPT> 17 <INPUT NAME="meal" TYPE="optionlist"> 18 <OPTION NEXT="#deliver"> pizza </OPTION> 19 <OPTION NEXT="#deliver"> tacos </OPTION> 20 </INPUT> 21 </STEP>

The code shown on lines 1-5 illustrates the use of the CLASS element to define a HELP element and an ERROR element that will be used in several STEPs within this DIALOG.

The code on lines 7 and 15 illustrates the use of the PARENT attribute on the STEP element to refer to the CLASS element, and therefore inherit the behaviors defined within it.

When interpreted by the VoxML voice browser, the STEPs defined on lines 713 and lines 15-21 will behave as if the HELP and ERROR elements that are defined in the CLASS were defined explicitly in the STEPs themselves.

October 1998 VoxML 1.0 Language Reference 13

+ 37 hidden pages