WOZ - Wizard of Oz - v2.31

This software is copyright © 2001-09 by Richard Breuer.

 If you find a bug, please make sure you use the latest version from http://www.softdoc.de/woz.
If this is the case, pls contact richard.breuer@gmx.de

Date Version Changes
May 16, 2009 2.31 pl-PL is now supported, minor bugfixes in the VoiceXML part
Dec 20, 2008 2.30 Prompts can now be played in the sample call view; VXML export now works both on Deutsche Telekom VWP and Voxpilot 3.6 platform
July 5, 2008 2.29 More languages (fr-fr, en-uk), fixed some UTF-8 issues when testing with Arabic
May 4, 2008 2.28 (1) New function to fill empty fields of prompts, questions, concepts, or sample calls from another object of the same type (2) improved import of sample calls and designs from sample calls (3) improved object selections in sample calls
Apr 20, 2008 2.27 (1) Added a global VXML variable playttsprompts that controls the playback of textual prompts. Default is true. This is usefil (a) during development when you do not yet have audio prompts and (b) if the audio prompts are in a foreign language that you cannot understand. For me, that was Czech ;-) (2) Added another global VXML variable playvariabletts which that controls the TTS playback of variable prompts containing some kind of inline VXML code (3) added VXML export to the default toolbar.
Apr 13, 2008 2.26 (1) Computation of double phrases in a phrase list to indicate minimized recording efforts (2) 'Compact namespace' now works with sample calls and can be undone/redone. Note that ID's change -- you may not be able to reuse your exported prompt lists etc!
Apr 10, 2008 2.25 (1) Improved GML export, including prompt and question texts, and an explanation how to get a nice wallpaper with yED (see GML exports), (2) new function to automatically generate sample calls from the design
Apr 4, 2008 2.24 Fixed a bug in the handling of follow ups in VXML
Mar 28, 2008 2.23 (1) new functions improve the handling of standard audio filenames (2) worked on the UTF-8 capabilities (3) improved language settings for VoiceXML (4) some bugfixes
Mar 19, 2008 2.22 (1) Support for VXML blocks (prompts with VXML comment fields) (2) Fixed an issue when comments were exported to VXML that contain "-->". (3) support for {INLINE} in texts
Jan 05, 2008 2.21 (1) fixed a scrolling bug in the miniimage (2) audio paths in the runtime frontend are now the same as in the admin frontend (3) WOz window can now be maximized to screen size (4) the split screen in the runtime frontend can be adjusted (5) generated VoiceXML audio file names match the configuration
Nov 25, 2007 2.20 (1) bugfix for the "reachable" flags (2) configurable audio file names
Oct 27, 2007 2.19 (1) new attribute "always reachable" for prompts and questions (2) fixed a small bug in the VXML export
Jul 15, 2007 2.18 New OSDM properties export; bugfix for the handling of end states in the runtime frontend
Apr 09, 2007 2.17 Some bugfixes; new export of embedded prompts and random prompt playing to VoiceXML; question for start of application after exporting GML file. For the random prompt playing, I needed to make several changes to the skeleton file handling functions. Please note you cannot use older skeleton files for VXML, XML, GML, HTML, XHMI, and VDX without adapting them to the new format. Pls contact me if you need to know more.
Mar 25, 2007 2.16 New GML export for layouters like yEd
Feb 19, 2007 2.15 Removed Delete from the Edit menu, removed the Nuance RTF skeleton files (they were no longer up to date); new graphical mini display in the runtime frontend; fixed some minor issues in the docs
Feb 13, 2007 2.14 New: end state attribute for prompts and questions; fixed some minor issues in the docs
Jan 19, 2007 2.13 Fixes: Bug creating concepts when sync'ing sample calls; Changes: (1) Use of a builtin number grammar in en-US.woz for illustration purposes; (2) {VALUE} and {REPROMPT} can also be lower or mixed case
Jan 07, 2007 2.12 Fixes (1) for empty prompts in VoiceXML exports, (2) for BNF grammars using the + operator. New functions: (1) {REPROMPT} can be used in a question to repeat the initial prompt in event handlers, (2) the synchronisation of sample calls can create new concepts using the caller utterance, (3) in the synchronisation of sample calls, connection attributes are created as valid ECMA script expressions now, (4) reworked the RTF output, which contains barge-in flags now
Dec 17, 2006 2.11 Fixed bugs (1) loading old (project version 1.0) projects (2) deleting concepts (3) using special characters, e.g. spaces, in semantic SRGS grammar results (4) ignore empty conditions (5) switched to GIF, after having some problems displaying PNG colors correctly; Enhancements: (1) removed max size from design window; (2) allowed VoiceXML branches also after prompts; (3) enabled XML export again, a current DTD is included; (4) BNF grammars can be validated before exporting to VoiceXML
Dec 03, 2006 2.10 Fixed a bug in exports (certain texts could corrupt the export results); new PNG export; HTML export includes an image 
Nov 25, 2006 2.09 Added sound file references and logging to the VoiceXML skeleton file; modified the reference to the built-in grammar; support for context sensitive help command in VoiceXML
Nov 18, 2006 2.08 More VoiceXML improvements: promptLanguage is set, confirmConfidence controls whether confirmation questions are asked; moved all VoiceXML configurations in woz.ini to a separate section [VoiceXML]; confirmation questions are only generated if they are defined; included a complete VoiceXML example project en-US.woz; moved the skeleton files into a separate subdirectory under resources
Nov 11, 2006 2.07 Support for values from other questions: {VALUE:Qxxx}; export condition attributes as VXML conditions (see here)
Oct 31, 2006 2.06 Bugfixes in BNF2SRGS (Umlaute are supported now); new switches for Barge-In of prompts - in the runtime frontend this disables the STOP buttons for non barge-in prompts; support for {VALUE} in confirmation prompts; added ECMA tags to BNF grammars
Oct 22, 2006 2.05 The docs are available online in the web and from the Help menu; Built-in grammar converter (BNF to SRGS); possibility to reuse woz.ini files from older versions.
Sep 26, 2006 2.04 (Finally) VoiceXML export; RTF and sample calls export possible without file names; new switch Files.showExport; possibility to export sample calls audio; small changes in the docs
Sep 16, 2006 2.03 Introduced sample calls; create project file backup when saving
Aug 20, 2006 2.02 Additional textual representation; inserted some <Wikipedia> links; connections can be hidden
Aug 18, 2006 2.01 Minor changes in the documentation; bugfixes (connections removal, group connections); visualization of end states
July 23, 2006 2.00 Major changes: Graphical user interface, Undo/Redo functions, Attributed Connections

For version 1 change history, click here

This document gives some hints about the WOZ utility. There's definitely some more documentation to be done... First, some legal stuff.

The WOZ tool is distributed as freeware. You have to pay no money for it (if you did, you were fooled). If you like, please drop me a mail that you are evaluating or using it, so I can see if it is of any use. The drawback of freeware is that you have no warranty at all. If you run WOZ, do it on your own risk and responsibility. I do not promise any support or help. I do not even guarantee that WOZ doesn't harm your computer or other programs. WOZ is a result of my spare time, so just please accept it as it is.

However, if I am asked for help / changes / fixes in a friendly way, we'll see :-)

WOZ is not a professional product. You use it on your risk!


WOZ - Wizard of Oz
    1. About Wizard of Oz Tests
        1.1 About Multimodal Design
    2. Installation and Configuration
        2.1 Tcl/Tk
        2.2 WOZ
        2.3 Logging
        2.4 Sample projects
    3. Usage
        3.1 Projects (.woz)
        3.2 Window layout
            3.2.1 Prompts
            3.2.2 Questions
            3.2.3 Concepts
            3.2.4 Connections
            3.2.5 Sample Calls
        3.3 Controls
        3.4 Audio and Picture File Handling
            3.4.1 General Explanation
            3.4.2 Examples
            3.4.3 TTS Configuration
        3.5 VoiceXML Export Features
            3.5.1 BNF to SRGS Grammar Conversion
            3.5.2 Export of VoiceXML Conditions
            3.5.3 Prompts in VoiceXML
            3.5.4 Context Sensitive Help
            3.5.5 VoiceXML Logging Tags
            3.5.6 Tested Platforms
            3.5.7 INLINE Code
        3.6 GML Exports
    4. The Menu
        4.1 The File Menu
        4.2 The Edit Menu
        4.3 The View Menu
        4.4 The Run Menu
        4.5 The Help Menu
    5. The Runtime Module
        5.1 Usage
        5.2 Logging
        5.3 Dialog Logging
    6. Data Exchange
        6.1 Export Facilities
        6.2 Import Facilities
    7 Configuration
        7.1 [Common]
        7.2 [Windows], [Unix], [Macintosh]
        7.3 [Files]
        7.4 [Graphics]
        7.5 [Toolbar]
        7.6 [VoiceXML]
        7.7 [Exports]
    8. FAQ
    9. Known Problems
    10. Credits
    Appendix: Version 1 Change History

1. About Wizard of Oz Tests

I leave this more or less to the experts. Only some few words about these tests:

