=================================================
 ######  #######    #    ######  #     # #######
 #     # #         # #   #     # ##   ## #
 #     # #        #   #  #     # # # # # #
 ######  #####   #     # #     # #  #  # #####
 #   #   #       ####### #     # #     # #
 #    #  #       #     # #     # #     # #
 #     # ####### #     # ######  #     # #######
=================================================

--------------
 Introduction
--------------

Vox launcher is a simple speech-to-command program in Python that uses 
the Google's Speech Api to convert speech into text and then execute a command
on the local machine.


---------
 License
---------

This Program is distributed under the Gnu General Public License version 3.
See the file COPYING for details.


--------------
 Installation
--------------

Please read the INSTALL file located on the current folder.


----------------------
 Runtime Requirements
----------------------

This program is designed to run on Linux and depends on: 
- python-gtk2(>=2.16)
- python-dbus
- python-alsaaudio(>=0.5)
- python-xlib
- python-gobject-2(>=2.16)
- python-simplejson
- pynotify
- speech-dispatcher
- python-speechd
- xautomation
- python-sparqlwrapper
- sox

If you are using ubuntu you can simply run this command: 

  # sudo apt-get install python-dbus python-alsaaudio python-simplejson python-notify python-speechd speech-dispatcher xautomation python-sparqlwrapper
 
 
-------
 Usage
-------

Just run vox-launcher and speak!
Wait a bit and the related action will be done.
When the microphone in panel's notification area is red the program is not ready to listen you;
please wait the green light before speak an other time.

Examples
--------

vox-launcher can be used to launch processes:

  "open firefox"

Vocal Command list
------------------

You can see the default command list handled by vox launcher reading the left column
of your language configuration file (e.g. /etc/vox-launcher/vox_launcher_it.conf).
If the recognized words are not declared in the configuration file vox launcher will try 
to launch the recognized text as is.

Query/Answering
---------------
If the recognized test is not a command the program interpret your request as a query and it try
to answer using wikipedia data.

Now you can make query with these formats:
- Who is <Name Surmane>? (e.g. Who is Barack Obama?)
- What is <search query>? (e.g. What is Freemasonry?)

In italian language
- Chi è <Nome Cognome> (es. Chi è Beppe Grillo?)
- Cosa è <Soggetto> (es. Cosa è Massoneria?)

also these shortly form are allowed:
- <Name Surname> (e.g. Barack Obama)
- <search query> (e.g. Freemasonry)

Fast web access
---------------

You can open website whith this command:
- Go to "website" (e.g. Go to wikipedia)

In italian language:
- Vai su <sito web> (es. Vai su wikipedia)

Text Insertion
--------------

You can insert text with this vocal command:
- Write <string to be written> (e.g. Write George Washinghton)

In italian language:
- Scrivi <frase da srivere> (e.g. Scrivi Giuseppe Garibaldi)

Vocal pointer
-------------

With vox-launcher you will able to move the pointer with voice, the mouse is not required anymore.

Talk the keyword "grid" (or "griglia" if the italian language has been selected) a 3x3 grid on your screen
will appear:

  1 2 3
  4 5 6
  7 8 9 

Please speak the cell number where do you want move the cursor. You can continue to reiterate
the procedure in the selected cell.

When you will are upon the desired screen point you can click the pointer using these vocal command:
- "click"
- "double click" (or "doppio click" if the italian language has been selected)
- "right click" (or "click destro" if the italian language has been selected)

Customization
-------------

Vox launcher is highly configurable modifying some configuration file located
under the /etc/vox-launcher folder.
In order to customize the vox laucher we must edit the the correspondent language file.
For example to customize the recognition in italian language we can modify the
/etc/vox-launcher/vox_launcher-it_IT.conf file.

The semantic of the conf file is the simplest as possible following the behavioural 
stimulus-response pattern:

[detected word] -> [command to run]

e.g.
browser -> chromium-browser

Voice launcher when will detect the browser world will launch the chromium-browser command.
You can change the default browser from chromium to firefox simply changing the previous line 
into:

browser -> firefox

-------
 Info
-------

  * To get info about the tool, please contact:

      pilolli.pietro@gmail.com

  * To report bugs, please contact:

      pilolli.pietro@gmail.com


Have fun!

===
EOF
===