STK: A ToolKit of Audio Synthesis Classes and Instruments in C++
Version 3.1

By Perry R. Cook, 1995-2000
and Gary P. Scavone, 1997-2000.

Please read the Legal and Ethical notes near the bottom of this document.


OVERVIEW:

STK is a set of audio signal processing C++ classes and instruments for music synthesis.  You can use these classes to create programs which make cool sounds using a variety of synthesis techniques.  This is not a terribly novel concept, except that STK is very portable (it's mostly platform-independent C and C++ code) AND it's completely user-extensible.  So, the code you write using STK actually has some chance of working in another 5-10 years.  STK currently runs on SGI (Irix), Linux, NeXTStep, and Windows computer platforms.  Oh, and it's free for non-commercial use.  The only parts of STK that are platform-dependent concern real-time sound and MIDI input and output ... but we've taken care of that for you.  The interface for MIDI input and the simple Tcl/Tk graphical user interfaces (GUIs) provided is the same, so it's easy to voice and experiment in real time using either the GUIs or MIDI.

STK isn't one particular program.  Rather, STK is a set of C++ classes that you can use to create your own programs.  We've provided a few example applications that demonstrate some of the ways that you could use these classes.  But if you have specific needs you will probably have to either modify the example programs or write a new program altogether.  Further, the example programs don't have a fancy GUI wrapper.  If you feel the need to have a "drag and drop" GUI, you probably don't want to use STK.  Spending hundreds of hours making platform-dependent GUI code would go against one of the fundamental design goals of STK - platform independence.  STK can generate simultaneous .snd, .wav, and .mat output soundfile formats (beside realtime sound output), so you can view your results using one of the numerous sound/signal analysis tools already available over the WWW (e.g. Snd, Cool Edit, Matlab).  For those instances where a simple GUI with sliders and buttons is helpful, we use Tcl/Tk (which is freely distributed for all the STK supported platforms).  A number of Tcl/Tk GUI scripts are distributed with the STK release.


SYSTEM REQUIREMENTS:

See the individual README's (eg. README-linux) for platform specific information and system requirements.  In general, you will use either the provided Makefiles (Unix platforms) or the VC++ workspace files to compile the example programs.  To use the Tcl/Tk GUIs, you will need Tcl/Tk version 8.0 or higher.


WHAT'S NEW:

STK has undergone several key revisions, changes, and additions since its last release in 1998.  Despite being available in one form or another since 1996, we still consider STK to be alpha software.  Thus, backward compatability has not been a priority.  Please read the ReleaseNotes to see what has changed since the last release.

Realtime audio input capabilities were added to STK with release 3.0, though the behavior of such is very hardware dependent.  Under Linux and Irix, audio input and output are possible with very low latency.  Using the Windoze DirectSound API, minimum dependable output sound latency seems to be around 15 milliseconds, while input sound latency is on the order of several hundred milliseconds!  It is also possible to generate simultaneous .snd, .wav, .raw, and .mat (Matlab MAT-file) output file types, as well as SKINI scorefiles using MD2SKINI.  Finally, STK should compile with non-realtime functionality on any platform with a generic C++ compiler.

Socketing capabilities were extended in release 3.0 to function under Unix platforms, as well as Windoze platforms.  Further, the socket server thread was updated to accept multiple simultaneous socket connections.  Thus, it is now possible to have several different socket clients sending SKINI control messages to the server at the same time.  Under Linux and Irix, it is also possible to pipe GUI messages through MD2SKINI, enabling both MIDI and GUI control via piping at the same time.


GETTING STARTED:

A number of example executables are provided with this distribution.  The effects directory contains a program that demonstrates realtime duplex mode (simultaneous audio input and output) operation, as well as several simple delay-line based effects algorithms.  The MUS151 directory contains a simple two-oscillator program that can be used to demonstrate psychoacoustic masking effects.  RagaMatic is a totally cool application for achieving inner piece.  The syntmono directory offers a program for monophonic STK instrument playback and manipulation.  Syntmono is the primary STK synthesis server and is used to demonstrate all the current STK instruments.  MD2SKINI is an executable (currently compiles from the syntmono project) which takes raw MIDI input, converts it to SKINI format, and outputs the result to stdout or any socket host and port ID.  Control data (in the form of SKINI messages) can be fed to syntmono through three principal means - SKINI scorefiles, MD2SKINI output, and Tcl/Tk GUIs.  A variety of SKINI scorefiles are distributed with STK and can be found in the "scores" directory of the syntmono project.

Unless you downloaded the distribution with precompiled Windoze binaries, it is necessary to first compile the sources.  Under Linux or Irix, simply typing "make" in any of the particular project directories will begin the compilation process.  If your Unix system does not have the GNU Makefile utilities, you will have to use one of the platform specific Makefiles (eg. make -f Makefile.sgi).  To compile the projects under Windoze, you should use the VC++ project files provided with the STK distribution.


SYNTMONO:

Syntmono is the primary STK synthesis server and is used to demonstrate all the current STK instruments.  Syntmono can take realtime control (SKINI) input via pipes or sockets, or it can be fed SKINI scorefile (non-realtime) input.  Syntmono can output data in realtime, .wav, .snd, .mat (Matlab MAT-file), and/or .raw formats.  Assuming you have successfully compiled the syntmono executable, a scorefile can be redirected to syntmono and the output heard in realtime in the following way:

    syntmono Clarinet -r < scores/streetsf.ski

The "-r" flag specifies the realtime output option.  Typing syntmono without arguments will provide a brief description of the instruments possible and the various input/output option flags.  Tcl/Tk GUIs are provided in the "tcl" directory of each project, though you will have to install Tcl/Tk version 8.0 or higher on your system to use them (older versions of Tcl/Tk under Linux seem to be more forgiving than under IRIX).  Realtime SKINI control data (via MD2SKINI or GUIs) can be piped to syntmono on Unix platforms and WinNT in the following way:

    MD2SKINI | syntmono Clarinet -r -ip
or
    wish < TCLSpecs/TCLPhys.tcl | syntmono Clarinet -r -ip

The "-ip" flag specifies piped realtime input.  It is not possible to use realtime pipes under Windoze95/98, so socket communication must be used instead.    For socket communication, it is necessary to first start the syntmono socket server using the "-is" flag (socketed realtime input).  For the time being, a default (hardwired) socket port of 2001 is being used by syntmono.  After syntmono is running (and waiting for a socket client connection), either MD2SKINI or a Tcl/Tk GUI can be started.  When using the GUI, it is necessary to invoke the "communications" menu item and select "socket" to establish the connection.  The same procedure is also possible on Unix platforms.


DISCLAIMER:

You probably already guessed this, but just to be sure, we don't guarantee anything works.  :-)  It's free ... what do you expect?  If you find a bug, please let us know and we'll try to correct it.  You can also make suggestions, but again, no guarantees.  Send email to prc@cs.princeton.edu and gary@ccrma.stanford.edu. 


LEGAL AND ETHICAL:

This software was designed and created to be made publicly available for free, primarily for academic purposes, so if you use it, pass it on with this documentation, and for free.  

If you make a million dollars with it, give us some.  If you make compositions with it, put us in the program notes.

Some of the concepts are covered by various patents, some known to us and likely others which are unknown.  Many of the ones known to us are administered by the Stanford Office of Technology and Licensing.  

The good news is that large hunks of the techniques used here are public domain.  To avoid subtle legal issues, we'll not state what's freely useable here, but we'll try to note within the various classes where certain things are likely to be protected by patents.


FURTHER READING:

For more documentation on this ToolKit, the classes, etc., read the file HIERARCH.txt and the individual class definitions.  Also check the platform specific README's for specific system requirements.


PERRY'S NOTES FROM THE ORIGINAL DISTRIBUTION:

This whole world was created with no particular hardware in mind.  These examples are intended to be tutorial in nature, as a platform for the continuation of my research, and as a possible starting point for a software synthesis system.  The basic motivation was to create the necessary unit generators to do the synthesis, processing, and control that I want to do and teach about.  Little thought for optimization was given (see Object.cpp), and therefore improvements, especially speed enhancements, should be possible with these classes.  It was written with some basic concepts in mind about how to let compilers optimize.

Your question at this point might be, "But Perry, with CMix, CMusic, CSound, CShells, CMonkeys, etc. already cluttering the landscape, why a new set of stupid C functions for music synthesis and processing?"  The answers lie below.

1) I needed to port many of the things I've done
   into something which is generic enough to port
   further to different machines.

2) I really plan to document this stuff, so that
   you don't have to be me to figure out what's 
   going on. (I'll probably be sorry I said this 
   in a couple of years, when even I can't figure
   out what I was thinking.)

3) The classic difficulties most people have in 
   trying to implement physical models are:

   A) They have trouble understanding the papers, 
      and/or in turning the theory into practice.

   B) The Physical Model instruments are a pain to get 
      to oscillate, and coming up with stable and 
      meaningful parameter values is required to 
      get the models to work at all.

   This set of C++ unit generators and instruments
   might help to diminish the scores of emails I
   get asking what to do with those block diagrams
   I put in my papers.

4) I wanted to try some new stuff with modal synthesis, 
   and implement some classic FM patches as well.

5) I wanted to reimplement, and newly implement
   more of the intelligent and physical performer
   models I've talked about in some of my papers.
   But I wanted to do it in a portable way, and in 
   such a way that I can hook up modules quickly.
   I also wanted to make these instruments connectable
   to such player objects, so folks like Brad Garton
   who really think a lot about the players can connect
   them to my instruments, a lot about which I think.

6) More rationalizations to follow . . .