$Id: 00README-en,v 1.2 2005/12/15 07:56:16 nishi Exp $

TODO: UPDATE THIS DOCUMENT

=======================================================
Galatea V3.0 and Galatea Dialog Manager Document
=======================================================

Project website: http://hil.t.u-tokyo.ac.jp/~galatea/

2003-11-15 Takuya Nishimoto (The University of Tokyo)
           nishi@hil.t.u-tokyo.ac.jp


1 Install
---------

1.1 Requirements
----------------

Galatea DM 1.0 is tested with the following environment.
We recommend to use computer with higher performance as possible.

  Hardware:

    - CPU : Pentium 4 2.8GHz
    - RAM : 1GB
    - Video : NVIDIA GeForce4 Ti4200 128M-VRAM
    - Sound : Creative SoundBlaster Live! PCI

  Software:

    - Redhat Linux 9.0 Publisher's Edition (full install)	
    - NVIDIA-Linux-x86-1.0-4496 (video driver from NVidia)
    - Galatea v3.0 for Linux

Galatea for Linux uses Kernel sound driver, but in some cases,
you may need to use ALSA (Advanced Linux Sound Architecture).


1.2 Installing Galatea Modules
--------------------------

We recommend to setup and test each modules 
step-by-step as shown in this document.

1.2.1 Galatea Files 
----------------------------

    - galatea-v3.0/ (toolkit directory)
          - AM/
            - AgentManager.pl
            - AM-MCL.pl
            - ...
          - TM/
          - FSM/
          - SRM/
          - SSM/
          - app/
          - morph/
            - darts-0.2/
            - chasen-2.3.3/
            - unidic-1.1.0/
            - chaone-1.1.0.jar
          - DM/
            - galatea (executable file)
            - galatea.conf (configuration file)
            - tests/ (sample vxml files)
            - Document/ 
            - Modules/ (extention modules)
              - am4dm.conf
              - DM-MCL.pl
              - MON.rb
              - PAR.rb
              - SIM.rb
              - SND.rb
              - ...
            - ...


1.2.2 GLUT update
-----------------

Redhat Linux 9.0 is shipped with glut-3.7-12, that is not 
imcompatible with current version of Galatea FSM.

You can check the version of GLUT installed in your system.

+--------------------------------------------------------------------+
| $ rpm -q glut                                                      |
| glut-3.7-12                                                        |
+--------------------------------------------------------------------+

The procedure of updating GLUT is:

+--------------------------------------------------------------------+
| $ su                                                               |
| # rpm -e glut-devel-3.7-12                                         |
| # rpm -Uvh glut-3.7-14.i386.rpm                                    |
| # rpm -ivh glut-devel-3.7-14.i386.rpm                              |
+--------------------------------------------------------------------+


1.2.3 FSM setup
-------------------------------------

Please test FSM as a stand-alone software.

+--------------------------------------------------------------------+
| $ pwd                                                              |
| /home/demo/galatea-v3.0                                            |
| $ cd FSM/bin                                                       |
| $ ./fsm                                                            |
+--------------------------------------------------------------------+

Mouse operation:

    - Left button drag   - X-Y axis rotation
    - Middle button drag - X-T axis movement
    - Right button drag  - scale change

Keyboard operation:

    - "r" or "R" - reset movement via mouse
    - "f" or "F" - full screen mode (cannot return to the default mode)
    - "Esc"      - exit

+------ changing frame-rate ----------------------------------+
| FSM/data/config.txt                                         |
|+-----------------------------------------------------------+|
|| #MaxFrameRate 30                                          ||
|| MaxFrameRate 100                                          ||
|+-----------------------------------------------------------+|
+-------------------------------------------------------------+


1.2.4 Java setup
------------------------

Java2 SDK for Linux (RPM) is available from:
http://java.sun.com/
J2SE version 1.4.2 or later is recomended.

