### 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;
    }