ID : README Sun Apr 30 01:21:59 EDT 2006 ground/X

README for agi applications

by ground Email <grnd@users.sourceforge.net>

The following applications are included in this package:
bashlib.agi: Main library of functions used by all of the other scripts.  
The APIs supported by this library will be covered later in this document.
bboard.agi: General message board for asterisk
logtail.agi: Tail files and speak new output to a phone as it arrives in 
the file. Requires Viavoice and an external program for generating speech.
mpgctrl.agi: Remotely control your MP3 player by using the telephone.
temp.agi: Retrieve the current temperature for a zip code that is 
currently hard coded in the script.
wakeup.agi: Supports generation of wake up calls at a specified time of 
day or in a specified number of minutes.
wthr.agi: Retrieve the forecast for a specified zip code.  This requires 
Viavoice and an external program to generate speech.

Notes:
These programs have not seem much testing outside of my local setup.  You 
will almost certainly have to edit each one of them if you expect good 
results.  This archive also does not contain the sound files that are used 
by these scripts.  Perhaps if demand increases I will make the sound files 
available.  For now you can just email me and ask if you don't feel like 
generating your own.

The wthr.agi and logtail.agi programs both use the Viavoice TTS library 
for speech output.  I have hacked the command line demo application to be 
used with scripts.  The license for Viavoice prevents me from 
redistributing this code.  You might be better off hacking voice support 
for your favorite TTS engine in to bashlib.agi.  Perhaps some day I will 
get around to adding festival support, but this isn't very likely as I 
don't really like the way festival sounds.

bashlib.agi APIs:
Here are the functions and variables that are supported by the bashlib 
library.  

bashlib.agi should be sourced from the main agi script once you have set a
reasonable path containing the GNU Unix utilities.  There is a
customization section at the top of the bashlib script that defines where
the log file will be placed, when debugging output is requested, and other
important paths used by all the scripts.  If you don't have a look at this
section of the script bashlib.agi will likely fail in strange ways.

Special global variables used by bashlib and made available to programs:

$agi_resp: The entire response to the last agi command issued.

$agi_result: The data only to the last AGI response.  This has the AGI 
protocol information striped and contains only the information the user 
entered on the key pad.  These two variables are set by a call to 
get_agi_resp 
discussed later in this document.

$agi_exit_local: This should be set by the calling AGI script to a 
function that will be called on script termination.  This should handle 
local cleanup procedures.  All exits must be tracked by bashlib.agi as it 
creates its own temp files.  You should never directly exit from an agi 
script using bashlib.agi.  Always call the agi_exit function unless you 
really know what you are doing and have reason not to use the library's 
hooks.

$tts_buffer: A variable containing the path to a file where data is 
written that will be spoken by a subsequent call to the tts function.  See 
the information on the tts function later in this file.

function listings:

function: agi_exit
Arguments: 
$1: The exit status (0-255)
$2: If 'q' then exit will be quiet and the user will not get the 
application exiting/application error messages.
Description: Cleans up temp files and exits the script.
Examples:
agi_exit 0 # successful exit
agi_exit 1 q # exit quietly with an error

Function discard_agi_header:
Arguments: None
Description: throws away the AGI header information provided by asterisk.  
This should be used if you don't need any of the header information as it 
is faster than having the script parse the header data.

Function: parse_agi_header
Arguments: none
Description: Parses the AGI header information from asterisk and makes 
that information available in global variables.  Maybe some day I will 
list the global variables in this document, for now RTFS.

Function: debug
Arguments:
$*: Text to write to the debug log or file if enabled.
Description: This will log the specified message to the debug log which 
can either be sent to a file or to the asterisk verbose console.
Example:
debug 'Error in data file, exiting.'
debug "Could not open $input_file"

Function: get_agi_resp
Arguments: none
Description: This will read a response from asterisk and make the data 
available in the $agi_resp and $agi_result variables discussed earlier in 
this document.

Function: play_file
Arguments:
$1: The file to play relative to the top of the asterisk sounds directory
$2: if 1 then  the controlled playback application will be used and the 
user will be able to rewind and fast-forward the playing file.
$3: The number of MS to skip backwards or forwards in a file when the 
rewind and fast-forward keys are pressed.  Defaults to 5000 (5 seconds).
Description: Plays a file to the user.  If controlled playback is used the 
user can rewind with 1, pause with 2, fast-forward with 3, and stop with 4.  
This also calls the get_agi_resp function discussed above so you can use 
the $agi_result variable to get any result from the playing application.  
This result will be the ASCII value of the digit pressed.
Examples:
play_file invalid_extension
play_file user_directory 1 # this one uses controlled playback
play_file user_directory 1 10000 # this one uses controlled playback and 
# changes the skip time to 10 seconds

Function: dump_file
Arguments:
$1: The file to play
Description: Plays a file to the user but does not attempt to parse the 
results of any data the user enters.  This function also does not support 
controlled play back.  The primary use of this function is for playing an 
error message back to a user before exiting a script when something has 
gone very wrong and we might not want to try to parse any results.
Example:
dump_file application_error

Function: tts_init
Arguments; none
Description: This initializes the text to speech sub system of bashlib.  
This function should be called before using the tts function discussed 
below.  This function will return 0 if the tts sub system is successfully 
initialized and 1 if there was a problem.  This function also initializes 
the $tts_buffer variable.

Function: tts
Arguments:
$1: Number of ms to rewind or fast-forward while playing the text.  
Defaults to that set by the play_file function discussed above.  Control 
keys are also the same as in play_file.
Description: This function will use the vv-phone program to generate a 
file called vv.wav which will contain the synthesized text of what is in 
the file pointed to by the $tts_buffer variable.  The function will then 
play vv.wav to the calling user
Example:
Note: This example will show a small skeleton program to speak a line of 
text.  This serves as the example for both the tts_init and tts 
functions.
if ! tts_init
then
agi_exit 1 # Error so do not continue
fi
echo 'This is the text to say' > $tts_buffer
tts
agi_exit 0 # success