+--------------------------------------------------------------------+
| $ chmod 755 j2sdk-1_4_2-linux-i586-rpm.bin                         |
| $ ./j2sdk-1_4_2-linux-i586-rpm.bin                                 |
| $ su                                                               |
| # rpm -ivh j2sdk-1_4_2-linux-i586.rpm                              |
+--------------------------------------------------------------------+

RedHat Linux has /usr/bin/java, which is not Sun Java.

+--------------------------------------------------------------------+
| # cd /usr/bin/                                                     |
| # mv java java.org                                                 |
+--------------------------------------------------------------------+

Make sure your system has /usr/local/bin/java.

+--------------------------------------------------------------------+
| # cd /usr/local/bin                                                |
| # ln -s /usr/java/j2sdk1.4.2_03/bin/j* .                              |
| # exit                                                             |
+--------------------------------------------------------------------+


1.2.5 Japanese text analyser (morph) for speech synthesys
-------------------------------------

Install of darts and chasen is required.

darts-0.2:

+--------------------------------------------------------------------+
| $ pwd                                                              |
| /home/demo/galatea-v3.0/morph                                      |
| $ cd darts-0.2                                                     |
| $ ./configure                                                      |
| $ make                                                             |
| $ make check                                                       |
| $ su                                                               |
| # make install                                                     |
| # exit                                                             |
| $ cd ..                                                            |
+--------------------------------------------------------------------+

chasen-2.3.3:

+--------------------------------------------------------------------+
| $ pwd                                                              |
| /home/demo/galatea-v3.0/morph                                      |
| $ cd chasen-2.3.3                                                  |
| $ ./configure --prefix=/usr/local/chasen-2.3.3                     |
| $ make                                                             |
| # su                                                               |
| # make install                                                     |
| # exit                                                             |
| $ cd ..                                                            |
+--------------------------------------------------------------------+

+------ unidic compile  ---------------------------------------+
|This process is not necessary.                                |
|+------------------------------------------------------------+|
|| $ pwd                                                      ||
|| /home/demo/galatea-v3.0/morph                              ||
|| $ cd unidic-1.1.0                                          ||
|| $ ./configure --with-mkchadic=../chasen-2.3.3/mkchadic \   ||
||     --with-chasen-config=../chasen-2.3.3/chasen-config \   ||
||     --with-exclude-dic=fillers.dic                         ||
|| $ make                                                     ||
|+------------------------------------------------------------+|
+--------------------------------------------------------------+


1.2.6 Volume control
----------------------------

+--------------------------------------------------------------------+
| $ gnome-volume-control &                                           |
+--------------------------------------------------------------------+

+--------------------------------------------------------------------+
| vol :   mute-off,              move slider to appropriate position
| pcm :   mute-off,              move slider to appropriate position
| mic :   mute-on, recording-on
| igain : mute-on, recoding-off  move slider to appropriate position
+--------------------------------------------------------------------+

+--------------------------------------------------------------------+
| $ gnome-sound-recorder &                                           |
+--------------------------------------------------------------------+

[record] -> speak to mic -> [stop] -> [play]


1.2.7 Speech synthesis (SSM) setup
-----------------------------

NOTICE:
Galatea is developed and tested with Japanese environment.
You may need change default locale as follows:

 $ export LANG=ja_JP.eucJP
 $ export LC_ALL=ja_JP.eucJP

Execute RUN script and tests.

+--------------------------------------------------------------------+
| $ pwd                                                              |
| /home/demo/galatea-v3.0/SSM                                        |
| $ perl RUN                                                         |
+--------------------------------------------------------------------+

+------ FYI: ssm.conf and chasenrc ---------------------------------+
|If you have to modify GalateaTalk, please check the related
|configulation files are appropreate.
|                         
|    List 1.1 SSM/ssm.conf
|--------------------------------------------------------------------|
| # path name of 'chasen'                                            |
| CHASEN: /usr/local/chasen-2.3.3/bin/chasen                         |
|                                                                    |
| # configuration file for 'chasen'                                  |
| CHASEN-RC: ./chasenrc                                              |
|                                                                    |
| # command of running 'chaone'                                      |
| CHAONE: /usr/local/bin/java -jar ../morph/chaone-1.1.0.jar         |
|--------------------------------------------------------------------|
|    List 1.2 SSM/chasenrc
|--------------------------------------------------------------------|
| (GRAMMAR  ../morph/unidic-1.1.0)                                   |
|--------------------------------------------------------------------|
+--------------------------------------------------------------------+


