The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
VoiceXML-Server-1.6
River stage zero No dependents
++
/ VoiceXML::Server

NAME

VoiceXML::Server -- An easy-to-use VoiceXML server class

SYNOPSIS

 #!/usr/bin/perl -w
 use diagnostics;
 use strict;

 require VoiceXML::Server;
 my $server = VoiceXML::Server->new(avoidfirewall => 1);

 $server->Audio("Pick a number between 1 and 99.");

 my $num = int(rand(99)) + 1;

 while (1) {
     my $guess = $server->Listen(grammar => "NATURAL_NUMBER_THRU_99");
     if ($guess < $num) {
         $server->Audio("No, $guess is too low.  Try again.");
     } elsif ($guess > $num) {
         $server->Audio("No, $guess is too high.  Try again.");
     } else {
         $server->Audio("That's right, my number was $num.  OK, " .
                        "let's play again.  I'm thinking of a " .
                        "different number.");
         $num = int(rand(99)) + 1;
     }
 }

DESCRIPTION

VoiceXML::Server is a class implementing a simple server for VoiceXML applications. It was designed in particular to work with Tellme Studio ( http://studio.tellme.com/ ), although it should also work with other VoiceXML products.

Using this library, you can make programs that you interact with over the phone. Using Tellme Studio, you can develop and debug your program by calling a toll-free number. You can then publish your finished application to be a part of the main Tellme service, at 1-800-555-TELL.

Applications written using VoiceXML::Server install as a CGI scripts. However, unlike most web server software, they do not get repeatedly executed every time the user responds to an interaction. Instead, the script gets invoked only once per user, and it can remember the state of the interaction on the stack and in local variables. This is a much, much easier way to code than traditional web solutions provide, as the above example should illustrate.

The disadvantage of this approach is that it can be more expensive to support, and performance can suffer compared to hand-tuned VoiceXML code.

INSTALLATION

The trickiest part of all this is setting up Tellme Studio and an initial application and getting things up and limping. Once you've done that, it's easy to tweak the application to make it do virtually anything you can think of.

Here's the steps to get the above "guess a number" example code up and running.

First, get yourself a webserver where you can install CGI scripts. Learning about that is beyond the scope of this document.

Next, make sure that the version of perl on that server includes this VoiceXML::Server module. This is done by the usual CPAN method of unpacking the tarball and running the following commands (you may have to be root to do 'make install'):

    perl Makefile.PL
    make
    make test
    make install

Next, cut and paste the above example code into a file on your server. I'll assume that file is called "guessanumber.cgi". You may need to change the first line to point to your perl executable.

Next, you can run the "guessanumber.cgi" executable on the command line. The VoiceXML::Server library will automatically detect that you are running on the command line instead of being served from a webserver, and will play the game in dumb terminal mode. This is a very useful technique for debugging the logic of your program without worrying about all the telephony details.

When you can run guessanumber.cgi on the command line, then you know you have all the perl setup done properly. Next, go to http://studio.tellme.com/ and create an account by clicking the "join studio" link. This is all pretty self-explainatory.

Once you're able to log into your Tellme Studio account, and have accepted the terms of service, you need tell Studio where your application lives. Click on the "MyStudio" link at left of the screen. Log in if necessary. Make sure the "Application URL" tab is selected; click on it if it is not. Then type the full URL to get to your guessanumber.cgi script, and click the "Update" button.

At this point, you should be able to call the toll-free number listed on that page. Enter your Studio Developer ID and PIN on the phone, and you should find yourself playing the "guess a number" game.

METHODS

The following methods are available:

$server = VoiceXML::Server->new([name => value, ...]);

Constructs the server object. Can take the following named arguments:

minport

Specifies the smallest port number to try and use. Defaults to 7500.

maxport

Specifies the biggest port number to try and use. Defaults to 7550.

avoidfirewall

If set to 1 (as in the example at the top of this document), then extra stuff will be done to avoid firewalls. VoiceXML::Server works by spawning off a new server process, speaking the HTTP protocol, usually on a port between 7500 and 7550. Sometimes firewalls will get in the way and prevent the VoiceXML browser from reaching these ports. If you turn on avoidfirewall, then things will always work, but there will be a noticable performance penalty. If at all possible, don't use this.

If all the ports in the designated range are already being used, it will continue to try and use a higher port number, but will turn on the avoidfirewall behavior. So, you can just punch a few ports through your firewall, and have things work even if those get filled up.

debug

If you set debug to 1, then files will be created in /tmp containing debugging output. This is very useful to determine what causes crashes or weird behaviors. But remember, the first thing to try is just running your program on the command line.

$server->Audio([wav => 'file.wav'], [tts =>'text here']);

The Audio method takes up to two named parameters, wav and tts. At least one of these must be provided.

wav

wav specifies a .wav audio file. This file will be played.

tts

tts specifies plain text. (tts stands for Text To Speech.) This will be read in a computerized voice over the phone if a .WAV file isn't specified or isn't found.

You can also call Audio with one or two non-named parameters. If you pass it only one parameter, it is assumed to be a tts value. If you pass it two parameters, the first one is treated as a wav value, and the second as a tts value.

$server->Pause(milliseconds => $num)

The Pause method introduces a pause of the given number of milliseconds. Use it between pieces of audio so that the audio sounds more natural. It must be called using the named parameter syntax.

$server->Listen(grammar => $grammar, [nomatch => $nomatchstr], [noinput => $noinputstr], [timeout => $seconds]);

The Listen method will wait for the user to say something, and return that value.

grammar => $grammar

grammar specifies the set of valid expressions that a user can say at this point. To learn more about grammars, please see the Tellme Studio documentation at http://studio.tellme.com/grammarref/. You must specify either grammar or grammarsrc.

grammarsrc => $grammarfile

grammarsrc specifies a file containing a grammar. The grammar file will be downloaded in a separate server transaction, much as audio files (or image files in the HTML world) get downloaded separately. This is the right thing to do if your grammar is very big and does not dynamically change.

nomatch => $nomatch

nomatch specifies what value to return if the user says something that could not be matched by the grammar. If you do not give this parameter, then the VoiceXML::Server library will automatically tell the user it didn't understand and will reprompt them. This behavior does not always work out so well, though, and it is a good idea to provide your own nomatch handling.

noinput => $noinput

noinput specifies what value to return if the user does not say anything. If you do not give this parameter, then the VoiceXML::Server library will automatically tell the user it didn't hear anything and will reprompt them. This behavior does not always work out so well, though, and it is a good idea to provide your own noinput handling.

timeout => $seconds

timeout specifies how many seconds to wait before generating a noinput event. If you do not specify one, a platform default value is used.

$server->GoToURL(url)

GoToURL is used to exit your application. It specifies a URL of another VoiceXML page that should be loaded.

CHANGE LOG

 * $Log: Server.pm,v $
 * Revision 1.6  2000/10/03 22:07:08  weissman
 * Fixed minor typo.
 *
 * Revision 1.5  2000/10/03 19:17:25  weissman
 * Added "Cache-Control: no-cache" header.
 *
 * Revision 1.4  2000/09/29 22:35:54  weissman
 * Added 'grammarsrc' parameter to Listen(), so that you can now specify
 * a separate grammar file.
 *
 * Revision 1.3  2000/09/27 22:23:53  weissman
 * GoToURL() wasn't working if given a relative URL.
 *
 * Revision 1.2  2000/09/27 18:22:05  weissman
 * Allow specifying the range of ports to use.
 *
 * Revision 1.1  2000/09/26 23:26:53: weissman
 * Initial release of Server::VoiceXML module.

AUTHOR

Terry Weissman <weissman@tellme.com>

Web page: http://studio.tellme.com/downloads/VoiceXML-Server/