stk/doc/doxygen/usage.txt

/*! \page usage Usage Documentation

- \ref directory
- \ref compiling
- \ref control
- \ref instruments
- \ref nort
- \ref rt
- \ref tcl
- \ref midi

<HR>

\section directory Directory Structure:

The top level distribution contains the following directories:

<UL>
<LI> The <I><B>src</B></I> directory contains the source .cpp files for almost all the STK unit generator and algorithm classes.</LI><P>

<LI> The <I><B>include</B></I> directory contains the header files for almost all the STK unit generator and algorithm classes.</LI><P>

<LI> The <I><B>rawwaves</B></I> directory contains various raw, monophonic, 16-bit, big-endian soundfiles used with the STK classes.</LI><P>

<LI> The <I><B>doc</B></I> directory contains documentation about STK.</LI><P>

<LI> The <I><B>projects</B></I> directory contains various demo and example STK programs.</LI><P>
</UL>

This release of STK comes with four separate "project" directories:

<OL>
<LI> The <I><B>demo</B></I> project is used to demonstrate nearly all of the STK instruments.  The <I><B>demo</B></I> program has been written to allow a variety of control input and sound data output options.  %Simple graphical user interfaces (GUIs) are also provided.<P></LI>

<LI> The <I><B>effects</B></I> project demonstrates realtime duplex mode (simultaneous audio input and output) operation, when available, as well as various delay-line based effects algorithms.<P></LI>

<LI> The <I><B>ragamatic</B></I> project is just cool.  Fire it up and be enlightened.<P></LI>

<LI> The <I><B>examples</B></I> project contains several simple programs which demonstrate audio input/output, as well as the use of the audio internet streaming classes.</LI>
</OL>

\section compiling Compiling:

<UL>
<LI><B>Generic (non-realtime):</B> Most STK classes are operating system <I>independent</I> and can be compiled using any current C++ compiler. STK assumes big-endian host byte order by default, so if your system is little-endian (i.e. Intel processor), you must provide the <TT>__LITTLE_ENDIAN__</TT> preprocessor definition to your compiler.  The <I><B>demo</B></I> project will compile without realtime support, allowing the use of SKINI scorefiles for input control and output to a variety of soundfile formats.  The following classes <I>cannot</I> be used without realtime support: RtAudio, RtWvIn, RtWvOut, RtDuplex, RtMidi, Socket, Thread, TcpWvIn, TcpWvOut.  Because of this, it is not possible to compile the <I><B>effects</B></I>, <I><B>ragamatic</B></I>, and most of the <I><B>examples</B></I> projects for non-realtime use.</LI>

<LI><B>Linux:</B> Realtime support is enabled with either the <TT>__LINUX_OSS__</TT> or <TT>__LINUX_ALSA__</TT> preprocessor definitions, which are used to select the underlying audio/MIDI system API.  Realtime programs must also link with the <TT>pthread</TT> library.  When using the ALSA API, it is also necessary to link with the <TT>asound</TT> library.  In addition, the <TT>__LITTLE_ENDIAN__</TT> preprocessor definition is necessary if compiling on a little-endian system.  Assuming your system has the <A HREF="http://gnu.cetcol.net.co/">GNU</A> Makefile utilities installed, typing <TT>make</TT> within a particular project directory will initiate the compilation process.  The <TT>Makefile</TT> will have to be modified to change the default audio/MIDI system API and for big-endian processors.  Special support exists under Linux for the MIDIator serial MIDI device, enabled using the __MIDIATOR__ preprocessor definition (together with either the __LINUX_ALSA__ or __LINUX_OSS__ definitions).  See the README-Linux file for further system configuration information.</LI>

<LI><B>SGI:</B> Realtime support is enabled with the <TT>__IRIX_AL__</TT> preprocessor definition and linkage with the <TT>audio</TT>, <TT>md</TT>, and <TT>pthread</TT> libraries.  If your system has the <A HREF="http://gnu.cetcol.net.co/">GNU</A> Makefile utilities installed, typing <TT>make</TT> (or <TT>gmake</TT>) within a particular project directory will initiate the compilation process.  If your system does not have the GNU Makefile utilities, you should first try to download and install them.  If this is not possible, a generic Makefile is provided with the <I><B>demo</B></I> project (Makefile.sgi).  It can be invoked by typing <TT>make -f Makefile.sgi</TT> within that project directory.  STK 4.0 is confirmed to compile using CC version 7.30.  There may be problems with old compiler versions.</LI>

<LI><B>Windows95/98/2000/XP:</B> Realtime support is enabled with the <TT>__WINDOWS_DS__</TT> preprocessor definition and linkage with the <TT>dsound.lib</TT>, <TT>winmm.lib</TT>, and <TT>Wsock32.lib</TT> libraries. In addition, the <TT>__LITTLE_ENDIAN__</TT> preprocessor definition is necessary for all Windows systems.  A distribution of the release is available with precompiled binaries for all the projects.  In order for these binaries to function properly, your system must have the DirectX 5.0 (or higher) runtime libraries installed (available from <A HREF="http://www.microsoft.com/directx/">Microsoft</A>).  Further, the <I><B>effects</B></I> project requires that your soundcard and drivers provide full duplex mode capabilities.  Visual C++ 6.0 project file are provided in each project directory as well should you wish to compile your own binaries.  It is important to link with the non-debug libraries when compiling "release" program versions and debug libraries when compiling "debug" program versions.</LI>

<LI><B>WindowsNT:</B> I've given up trying to make things work under NT.  You'll have to switch to Windows 2000 (which does seem to work).</LI>
</UL>


\section control Control Data:

All STK programs in this distribution take input control data in the form of <A HREF="skini.html">SKINI</A> or MIDI messages only.  The Messager class unifies the various means of acquiring control data under a single, easy to use set of functions.  The way that SKINI messages can be sent to the programs is dependent upon the operating system in use, as well as whether the program is running in realtime or not.  In general, it is possible to:

<OL>
<LI>Redirect or pipe SKINI scorefiles to an executable.</LI>
<LI>Pipe realtime SKINI input messages to an executable (not possible under Windows95/98).</LI>
<LI>Socket realtime SKINI input messages to an executable.</LI>
<LI>Acquire realtime MIDI messages from a MIDI port on your computer.</LI>
</OL>

<A HREF="http://dev.scriptics.com">Tcl/Tk</A> graphical user interfaces (GUI) are provided with this distribution which can generate realtime SKINI messages.  Note that the Messager class allows multiple simultaneous socket client connections, together with MIDI and/or piped input.  The <I><B>Md2Skini</B></I> program (in the <I><B>demo</B></I> directory) is mostly obsolete but can be used to create SKINI scorefiles from realtime MIDI input.  


\section instruments Demo: STK Instruments

The <I><B>demo</B></I> project demonstrates the behavior of all the distributed STK instruments.  The instruments available with this release include:
<UL>
<LI>Clarinet: Pretty good physical model of the clarinet</LI>
<LI>BlowHole: A clarinet physical model with one tonehole and one register vent</LI>
<LI>Saxofony: A psuedo-conical bore reed instrument which sometimes sounds like a saxophone</LI>
<LI>Flute: Pretty good physical model of the flute</LI>
<LI>Brass: Not so bad physical model of a brass instrument</LI>
<LI>BlowBotl: A basic helmholtz resonator and air jet model</LI>
<LI>Bowed: Not hideous physical model of a bowed string instrument</LI>
<LI>Plucked: Yer basic plucked string physical model</LI>
<LI>StifKarp: A simple plucked, stiff string physical model</LI>
<LI>Sitar: A simple sitar/plucked string physical model</LI>
<LI>Mandolin: Two-string mandolin physical model</LI>
<LI>Rhodey: Rhodes-like electric piano FM synthesis model</LI>
<LI>Wurley: Wurlitzer-like electric piano FM synthesis model</LI>
<LI>TubeBell: FM synthesis model</LI>
<LI>HevyMetl: Distorted synthesizer FM synthesis model</LI>
<LI>PercFlut: Percussive flute-like FM synthesis model</LI>
<LI>BeeThree: Cheezy organ FM synthesis model</LI>
<LI>Moog: Swept filter sampler</LI>
<LI>FMVoices: Three-formant FM voice synthesis</LI>
<LI>Resonate: Noise through a BiQuad filter</LI>
<LI>Drummer: Sampling synthesis</LI>
<LI>BandedWG: Banded waveguide meta-object for bowed bars, tibetan bowls, etc.</LI>
<LI>Shakers: Various stochastic event models of shaker instruments</LI>
<LI>ModalBar: Various four-resonance presets (marimba, vibraphone, etc...)</LI>
<LI>Mesh2D: Two-dimensional, rectilinear digital waveguide mesh</LI>
</UL>

\section nort Demo: Non-Realtime Use

See the information above with respect to compiling STK for non-realtime use.

In non-realtime mode, it is assumed that input control messages are provided from a SKINI scorefile and that audio output is written to a soundfile (.snd, .wav, .aif, .mat, .raw).  A number of SKINI scorefiles are provided in the <I>scores</I> directory of the <I><B>demo</B></I> project.  Assuming a successful compilation of the <I><B>demo</B></I> program, typing:

\code
cat scores/bookert.ski | demo BeeThree -w myfile.wav
\endcode

or (on WindowsXX and/or Unix)

\code
demo BeeThree -w myfile.wav < scores\bookert.ski
\endcode

from the <I><B>demo</B></I> directory will play the scorefile <I>bookert.ski</I> using the STK BeeThree instrument and write the resulting audio data to a WAV formatted soundfile called "myfile.wav".  Typing <TT>demo</TT> without any arguments will provide a full program usage description.


\section rt Demo: Realtime Use

STK realtime audio and MIDI input/output and realtime SKINI control input via socketing support is provided for Linux, SGI, and Windows95/98/2000/XP operating systems.  STK realtime SKINI control input via piping is possible under Linux, SGI, and Windows2000/XP only.
<P>
Control input and audio output options are typically specified as command-line arguments to STK programs.  For example, the <I><B>demo</B></I> program is invoked as:

\code
demo instrument flags
\endcode

where instruments include those described above and flags can be any or all of:
<UL>
<LI><I>-or</I> for realtime audio output,</LI>
<LI><I>-ow <file name></I> for WAV soundfile output,</LI>
<LI><I>-os <file name></I> for SND (AU) soundfile output,</LI>
<LI><I>-om <file name></I> for MAT-file output,</LI>
<LI><I>-ip</I> or <I>-is</I> for realtime SKINI control input via piping or socketing, respectively,</LI>
<LI><I>-im <file name></I> for MIDI control input</LI>
</UL>
The <-ip> and <-is> flags must be used when piping or socketing realtime SKINI control data to an STK program.  The <-im> flag must be used to read MIDI control input from your MIDI port.  Note that you can use all three input types simultaneously.

Assuming a successful compilation of the <I><B>demo</B></I> program, typing:

\code
cat scores/bookert.ski | demo BeeThree -or
\endcode

or (on WindowsXX and/or Unix)

\code
demo BeeThree -or < scores\bookert.ski
\endcode

from the <I><B>demo</B></I> directory will play the scorefile <I>bookert.ski</I> using the STK BeeThree instrument and stream the resulting audio data in realtime to the audio output channel of your computer.  Typing <TT>demo</TT> without any arguments will provide a full program usage description.


\section tcl Realtime Control Input using Tcl/Tk Graphical User Interfaces:

There are a number of <A HREF="http://dev.scriptics.com">Tcl/Tk</A> GUIs supplied with the STK projects.  These scripts require Tcl/Tk version 8.0 or later, which can be downloaded for free over the WWW.  On Unix and Windows2000/XP platforms, you can run the various executable scripts (e.g. StkDemo.bat) provided with each project to start everything up (you may need to symbolically link the wish80 executable to the name <I>wish</I>).  The PhysicalDemo script just implements the following command-line sequence:

\code
wish < tcl/Physical.tcl | demo Clarinet -or -ip
\endcode

On WindowsXX and Unix platforms, the following operations are necessary to establish a socket connection between the Tcl/Tk GUI and the STK program:
<OL>
<LI>Open a DOS shell and start the STK program with the <I>-is</I> flag (ex. <I><B>demo Clarinet -or -is</B></I>).</LI>
<LI>Open the Tcl/Tk GUI (e.g. tcl/Physical.tcl) by double-clicking on it, or type <TT>wish < tcl/Physical.tcl</TT> in another DOS shell.</LI>
<LI>Establish the socket connection by selecting <I>Socket</I> under the Communications menu item in the Tcl/Tk GUI.</LI>
</OL>

Note that it is possible to specify a hostname when establishing the socket connection from the socket client.  Thus, the STK socket server program and the Tcl/Tk GUI need not necessarily reside on the same computer.


\section midi Realtime MIDI Control Input:

On all supported realtime platforms, you can direct realtime MIDI input to the STK Clarinet by typing:

\code
demo Clarinet -or -im
\endcode

*/