1.2.8 Speech recognition (SRM) setup
-----------------------------

+--------------------------------------------------------------------+
| $ cd /home/demo/galatea-v3.0                                       |
| $ cd SRM                                                           |
| $ ./configure                                                      |
| $ perl ./SRM_Main.pl                                               |
| set Run = INIT                                                     |
| set Run = START                                                    |
+--------------------------------------------------------------------+

Speak for example "uwagi wo shiro ni shite kudasai" 
and check the results.

Type the following command directly to the console
for testing the grammar change.

+--------------------------------------------------------------------+
| set Grammar = GramXML/renraku/renraku.xml                          |
+--------------------------------------------------------------------+

Speak for example "kai sensei no renraku saki wo oshiete kudasai"
and check the results.

Exit : Control-C

+------ recompile julian (SRM subprocess) ---------------------------+
|This procedure is usually not required.
|+------------------------------------------------------------------+|
|| $ tar xzvf julius-3.3p3-Galatea.tar.gz                           ||
|| $ cd julius-3.3p3-Galatea                                        ||
|| $ ./configure --enable-julian                                    ||
|| $ make                                                           ||
|| $ cp julius/julian adinrec/adinrec adintool/adintool \           ||
||   gramtools/generate/generate \                                  ||
||   gramtools/accept_check/accept_check \                          ||
||   gramtools/mkdfa/mkfa-1.44-flex/mkfa ../bin                     ||
|+------------------------------------------------------------------+|
+--------------------------------------------------------------------+


1.2.9 Task manager (TM) test
------------------------------------

TM can be used for integration test of FSM, SSM and SRM modules.
Galatea DM, however, is not using TM itself.

+--------------------------------------------------------------------+
| $ cd /home/demo/galatea-v3.0                                       |
| $ cd TM                                                            |
+--------------------------------------------------------------------+

+--------------------------------------------------------------------+
| $ ./demo_Repeat.sh                                                 |
+--------------------------------------------------------------------+

+--------------------------------------------------------------------+
| $ ./demo_Appoint.sh                                                |
+--------------------------------------------------------------------+

+--------------------------------------------------------------------+
| $ ./demo_Renraku.sh                                                |
+--------------------------------------------------------------------+


1.2.10 Ruby/TK check
---------------------

+--------------------------------------------------------------------+
| $ ruby -r tcltk -e "p 'ok'"                                        |
+--------------------------------------------------------------------+

If "ok" is not shown, please install:

    - ruby-1.6.8-5
    - ruby-tcltk-1.6.8-5


1.3 Galatea DM setup
---------------------


1.3.1 Check audio volume
----------------------------

Please use gnome-volume-control,
or if you are using alsa sound driver:
+--------------------------------------------------------------------+
|$ cd DM                                                             |
|$ ./setup_amixer                                                    |
+--------------------------------------------------------------------+

1.3.2 Executing dialog (galatea command)
---------------------------------

The executable file of Galatea DM is 'galatea'.

+--------------------------------------------------------------------+
| $ cd galatea-v3.0                                                  |
| $ cd DM                                                            |
| $ ./galatea tests/weather.vxml                                     |
+--------------------------------------------------------------------+

Please wait patiantly until he dialog starts.
It usually takes about 15 seconds until FSM window appears,
and 30 seconds until the dialog starts. 
The time may change depending on your machine performance.

You can terminate Galatea DM by pressing Ctrl-C.

+------ changing current directory ----------------------------------+
|You may want to change INSTALLDIR value to execute galatea command
|other than the DM directory.
|    List 1.3 DM/galatea 
|--------------------------------------------------------------------|
| #INSTALLDIR=.                                                      |
| INSTALLDIR=/home/demo/galatea-v3.0/DM                              |
|--------------------------------------------------------------------|
+--------------------------------------------------------------------+


