Getting started

1. Downloading OpenDial

The Download page contains the various OpenDial releases.

System requirements:

  • Java 8
  • Gradle (if you want to modify or extend the source code)

NB: If you are using Maven/Gradle for your software and are only interested in fetching OpenDial as an external dependency, there a Maven package for Opendial on Jcenter (groupId:opendial,artifactId:opendial).

2. Running OpenDial

When you have downloaded the package, simply unzip it and cd to the main directory:

unzip opendial-X.zip
cd opendial

(of course, X should be replaced by the particular version you are using).

If you have downloaded one of the stable packages, the source code is already compiled, so you can directly run OpenDial out-of-the-box by executing one of the following scripts:

- Linux / Mac OS X:

- Windows:

./scripts/opendial
.\scripts\opendial.bat

If everything goes well, you should see a window like this pop up:

If you get an "UnsupportedClassVersionError" exception instead, this probably means that your version of Java is older than Java 8 (you can check this by typing java -version). This means you should update your Java installation to the latest version. Simply google "how to install Java 8 on [your platform]" to find the easiest way to do so (ready-made packages are available for most platforms). If you experience other types of problems running OpenDial, do not hesitate to send an email to the opendial-users mailing list.

From there, you can either start a new dialogue domain (Domain > New) or load one of the domain examples in the directory domains/examples (Domain > Open File).

3. Compiling OpenDial from source (optional)

In case you plan to work on OpenDial's source code, or if you have fetched the bleeding-edge source code from the github repository, you will need to recompile the source. Since version 1.4, OpenDial relies on the Gradle build framework (before 1.4, we used ant).

If you do not yet have Gradle on your machine, you first need to install it (on Mac OS X, you can install it via Brew, and a gradle package is also available on Ubuntu). Once this is done, simply go to the main directory and type:

gradle compile

This should compile the source code in a few seconds. You can verify that everything works correctly by running the unit tests for Opendial:

gradle test

Once the compilation is completed, you can run OpenDial through the scripts mentioned above (./scripts/opendial or .\scripts\opendial.bat).

4. Using OpenDial

You can try out OpenDial by opening a dialogue domain such as the one specified in domains/example/example-step-by-step_fixed.xml and typing a new user input such as: "please turn left". You should then see in the chat window the system answer: "OK, turning Left".

OpenDial contains 3 tabs: an interaction tab listing the dialogue history, a state monitor tab showing the current dialogue state and its latest updates, and a domain editor tab allowing you to edit the domain specification.

Interaction tab

The first tab displays the dialogue history and allows the user to interactively test the dialogue system.

At the bottom of the page, a text field can be used to enter new inputs (this feature is useful to test the system behaviour without a speech recognizer). N-best lists can be entered by specifying probabilities in parentheses and separating alternative hypotheses with a semicolon (;). For instance, the user input:

now move left (0.55) ; do not move left (0.15)

represents a N-best list with three alternative elements: "now move left" with probability 0.55, "do not move left" with probability 0.15, and a last empty element (no input) with probability 0.3.

If you include modules related to speech recognition or synthesis to your architecture, you will also see a bottom panel allowing you to easily provide speech inputs.

State Monitor Tab

The state viewer displays the current dialogue state as a Bayesian network.

The user can click on each variable (or sets of variables) and derive their marginal probability distribution. In addition, the distribution of individual variables can be represented graphically in a chart or density function.

In addition to the current dialogue state, the system can also keep track and record past dialogue states. This can be very useful for debugging, as it shows how the dialogue state evolves during processing. The menu item Options > Record Intermediate States allows you to determine which states to record.

Domain Editor Tab

Finally, the domain editor allows you to interactively edit the dialogue domain (in XML format).

The editor is a XML editor with syntax highlighting and auto-completion features (for instance, if you type <rule>, the editor will automatically generate for you a basic skeleton for your rule specification). When you have made changes to the domain, you can save it (Domain > Save or the usual keyboard shortcut for your platform). This will both save the dialogue domain on disk, and update the dialogue domain in OpenDial.

5. Command line parameters

As mentioned above, you can run OpenDial through the scripts available in the scripts directory. Alternatively, you can also directly run the Java main class: java -cp "lib/*" opendial.DialogueSystem.

You can specify additional (optional) parameters at runtime via the command line:

./scripts/opendial -Dname_of_param1=value1 -Dname_of_param2=value2 ...

where name_of_paramX is one of these parameters:

Please note the -D standing before each parameter name (these parameters are JVM arguments).

6. Menu bar

The OpenDial menu bar offers several functions: