\chapter{Getting Started}
\label{section:getting_started}
In this section we look at a typical session with \tao\ from beginning to
end. I will assume that you have successfully installed the package and
that the test script worked OK.

\section{Writing a script}
First of all open a new text file in your favourite text editor and copy
the following text into it:

\begin{verbatim}
    Audio rate: 44100;

    String string(200 Hz, 20 secs);

    Output output(stereo);

    Init:
        string.lockEnds();
        ...

    Score 20 secs:
        At 0 secs for 1 msecs:
            string(0.2).applyForce(1.0);
            ...

        output.chL: string(0.1);
        output.chR: string(0.9);
        ...
\end{verbatim}

Now save the file as ``new.tao''.

In plain English this script does the following:

\begin{enumerate}
\item
declares the audio sampling rate for any output files to be 44.1 KHz
\item
declares a \emph{string} instrument called \verb|string|
\item
declares a two channel \emph{output} device called \verb|output|
\item
initialises the string by locking both ends (fixing them at their
initial position: $z=0$)
\item
states that the \emph{performance} will last for 20 seconds
\item
applies a fixed force of magnitude 1.0 to a point on the string
one fifth of the way along its length (from the left hand side)
for a short time interval (0 seconds to 0.001 seconds)
\item
writes the movements of the string out to a stereo output file
called ``new\_output.dat'' with the left and right channels following
the movements of a point one tenth of the way along its length and
another point nine tenths of the way along the string, respectively.
\end{enumerate}

In case you are wondering, the name of an output file is formed
by appending the name of the output device onto the name of the
script (minus the \verb|.tao| extension) and adding a \verb|.dat|
extension, indicating that the file contains raw floating point data,
i.e. ``new\_output.dat''. These files require further processing before
they can be played back. See section \ref{section:output_files}.

\section{Executing the script}
To execute this script simply type the following:

\begin{verbatim}
    tao new
\end{verbatim}

\tao\ should respond with the following messages in the shell window:

\begin{verbatim}
    ========================================
    |     Tao (c) 1996-99 Mark Pearson     |
    | Sound Synthesis with Physical Models |
    ========================================

    Processing new.tao
    Making new.exe
    Executing new.exe

    Sample rate=44100 KHz
    Score duration=20 seconds                
\end{verbatim}

You should then see the \emph{instrument visualisation window}
open. It should look something like the following:

\begin{figure}[h]
  \begin{Label}{fig:new}
    \begin{center}
    \Image{new}{height=6cm}{gif}
    \end{center}
    \caption{The instrument visualisation window generated by script new.tao}
  \end{Label}
\end{figure}    

When the visualisation window opens \tao\ is initially in \Term{pause mode}.
To get it out of this mode you should press the right cursor key once.
You can pause the whole system again by pressing the left cursor key at
any point in time. If you repeatedly press the right cursor key you will
see that the animation begins to move more and more rapidly although eventually
it becomes less smooth. If you now repeatedly press the left cursor
key, the animation slows down again and becomes smoother.

The reason for this is that it is possible to change the frequency with
which the visualisation window is updated. \tao\ has a \emph{synthesis engine}
which keeps track of all the instruments and devices created in a script, and
carries out all the calculations involved in bringing them to life. It also
has a \emph{graphics engine} which is responsible for displaying the
instruments and devices in the visualisation window. Pressing the left and
right cursor keys simply changes how frequently the graphics engine 
visualises what is going on inside the synthesis engine. Displaying the
instruments and devices on every tick of the synthesis engine leads to
smooth animations but at the expense of making the whole system slow
down. Conversely, displaying the instruments less frequently gives
a bigger slice of the processing power over to the synthesis engine at the
expense of producing more jerky animations.

Now supposing you want to run a performance at maximum efficiency, without
the overhead of the graphics window. When executing a script for the
first time you can simply hit the right cursor key to set the synthesis
engine in motion, and then mimimise the graphics window. This means
that all the computational resources available will be put into the
synthesis itself, until the graphics window is restored.

\section{The output of the `tao' command}
Whenever a \tao\ script is executed a \verb|.exe| file is generated as a
by-product. If you want to re-run the script at any point, instead of typing:

\begin{verbatim}
    tao new.tao
\end{verbatim}

you can simply type:

\begin{verbatim}
    ./new.exe [-g]
\end{verbatim}

The \verb|-g| option turns the visualisation window on. If you omit
this option then \tao\ proceeds with the synthesis without opening
the visualisation window. This is the most efficient way to execute
a script.

\section{Moving the image in the visualisation window}
The image displayed in the instrument visualisation window can be
rotated, translated and zoomed using the mouse. Try holding the
three mouse buttons down one at a time and moving the mouse to get a
better idea of how to manipulate the image. For more details on
keyboard and mouse bindings refer back to section
\ref{section:key_and_mouse_bindings}.

\section{Quitting the synthesis before the performance finishes}
If you want to quit the synthesis before the performance completes
either type [Ctrl-C] in the shell window you launched \tao\ from or
press the [Esc] key whilst the instrument visualisation window is the
active window.

\section{Post-processing the output files}
\label{section:output_files}
\tao's output files are written in raw-floating point format. This means
that they are not immediately playable, but require a further
post-processing step to convert them into a more usable format. This
is achieved with the \verb|taosf| command. The general syntax of this
command is:

\begin{verbatim}
    taosf <output_filename>
\end{verbatim}

Where \verb|output_filename| is the name of the output file minus the
\verb|.dat| extension. This reads the floating point sample data stored
in the output file, normalises it to fit the maximum sample range
available, and adds an appropriate WAV header to the file describing
the number of channels and sample data format.

The reason for \tao's output files being written in floating point
format is that it is difficult, if not impossible, to know in advance
the amplitudes of the waves in the instruments, especially in cases
where some sort of feedback is present in the system. It is therefore
easier to write the output samples in a format which presents no danger
of overflows (as often happens with CSound) and then normalise these
samples once the performance is finished.