After a successful installation, three new services will be available to run:

• dynlog
• phoneglue
• voiceglue

They cannot be started successfully, however, until Asterisk is properly configured.

The phoneglue service needs to log in to the Asterisk manager with username “phoneglue” and password “phoneglue” (configurable with command-line arguments), so configure Asterisk's manager.conf with an entry like this for Asterisk 1.2 and 1.4:

     [phoneglue]
     secret=phoneglue
     read = system,call,log,verbose,command,agent,user
     write = system,call,log,verbose,command,agent,user

and like this for Asterisk 1.6:

     [phoneglue]
     secret=phoneglue
     read = system,call,log,verbose,command,agent,user,originate
     write = system,call,log,verbose,command,agent,user,originate

Also make sure you have:

     enabled=yes

in the same file.

Phoneglue also needs to be contacted via FastAGI for all calls that it will handle, and it needs to use a particular context, extension, and priority to send calls to itself. So put a context like this in Asterisk's extensions.conf:

     [phoneglue]
     exten => 1,1,Answer
     exten => 1,2,Agi(agi://localhost)
     exten => 1,3,Hangup

(Phoneglue can use a different context, extension, and priority than these by using command-line arguments to phoneglue.)

The result of this is that whenever an Asterisk call is directed to the “phoneglue” context at extension 1 and priority 1, it will get routed to the phoneglue program, which will in turn route it to voiceglue.

The asterisk dialplan can pass per-call parameters to voiceglue. If the AGI command to start voiceglue appears as above, e.g.:

      Agi(agi://localhost)

then the /etc/voiceglue.conf file will be used to determine the mapping of calls to initial VXML documents.

However, the AGI command can specify the initial VXML document's URL explicitly, and it can optionally pass parameters to that document. To do this, use an AGI command like this in the dialplan:

      Agi(agi://localhost/url=http%3A%2F%2Falt.com%2Fvxml%2Fdoit.vxml&arg1=foo&arg2=bar)

This will load the first VXML page from http://alt.com/vxml/doit.vxml, and will pass remaining urlencoded arguments vertabim to that URL. Notice that percent-encoding (a.k.a. url-encoding) must be used to protect the parameters from further interpretation by the AGI command. For details on percent-encoding, see a reference such as http://en.wikipedia.org/wiki/Percent_encoding

To use Asterisk variables to specify the VXML URL and/or args, do something like the following in the extensions.conf dialplan:

      Set(vxmlurl=http%3A%2F%2Falt.com%2Fvxml%2Fdoit.vxml)
      Set(vxmlarg=foo)
      Agi(agi://localhost/url=${vxmlurl}%26arg=${vxmlarg})

Notice that %26 is the ampersand (&) url-encoded (this is needed at least with Voiceglue 0.9 and Asterisk 1.4).

Also notice that if you are going to pass another URL as a parameter, then you need to URL encode also the percent sign. E.g.:

      Set(vxmlurl=http%3A%2F%2Falt.com%2Fvxml%2Fdoit.vxml)
      Set(vxmlarg=http%253A%252F%252Fanother.site%252Fdot%252Fcom.vxml)
      Agi(agi://localhost/url=${vxmlurl}%26arg=${vxmlarg})

If you are getting the url from an external source (SIP for instance), then you can encode it like this:

      Set(uri_encoded=${URIENCODE(${BASE64_ENCODE(${external_uri})})})
      Agi(agi://localhost/url=${vxmlurl}%26uri=${uri_encoded})

Remember to (base64) decode it in your script!

Even if you use explicit arguments to the AGI command in your asterisk dialplan, the /etc/voiceglue.conf file must be present and valid. The file /etc/voiceglue.conf containins a whitespace-separated DNIS (incoming number) and url pair per line. Such a pair maps the incoming phone number to that url to load. As mentioned above, when passing parameters to the AGI command from asterisk, this is ignored.

The /etc/voiceglue.conf file can be changed dynamically and voiceglue will immediately notice any changes. The wildcard dnis * can be used to match anything that isn't matched otherwise.

So, an example /etc/voiceglue.conf could contain:

        * http://localhost/vxml/welcome-audiofile.vxml

This would result in all incoming calls being handled by the welcome-audiofile.vxml script found at http://localhost/vxml/.

By default, the dynlog program collects all logs from the phoneglue and voiceglue processes. It is not strictly required, but without it you will be scouring multiple log files to find out what's happening. The logs are written to /var/log/dynlog/dynlog. Dynlog has a dynamic log-level changing capability, so by running “dynlog_level 7” you will get the full output from all voiceglue components. Running “dynlog_level 4” will get you back to a more sane level. These levels are identical to those used by syslog. I recommend setting the level to 7 (the highest) when you are trying to debug a problem with voiceglue. Note that you don't have to stop or re-start anything; dynlog and its clients coordinate dynamically to achieve the appropriate level of logging. Note, also, that this could cause massive performance changes if done on a loaded system.

The VXML <log> markups appear in dynlog as well, and are assigned log level 5.

After performing the above configuration steps and making sure asterisk is running, start the voiceglue services by rebooting or running as root:

      /etc/init.d/dynlog start
      /etc/init.d/phoneglue start
      /etc/init.d/voiceglue start

These services must always be brought up in this order (and after Asterisk is running), and be brought down in the reverse order.

Once everything is up and stays up, you should be able to call in and have the VXML file(s) specified in /etc/voicemail.conf or in the arguments interpreted.

Using an alternate TTS implementation should be fairly straightforward. Every time a TTS is required, voiceglue runs the /usr/bin/voiceglue_tts_gen program with two arguments. The first is the text to create, the second is the file in which to place the audio. (This audio file must be in a format that asterisk is happy with).

The default implementation of voiceglue_tts_gen for flite is:

#!/usr/bin/perl --       -*-CPerl-*-
$file = $::ARGV[$#ARGV];
system ("flite", @::ARGV);
system ("mv", $file, $file . ".16khz.wav");
system ("sox", $file . ".16khz.wav", "-r", "8000", $file);

The last two lines convert the format from flite's default (on Ubuntu) output of 16khz wav to 8khz.

If you want to use Cepstral, this voiceglue_tts_gen file has worked:

#!/usr/bin/perl --       -*-CPerl-*-
# Cepstral interface
$file = $::ARGV[$#ARGV];
system ("/usr/local/bin/swift", "-m", "text", "-o" , $file , $ARGV[1]);

The directory “examples” here contains some example VXML files that work with voiceglue. Keep in mind that there is much (some say too much) latitude in the VXML specification as to what could be supported, so not all VXML files will run without modification. Specifically, voiceglue only supports simple SRGS XML DTMF grammars, and no speech input (but working on it).

Here are what the example files do:

welcome-tts.vxml – Speaks “Welcome” in TTS

welcome-audiofile.vxml – Recorded audio of Allison saying “Welcome”

single-digit-input.vxml – Repeatedly gets and speaks a single digit

menu-input.vxml – Repeatedly gets a menu input

multi-digit-input.vxml – Repeatedly gets and speaks multiple digits

record-audio.vxml – Repeatedly records audio from the caller