1.3.3 Terminating garbage process (fin command)
-------------------------------------

Galatea DM sometimes leaves garbage subproceses.
You can use script for clean-up processes.

+--------------------------------------------------------------------+
| $ ./fin                                                            |
+--------------------------------------------------------------------+


1.3.4 Interpretation-only mode (-p option)
----------------------------------------------

galatea -p option can be used for just checking the syntax of 
VoiceXML documents and interpretation result 
of intermediate format (.pdoc).

+--------------------------------------------------------------------+
| $ ./galatea -p tests/kani.vxml                                     |
+--------------------------------------------------------------------+

You can execute .pdoc file with galatea DM interpreter.
Specification of pdoc may changed, so the detail is undocumented now.

+--------------------------------------------------------------------+
| $ ./galatea -p tests/kani.vxml > _kani.pdoc                        |
| $ ./galatea _kani.pdoc                                             |
+--------------------------------------------------------------------+


1.3.5 Show version (-v option)
------------------------------------

+--------------------------------------------------------------------+
| $ ./galatea -v                                                     |
+--------------------------------------------------------------------+


2 VoiceXML Samples
----------------------------

    Table 2.1 tests/*.vxml list 
+--------------------------+----------------------------------------------------+
|drivenavi.vxml            | 
|--------------------------+----------------------------------------------------|
|kani.vxml                 | 
|--------------------------+----------------------------------------------------|
|ssmdemo.vxml              | 
|--------------------------+----------------------------------------------------|
|gtalk.vxml                | 
|--------------------------+----------------------------------------------------|
|number.vxml               | 
|--------------------------+----------------------------------------------------|
|menu.vxml                 | 
|--------------------------+----------------------------------------------------|
|weather.vxml              | 
|--------------------------+----------------------------------------------------|
|clear.vxml                | 
|--------------------------+----------------------------------------------------|
|filled.vxml               | 
|--------------------------+----------------------------------------------------|
|promptcount.vxml          |
|--------------------------+----------------------------------------------------|
|var.vxml                  |
|--------------------------+----------------------------------------------------|
|break.vxml                |
|--------------------------+----------------------------------------------------|
|help.vxml                 |
|--------------------------+----------------------------------------------------|
|if.vxml                   |
|--------------------------+----------------------------------------------------|
|reprompt.vxml             |
|--------------------------+----------------------------------------------------|
|emotion.vxml              |
|--------------------------+----------------------------------------------------|
|native.vxml               |
|--------------------------+----------------------------------------------------|
|par.vxml                  |
|--------------------------+----------------------------------------------------|
|recogsym.vxml             |
|--------------------------+----------------------------------------------------|
|appli/drivenavi_start.vxml|
+--------------------------+----------------------------------------------------+


2.1 drivenavi.vxml
------------------

+--------------------------------------------------------------------+
|  ./galatea tests/drivenavi.vxml                                    |
+--------------------------------------------------------------------+


2.2 kani.vxml
-------------

+--------------------------------------------------------------------+
| ./galatea tests/kani.vxml                                          |
+--------------------------------------------------------------------+


3 About Galatea DM 
-------------------


3.1 VoiceXML details
--------------------------


  VXML2.0        W3C VoiceXML 2.0 (http://www.w3.org/TR/voicexml20/)?

  SRGS1.0        W3C Speech Recognition Grammar Specification 1.0
                 (http://www.w3.org/TR/speech-grammar/)
                 Galatea extention : <token phoneme=""> <token sym="">

  JEIDA-62-2000  Speech Synthesis Markup: JEIDA-62-2000

  Galatea        <emotion> <native>

  ECMAScript     http://www.ecma-international.org/publications/standards/ECMA-262.HTM



4 Extentions
--------------------------

4.1 MON (Galatea Monitor)
----------------------------------------

+--------------------------------------------------------------------+
| $ cd /home/demo/galatea-v3.0                                       |
| $ cd AM                                                            |
| $ perl ./AgentManager.pl -C ../DM/Modules/am4dm.conf               |
+--------------------------------------------------------------------+

Window pane:

  upper: System Log (Syslog)     
  lower: Application Log (Applog)

Galatea Monitor GUI:

    - 
      File
          - Clear Logs 
          - Save Syslog
          - Save Applog
    - 
      Bg
          - bg1, bg2, bg3, bg4
    - 
      Mask
          - man01, man02, woman01
    - 
      Speaker
          - male01, male02, female01
    - 
      Auto
          - AutoBlink OFF
          - AutoBlink ON 
          - AutoMove OFF 
          - AutoMove ON
    - 
      FaceExp
          - Neutral
          - Happy, Disgusted, Sad, Angry, Surprised, Feared
    - 
      HeadRot
          - Left 
          - Center
          - Right 
    - 
      EyeRot
          - Left 
          - Center
          - Right
    - 
      FaceMot
          - Blink
          - Nod 
          - Refuse
          - Listen
    - 
      Demo
          - Say Hello
          - Say Bye 
          - Use PAR 
          - Use SND (/usr/share/sndconfig/sample.au)
    - 
      SRM
          - Start 
          - XML renraku 
          - Julian vfr
          - Julian name
          - Pause
          - Resume
          - Stop 


4.2 SND module
----------------------

The implemation of SND is experimental.

SND uses : /usr/bin/play

    List 4.1 SND command
----------------------------------------------------------------------
 to @SND set Play = /usr/share/sndconfig/sample.au
 From @SND tell start /usr/share/sndconfig/sample.au
 From @SND tell end /usr/share/sndconfig/sample.au
----------------------------------------------------------------------


4.3 PAR module
----------------------

The implemation of PAR is experimental.

    List 4.2 PAR usage
----------------------------------------------------------------------
 to @PAR set Init = 1
 to @PAR set Cmd = sleep 1.0
 to @PAR set Cmd = to @FSM set FaceExp = HAPPY 1 100 1000
 to @PAR set Cmd = sleep 1.4
 to @PAR set Cmd = to @FSM set FaceExp = SAD 1 100 1000
 to @PAR set Cmd = sleep 2.0
 to @PAR set Cmd = to @FSM set FaceMot = NOD 1
 to @AM-MCL set Speak = foobar
----------------------------------------------------------------------


4.4 GUI module
----------------------

The implemation of GUI is experimental.

Please change configuration as follows to use GUI.

    List 4.3 DM/Modules/am4dm.conf 
----------------------------------------------------------------------
 module:GUI commands:cd ../DM/Modules ; ruby ./GUI.rb
----------------------------------------------------------------------

    List 4.4 GUI command
----------------------------------------------------------------------
 to @GUI set Text = message
 to @GUI set F1 = label text-send-to-dm
----------------------------------------------------------------------


4.5 SIM and DM-MCL modules
------------------------------------

SIM and DM-MCL are helper modules of Galatea DM.
Specifications may changed, so the detail is undocumented now.


5 Copyright
-------------------------------

    - 
      Galatea Dialog Manager
          - (c)2003 Takuya NISHIMOTO (nishi@hil.t.u-tokyo.ac.jp)
          - 
            Based on "Phoenix" Task Manager
                - 2002-2003 by Takuya NISHIMOTO (University of Tokyo)
                - 2001-2002 by Takuya NISHIMOTO and Mitsuhiro KIZU
                  (Kyoto Institute of Technology)
    - 
      Uses Relaxer (phoenix/relaxer)
          - Files generated by Relaxer are under the Apache licence.
          - Relaxer Version 1.0RC by asami@relaxer.org
          - http://www.relaxer.org/
    - 
      Uses Mozilla Rhino executables (as-is) (lib/js.jar)
          - Galatea-DM is Larger Works as defined in NPL 1.1.
          - Mozilla Rhino 1.5R4.1
          - The source code for Rhino is available under NPL 1.1.
          - http://www.mozilla.org/rhino/