<WOZ tests> are useful in designing <dialogue systems>, which are driven by human speech , using <Speech Recognition> and sometimes <Speech Synthesis>. In the test scenario one person takes the role of the wizard, a second the role of a caller. Finally, one person just listens and writes a session protocol. My tool is designed to support the wizard at his task of finding the correct reaction of a system to a certain user input. This is normally done with the help of some pieces of paper. The WOZ tool provides the wizard

There are two principle ways to start designing your applications. You can either start by creating and connecting prompt and question objects, or by writing down some sample calls you have in mind, and generate a design from these calls. Finally, the design can be exported to various formats and imported into other systems. You can also easily create a VoiceXML prototype from your design.

1.1 About Multimodal Design

In 2005, we at Nuance discussed how WOz could be used to design and test <multimodal> applications as well. Multimodal applications are special because the system not only reacts with voice, but additionally with visual feedback. The idea to incorporate this in WOz (without the need to change the tool - which is especially attractive to me :-)) is to store graphic files, e.g. <PNG> images, in the directory prompts (or a different one, if you configure that)..

One thing must be solved still: currently, the pictures are displayed on the computer used for the WOz session. Under Unix, it would be easy to use a different display, under Windows this is still an open point. I wait for the first real project to address this issue.

2. Installation

Currently, I only describe the Windows installation. WOz runs under Unix as well, though. And probably even better - but who cares... Please note that version 2 has not been tested under Unix  yet.

2.1 Tcl/Tk

WOZ is programmed in <Tcl/Tk> and needs this software to be executed. Therefore, install Tcl/Tk version  8.4 or higher first. Tcl/Tk is available for Windows e.g. at http://www.activestate.com/. Get installation exe and execute it under Windows. The installation is straightforward. Reboot the machine afterwards. BTW, most Linux distributions contain Tcl/Tk as a package already. I did not test the latest WOz version under Linux yet.

Some packages are also necessary (but already compiled into the ActiveState version): "snack" to play audio files, and "iTcl" to run the BNF to SRGS converter created with the great YETI package.

Since ActiveState TCL 8.5, some required packages are no longer part of the Tcl/Tk package. You may need to start tcl/bin/wish85 once and enter the following commands, while being connected to the internet:

teacup install Itcl
teacup install snack
teacup install Img
teacup install tcom

2.2 WOZ

You can download WOZ from www.softdoc.de/woz. Please contact me for older versions.

WOZ comes in a ZIP file. Open the archive with WinZip (Linux: gzip). You get that e.g. under www.winzip.com. Unpack the archive to a directory of your choice. I recommend \Program Files\WOZ on your boot drive. Make sure that all subdirectories are created.

After the installation, you start WOz by double clicking woz.tcl!

2.3 Logging

Whenever you would like to see the actions performed in the WOZ tool, you may check the log file woz.log in the installation directory. It contains all important runtime messages.

060723053644 WOZ started: Version 2.03 Copyright (c) 2001-06 Richard Breuer
060723053644 opened project ./project/hotel.woz
060723053651 Analysis: WOZ DATA ANALYSIS~
060723053651 Analysis: WARNING: Audio file hotel/no_song.wav missing in P003.p_prompt
060723053651 Analysis: WARNING: Picture file hotel/no_pic.gif missing in P003.p_prompt
060723053651 Analysis: ~INFO: Everything's fine.
060723053654 exported project (WOZ session) to C:/Program Files/woz200/export/hotel.tcl
060723053657 WOZ stopped -------------------------------------------------------------------------------

2.4 Sample Projects

WOz comes with some sample projects:

File name Contents VoiceXML Recorded Prompts Rich Feature Set
hotel.woz Hotel reservation application, open question -- X X
movies.woz Sample movie information system -- X (X)
demo.woz Small connection demo for doc purposes -- -- --
en-US.woz Simple VoiceXML application X -- --
de-DE.woz Simple German VoiceXML application X -- --

3. Usage

The following explanations refer to the English version of the front-end. We assume the default settings, color scheme, and toolbar as well.

After you start WOZ, a splash screen comes up. You can get that screen whenever you like with the Help / About menu command :-) <ESC>, <Return>, or a click on the "Close" button will close the splash screen.

3.1 Projects (.woz)

All information is stored in so-called project files with the default extension .woz in the default directory export under WOZ. There are some demo projects already prepared for you. Project files are <ASCII> files. You will find them hard to read, however. The default project loaded at startup time is hotel.woz. You can change this default by modifying the woz.ini file (see chapter 7). Open a project with the menu command File / Open or the appropriate toolbar command. The Open window will look a bit different under different operating systems (the picture below is taken from the Windows version).

3.2 Window layout

WOZ will display all prompts and questions in the current project as graphical boxes on the left hand side, and as text on the right hand side. The name of the project can be modified in the entry field beside the toolbar. At the right hand side of the name entry field, a button allows choosing the language for prompts and grammars. This becomes important when generating VoiceXML code from the design. The label of the button is the current language setting, e.g. en-US.

main.png (31321 Byte)

Different colors are used for start prompt, normal prompts, and questions. There are three more objects: connections, sample calls, and concepts. Connections are shown as arrows, sample calls and concepts are not visible in the graphical display, only in the text list. 

Normal Prompts These are text messages in a dialog system. They are just replayed to the caller.
Start Prompt This is the first prompt in the application. Note: If your application starts with a question, you must include an empty dummy prompt to have a starting point.
Questions These are the interactive part of an application. The wizard reads the initial prompt and waits for the user to say something. There may be several error handlers attached to a question, as well as a prompt for context sensitive help.
Concepts Build the set of entries your system understands. E.g., a "yesno" prompt typically indicates that your system understands yes, no, and variants of these at a certain point of the dialog. By default, the contents of a concept should be a BNF style grammar, which is then automatically converted to SRGS (XML style).
Connections These objects connect prompts and questions with each other. They are always directed, meaning they lead from one object to another. Objects may be connected with themselves, e.g. if a question is directly revisited. If a connection has an attribute (normally a condition), it is shown in blue, otherwise in black.
Sample Calls Each sample call is a sample call using the designed objects to show a sample application usage. Sample calls are the best method to create a first impression of a call. Typically, sample calls for novice, normal, and experience callers are used in speech application designs. Sample calls in WOz can be created after the design, or the design can be started by defining sample calls and derive prompts, questions, and connection from these calls. If the text for a sample call is red instead of the normal black, there are differences to the design. Try the context menu command Analyze on that call to find out more. You can use Edit / Sync Sample Calls to synchronize the call with the design. With Edit / Generate Sample Calls you can generate those calls automatically form the current design.

corners.png (716 Byte)Questions, Prompts, Sample Calls, and Concepts are assigned a unique Id <type><number> by the system. Type is P(rompt), Q(uestion), S(sample call) or C(oncept). Examples are P006, Q002, S002, or C003 for a prompt, a question, a sample call, or a concept respectively. All other information is optional. End states (which have no follow up state) are marked with a small black triangle in the lower right corner. If a question or prompt contains VXML code in the comment field, a small blue triangle in the lower left corner is displayed.

The allocation of the screen to graphical and text display can be modified by shifting the panel button.

You can control some functions with the mouse in the graphical representation.


Event Action
Move the mouse If you move the mouse above an abject, this will become active, indicated by a different color. If you move it over a connection, the arrow will be highlighted. This is convenient because sometimes you may not see where a connection leads to.
Double click an object If you double click the left mouse button on an object, the properties dialog will be opened. See below for more information on these dialogs. You can leave the dialog by clickling Apply or Cancel or pressing ESC (=Cancel). If there are changes, you will  be warned. One special case occurs, if there are connections between two objects in both directions. In this case, the zwo properties dialogs are opened after each other.
Right click This opens a context menu. The contents of the menu depends on the current location. There are four possible locations. The meaning of the menu options should be self explanatory. In 2.28 a function to fill empty fields ("Fill from") has been added to the context menus of prompts, questions, concepts, and sample calls. This allows e.g. to quickly copy event handler prompts from one question to another.
Location Context Menu
Window Background
Sample call (in 2.04 "Export Audio..." has been added)
Drag a prompt or  question By left clicking one of these objects, and moving the mouse somewhere keeping the button pressed, you change the position of the object on the screen. If you defined an area before using the middle mouse button, the movement will be applied to all objects touched by the area. Connections are repositioned automatically.
Drag using middle mouse button By this, you can create an area affecting the movement of objects, as described above. In the picture, P004, Q001, and Q004 are touched by the area.

In the textual representation, double clicking on an object opens the respective properties dialog. Some other commands are also available by clicking the right mouse button. Let's take a closer look at the property dialogs of prompts, questions, concepts, and connections now:

3.2.1 Prompts

The prompt screen contains the following information:

Prompt text This information is read by the wizard.
Title The title ("ID") is a very short name of the prompt for later button texts.
Comment You may use this for later reference. It's a pretty good idea to memorize design considerations here.
Welcome Prompt This flag indicates whether the prompt is the first one of your system. WOz assumes that an application always starts with a prompt. If in reality it starts with a question, you must design an empty prompt upfront. There must be exactly one welcome prompt in a project.
Possible Followups Here, you can choose one or more prompts or questions, which may be played after the prompt. In the runtime module, these followups are buttons which allow you to navigate to the next system action. Alternatively, you can modify the follow ups graphically.
Predecessors Here, all objects are displayed which precede the current object in the dialogue.
Barge-In This switch allows designing prompts that can be interrupted by the caller (default) or not
End? An end prompt terminates the application. This will be considered in WOz tests and VoiceXML exports.
Always Reachable? A prompt that is always reachable will be available for the wizard in the runtime frontend in every dialog state. This can be used for global exits like operator announcements. This switch does not affect the graphical layout or the VoiceXML export.
VXML Code If this box is checked, the contents of the Comment field is exported to VoiceXML as a <block> of executable commands. The commands are executed after playing the prompt itself (which may be empty). As a special case, the VXML code of the (one) welcome prompt is rendered as global commands - perfect e.g. for declaring global variables.

When you insert a new prompt, WOz will initialize the text fields with the names of audio prompts, if the audioPrefix value in woz.ini is defined. This may safe typing time if you want to use recorded prompts later on. The file name prefix (hotel/ in the standard configuration) can be changed in the resource/woz.ini file (audioPrefix).

See here for details on audio and picture file handling.

3.2.2 Questions

The question screen contains the following information:

Initial Prompt This information is read by the wizard the first time the question is activated.
Title The title ("Arrival") is a very short name of the question for later button texts.
Comment You may use this for later reference. It's a pretty good idea to memorize design considerations here.
Recognizable Concepts Here, you can choose one or more concepts which are understood at that question.
Possible Followups Here, you can choose one or more prompts or questions, which may be played after the prompt. In the runtime module, these followups are buttons which allow you to navigate to the next system action. Alternatively, you can modify the follow ups graphically.
Retry 1..3 The retry handler texts define actions if the system does not understand the caller once, two, or three times in a row.
Timeout 1..3 These are timeout handlers for situations when the system detects no input at all.
Confirmation 1..3 You can as well specify different reactions for confirmations.
Context Help This prompt is normally initiated by the help concept.
Predecessors Here, all objects are displayed which precede the current object in the dialogue.
Barge-In These switches allow designing prompts and handlers that can be interrupted by the caller (default) or not
End? An end question terminates the application. This will be considered in WOz tests and VoiceXML exports.
Always Reachable? A question that is always reachable will be available for the wizard in the runtime frontend in every dialog state. This can be used for global exits like operator announcements. This switch does not affect the graphical layout or the VoiceXML export.
VXML Code If this box is checked, the contents of the Comment field is exported to VoiceXML as a <block> of executable commands. The commands are executed in the <filled> section of the question, after after the questions has been asked, the caller has answered, and the field value has been filled.

One general remark about the error and help prompts: WOz assumes that the original question is not repeated after nomatch, noinput, or help. This allows you to modify the wording of the question within the handler prompts. If you want to reuse the original text, you can embed {REPROMPT} in the text of an event handler. When you export the design, the initial text will be inserted here.

When you insert a new question, WOz will initialize the text fields with the names of audio prompts, if the audioPrefix value in woz.ini is defined. This may safe typing time if you want to use recorded prompts later on. The file name prefix (hotel/ in the standard configuration) can be changed in the resource/woz.ini file (audioPrefix).

See here for details on audio and picture file handling.

3.2.3 Concepts

The concept screen contains the following information:

Name Each concept should have a name to identify it later on.
Title The title ("Duration") is a very short name of the concept for later button texts.
Comment / Grammar You may use this to specify a grammar. Depending on the grammarStrategy setting in the ini file, WOz handles the contents of a grammar differently.

For <VoiceXML> or xHMI, a <W3C> grammar (<SRGS>) would be perfect for later reuse. If you are not going to create a prototype application by exporting something from WOZ, you can simply add some design considerations here.

Always Active An always active concept is included as possibility for each system question. You don't have to mention it over and over again in the Recognizable Concepts entry of each question. Typical examples for always active concepts are help and repeat.
Used By Here, all questions are displayed where the current concept is used in the dialogue. If the concept is always active, all questions will be listed here.

When you insert a new concept, the grammarStrategy switch decides what will be used as initial grammar contents.

3.2.4 Connections

The connection screen contains the following information:

Name The name of a connection is FROM > TO
Condition Here, you may document under which condition the connection between the two objects will be used. Example: Imagine you have a connection from Q001 to P001 and P002. Under condition you could documennt that the connection to P001 is used for X>5, the one to P002 for X<=4.

Please note that if you want to automatically export conditions as valid VoiceXML conditions, you need to enter a valid if condition. See here for more information.

3.2.5 Sample Calls

The sample call screen contains the following information:

Name The name of a sample call, e.g. "Newbie"
Comment This field allows you to write a design comment. Typically, you would like to write why you picked that particular call.
Dialog Turns

This list contains the turns of the call. A turn can either be a prompt or a question. You can find several buttons in the sample calls properties window:

Delete a dialog turn Undo last sample call operation
Shift a turn up in the call flow Redo last sample call operation
Shift a turn down in the call flow Undo all sample call operations
Create a new prompt at the end Undo all sample call operations
Create a new question at the end  

Prompt and question turns have a different layout.

By clicking on the prompt ID (here P004) you can choose a different prompt from the current design. You can also choose "Pnew" which means the prompt is new and not yet part of the design. Pnew will typically be used when you start the design with a sample call.

By clicking on the question ID (here Q002) you can choose a different question from the current design. You can also choose "Qnew" which means the question is new and not yet part of the design. Qnew will typically be used when you start the design with a sample call. By clicking on the subtype (here q_init) you can choose between initial prompt, handler, or context help of a question. A question has - other than a prompt - a caller section. This allows you to document the caller's utterance to that question. The subtype (here 'text') can also be 'dtmf' of 'noinput'.

If the text of a prompt or question is red instead of the normal black, it differs from the current prompt or question texts in the WOz design. You can change the text in a sample call independantly from the design of prompts and questions. Later, you can synchronize the calls with the design (Edit / Sync Sample Calls).

3.3 Controls

Besides typing any text you like into the respective fields, the following special controls are possible:

Left Arrow Scroll one character left
Right Arrow Scroll one character right
Control/Left Arrow Scroll one word left
Control/Right Arrow Scroll one word right
Control/Up Arrow Scroll to the begginng of a text field
Control/Down Arrow Scroll to the end of a text field
<Escape> Same as Cancel button. If there are changes, you will be warned.


<ESC> in texts will be replaced by ASCII 27 for TTS control.

3.4 Audio and Picture File Handling

3.4.1 General Explanation

In text fields with prompts and in the caller utterances of sample calls you can use expressions like [A:<name1>,<name2>,...] for audio files and [P:<name1>,<name2>,<name3>,...] for picture references may be used. Audio files can be played by pressing the play button (if the snack package of Tcl/Tk is installed), all picture files will be shown in the runtime frontend. If you mention more than one file, the files will be offered in a dialogue box for choosing.

If you enclose the file list in {} instead of [], the runtime frontend will randomly choose one of the files automatically.

If a text starts with a [] file name, this is considered the standard audio file name for the prompt. Standard audio file names can easily be added or removed using the dedicated functions in the Edit menu.

One special case is [A:TTS]. If a prompt contains this, TTS mode is switched on no matter whether it has been allowed. Another special symbol in TTS mode is [A:...], meaning that the wizard will be prompted for the string to output via TTS. If you append a string, this will be used as the default string in the text input field. Example: [A:...1-2-3-4] will make "1-2-3-4" appear (selected) in the text field. The actual output after the wizard's input will be logged separately.

In a question, {REPROMPT} will be replaced with the contents of the initial prompt of the question, when you export the design.

3.4.2 Examples

Let's make all that clearer using examples. In the following table WOz's reaction to some prompts is explained. We speak of TTS mode when SAPI TTS is used to play a prompt, record  mode if prerecorded mode is used. TTS mode is used if it is (a) installed and configured properly (see below) and (b) switched on in the Run menu. Currently, the two modes cannot be used together for one prompt.

