28.4 C/C++ API

As well as offerening an interface through Scheme and the shell some users may also wish to embedd Festival within their own C++ programs. A number of simply to use high level functions are available for such uses.

In order to use Festival you must include festival/src/include/festival.h which in turn will include the necessary other include files in festival/src/include and speech_tools/include you should ensure these are included in the include path for you your program. Also you will need to link your program with festival/src/lib/libFestival.a, speech_tools/lib/libestools.a, speech_tools/lib/libestbase.a and speech_tools/lib/libeststring.a as well as any other optional libraries such as net audio.

The main external functions available for C++ users of Festival are.

void festival_initialize(int load_init_files,int heapsize);

This must be called before any other festival functions may be called. It sets up the synthesizer system. The first argument if true, causes the system set up files to be loaded (which is normally what is necessary), the second argument is the initial size of the Scheme heap, this should normally be 210000 unless you envisage processing very large Lisp structures.

int festival_say_file(const EST_String &filename);

Say the contents of the given file. Returns TRUE or FALSE depending on where this was successful.

int festival_say_text(const EST_String &text);

Say the contents of the given string. Returns TRUE or FALSE depending on where this was successful.

int festival_load_file(const EST_String &filename);

Load the contents of the given file and evaluate its contents as Lisp commands. Returns TRUE or FALSE depending on where this was successful.

int festival_eval_command(const EST_String &expr);

Read the given string as a Lisp command and evaluate it. Returns TRUE or FALSE depending on where this was successful.

int festival_text_to_wave(const EST_String &text,EST_Wave &wave);

Synthesize the given string into the given wave. Returns TRUE or FALSE depending on where this was successful.

Many other commands are also available but often the above will be sufficient.

Below is a simple top level program that uses the Festival functions

int main(int argc, char **argv)
{
    EST_Wave wave;
    int heap_size = 210000;  // default scheme heap size
    int load_init_files = 1; // we want the festival init files loaded

    festival_initialize(load_init_files,heap_size);

    // Say simple file
    festival_say_file("/etc/motd");

    festival_eval_command("(voice_ked_diphone)");
    // Say some text;
    festival_say_text("hello world");

    // Convert to a waveform
    festival_text_to_wave("hello world",wave);
    wave.save("/tmp/wave.wav","riff");

    // festival_say_file puts the system in async mode so we better
    // wait for the spooler to reach the last waveform before exiting
    // This isn't necessary if only festival_say_text is being used (and
    // your own wave playing stuff)
    festival_wait_for_spooler();

    return 0;
}