NAME

Speech::Festival - Communicate with a festival server process.

SYNOPSIS

use Festival;
$festival = new Festival -host => 'serverhost', -port => 1314;

conn $festival;
disconnect $festival;

request $festival '(some scheme)';
request $festival '(some scheme)', \&result_handler, $args, $for, $handler;

if (result_waiting $festival) { # process it }
wait_for_result $festival, $timeout;
($type, $data) = get_result $festival;

DESCRIPTION

This package provides a simple interface to an instance of the festival speech synthesis system running as a server on some machine. If you want a simple speech-ouput module using this interface see Speech::Synthesis.

Since festival can return an unpredictable number of results from a single request, and since it is useful to process them as they arrive, something a little more complex than a simple remote-procedure-call interface is needed.

There are basicly three ways to organise your application's interaction with festival. In the simplest cases you can pass a result handling procedure along with your request. For more control you can process one value at a time by using result_waiting to poll for results or wait for result to block until a result is available.

In any case results consist of a type and some data. The types are

$Speech::Festival::SCHEME

The data is a Scheme expression, for instance a number or a list.

$Speech::Festival::WAVE

The data is a waveform. what format this is in willbe determined by what you have previously told festival.

$Speech::Festival::OK

All the results for this request have been sent. No data.

$Speech::Festival::ERROR

Festival has reported an error. No data. Unfortunatly festival doesn't sen any information about the error, so for details you will have to check the server's log.

A single festival session (between calls to conn and disconnect) talks to a single Scheme interpreter in festival, and hence state will be remembered between requests.

$festival = new Festival 'serverhost', 1314;

Create a new festival session which will connect to the given host and port. If ommitted these default to localhost and 1314.

conn $festival;

Connect to festival. Returns true if all is well, false otherwise. In the event of an error the variable $speech_error conatains a description of it.

disconnect $festival;

Disconnect from festival. The connection mat be reopened later with conn, but any state will have been lost.

request $festival '(some scheme)';

Send the given Scheme to festival. You should use result_waiting, wait_for_result and get_result to process the results of the request.

request $festival '(some scheme)', \&result_handler, $args, $for, $handler;

Send the given Scheme to festival asking it to call &result_handler on each result returned. The handler is called as:

result_handler($type, $data, $args, $for, $handler)

if (result_waiting $festival) { # process it }

Look to see if there are any results waiting to be processed. This only guarantees that the start of the result has arrived, so a subsequent call to get_result may not return instantly, but should not block for an extended time.

wait_for_result $festival, $timeout;

Blocks until festival sends a result. Timeout is in seconds, if can be omitted, in which case the call waits for an unbounded time. Returns false if he call timed out, true if there is a request waiting. Again, this only guarantees that a result has started to arrive.

($type, $data) = get_result $festival;

Reads a single result.

EXAMPLES

The code below does some arithmatic the hard way.

    use Speech::Festival;
    $festival = new Speech::Festival -host => 'festival-server.mynet';

    conn $festival 
	 || die "can't talk to festival - $speech_error";

    request $festival '(+ 123 456)', 
	    sub {
		my ($type, $data) = @_;

		print "Scheme Result=$data"
			if $type eq $Speech::Festival::SCHEME;
		print "ERROR!\n"
		        if $type eq $Speech::Festival::ERROR;
	    };

AUTHOR

Richard Caley, R.Caley@ed.ac.uk

SEE ALSO

Speech::Synthesis, Speech::Festival::Synthesis, perl(1), festival(1), Festival Documentation