Welcome to the Malibu Beach hotel reservation system! The wizard can read that prompt to the caller or use TTS mode to play this prompt.
Good morning.<esc>P4 Welcome! For TTS mode, <esc> is replaced by an escape character at runtime. For Nuance RealSpeak, ESC P4 means a long pause.
Welcome! [A:hotel/P001.p_prompt.wav,hotel/P001.p_prompt_hello.wav] In TTS mode, "Welcome" is played. In record mode, the wizard gets a selection dialog at runtime and needs to choose one of the sound files A:hotel/P001.p_prompt.wav and hotel/P001.p_prompt_hello.wav. The audio files are searched relative to the directory prompts under the WOz root. 
Welcome! {A:hotel/P001.p_prompt.wav,hotel/P001.p_prompt_hello.wav} As in the sample before, there is a choice between two prompts. This time, however, WOz chooses one of teham randomly ("random prompting")
[A:hotel/0.wav][A:hotel/1.wav][A:hotel/1.wav,hotel/2.wav][A:hotel/2.wav] If more than one audio file is used, the audio is concatenated seamlessly ("prompt concatenation"). If there are disambiguities as in the sample, those are resolved first, one after the other.
[A:TTS]This is always TTS, or silent [A:TTS] may be used to enforce TTS mode. If TTS is not available for technical reasons, no audio will be played. If TTS is only configured to be off, this config setting is overridden here.
[A:TTS]Your password is [A:...], dear [A:...Ricki] In TTS mode, [A:...] may be used to offer the wizard an entry field where he can enter a string at runtime that will be replayed. This allows the wizard to dynamically react on the caller's behaviour. The string after ... is used as a default contents of the string entry field. In record mode, ... is ignored.
Did you say {VALUE}? A special replacement is made, if {VALUE} appears in a prompt, and the application is exported as a VoiceXML program. In these cases, {VALUE} is replaced by <value expr="field_{ID}"/>, where {ID} is the ID if the current question. By this, you can use the recognized value automatically in confirmation prompts.
Sorry, I did not understand that. {REPROMPT} After the apology, the initial prompt will be repprompted.
Okay we reserved a {VALUE:Q002} for you. With this, you can refer to values of other questions in your VoiceXML program.
[A:P001-ni1.wav] Sorry, I did not get that! P001-ni1.wav is considered the "standard audio file name" for this prompt. It can easily be removed or re-created using the dedicated Edit functions.

Many samples are available in the default application "Malibu Hotel Reservation" delivered with WOz.

3.4.3 TTS Configuration

When the admin or the runtime tool is started and the initial setting "common.tts" is set to 1, it checks whether a default SAPI 5.1 voice is available on the computer. If yes, a menu entry "text-to-speech" is enabled. The initial setting "common.tts_on" controls whether TTS is initially switched on (1) or off (0). TTS cannot be interrupted (no barge in)!

3.5 VoiceXML Export Features

3.5.1 BNF to SRGS Grammar Conversion

WOz contains a built-in parser to convert BNFG style grammars into SRGS grammars. The parser is invoked if all of these conditions are true:

  1. the project is exported as VoiceXML program,
  2. the grammarStrategy switch is bnf_2_srgs,
  3. the contents of the grammar is not already in XML format (determined by a leading "<?xml"), and
  4. the grammar skeleton file exists

The following syntax rules are applied:

Rule Meaning Symbol Names
expression :== expression expression
expression :== expression+
expression :== expression*
expression :== (expression)
expression :== {expression|...}
expression :== [expression|...]
expression :== expression<VALUE>
Sequence of expressions
at least one occurrence
null or more occurences
grouping parentheses
one of many alternatives
one or more alternative options
add a return value


 Here are some examples of valid BNF style grammars:

[i {need | want}] {help | assistance | guidance} [please]
{yes<1> | no<0>}
{repeat [that] | replay [that] | [say [that]] again} [please]
{[a] single room | [a] double room | [a | the] honeymoon suite} [please]
[i will stay] [for] {one | two | three} {days | nights | weeks} [please]

And here is the created SRGS grammar for the first sample:

<?xml version="1.0" encoding="ISO-8859-1"?>
root="_ROOT_" >

<rule id="_ROOT_" scope="public">

<item repeat="0-1">
<item> need </item>
<item> want </item>

<item> help </item>
<item> assistance </item>
<item> guidance </item>

<item repeat="0-1">


In the second sample, <0> and <1> will become ECMA Script tags filling the SWI_meaning value when returning the recognition result. Here's the corresponding code:

<?xml version="1.0" encoding="ISO-8859-1"?>
root="_ROOT_" >

<rule id="_ROOT_" scope="public">

<item> yes <tag>SWI_meaning='1'</tag> </item>
<item> no <tag>SWI_meaning='0'</tag> </item>



3.5.2 Export of VoiceXML Conditions

If the configuration value generateCondition is set to 1 (see here for details), the contents of attributed connections is exported in VoiceXML as a condition for the respective transition. An example: If you attribute the connection from Q001 to P002 with the value "{VALUE:Q001} &lt; 20", and the transition from Q001 to P003 with "{VALUE} &gt; 19", the resulting VoiceXML code will be:

<if cond="global_Q001 &lt; 20">
<goto next="#form_P002"/>

<if cond="field_Q001 &gt; 19">
<goto next="#form_P003"/>

As you can see in the example, quotes like &lt; must be included in the text. {VALUE} is replaced with the value of the question before the transition. This is only done, if the connection comes from a question (since prompts have no value). {VALUE:Qxxx} is replaced with the value of Question Qxxx.

3.5.3 Prompts in VoiceXML

Embededded prompts, as explained above, will be exported to VoiceXML as well, if not reqested otherwise. Both manual prompt choices as [A:prompt1.wav,prompt2.wav] and random prompt choices as {A:prompt1.wav,prompt2.wav} are exported as random prompt choices in VoiceXML (because the wizard has no chance to control the dialog). TTS input's {A:...} are ignored.

The second form of audio prompts are the Default Audio Prompts. These are generated by WOz automatically. There is always one prompt per possible prompt in the dialog states. The following list shows the file names used for these, for one example prompt and question:

Prompt Question
P017.p_prompt.wav Q023.q_init.wav

Besides the audio prompts, there are Text Prompts, which are used in VoiceXML whenever the associated audio prompt cannot be found by the VoiceXML browser. WOz generates these texts as an alternative for the default audio file of the prompt.

Let's look at an example. If you have the prompt "Your reservation ID is 0-1-1-2-2. [A:hotel/P002.p_prompt.wav] [A:hotel/0.wav] [A:hotel/1.wav] [A:hotel/1.wav,hotel/2.wav] {A:hotel/1.wav,hotel/2.wav} [A:hotel/2.wav] [A:...]", the following VoiceXML code will be rendered, if ttsStrategy is set to "both". See here for details on ttsStrategy.

<prompt xml:lang="de-DE" bargein="true"><audio src="P002.p_prompt.wav">Your reservation ID is 0-1-1-2-2.</audio></prompt>

<prompt bargein="true"><audio src="hotel/P002.p_prompt.wav"></audio></prompt>
<prompt bargein="true"><audio src="hotel/0.wav"></audio></prompt>
<prompt bargein="true"><audio src="hotel/1.wav"></audio></prompt>

<prompt bargein="true" cond="rnd_4 &gt; 0.0 &amp;&amp; rnd_4 &lt;= 0.5"><audio src="hotel/1.wav"></audio></prompt>
<prompt bargein="true" cond="rnd_4 &gt; 0.5 &amp;&amp; rnd_4 &lt;= 1.0"><audio src="hotel/2.wav"></audio></prompt>

<prompt bargein="true" cond="rnd_5 &gt; 0.0 &amp;&amp; rnd_5 &lt;= 0.5"><audio src="hotel/1.wav"></audio></prompt>
<prompt bargein="true" cond="rnd_5 &gt; 0.5 &amp;&amp; rnd_5 &lt;= 1.0"><audio src="hotel/2.wav"></audio></prompt>

<prompt bargein="true"><audio src="hotel/2.wav"></audio></prompt>

If ttsStrategy is set to "audio_only", the text ("Your reservation ID is 0-1-1-2-2.") is omitted, if it is "text_only", only the first line is created.

3.5.4 Context Sensitive Help

A context senstive help prompt can be designed for each question using the Context help field of that question (see here). If you want that prompt to be played in VoiceXML after a recognition, you must activate a concept that returns help as result. An example for such a concept is contained in en-US.woz (C003, used in Q001).

3.5.5 VoiceXML Logging Tags

WOz inserts some <log> tags in the generated VoiceXML code to allow debugging and evaluation of an application. E.g., the following information is logged:


WOZ.context=form_Q001.field_Q001_confirm|WOZ.recognition=yes please|WOZ.confidence=0.67789

3.5.6 Tested VoiceXML Platforms

