Usage Documentation

• Directory Structure:
• Compiling:
• Debugging:
• Control Data:
• Demo: STK Instruments
• Demo: Non-Realtime Use
• Demo: Realtime Use
• Realtime Control Input using Tcl/Tk Graphical User Interfaces:
• Realtime MIDI Control Input:
• Polyphony:

---

Directory Structure:

The top level distribution contains the following directories:

• The src directory contains the source .cpp files for all the STK unit generator and algorithm classes.

• The include directory contains the header files for all the STK unit generator and algorithm classes.

• The rawwaves directory contains various raw, monophonic, 16-bit, big-endian, 22050 Hz soundfiles used with the STK classes.

• The doc directory contains documentation about STK.

• The projects directory contains various demo and example STK programs.

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

1. The demo project is used to demonstrate nearly all of the STK instruments. The stk-demo program has been written to allow a variety of control input and sound data output options. Simple graphical user interfaces (GUIs) are also provided.

2. The effects project demonstrates realtime duplex mode (simultaneous audio input and output) operation, when available, as well as various delay-line based effects algorithms.

3. The ragamatic project is just cool. Fire it up and be enlightened.

4. The eguitar project demonstrates how to make an electric guitar with feedback and distortion.

5. The examples project contains several simple programs that demonstrate audio input/output, including the audio internet streaming classes, as well as most of the tutorial programs.

Compiling:

• Windows95 and later: For specifics on creating Windows applications using Visual Studio, see README-Win.txt.

• Unix (and MinGW) Systems: A GNU configure shell script is included in the distribution for unix-based systems. From the top-level distribution directory, type './configure' and the script will create Makefiles in each project directory specific to the characteristics of the host computer. Then from within any given project directory (example demo), type 'make' to compile the project. In addition, an STK library can be compiled from within the src directory.

  Several options can be supplied to the configure script to customize the build behavior:

  • –disable-realtime to only compile generic non-realtime classes
  • –enable-debug to enable various debug output
  • –with-alsa to choose native ALSA API support (default, linux only)
  • –with-oss to choose native OSS audio API support (linux only, no native OSS MIDI support)
  • –with-jack to choose native JACK API support (linux and Macintosh OS-X)
  • –with-core to choose CoreAudio API support (Macintosh OS-X)
  • –with-asio to choose ASIO Audio API support (Windows)
  • –with-ds to choose Windows DirectSound Audio API support (Windows)

  Note that it is possible to specify as many of the "–with-" options as desired to compile multi-API support. In addition, it is possible to specify the location of the STK rawwaves and the STK include path as follows:

  ./configure RAWWAVE_PATH="/home/gary/rawwaves/"
  ./configure INCLUDE_PATH="/home/gary/include/"

  For novice STK users, the default configuration should be adequate.

For those who wish to create their own system-specific Makefiles:

• Linux: Realtime audio support is enabled with either the __LINUX_ALSA__, __UNIX_JACK__, and/or __LINUX_OSS__ preprocessor definitions, which are used to select the underlying audio system API(s). Because the ALSA library is now integrated into the standard Linux kernel, it is the default audio/MIDI API with STK versions 4.2 and higher. The __LINUX_ALSASEQ__ preprocessor definition must be included for MIDI support. Note that native OSS MIDI support no longer exists in RtMidi. If the __LINUX_OSS__ preprocessor definition is specified, only OSS (version 4.0) audio support will be compiled and RtMidi will still be compiled using the ALSA API (assuming the __LINUX_ALSASEQ__ definition is defined). For this reason, STK now requires the asound library for realtime support. Realtime programs must also link with the pthread library. In addition, the __LITTLE_ENDIAN__ preprocessor definition is necessary if compiling on a little-endian system. See the README-Linux file for further system configuration information.

• Macintosh OS X: Realtime support is enabled with the __MACOSX_CORE__ and __UNIX_JACK__ preprocessor definitions, which incorporate the CoreAudio audio/MIDI API and/or the JACK API. Realtime programs must also link with the pthread library and the CoreAudio, CoreMIDI, and CoreFoundation frameworks (for CoreAudio support) and/or the JACK library. See the README-MacOSX file for further system configuration information.

