=================
INSTALL
=================

Requirements
=============

SpeechLion requires the following software packages to
run:

+ Java_ runtime environment 1.6 or greater
+ Jython_ 2.2.1 or greater
+ Sphinx-4_ 1.0beta4 or newer
+ Optional: FreeTTS_ 1.2.2 binary or greater


Install Java_ 1.6 JRE
======================

Sphinx-4 is written in Java and therefore requires the JVM
to run.  To install Java on Ubuntu Linux, this requires the following::

  sudo apt-get install sun-java6-jre

SpeechLion may not work with other JVMs besides the Sun JVM.  To ensure that 
you are using Sun's JVM by default on Ubuntu, do the following::

  sudo update-alternative --config java

and choose the one with ``java-6-sun`` in the path.


Install Jython_ 2.2.1
=======================

SpeechLion is written in Jython.  This is the Python programming
language running on top of the JVM.  It is excellent for scripting
Java programs and rapid development.  To install Jython on Ubuntu Linux, do
the following::

  sudo apt-get install jython

Now test that jython is working::

    jython

You should see some messages followed by the ``>>>`` jython prompt.
Press the ``ctrl-D`` key sequence to exit.


Install sharutils
==================

Sphinx-4 requires ``sharutils``.  To install it on
Ubuntu Linux::

  sudo apt-get install sharutils


Install Sphinx-4_ 1.0beta4
================================

See the `Sphinx-4 download instructions`__ for more details.

__ http://cmusphinx.sf.net/sphinx4/#download_and_install

Download the `Sphinx-4 1.0beta4`_ package from SourceForge.
Next::

  unzip sphinx4-1.0beta4-bin.zip
  cd sphinx4/lib
  sh jsapi.sh

Now accept the BCL license agreement which will unpack ``jsapi.jar``.

Now test Sphinx-4::

  cd ..
  java -jar bin/Dialog.jar

Press ``ctrl-C`` to exit the Sphinx4 dialog demo.

.. _Sphinx-4 1.0beta4: 
   http://sourceforge.net/projects/cmusphinx/files/sphinx4/1.0%20beta4/sphinx4-1.0beta4-bin.zip/download

Optional: Install FreeTTS_ 1.2.2 binary
=======================================

FreeTTS is used to provide spoken acknowledgement of speech input.
See the `FreeTTS download instructions`__ for more details on
installing FreeTTS.

__ http://freetts.sourceforge.net/docs/index.php#download_and_install

Download the `FreeTTS 1.2.2 binary package`_ from SourceForge.
Next::

  unzip freetts-1.2.2-bin.zip
  cd freetts-1.2
  cp speech.properties ~
  cd lib
  sh jsapi.sh

Now accept the BCL which will unpack ``jsapi.jar``.

Test FreeTTS::

  cd ..
  java -jar bin/HelloWorld.jar

You should hear a computerized voice say "hello world".

.. _FreeTTS 1.2.2 binary package: 
   http://prdownloads.sourceforge.net/freetts/freetts-1.2.2-bin.zip?download


Configure SpeechLion Paths
===========================

The ``speechlion`` script simply runs ``jython`` with the appropriate 
``CLASSPATH`` settings and other options.  Simply modify ``speechlion`` 
so that ``SPHINX4`` points to your Sphinx-4 installation and ``FREETTS``
points to your FreeTTS installation.

If you don't have FreeTTS installed, SpeechLion should detect
this and print a message at startup.

Run SpeechLion
===============

If everything is built and installed correctly, try running
SpeechLion from its installed directory::

  ./speechlion

Startup is fairly slow, be patient.  Assuming nothing crashes, when
you see the message ``start speaking``, you can now start speaking
commands to it.  Try putting your mouse pointer over your Firefox
window and say "browse google".

Now read the documentation in the USAGE file.


.. _Java:     http://java.sun.com
.. _Jython:   http://www.jython.org
.. _Sphinx-4: http://cmusphinx.sf.net/sphinx4
.. _FreeTTS:  http://freetts.sf.net