Currently, the VoiceXML export runs on the German T-Com hosting platform that can be reached via the "Voice Test Center" (http://www.voice-community.de), running Nuance OpenSpeech Recognizer 3.0, Nuance Speechify 2.1, and Genesys GVP:NE 6.5.4.

So the VXML code will work best on this platform. If you have problems running the code on other platforms, pls fix them and send me the fixed VXML code along with name+version of your target platform. Maybe I can add support for other platforms as well.

If you want to check out the en-US demo coming with WOz, feel free to call +49 1805 330320 0031 5. Since this is my test number, there's no access garantee.

3.5.7 INLINE Code

In prompt and question texts you can use {INLINE text} to avoid that text is made XML save by replacing reserved characters. This is very useful if you want to export your design to VoiceXML, and need to include variable values in your prompts. Example:

Your account balance is {INLINE <value expr="money"/>} Euros

3.6 GML Exports

GML exports provide a convenient way to produce wallpapers and documentation of your designs in very high quality. The approach is to export your design as a GML file, import that file in a graph layout tool, compute a layout, and proceed from there. I recommend using the yEd tool. It is free, and produces the most impressive graph layout results I have seen so far. You can get more information about it under http://www.yworks.com/en/products_yed_about.htm.

Hint: When I produce graphs for my work at Nuance, I perform the following steps:

  1. Export a WOZ project to GML, normally including prompt texts (unless you only need an overview)
  2. Start yEd, loading the GML file (you can do this directly from WOZ if yED is installed properly)
  3. The layout looks messy, because (a) the node size is not yet adapted and (b) the layout coordinates are simply copied from WOZ [screenshot]
  4. In yEd, start Tools / Fit Node to Label, uncheck "ingnore widths" if necessary [screenshot 1] [screenshot 2]
  5. Start Layout / Hierarchical / Interactive, in the "Labeling" tab choose "Consider Node Labels", "Hierarchic", and "Best" [tab 1] [tab 2] [tab 3] [tab 4]
  6. Click OK [screenshot]. You can also see the impressive result as a PDF here.

yEd Screenshots with kind permission from yWorks GmbH, Vor dem Kreuzberg 28, 72070 Tübingen, Germany.

4. The Menu

You find some the menu commands in the (configurable) tool bar as well.

4.1 The File Menu

In the File menu you find the following commands:

Open Open an existing project. The default directory is project under WOZ
New Create a new empty project. If there are unsaved changes, there's a savety question.
Close Close the current project.  If there are unsaved changes, there's a savety question.
Save Save the current project under the same name as you opened it. The system will ask for a name if the project is a new one.
Save as Save it under a new name.
Merge Merge an existing project into the current one. All entries are consistently renamed, all relations are preserved. Currently disabled.
Export Export data to other files
Import Import data from other files
Exit Well, exit. If there are unsaved changes, there's a safety question.

4.2 The Edit Menu

In the Edit menu you find the following commands:

New Prompt Create a new prompt. The system automatically creates a P<number> Id.
New Question Create a new question. The system automatically creates a Q<number> Id.
New Concept Create a new concept. The system automatically creates a C<number> Id.
New Sample Call Create a new sample call. The system automatically creates a S<number> Id.
Rename Reserved for a future version (never active)
Undo All
Redo All
Undo the last commands, redo undone commands
Group Connection If you issue this command, you can choose some of the prompts and questions. The system will then create connections from each of these entries to each others. This way they make a group of entries where each can be reached from the other group members. 
Remove Connections Here you can choose prompts or concepts whose connections will be removed completely.
Sync Sample Calls Synchronize sample calls and design. The synchronization is controlled by several parameters that can be set in an options window:

sync.png (6381 Byte)

 The meaning of the parameters is as follows:

Create deleted objects If this is checked, a new prompt or question is created whenever a prompt is used in a sample call that does no longer exist. An example: you created a sample call using P001, then deleted P001 in the design. A synchronization will create P001 again. 
Create new objects If this is checked, a new prompt or question is created whenever Pnew or Qnew is used in a sample.
Create connections If this is checked, a new connection is created whenever two objects follow each other in a sample call that are not connected to each other.
Create concepts If this is checked, a new concept will be created and associated to the question, if the question does not have a concept yet. The contents of the concept will be the caller utterance.
Text Syncronization Here, you can choose one of three alternatives:
Change sample call texts When a text differs in a sample call and the design, the sample call text is changed. Please note that the last call processed "wins".
Change design texts When a text differs in a sample call and the design, the design text is changed. Please note that the last call processed "wins".
Keep texts unchanged Do nothing.
Objects to synchronize By default, all sample calls are synchronized. Here, you can choose subsets.
Compact Namespace With this command, all dialog objects are renamed, so that no gaps in the naming remain.
Options Set some values for the runtime module.
Remove Std Audio Files Remove all standard audio file names from all prompts and questions
Renew Std Audio Files Recreate all standard audio file names for all prompts and questions
Generate Sample Calls Automatically generate sample calls from the current design. This is done by computing all possible paths through the dialog, as defined at the moment when the generation is started. You can influence the computation by setting several parameters in a popup dialog box.

gencalls.png (4297 Byte)

.The parameters are

Max number of loops This controls how often one element may occur in a generated call. "1" means that no loop may occur. If you set the value to 2 or higher, aeach state may be revisitied up to the number you set
Call must reach end state If checked, every call ends at an end state (which is either explicitely set in the object properties or computed, if the object has no successors). If not set, calls may end in the middle (which makes sense because callers may simply hang up)
Min number of Dialog States
Max number of Dialog States
These numbers define an interval for the length of the generated calls. By default, nearly all calls will be computed (1..999)
Mandatory states If you click the button, you may choose some dialog states that must be visited to make the currewnt path a candidate for the result. If you pick objects that cannot be visited in one call, because they are not connected, the result will be empty

4.3 The View Menu

In the View menu you find the following commands:

Refresh Redisplay the list and the current entry.
Show Connections This switch controls whether connections are graphically displayed

4.4 The Run Menu

In the Run menu you find the following commands:

Create Session Create a runtime version (in Tcl/Tk) of the current project. This menu command can also be found as File / Export / Tcl/Tk Program. A project can only be exported if the automatically started analysis returns no errors.
Create Session and Execute This button creates a session like Run / Create Session, and afterwards directly this sessions in a separate process. You must have configured wish as described above.
Analysis Check the current project for inconsistencies. Fatal errors are listed in red, warnings in orange, and infomation in green. Analysis messages are additionally written into the log file. An example for an analysis is:
060916230115 Analysis: WOZ DATA ANALYSIS~
060916230115 Analysis: WARNING: Audio file hotel/P002.p_prompt.wav missing in P002.p_prompt
060916230115 Analysis: WARNING: Audio file hotel/0.wav missing in P002.p_prompt
060916230115 Analysis: ~INFO: Everything's fine.
Sample Call Analysis Analyze all sample calls and report missing dialogue objects, missing connections, and modified texts. Analysis messages are additionally written into the log file. An example for an analysis is:
060916225530 Analysis: SAMPLE CALL DATA ANALYSIS~
060916225530 Analysis: WARNING: Text P004.p_prompt has changed in sample call S001.
060916225530 Analysis: WARNING: Text Q001.q_init has changed in sample call S001.
060916225530 Analysis: WARNING: Missing connection Q002 to Q003 used in sample call S001.
060916225530 Analysis: ~Sample Call Analysis Finished
Automatic Layout An algorithm for an automatic layout is applied. Stay calm, the result can be undone :-)
Update Dialog Logfile This function allows you to replace the texts in a dialog log file written by the runtime frontend with the current values of your application. Dialog log files are e.g. named hotel.050803134933.log
Text-to-Speech This switch allows turning on and off usage of the <SAPI> 5.1 standard system TTS voice (configured in the Windows control panel). If off, the play buttons play recorded speech. 

4.5 The Help Menu

Documentation Opens the default web browser and display the WOz documentation
About The WOz splash screen
Show Logfile Opens an editor to display the current log file contents. Can be useful in combination with the File/Import command(s)

5. The Runtime Module

You can export a WOZ project as a Tcl/Tk program of its own. This program runs without the WOZ frontend itself. It is well suited for sending it to a customer without giving him the possibility to modify the system easily. The export itself is rather simple. Use File / Export / As Tcl/Tk Program or Run / Create Session. The default directory for the export is export under the WOZ folder. Just keep care that the share folder is shipped together with the resulting Tcl program! And: Tcl/Tk must be installed on that target machine as well (see here).

5.1 Usage

The frontend itself is rather simple. In general, the Wizard sees the current prompt or question on the left hand side and can move to follow ups on the right hand side.

On the left hand side, he can also see which concepts should be recognized by him at that point ("recognizable concepts"), and can play and stop prompts. If TTS is switched on (in the Run menu), SAPI TTS is used to play back prompts, otherwise prerecorded files are played. A prompt can only be stopped if Barge-In is allowed.

On the right hand side, the Wizard can restart the application or go back one step (in case of mistakes). Under the follow ups there's are radion buttons to sort the follow-ups, and a graphical overview of the design that may make it easier to navigate. Finally, there's a text input field that the wizard can fill with the caller's answers or other comments. These inputs will be logged.

session.png (24847 Byte)

Please note the following differences to the WOZ editing frontend:

File Menu Here, you will only find the Exit command.
Run Menu In this menu you can Restart the dialog from the beginning and modify the behaviour of creating Random Exceptions for retries, timeouts, confirmations, and recognition errors. If you switch these on, the system uses the probabilities from the WOZ option settings. Moreover, you find here the command Back (Ctrl/Z) and Forward (Ctrl/Y), which switch to the previous or next dialogue step you used. Finally, a flag Restrictive Navigation may be switched off to reach not only the connected entries but all of them. The switch Prompt Autoplay can be turned off if the audio of prompts or questions should not be replayed automatically. If Prompt Autostop is turned off, a new prompt does not automatically turn off an old one. Finally, the usage of Text-to-Speech can be switched on or off.
Possible Followups Click on an entry in the list to switch from one dialog step to a next one. The radio buttons Name, Cond, Text, and Ix resort the list after the third, second, fourth, or first column respectively. Default is sorting after condition.

The buttons |< and < activate the restart and undo function respectively.