• Generic (non-realtime): Most STK classes are operating system independent 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 __LITTLE_ENDIAN__ preprocessor definition to your compiler. The demo 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 cannot be used without realtime support: RtAudio, RtWvIn, RtWvOut, RtDuplex, RtMidi, Socket, Thread, Mutex, TcpWvIn, TcpWvOut. Because of this, it is not possible to compile the effects, ragamatic, and most of the examples projects for non-realtime use.

Debugging:

When developing applications with STK, it is recommended that you define the preprocessor definition _STK_DEBUG_ when compiling (or specify the –enable-debug option to the configure script). This will enable all levels of function argument and error checking within the STK classes. Without this definition, argument checking does not occur in functions that are expected to be called frequently in an iterative manner.

Control Data:

All STK programs in this distribution take input control data in the form of SKINI 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:

1. Redirect or pipe SKINI scorefiles to an executable.
2. Pipe realtime SKINI input messages to an executable (not possible under Windows95/98).
3. Acquire realtime MIDI messages from a MIDI port on your computer.

Tcl/Tk graphical user interfaces (GUI) are provided with this distribution that can generate realtime SKINI messages. Note that the Messager class allows multiple simultaneous socket client connections, together with MIDI and/or piped input. The Md2Skini program (in the demo directory) is mostly obsolete but can be used to create SKINI scorefiles from realtime MIDI input.

Demo: STK Instruments

The demo project demonstrates the behavior of all the distributed STK instruments. The instruments available with this release include:

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

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 scores directory of the demo project. Assuming a successful compilation of the stk-demo program, typing:

stk-demo BeeThree -ow myfile.wav -if scores/bookert.ski

from the demo directory will play the scorefile bookert.ski using the STK BeeThree instrument and write the resulting audio data to a WAV formatted soundfile called "myfile.wav" (note that you may need to append ./ to the program name if your default shell setup is not set to look in the current directory). Typing stk-demo without any arguments will provide a full program usage description.

Demo: Realtime Use

STK realtime audio and MIDI input/output and realtime SKINI control input via socketing support is provided for Linux, Mac OS-X, and Windows95 and later operating systems. STK realtime SKINI control input via piping is possible under Linux, Mac OS X, and Windows2000 and later only.

Control input and audio output options are typically specified as command-line arguments to STK programs. For example, the stk-demo program is invoked as:

stk-demo instrument flags

where instruments include those described above and flags can be any or all of:

• -or for realtime audio output,
• -ow <file name> for WAV soundfile output,
• -os <file name> for SND (AU) soundfile output,
• -om <file name> for MAT-file output,
• -if <file name> for a SKINI formatted control file,
• -ip for realtime SKINI control input via piping,
• -im <port> for MIDI control input (with optional port, -1 = virtual port where possible),
• -s RATE to specify a sample rate,
• -n NUMBER to specify multivoice polyphony

The -ip flag must be used when piping 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 both input types simultaneously.

Assuming a successful compilation of the stk-demo program, typing:

stk-demo BeeThree -or -if scores/bookert.ski

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

Realtime Control Input using Tcl/Tk Graphical User Interfaces:

There are a number of Tcl/Tk 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 and later 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 wishXX executable to the name wish). The Physical.bat script just implements the following command-line sequence:

wish < tcl/Physical.tcl | stk-demo Clarinet -or -ip

Realtime MIDI Control Input:

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

stk-demo Clarinet -or -im

This will attempt to use the default MIDI port for input. An optional MIDI port number can be specified after the -im flag. Valid MIDI ports are numbered from 0 (default) and higher. On Linux and Macintosh OS-X systems, it is possible to open a virtual MIDI input port (that other software applications can connect to) by specifying a port identifier of -1.

Polyphony:

The stk-demo program supports an arbitrary number of voices via the -n NUMBER command-line flag and argument. For example, you can play eight BeeThree instruments with realtime output and control them from a MIDI device by typing:

stk-demo BeeThree -n 8 -or -im