### 28.1 Scheme API ¶

Festival includes a full programming language, Scheme (a variant of Lisp) as a powerful interface to its speech synthesis functions. Often this will be the easiest method of controlling Festival’s functionality. Even when using other API’s they will ultimately depend on the Scheme interpreter.

Scheme commands (as s-expressions) may be simply written in files and interpreted by Festival, either by specification as arguments on the command line, in the interactive interpreter, or through standard input as a pipe. Suppose we have a file `hello.scm` containing

    ;; A short example file with Festival Scheme commands
    (voice_rab_diphone) ;; select Gordon
    (SayText "Hello there")
    (voice_don_diphone) ;; select Donovan
    (SayText "and hello from me")

From the command interpreter we can execute the commands in this file by loading them

    festival> (load "hello.scm")
    nil

Or we can execute the commands in the file directly from the shell command line

    unix$ festival -b hello.scm

The ‘`-b`’ option denotes batch operation meaning the file is loaded and then Festival will exit, without starting the command interpreter. Without this option ‘`-b`’ Festival will load `hello.scm` and then accept commands on standard input. This can be convenient when some initial set up is required for a session.

Note one disadvantage of the batch method is that time is required for Festival’s initialisation every time it starts up. Although this will typically only be a few seconds, for saying short individual expressions that lead in time may be unacceptable. Thus simply executing the commands within an already running system is more desirable, or using the server/client mode.

Of course its not just about strings of commands, because Scheme is a fully functional language, functions, loops, variables, file access, arithmetic operations may all be carried out in your Scheme programs. Also, access to Unix is available through the `system` function. For many applications directly programming them in Scheme is both the easiest and the most efficient method.

A number of example Festival scripts are included in `examples/`. Including a program for saying the time, and for telling you the latest news (by accessing a page from the web). Also see the detailed discussion of a script example in See POS Example.