Recognizable concepts All are listed for a question (including the always active ones on the left hand side of the separator). Use the bubble help to see the name and contents of a concept.
Status information In the status line above each entry there are two pieces of information: You see the current number of dialog turns and the elapsed time since the start of the dialog in seconds.
Log! This button allows you to enter any text you type into the session log file (for Wizard comments, e.g. to type in user input). The <Return> key is bound to Log!

If WOZ is fully configured (see the play and stop commands), the Play and Stop buttons replay a prompt (prerecorded from $woz/prompts or via TTS) and stop the replay.

5.2 Logging

During a running WOZ session, the tool logs each dialog step in a <name>.log file in the same directory of the session tcl file itself. So you will find a hotel.log file in export/ containing all dialogue turn of a hotel session. Each action is logged with a timestamp.

060723053752 WOZ Session started (Version 2.00 Copyright (c) 2001-06 Richard Breuer)
060723053752 Restart -------------------------------------------------------------------------------
060723053752 1|P004|Welcome|Good morning.<esc>P4 Welcome to the~Malibu Beach hotel reservation system! {A:hotel/P001.p_prompt.wav,hotel/P001.p_prompt_hello.wav,hotel/P001.p_prompt_hi.wav}[P:hotel/P001.p_prompt.gif]
060723053752 play|P004|p_prompt|Good morning.<esc>P4 Welcome to the~Malibu Beach hotel reservation system! {A:hotel/P001.p_prompt.wav,hotel/P001.p_prompt_hello.wav,hotel/P001.p_prompt_hi.wav}[P:hotel/P001.p_prompt.gif]
060723053757 2|Q001|Start|How can I help you?[A:hotel/Q001.q_init.wav][P:hotel/Q001.q_init.gif]
060723053757 play|Q001|q_init|How can I help you?[A:hotel/Q001.q_init.wav][P:hotel/Q001.q_init.gif]
060723053804 Log|i need a room
060723053806 3|Q002|Arrival|When would you like to arrive?[A:hotel/Q002.q_init.wav]
060723053806 play|Q002|q_init|When would you like to arrive?[A:hotel/Q002.q_init.wav]
060723053813 Log|tomorrow
060723053816 4|Q003|Duration|How long would you like to stay?[A:hotel/Q003.q_init.wav]
060723053816 play|Q003|q_init|How long would you like to stay?[A:hotel/Q003.q_init.wav]
060723053821 Log|two days
060723053823 5|Q004|Room|Which type of room would you like?[A:hotel/Q004.q_init.wav]
060723053823 play|Q004|q_init|Which type of room would you like?[A:hotel/Q004.q_init.wav]
060723053834 Log|a single room please
060723053837 6|P002|ID|Your reservation ID is 0-1-1-2-2.[A:hotel/P002.p_prompt.wav][A:hotel/0.wav][A:hotel/1.wav][A:hotel/1.wav,hotel/2.wav]{A:hotel/1.wav,hotel/2.wav}[A:hotel/2.wav][A:...]
060723053837 play|P002|p_prompt|Your reservation ID is 0-1-1-2-2.[A:hotel/P002.p_prompt.wav][A:hotel/0.wav][A:hotel/1.wav][A:hotel/1.wav,hotel/2.wav]{A:hotel/1.wav,hotel/2.wav}[A:hotel/2.wav][A:...]
060723053844 7|P003|Bye|Thank you for using our service. Good-bye![A:hotel/P003.p_prompt.wav] <Song> [A:hotel/ill_song.wav] [A:hotel/no_song.wav] [A:hotel/pause_500.wav][A:hotel/song.wav][P:hotel/no_pic.gif][P:hotel/ill_pic.png]
060723053844 play|P003|p_prompt|Thank you for using our service. Good-bye![A:hotel/P003.p_prompt.wav] <Song> [A:hotel/ill_song.wav] [A:hotel/no_song.wav] [A:hotel/pause_500.wav][A:hotel/song.wav][P:hotel/no_pic.gif][P:hotel/ill_pic.png]

Since version 1.04 also the actions "play" and "stop" are logged. If you equip your WOz test with sound files, this means that you can follow the dialog flow by looking for "play" logs, and detect barge-in by "stop" logs. Additionally, any message logged with the Log! button is entered here.

5.3 Dialog Logging

Whenever you start a new session in the runtime frontend, along with <name>.log a new file <name>.<timestamp>.log is created. This file contains the current session as a dialog log that can be included into documents easily to illustrate a sample application dialog. The columns (system/caller and prompt) are separated by a tab character. The caller's utterances can be created by pressing the "Log!" button in the runtime frontend, the system's utterances are created automatically.

Since the dialog logging contains the unique dialog objects IDs (P004 and so on) and the context (e.g. p_prompt), they can be updated when the prompts have changed during the system design. You can use the Run / Update Dialog Logfiles menu command in the WOz admin frontend to do this.

P004 p_prompt System Good morning.<esc>P4 Welcome to the~Malibu Beach hotel reservation system! {A:hotel/P001.p_prompt.wav,hotel/P001.p_prompt_hello.wav,hotel/P001.p_prompt_hi.wav}[P:hotel/P001.p_prompt.gif]
Q001 q_init System How can I help you?[A:hotel/Q001.q_init.wav][P:hotel/Q001.q_init.gif]
Caller i need a room
Q002 q_init System When would you like to arrive?[A:hotel/Q002.q_init.wav]
Caller tomorrow
Q003 q_init System How long would you like to stay?[A:hotel/Q003.q_init.wav]
Caller for just one night
Q004 q_init System Which type of room would you like?[A:hotel/Q004.q_init.wav]
Caller a single room please
P002 p_prompt System Your reservation ID is 0-1-1-2-2.[A:hotel/P002.p_prompt.wav][A:hotel/0.wav][A:hotel/1.wav][A:hotel/1.wav,hotel/2.wav]{A:hotel/1.wav,hotel/2.wav}[A:hotel/2.wav][A:...]
P003 p_prompt System Thank you for using our service. Good-bye![A:hotel/P003.p_prompt.wav] <Song> [A:hotel/ill_song.wav] [A:hotel/no_song.wav] [A:hotel/pause_500.wav][A:hotel/song.wav][P:hotel/no_pic.gif][P:hotel/ill_pic.png]

Additionally, a dialog log can be used to update the design (File / Import / Design from Sample Call) or to create a Sample Call (File / Import / Sample Call).

6. Data Exchange

6.1 Export Facilities

One of the most important issues in the design phase is the possibility to re-use the data and work you put into that process. Therefore, WOz offers various ways to export data to other formats for further processing. The import facilities are limited. The export commands ask for a filename (phrase, text, Tcl/Tk, xml etc.) or a directory (RTF, sample calls) to write to. See here for questions about the configuration of the export functions.

Phrase List A phrase list is merely a text file containing all phrases from your application. Actually, two lists are exported, separated with an empty line. The first contains all file names, followed by the prompts, the second maps a list of file names to each unique text.
Tcl/Tk Program This option creates the runtime version of your project, the one you can use in a WOZ test. See here for details.
RTF Documentation With the RTF export command you can create a set of documents in Microsoft's RTF format. They can directly be loaded e.g. in MS Word. This allows you to create a project documentation for your application easily.
OSDM properties WOZ can create two OSDM configuration files for each question
XML File This options writes your application into an XML file for further processing. You find a corresponding DTD in resource/woz.dtd.
HTML Document The project contents is exported into one single HTML file with hyperlinks and references. Check out the sample export file.
xHMI Document With this function, you can create a first application version in the xHMI application configuration language that can e.g. be executed by Nuance's OpenSpeech Dialog (OSD) platform.
StudioWorks File Export as a phrase list for the StudioWorks tool from Nuance
Visio Diagram Eport as visio digram (only the objects, not the layout). Currently disabled.
Postscript File The graphical layout is written to a postscript file.
PNG Image The graphical layout is written to a PNG image file.
Sample Calls All sample calls are exported to text files in a specified directory.
Sample Calls Audio WOz creates WAVE files with the audio contents of the sample calls. Currently, this works only if prerecorded audio is used. See here for details.
GML File Layout information for graphs with nodes and edges, see http://www.infosun.fim.uni-passau.de/Graphlet/GML/

6.2 Import Facilities

The possibilities to import data from other systems or files are still a bit limited.

Design from Sample Call A text file is a list of wave file names (.wav is optional) and the corresponding strings for recoding. If the import finds dialog objects that have been previously unused, the user is asked whether to create new objects. If errors occur during input due to illegal context names, this is stated in the status line and an entry in the log file is written. Try e.g. to import hotel-import.txt into the Hotel project:
P002.p_prompt Your reservation ID is 0-1-1-2-2.[A:hotel/P002.p_prompt.wav][A:hotel/0.wav][A:hotel/1.wav][A:hotel/1.wav,hotel/2.wav]{A:hotel/1.wav,hotel/2.wav}[A:hotel/2.wav][A:...]
P003.p_prompt Thank you for using our service. Good-bye![A:hotel/P003.p_prompt.wav] <Song> [A:hotel/ill_song.wav] [A:hotel/no_song.wav] [A:hotel/pause_500.wav][A:hotel/song.wav][P:hotel/no_pic.gif][P:hotel/ill_pic.png]
P004.p_prompt Good morning.<esc>P4 Welcome to the Malibu Beach hotel reservation system! {A:hotel/P001.p_prompt.wav,hotel/P001.p_prompt_hello.wav,hotel/P001.p_prompt_hi.wav}[P:hotel/P001.p_prompt.gif]
Q001.q_init How can I help you?[A:hotel/Q001.q_init.wav][P:hotel/Q001.q_init.gif]
Q001.q_ctxhelp With this application, you can book rooms at the Malibu Beach hotel.[A:hotel/Q001.q_ctxhelp.wav]
Q002.q_init When would you like to arrive?[A:hotel/Q002.q_init.wav]
Q002.q_nu1 Sorry, I didn't understand you. Please say the date of your arrival now.[A:hotel/Q002.q_nu1.wav]
Q002.q_nu2 Sorry, I still didn't get you. Please use common date expressions like 'the first of May' or usual holidays.[A:hotel/Q002.q_nu2.wav]
Q002.q_nu3 One moment please, I transfer you to an operator.[A:hotel/Q002.q_nu3.wav]
Q002.q_nr1 Please speak to me![A:hotel/Q002.q_nr1.wav]
Q002.q_nr2 The phone line seems to have a problem. Try again later, please.[A:hotel/Q002.q_nr2.wav]
Q002.q_tl1 That was too much for me. Try again, please.[A:hotel/Q002.q_tl1.wav]
Q002.q_tl2 That was too much information again. One moment please, I transfer you to an operator.[A:hotel/Q002.q_tl2.wav]
Q002.q_ctxhelp Please state the date of your arrival like 'the first of May'. You can use common holiday expressions like 'Easter' or 'Christmas' as well.[A:hotel/Q002.q_ctxhelp.wav]
Q003.q_init How long would you like to stay?[A:hotel/Q003.q_init.wav]
Q004.q_init Which type of room would you like?[A:hotel/Q004.q_init.wav]
Q004.q_nu1 Sorry? You can book a single or a double room. We offer honeymoon and president suites as well.[A:hotel/Q004.q_nu1.wav]
Q004.q_nu2 Sorry, I did not get that! Please tell me, which type of room you'd like.[A:hotel/Q004.q_nu2.wav]
Q004.q_ctxhelp Say 'single' or 'double' room, 'honeymoon' or 'president suite' now.[A:hotel/Q004.q_ctxhelp.wav]

Another format that can be imported, is the sample call format used by File / Export / Sample Calls or the logging of dialogs in the runtime frontend.

P004 p_prompt System Good morning.<esc>P4 Welcome to the~Malibu Beach hotel reservation system! {A:hotel/P001.p_prompt.wav,hotel/P001.p_prompt_hello.wav,hotel/P001.p_prompt_hi.wav}
Q001 q_init System How can I help you?[A:hotel/Q001.q_init.wav]
text Caller I need a room
Q002 q_init System When would you like to arrive?[A:hotel/Q002.q_init.wav]
text Caller err, today
Q002 q_nu1 System Sorry, I didn't understand you. Please say the date of your arrival now.[A:hotel/Q002.q_nu1.wav]
text Caller today
Q003 q_init System How long would you like to stay?[A:hotel/Q003.q_init.wav]
text Caller one night
Q004 q_init System Which type of room would you like now?[A:hotel/Q004.q_init.wav]
text Caller a single room
P002 p_prompt System Your reservation ID is 0-1-1-2-2.[A:hotel/P002.p_prompt.wav][A:hotel/0.wav][A:hotel/1.wav][A:hotel/1.wav,hotel/2.wav]{A:hotel/1.wav,hotel/2.wav}[A:hotel/2.wav][A:...]
P003 p_prompt System Thank you for using our service. Good-bye![A:hotel/P003.p_prompt.wav] <Song> [A:hotel/ill_song.wav] [A:hotel/no_song.wav] [A:hotel/pause_500.wav][A:hotel/song.wav][P:hotel/no_pic.gif][P:hotel/ill_pic.png]
Sample Call With this function, a sample call can be imported from a text file. The text file can be in one of the formats described above.

7. Configuration

There are two files which can be edited to adjust the system behaviour. The one (resources/text-language.dat) can be edited and renamed to support a different language than English or German. If you ever translate text*.dat to another language, I would be happy if you returned text*.dat to me and allow me to include it in the distribution. The contents of the file should be self-explaining.

The other, resources/woz.ini, contains several settings in the usual Windows INI format. The values are organized in different categories described below. The flags used in the tables below mean:

Flag Meaning
- Changes will normally not be necessary
X This value should be configured in your system
? A configuration is normally not necessary, but it might be useful

Since 2.05, a file default.ini is distributed with WOz. This allows you to reuse your woz.ini file from older versions. Simply copy it into the resource folder, replacing the woz.ini from the current distribution.

7.1 [Common]

This category contains all values with a kind of global meaning.

Name Example Flag Meaning
initialProject ./project/hotel.woz ? This project file will be read directly at startup time. If you continuously work on one project, you should enter it here
textDisplayLength 40 - With this value you can influence how many of the contents of an object is shown in the list on the left hand side in the admin frontend. Longer texts will be hidden behind ...
audioPrefix hotel/ X The prefix used if you initialize question or prompt fields with an audio name. If AudioPrefix is not set at all, no audio file names will be initialized for new objects. AudioPrefix may be empty.
conceptBubbleLength 40 - Max Length of a bubble help text
- Hex <RGB> values or names for the colors used for concepts, prompts, questions, connections, start prompt, sample calls, and sample call warnings respectively. If you modify these values, you might want to change the icons c.gif , p.gif , s.gif , sync.gif and q.gif according to your colors.
X tts controls whether it is tried to use text-to-speech for prompts. If 1, the computer's standard voice will be used if possible (as set in control panel / speech in/output).

If tts_on is 1, TTS will initially be active if possible. If tts=0, tts_on will be ignored.

7.2 [Windows], [Unix], [Macintosh]

Each of these categories contains OS specific values. If you execute WOz, the settings for the current OS are used.

Name Example Flag Meaning
wish c:/tcl/bin/wish83.exe X You must set this value to the Tcl/Tk installation on your machine. Otherwise you get an error message "wish cannot be found..."
show notepad %s X This command is used to display the current log file contents (Help / Display Log File). %s is replaced with the file name.


If you do not adjust wish, the command Run / Create session and Execute will probably not work.
In this case, you can start the exported session manually (by double clicking the tcl file).

7.3 [Files]

Here you can set several values for directory and file handling, as well as choose skeleton files for some export processes.

Name Example Flag Meaning
wozDir ./project - This directory will be used as the default project directory if you open or save a project. You can leave it empty to use the operating system's default.
expDir ./export - Here, the system stores export files by default. You can leave it empty to use the operating system's default.
wavDir ./prompts - Directory to locate system prompts
logFile ./woz.log - WOz logs every important action in this file
allType=All Files
- These values define the default file types and extensions for various open and save dialogs. Normally, there's no need to change them.
XMLskelFile ./resource/skeleton.xml - When you export a project as <XML> file, this skeleton file contains the static part
? When you export a project as <RTF> files, these skeleton files contain the static parts for prompts, questions, and concepts. It makes much more sense to modify these skeleton files with an RTF editor like MS Word than by hand.
? Skeleton files for OSDM properties export
HTMLskelFile ./resource/skeleton.htm - Check out skeleton.htm for a list of replaced strings. It also shows how sub blocks may be used. I recommend to copy and edit this file with a <HTML> editor and use the same macros as you find in the original file :-)
xHMIskelFile ./resource/skeleton.xhmi - As for HTML, check out the skeleton file for a list of replaced strings and blocks / subblocks.
VDXskelFile ./resource/skeleton.vdx X Partial skeleton file for Microsoft Visio® export; Note: you must provide a complete file!!!
TclTkSkelFile ./resource/skeleton.tcl - When you export a project as Tcl/Tk file, this skeleton file contains the static part.
comment (C) 2007 MyCompany X Comment used in HTML exports
resourceFile text-en.dat - name of the localization file
GRMskelFileC ./resource/skeleton-c.grxml X Whenever a new concept is created, and this setting exists, the file contents is used as a default concept
- This pause is inserted in a sample call audio after each prompt (default 50ms)
...after each question (200ms)
...after each caller's utterance (1000ms)
showExport 1 - Show text file after finishing the export
playAudio 1 - Play sample call audio before writing it to file
X An audio file name for a new prompt or question field will be created from <OBJ><filename>.wav, e.g. P001-ini.wav; this is also exported to VoiceXML

7.4 [Graphics]

Here, you can configure the graphical display.

Name Example Flag Meaning
canvasDisplayLength 15 - Max length of text within the objects
connectionDisplayLength 25 - Max length of connection details displayed in the context menu
conceptDisplayLength 20 - Max length of concept details displayed in the context menu
sampleCallDisplayLength 20 - Max length of sample call details displayed in the context menu
- Grid sizes, makes positioning easier. Set to 1 to turn off
- Width and heights for the boxes. The header is the part where the object type and name are shown, the rest is the body.
Helvetica 9 bold
Helvetica 8
- Some colors and fonts
- Controls the layout of connections. Note: the display of connections can be switched off (details). This is best illustrated with some pics:




- Connection colors and thickness
- Factors for connection proportions in x and y directions. 1/1 means connections are divided 50/50. TZhe factors are used only if the connection type is not direct. Again, a pictures illustrates this better than words. The connections here are drawn with the factors 1,3,1,3.
- These settings control the layout of connections of an object with itself (P003 in our demo pics). The picture here is draw with the settings 1,1,1,1,30,30.
- These setttings control the look of the sample calls properties window. See here for details.

7.5 [Toolbar]

This section in the INI file allows you to configure the toolbar. You can configure Tool00...Tool05, Tool10...Tool15, and Tool20...Tool25. Between the groups is a small visible space on the screen.

Name Example Flag Meaning
Icon new - Name of a GIF file in resource/icons
Cmd file,new - menu command started by the tool bar button

Make sure that a matching GIF file in resource/icons exists and that Cmd is one of these commands:







7.6 [VoiceXML]

This category defines values controlling the VoiceXML export.

Name Example Flag Meaning
grammarStrategy bnf_2_srgs X This switch controls how WOz treats grammars defined in concepts when the project is exported to VoixXML. See here for more details. There are three possible values.

do_nothing: if a concept is created, the grammar is empty; when VoiceXML is exported, the grammar contents is simply copied.

bnf_2_srgs: if a concept is created, the grammar is empty; when VoiceXML is exported, the grammar is converted from the BNF contents of the concept.

use_skeleton: if a concept is created, the contents of the grammar skeleton file is inserted, if the file exists; when VoiceXML is exported, the grammar contents is simply copied

- no longer supported, refer to supportedLangaues instead
de-DE en-US - List of languages supported by WOz. "Supported" means there is a corresponding <lang>.dat file in the resource/languages directory. Stay tuned for more languages, or provide the dat file so I can include it in the distribution.
generateCondition 1 X If generateCondition is 1, the contents of connection attributes will become VXML conditions
confirmConfidence 0.7 X A confirmation question is skipped, if a slot is recognized with a con above this value. All slots use the same confirmation confidence value (in a real app you would differentiate). Special cases:
  • set confirmConfidence=1.0 to always confirm
  • set confirmConfidence=0.0 to never confirm
ttsStategy both X ttsStategy controls the generation of text and audio prompts
tts_only only text prompts will be generated, only standard audio files are generated standard audio files are e.g. Q003.q_nu1.wav for the nomatch-1 handler of Q003
audio_only WOz will not generate text within <prompt>s
both generate embedded audio AND tts text

7.7 [Exports]

This category contains values for the configuration of exports.

Name Example Flag Meaning
gmlTextDisplayLength 40 - This controls how long a text line may be in a GML export, before the text is wrapped


8. FAQ

Q: How can another display language be configured?
A: By default, WOz is configured for English. Another language can be activated only, if a corresponding resource/text-language file exists. You can activate this file by modifying the resource/woz.ini parameter resourceFile. Currently, besides English German is available.

Q: Creating a session fails.
A: The parameter wish in resource/woz.ini must be set correctly for your operating system. Then wish can be started.

Q: How can I start WOz with a different autostart project than hotel.woz?
A: You have two possibilities (besides copying a different project file to the name hotel.woz :-)): You can either modify the initialProject setting under [Common] in resource/woz.ini or pass the file name of your project as parameter to woz.tcl. Under Windows, this can be done in a program link as illustrated here (German Windows):

To start WOz with no project at all, simply remove or comment the parameter initialProject in resource/woz.ini.

Q: What (the hell) is xHMI?
A: xHMI is an XML based application development language invented by Nuance. It aims to become a standard for a higher-level programming of voice applications than VoiceXML. See http://www.nuance.com/xhmi/ for more information.

Q: Why can MS Visio not load my Visio export?
A: Woz does not contain a complete MS Visio skeleton VDX file, because these can easily be 17MB or more. You must provide such a file yourself. The filke coming with WOz illustrates only the possible replacements in a VDX file. You will have to provide a real file and edit this accordingly.

Q: Where are HDDL and SSL exports?
A: They were removed in Version 1.13, since I think noone really used them. Please use version 1.12 if you need them.

Q: Why is my language xy-AB not supported?
A: Because there is no corresponding xy-AB.dat file in resource/languages. If you create one, you can add your language to supportedLanguages in woz.ini and use it. It would be very kind to send that file to me, so I can include it in the next WOz release.

Q: Why are the prompts played only using TTS, and not recorded files?
A: Because TTS is switched on in the Run menu. Switch it off, and files will be played if available.

9. Known Problems

These are the problems I currently know of:

If you desperately need one of these functions, please let me know.

10. Credits

I'd like to thank the UI Design Group of Nuance (former Philips Speech Processing, ScanSoft) and especially Brigitte Giese and Peter Vranken for their superb introduction to the world of Human Factors in Dialogue Systems. If you like to know more of this, I highly recommend the Nuance training courses! Furthermore, I would like to thank Peter again for his most valuable input in various areas of the WOZ tool.. My Nuance colleague Per Gyllensvard was (afaik) the first to make heavy use of WOZ. He gave me a lot of ideas and urged me to fix several glitches :-) My colleagues Klaus Reiter, Klaus Allwicher, and Joe Brachoki helped me improve the usability and functionality of WOz. Last but not least Jamal Borno and Alexander Huggings allowed me to support Arabic and French.

More thanks go to Stewart Allen for his Tcl/Tk GUI Builder VisualTcl and Frank Pilhofer for his YETI package.

Finally I would like to thank my wife Marita for her patience during all those hours when I sat there with my notebook, especially in my holidays.

Appendix: Version 1 Change History

Date Version Changes
02/28/2001 0.90 First version
05/24/2001 0.91 Updates after suggestions from Philips Speech Processings Human Factors Group
07/08/2001 0.92 Larger follow up lists in the runtime module, modified HDDL export
07/15/2001 0.93 Several enhancements after a review by Peter Vranken. Runtime module: Back/Forwards commands, Runtime log file, Non-restrictive navigation, Alternate sorting orders. Design module: Easier session export with default name, Run/Run command, Group connections, Deletion of connections. And, as always, there were some fixes
07/16/2001 0.94 Documentation export in customizable RTF format
07/20/2001 0.95 Bug fix, use unique timestamps, forget maxsize
08/03/2001 0.96 Structure View, minor fixes and changes for convenience
10/16/2002 0.97 Added export as SSL program for an integration to Peter Vrankens Simple Scripting Language
12/07/2002 0.98 Tuned SSL export, added XML export, fixes
12/16/2002 0.99 Added some features (go to previous, audio buttons), and a real HDDL export
12/21/2002 1.00 Some testing, (Hopefully :-)) increased stability, more documentation
09/13/2004 1.01 Changes for Per, Preview, dropped the exe version again
09/29/2004 1.02 Playback of recorded prompts is these exist
10/02/2004 1.03 Bugfix for texts with " and {, filename in window name, modified text export
10/09/2004 1.04 Added a play/stop facility for the sound playback
10/27/2004 1.05 New arrow key bindings; more logging, support for ESC in prompts, minor changes
11/14/2004 1.06 Bugfix, some comments on designing multi modal applications, HTML export (check it out!)
11/15/2004 1.07 (Hidden) Nuance specific RTF export (with bookmarks); the guys know how to activate it easily :-)
11/16/2004 1.08 New button "goto question" for concepts; Import from text file (one bug remains)
11/20/2004 1.09 New functions "Edit/Copy" and "Help/Show logfile"
05/05/2005 1.10 Added xHMI export, bugfix in HTML export
06/04/2005 1.11 Added dialog logs in the runtime version and StudioWorks export; changed label configuration  to SSFT terminology; changes in the naming conventions used in the xHMI export
07/10/2005 1.12 Added Visio export; NOTE: Only a partial template file is provided, see skeleton.vdx for details
08/06/2005 1.13 Removed: HDDL export, SSL export, Inhuman Factors Sample; Added: Sound and picture references management, Dialog Logfile Update, Prompt Autoplay at Runtime, Prompt Autostop at Runtime, Movies Sample; Changed: Phrase List Export, Import Format so that phrase lists can be imported, HTML Export to reflect the new sound and pic facilities, Bugfix of a window focus, Tcl 8.4 is required now, The snack package is needed for sound replay
08/14/2005 1.14 Random play for audio files
08/17/2005 1.15 Bugfixes
02/05/2006 1.16 Enabled built-in SAPI 5.1 TTS using the system's standard text-to-speech voice
06/03/2006 1.17 Changed ScanSoft to Nuance; added robustness to SAPI problems; added TTS runtime input
06/04/2006 1.18 Small changes, better documentation of the prompt features (as they become more and more :-))


Copyright © 2001-09 by Richard Breuer
www.softdoc.de/woz * richard.breuer@gmx.de