e1lama/stk
1
0
Fork 0
mirror of https://github.com/thestk/stk synced 2026-01-31 23:06:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

Version 4.2.0

Browse Source
This commit is contained in:
Gary Scavone
2009-03-24 23:02:14 -04:00
committed by Stephen Sinclair
parent cf06b7598b
commit a6381b9d38
281 changed files with 17152 additions and 12000 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
doc/doxygen/Doxyfile
View File

@@ -4,7 +4,7 @@
# Project related configuration options
#---------------------------------------------------------------------------
PROJECT_NAME = STK
PROJECT_NUMBER =
PROJECT_NUMBER = 4.2.0
OUTPUT_DIRECTORY = .
OUTPUT_LANGUAGE = English
USE_WINDOWS_ENCODING = NO
@@ -18,10 +18,10 @@ STRIP_FROM_PATH =
SHORT_NAMES = NO
JAVADOC_AUTOBRIEF = NO
MULTILINE_CPP_IS_BRIEF = NO
DETAILS_AT_TOP = NO
DETAILS_AT_TOP = YES
INHERIT_DOCS = YES
DISTRIBUTE_GROUP_DOC = NO
TAB_SIZE = 8
TAB_SIZE = 9
ALIASES =
OPTIMIZE_OUTPUT_FOR_C = NO
OPTIMIZE_OUTPUT_JAVA = NO
@@ -67,13 +67,13 @@ WARN_LOGFILE =
INPUT = . \
../../include
FILE_PATTERNS = *.txt \
*.h \
*.cpp
*.msg \
*.h
RECURSIVE = YES
EXCLUDE = ../../src/asio
EXCLUDE_SYMLINKS = NO
EXCLUDE_PATTERNS =
EXAMPLE_PATH =
EXAMPLE_PATH = ../../projects/examples
EXAMPLE_PATTERNS =
EXAMPLE_RECURSIVE = NO
IMAGE_PATH =
@@ -83,7 +83,7 @@ FILTER_SOURCE_FILES = NO
# configuration options related to source browsing
#---------------------------------------------------------------------------
SOURCE_BROWSER = YES
INLINE_SOURCES = NO
INLINE_SOURCES = YES
STRIP_CODE_COMMENTS = YES
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION = YES
@@ -117,7 +117,7 @@ TREEVIEW_WIDTH = 250
#---------------------------------------------------------------------------
# configuration options related to the LaTeX output
#---------------------------------------------------------------------------
GENERATE_LATEX = YES
GENERATE_LATEX = NO
LATEX_OUTPUT = latex
LATEX_CMD_NAME = latex
MAKEINDEX_CMD_NAME = makeindex

28
doc/doxygen/compile.txt
View File

@@ -5,7 +5,7 @@ The Synthesis ToolKit can be used in a variety of ways, depending on your partic
\section rtvsnonrt "Realtime" vs. "Non-Realtime"
Most of the Synthesis ToolKit classes are platform independent. That means that they should compile on any reasonably current C++ compiler. The functionality needed for realtime audio and MIDI input/output, as well as realtime control message acquistion, is inherently platform and operating-system (OS) <I>dependent</I>. STK classes which require specific platform/OS support include RtAudio, RtWvOut, RtWvIn, RtDuplex, RtMidi, TcpWvIn, TcpWvOut, Socket, and Thread. These classes currently can only be compiled on Linux, Irix, Macintosh OS X, and Windows systems using the <TT>__LINUX_OSS__</TT>, <TT>__LINUX_ALSA__</TT>, <TT>__IRIX_AL__</TT>, <TT>__MACOSX_CORE__</TT>, <TT>__WINDOWS_DS__</TT>, or <TT>__WINDOWS_ASIO__</TT> preprocessor definitions.
Most of the Synthesis ToolKit classes are platform independent. That means that they should compile on any reasonably current C++ compiler. The functionality needed for realtime audio and MIDI input/output, as well as realtime control message acquistion, is inherently platform and operating-system (OS) <I>dependent</I>. STK classes which require specific platform/OS support include RtAudio, RtWvOut, RtWvIn, RtDuplex, RtMidi, TcpWvIn, TcpWvOut, Socket, Thread, and Mutex. These classes currently can only be compiled on Linux, Irix, Macintosh OS X, and Windows systems.
Without the "realtime" classes, it is still possible to read SKINI scorefiles for control input and to read and write to/from a variety of audio file formats (WAV, SND, AIFF, MAT-file, and RAW). If compiling for a "little-endian" host processor, the <TT>__LITTLE_ENDIAN__</TT> preprocessor definition should be provided.
@@ -25,25 +25,25 @@ STK compiles with realtime support on the following flavors of the Unix operatin
<TR>
<TD>Linux</TD>
<TD>ALSA</TD>
<TD>__LINUX_ALSA__, __LITTLE_ENDIAN__</TD>
<TD>__LINUX_ALSA__, __LINUX_ALSASEQ__, __LITTLE_ENDIAN__</TD>
<TD><TT>asound, pthread</TT></TD>
</TR>
<TR>
<TD>Linux</TD>
<TD>OSS</TD>
<TD>__LINUX_OSS__, __LITTLE_ENDIAN__</TD>
<TD><TT>pthread</TT></TD>
<TD>OSS (audio only, use ALSA for MIDI support)</TD>
<TD>__LINUX_OSS__, __LINUX_ALSASEQ__, __LITTLE_ENDIAN__</TD>
<TD><TT>asound, pthread</TT></TD>
</TR>
<TR>
<TD>Macintosh OS X</TD>
<TD>CoreAudio</TD>
<TD>__MACOSX_CORE__</TD>
<TD><TT>pthread, stdc++, CoreAudio, CoreMIDI, CoreFoundation</TT></TD>
<TD><TT>pthread, CoreAudio, CoreMIDI, CoreFoundation</TT></TD>
</TR>
<TR>
<TD>Irix</TD>
<TD>AL</TD>
<TD>__IRIX_AL__</TD>
<TD>__IRIX_AL__, __IRIX_MD__</TD>
<TD><TT>audio, pthread</TT></TD>
</TR>
</TABLE>
@@ -51,21 +51,21 @@ STK compiles with realtime support on the following flavors of the Unix operatin
The available C++ compilers on any of these systems can vary.
One approach in using STK is to simply copy the class files needed for a particular program into a project directory. Taking the <TT>sineosc.cpp</TT> example from the previous tutorial chapter, it would be necessary to set up a directory that includes the files <TT>sineosc.cpp</TT>, the rawwave file <TT>sinewave.raw</TT> in a subdirectory called <TT>rawwaves</TT>, and the header and source files for the classes Stk, WvIn, WaveLoop, and WvOut. The program could then be compiled on a Linux system using the GNU g++ compiler as follows:
One approach in using STK is to simply copy the class files needed for a particular program into a project directory. Taking the <TT>sineosc.cpp</TT> example from the previous tutorial chapter, it would be necessary to set up a directory that includes the files <TT>sineosc.cpp</TT>, the rawwave file <TT>sinewave.raw</TT> in a subdirectory called <TT>rawwaves</TT>, and the header and source files for the classes Stk, WvIn, WaveLoop, and WvOut. The program could then be compiled on a little-endian system, such as a PC running Linux, using the GNU g++ compiler as follows:
\code
g++ -Wall -D__LITTLE_ENDIAN__ -o sineosc Stk.cpp WvIn.cpp WaveLoop.cpp WvOut.cpp sineosc.cpp
\endcode
Note that the <TT>sineosc.cpp</TT> example does not make use of realtime audio or MIDI input/output classes. For programs using any of the STK realtime classes mentioned above, it is necessary to specify an audio/MIDI API preprocessor definition and link with the appropriate libraries or frameworks.
When working with a number of different projects that make use of ToolKit classes, the above approach can become cumbersome (especially when trying to synchronize with new STK releases). Most of the STK projects (e.g., demo, effects, ...) contain <TT>Makefiles</TT> (built by the configure script) which compile project-specific class objects from the distribution <TT>src</TT> and <TT>include</TT> directories. This approach makes it relatively easy when upgrading to a new STK release (by making path substitutions in the <TT>Makefile</TT> or by moving the projects to a similar relative path within the new STK source tree). A <TT>Makefile</TT> is provided in the <TT>projects/examples</TT> directory for compiling all the tutorial programs, as well as other example programs. To compile the <TT>sineosc.cpp</TT> program, for example, one need only type <TT>make sineosc</TT> from within the <TT>projects/examples</TT> directory. Note that this particular <TT>Makefile</TT> depends on a static library, as described in the next section.
When working with a number of different projects that make use of ToolKit classes, the above approach can become cumbersome (especially when trying to synchronize with new STK releases). Most of the STK projects (e.g., demo, effects, ...) contain <TT>Makefiles</TT> (built by the configure script) which compile project-specific class objects from the distribution <TT>src</TT> and <TT>include</TT> directories. This approach makes it relatively easy when upgrading to a new STK release (by making path substitutions in the <TT>Makefile</TT> or by moving the projects to a similar relative path within the new STK source tree). A <TT>Makefile</TT> is provided in the <TT>projects/examples</TT> directory for compiling all the tutorial programs, as well as other example programs. To compile the <TT>sineosc.cpp</TT> program, for example, one need only type <TT>make sineosc</TT> from within the <TT>projects/examples</TT> directory.
\subsection library Library Use:
The STK distribution provides a <TT>Makefile</TT> that can be used on Unix systems to build a static library. After unpacking the distribution (<TT>tar -xzf stk-4.x.tar.gz</TT>), run the configure script by typing <TT>./configure</TT> from the top level distribution directory (see the INSTALL file in the same directory for more information). Then from within the <TT>src</TT> directory, type <TT>make</TT>. After a successful build, you may wish to move the library (<TT>libstk.a</TT>) and the contents of the <TT>include</TT> directory to standard library and include search paths on your system. For example, the linux RPM distribution of STK puts the library in <TT>/usr/lib/</TT> and the STK header files in <TT>/usr/include/stk/</TT>.
The STK distribution provides a <TT>Makefile</TT> that can be used on Unix systems to build a static library. After unpacking the distribution (<TT>tar -xzf stk-4.x.x.tar.gz</TT>), run the configure script by typing <TT>./configure</TT> from the top level distribution directory (see the INSTALL file in the same directory for more information). Then from within the <TT>src</TT> directory, type <TT>make</TT>. After a successful build, you may wish to move the library (<TT>libstk.a</TT>) and the contents of the <TT>include</TT> directory to standard library and include search paths on your system. For example, the linux RPM distribution of STK puts the library in <TT>/usr/lib/</TT> and the STK header files in <TT>/usr/include/stk/</TT>.
Assuming the library is located in a standard search path and the header files are located in <TT>/usr/include/stk/</TT>, the <TT>sineosc.cpp</TT> example from the previous tutorial chapter can be compiled on a Linux system using the GNU g++ compiler as follows:
Assuming the library is located in a standard search path and the header files are located in <TT>/usr/include/stk/</TT>, the <TT>sineosc.cpp</TT> example from the previous tutorial chapter can be compiled on a little-endian system using the GNU g++ compiler as follows:
\code
g++ -Wall -D__LITTLE_ENDIAN__ -I/usr/include/stk -o sineosc sineosc.cpp -lstk
@@ -91,9 +91,9 @@ STK has been tested on Windows platforms using the Visual C++ compiler only. It
The approach when using Visual C++ is to build a project which includes the necessary ToolKit files from the distribution <TT>src</TT> and <TT>include</TT> directories. For the example program from the previous tutorial chapter, create a VC++ console application project, add the Stk, WvIn, WaveLoop, and WvOut class files, as well as <TT>sineosc.cpp</TT>, and make sure the <TT>sinewave.raw</TT> file is in the subdirectory <TT>rawwaves</TT>.
For programs using any of the STK realtime classes mentioned above, it is necessary to link with the DirectSound (<TT>dsound.lib</TT>), <TT>winmm.lib</TT>, and <TT>Wsock32.lib</TT> libraries, select the multithreaded library, and provide the <TT>__LITTLE_ENDIAN__</TT> and <TT>__WINDOWS_DS__</TT> preprocessor definitions.
For programs using any of the STK realtime classes mentioned above, it is necessary to link with the DirectSound (<TT>dsound.lib</TT>), <TT>winmm.lib</TT>, and <TT>Wsock32.lib</TT> libraries, select the multithreaded library, and provide the <TT>__LITTLE_ENDIAN__</TT>, <TT>__WINDOWS_DS__</TT>, and <TT>__WINDOWS_MM__</TT> preprocessor definitions.
For Steinberg ASIO support, use the <TT>__WINDOWS_ASIO__</TT> preprocessor definition, include all the files in the <TT>src/asio/</TT> directory (i.e., <TT>asio.h,cpp</TT>, <TT>asiodrivers.h,cpp</TT>, ...), and link with the <TT>winmm.lib</TT>, and <TT>Wsock32.lib</TT> libraries.
For Steinberg ASIO support, use the <TT>__WINDOWS_ASIO__</TT> preprocessor definition (and the <TT>__WINDOWS_MM__</TT> definition for RtMidi support), include all the files in the <TT>src/asio/</TT> directory (i.e., <TT>asio.h,cpp</TT>, <TT>asiodrivers.h,cpp</TT>, ...), and link with the <TT>winmm.lib</TT>, and <TT>Wsock32.lib</TT> libraries.
[<A HREF="realtime.html">Next tutorial</A>] &nbsp; [<A HREF="tutorial.html">Main tutorial page</A>]
[<A HREF="filtering.html">Next tutorial</A>] &nbsp; [<A HREF="tutorial.html">Main tutorial page</A>]
*/

113
doc/doxygen/control.txt
View File

@@ -17,114 +17,27 @@ StringDetune 0.100000 2 12.0
NoteOff 1.000000 2 69.0 64.0
\endcode
MIDI messages (with the exception of Sysex) are easily represented within the SKINI protocol.
MIDI messages are easily represented within the SKINI protocol.
The class Messager can be used to acquire and parse MIDI messages from a MIDI device and SKINI messages from STDIN and socket connections. Many of the example programs included with the ToolKit distribution use a Messager instance to accept control input from the accompanying tcl/tk graphical user interfaces, from external MIDI devices, or from SKINI scorefiles.
The class Messager can be used to acquire and parse MIDI messages from a MIDI device and SKINI messages from STDIN and socket connections. Incoming messages are acquired asynchronously and saved to an internal message queue of Skini::Message types (MIDI messages are converted to the Skini:Message format). The user then uses the Messager:popMessage() function to retrieve incoming control messages. This function does not block, instead returning a message type of zero when no more messages are in the queue. Many of the example programs included with the ToolKit distribution use a Messager instance to accept control input from the accompanying tcl/tk graphical user interfaces, from external MIDI devices, or from SKINI scorefiles.
In the following example, we'll modify the <TT>bethree.cpp</TT> program from the previous tutorial chapter and incorporate a Messager class to allow control via a SKINI scorefile.
In the following example, we'll modify the <TT>bethree.cpp</TT> program from the previous tutorial chapter and incorporate a Messager class to allow control via SKINI messages read from a SKINI file.
\include controlbee.cpp
A realtime control message will usually have a delta time of zero, in which case it is processed as soon as possible. Non-realtime messages, normally from a scorefile, will usually have non-zero delta times. The scheme used in this example is designed to work for both scorefile and realtime input types. When no message is available from the queue, the instrument is "ticked" for DELTA_CONTROL_TICKS and then the queue is checked again. The value of DELTA_CONTROL_TICKS roughly defines the program "control rate" in a realtime context, though multiple available messages in the queue are processed in immediate succession when their delta time values are zero.
The \c processMessage() function centralizes the handling of control messages. Other control update schemes can be implemented, perhaps using a separate thread or in the \c main() function, and this function should work in any context.
Assuming the program is compiled as <TT>controlbee</TT> and the SKINI scorefile <A HREF="tutorial/bookert.ski"><TT>bookert.ski</TT></A> is in the <TT>scores</TT> directory, the program can be run as:
\code
// controlbee.cpp
#include "BeeThree.h"
#include "RtWvOut.h"
#include "Messager.h"
#include "SKINI.msg"
#include <math.h>
int main()
{
// Set the global sample rate before creating class instances.
Stk::setSampleRate( 44100.0 );
Instrmnt *instrument = 0;
RtWvOut *output = 0;
Messager *messager = 0;
bool done = FALSE;
try {
// Define and load the BeeThree instrument
instrument = new BeeThree();
// Define and open the default realtime output device for one-channel playback
output = new RtWvOut(1);
}
catch (StkError &) {
goto cleanup;
}
try {
// Create a Messager instance to read from a redirected SKINI scorefile.
messager = new Messager();
}
catch (StkError &) {
goto cleanup;
}
// Play the instrument until the end of the scorefile.
int i, nTicks, type;
MY_FLOAT byte2, byte3, frequency;
while (!done) {
// Look for new messages and return a delta time (in samples).
type = messager->nextMessage();
if (type < 0)
done = TRUE;
nTicks = messager->getDelta();
try {
for ( i=0; i<nTicks; i++ )
output->tick( instrument->tick() );
}
catch (StkError &) {
goto cleanup;
}
if ( type > 0 ) {
// Process the new control message.
byte2 = messager->getByteTwo();
byte3 = messager->getByteThree();
switch(type) {
case __SK_NoteOn_:
frequency = (MY_FLOAT) 220.0 * pow( 2.0, (byte2 - 57.0) / 12.0 );
instrument->noteOn( frequency, byte3 * ONE_OVER_128 );
break;
case __SK_NoteOff_:
instrument->noteOff( byte3 * ONE_OVER_128 );
break;
case __SK_ControlChange_:
instrument->controlChange( (int) byte2, byte3 );
break;
case __SK_AfterTouch_:
instrument->controlChange( 128, byte2 );
break;
}
}
}
cleanup:
delete instrument;
delete output;
delete messager;
return 0;
}
\endcode
Assuming the program is compiled as <TT>controlbee</TT> and the SKINI scorefile <A HREF="tutorial/bookert.ski"><TT>bookert.ski</TT></A> is in the <TT>scores</TT> directory, the scorefile could be redirected to the program as:
\code
controlbee < scores/bookert.ski
controlbee scores/bookert.ski
\endcode
Only a few basic SKINI message type case statements are included in this example. It is easy to extend the program to support a much more elaborate set of instrument control parameters.
This example could also be easily extended to accept "realtime" control input messages via STDIN, socket, or MIDI connections. The Messager class constructor takes an optional argument consisting of a bitmask of the following options: <TT>STK_PIPE</TT>, <TT>STK_SOCKET</TT>, and/or <TT>STK_MIDI</TT>.
This example could also be easily extended to accept "realtime" control input messages via pipe, socket or MIDI connections. The Messager class provides Messager::startStdInput(), Messager::startSocketInput(), and Messager::startMidiInput() functions for this purpose.
[<A HREF="multichannel.html">Next tutorial</A>] &nbsp; [<A HREF="tutorial.html">Main tutorial page</A>]
*/

26
doc/doxygen/crealtime.txt Normal file
View File

@@ -0,0 +1,26 @@
/*! \page crealtime Realtime Audio (callback)
The previous section described the use of the RtWvOut class for realtime audio output. The RtWvOut::tick() function periodically pauses program execution in order to send a buffer of audio data to the computer's audio hardware (referred to as blocking functionality). These pauses will effectively limit a program's computations to the correct number of samples per second, which is defined by the sample rate of the hardware.
An alternative scheme for audio input/output is to define a specific function in which audio computations are performed and to let the audio system call this function when more input/output data can be accepted by the hardware (referred to as a callback scheme). In this section, we show how the previous <TT>rtsine.cpp</TT> program can be modified to work in a callback scenario. There is no "single-sample" interface for this functionality. The callback function will be invoked automatically by the audio system controller (RtAudio) when new data is needed and it is necessary to compute a full audio buffer of samples at that time (see \ref callback for further information).
\include crtsine.cpp
The sinusoidal oscillator is created as before. The instantiation of RtAudio requires quite a few more parameters, including output/input device and channel specifiers, the data format, and the desired buffer length (in frames). In this example, we request a single output channel using the default output device, zero channels of input, the RtAudio data format which corresponds to an <tt>StkFloat</tt>, and the RT_BUFFER_SIZE defined in Stk.h. The last argument is an API-dependent buffering parameter (see RtAudio for further information).
After the digital-to-analog converter (dac) and oscillator are successfully created, it is necessary to provide the audio system controller with a pointer to our callback function. The RtAudio::setStreamCallback() function takes a pointer to the callback function and an optional pointer to data that will be made available in the callback. In this example, we need to pass only the pointer to the oscillator. In more complex programs, it is typically necessary to put all shared data in a <tt>struct</tt> (see the next tutorial program for an example) or make use of global variables.
Our callback routine is the \c tick() function. %Function arguments include a pointer to the audio data buffer, the buffer size (in frames), and the data pointer passed to the RtAudio::setStreamCallback() function (if it exists). It is necessary to cast these pointers to their corresponding data types before use. Our tick() routine simply "ticks" the oscillator for \c bufferSize counts and writes the result into the audio data buffer before returning.
The \c main() function blocks at the std::cin.get() call until the user hits the "enter" key, after which the audio controller is shut down and program execution ends.
\section callback Blocking vs. Callbacks
Prior to version 4.2.0, all STK example projects and programs used blocking audio input/output functionality (typically with the RtWvIn, RtWvOut, or RtDuplex classes). In many instances, a blocking scheme results in a clearer and more straight forward program structure. Within a graphical user interface (GUI) programming context, however, callback routines are often more natural.
The RtAudio class provides both blocking and callback routines for all supported audio APIs. It should be noted that it is easy to embed blocking calls within a thread to create "callback-like" functionality. In fact, this is what RtAudio does for those audio APIs which are naturally based on blocking routines (Linux ALSA and OSS, SGI Irix, and Windows DirectSound). It is much more difficult to make an inherently callback-based system work like a blocking scheme. RtAudio attempts to do this with the Linux JACK, Macintosh OS-X CoreAudio, and Windows ASIO APIs, but the result is not fully robust (audio over/underruns are more likely to occur).
In order to allow all STK programs to function with equal proficiency on all supported computer platforms, a decision was made to modify the example projects to use audio callback routines. The result is a more complicated code structure, which is unfortunate given that we generally strive to make STK code as clear as possible for educational purposes. This was especially an issue with the demo program because it is designed to function in both realtime and non-realtime contexts. The use of global variables has been avoided by defining data structures to hold all variables which must be accessible to the callback routine and other functions. Alternative schemes for making control updates could be designed depending on particular program needs and constraints.
[<A HREF="instruments.html">Next tutorial</A>] &nbsp; [<A HREF="tutorial.html">Main tutorial page</A>]
*/

42
doc/doxygen/download.txt
View File

@@ -1,15 +1,39 @@
/*! \page download Download and Release Notes
<B>Version 4.1.3, 22 March 2004</B><P>
<B>Version 4.2.0, 4 October 2004</B><P>
<UL>
<LI><A HREF="http://www-ccrma.stanford.edu/software/stk/release/stk-4.1.3.tar.gz">Source distribution</A></LI>
<LI><A HREF="http://www-ccrma.stanford.edu/software/stk/release/stk-4.1.3.binaries.tar.gz">Source with precompiled Windows binaries</A></LI>
<LI><A HREF="http://www-ccrma.stanford.edu/software/stk/release/stk-4.2.0.tar.gz">Source distribution</A></LI>
<LI><A HREF="http://www-ccrma.stanford.edu/software/stk/release/stk-4.2.0.binaries.tar.gz">Source with precompiled Windows binaries</A></LI>
<LI><A HREF="http://www-ccrma.stanford.edu/planetccrma/software/">Linux RPMs from Planet CCRMA</A></LI>
</UL>
\section notes Release Notes:
\subsection v4dot2dot0 Version 4.2.0
<ul>
<li>Simultaneous multiple audio APIs supported at compile time.</li>
<li>Various changes to better conform to standard C++ programming practices.</li>
<li>Fixed hidden overloaded virtual functions.</li>
<li>New Asymp exponential envelope class.</li>
<li><tt>MY_FLOAT</tt> type converted to <tt>StkFloat</tt> and changed throughout (use \c treesed utility to search/replace in old files).</li>
<li>Most example programs rewritten to use an audio callback paradigm (which works better in OS-X).</li>
<li>New StkFrames class for vectorized multichannel data and associated new tick() functions making use of StkFrames.</li>
<li>New RtMidi class with MIDI output capabilities (API changes).</li>
<li>New MidiFileIn class for reading MIDI files.</li>
<li>Revised Filter classes to use std::vectors for coefficients (API changes).</li>
<li>Revised Messager class (API changes).</li>
<li>New abstract parent Effect class for various effects.</li>
<li>New abstract parent Generator class for various signal sources.</li>
<li>New abstract parent Function class for tables and various non-linear functions.</li>
<li>Skini class completely rewritten (simplified) using the C++ STL (API changes).</li>
<li>WvOut classes now clip to -1.0 to +1.0 and report out of range.</li>
<li>New Mutex class.</li>
<li>Turned Nagle algorithm off by default in Socket class.</li>
<li>Error reporting standardized in all classes.</li>
</ul>
\subsection v4dot1dot3 Version 4.1.3
<ul>
@@ -30,7 +54,7 @@
<li>Update to the contentsAt() method of Delay class.</li>
<li>WAV file fixes (8-bit) in WvIn and WvOut classes.</li>
<li>Configure script changes.</li>
<li>Updated <iostream> include statements and appended "std::" as necessary throughout for compatibility with gcc 3.</li>
<li>Updated \<iostream\> include statements and appended "std::" as necessary throughout for compatibility with gcc 3.</li>
</UL>
\subsection v4dot1dot1 Version 4.1.1
@@ -138,7 +162,7 @@
<LI>Added RawWvOut class.</LI>
<LI>New WvIn class with RawWvIn, SndWvIn, WavWvIn, MatWvIn, and RTWvIn subclasses.</LI>
<LI>Removed RawWave, RawShot, RawInterp, and RawLoop classes (supplanted by RawWvIn).</LI>
<LI>Multi-channel data support in WvIn and WvOut classes using MY_MULTI data type (pointer to MY_FLOAT) and the methods mtick() and mlastOutput().</LI>
<LI>Multi-channel data support in WvIn and WvOut classes using MY_MULTI data type (pointer to StkFloat) and the methods mtick() and mlastOutput().</LI>
<LI>Now writing to primary buffer under Windoze when allowed by hardware.</LI>
<LI>Cleaned up Object.h a bit.</LI>
<LI>Pulled various utility and thread functions out of syntmono.cpp (to aid readability of the code).</LI>
@@ -160,11 +184,11 @@
<UL>
<LI>Unification of the capabilities of STK across the various platforms. All of the previous SGI functionality has been ported to Linux and Windows, including realtime sound output and MIDI input.</LI>
<LI>MIDI input (with optional time-stamping) supported on SGI, Linux (OSS device drivers only), and Windows operating systems. Time stamping under IRIX and Windows is quantized to milliseconds and under Linux to hundredths of a second.</LI>
<LI>Various Sound Output Options - .wav, .snd, and .mat (Matlab MAT-file) soundfile outputs are supported on all operating systems. I hacked out the MAT-file structure, so you don't have to include any platform-specific libraries. Realtime sound output is provided as well, except under NeXTStep. </LI>
<LI>Various Sound Output Options - .wav, .snd, and .mat (Matlab MAT-file) soundfile outputs are supported on all operating systems. I hacked out the MAT-file structure, so you don't have to include any platform-specific libraries. Realtime sound output is provided as well, except under NeXTStep.</LI>
<LI>Multiple Reverberator Implementations - Reverb subclasses of JCRev and NRev (popular reverberator implementations from CCRMA) have been written. Perry's original reverb implementation still exists as PRCRev. All reverberators now take a T60 initializer argument.</LI>
<LI>MD2SKINI - A program which parses a MIDI input stream and spits out SKINI code. The output of MD2SKINI is typically piped into an STK instrument executable (eg. <FONT FACE="Geneva">MD2SKINI | syntmono Clarinet -r -i</FONT>). In addition, you can supply a filename argument to MD2SKINI and have it simultaneously record a SKINI score file for future reuse.
<LI>Modifications to <I>Object.h</I> for OS_TYPE compilation dependencies. <I>Makefile</I> automatically determines OS_TYPE when invoked (if you have the GNU makefile utilities installed on your system).
<LI>A single distribution for all platforms. The Unix and Windows versions have been merged into a single set of classes. Makefiles and Visual C++ workspace/project files are provided for compiling.
<LI>MD2SKINI - A program which parses a MIDI input stream and spits out SKINI code. The output of MD2SKINI is typically piped into an STK instrument executable (eg. <tt>MD2SKINI | syntmono Clarinet -r -i</tt>). In addition, you can supply a filename argument to MD2SKINI and have it simultaneously record a SKINI score file for future reuse.</LI>
<LI>Modifications to <I>Object.h</I> for OS_TYPE compilation dependencies. <I>Makefile</I> automatically determines OS_TYPE when invoked (if you have the GNU makefile utilities installed on your system).</LI>
<LI>A single distribution for all platforms. The Unix and Windows versions have been merged into a single set of classes. Makefiles and Visual C++ workspace/project files are provided for compiling.</LI>
</UL>
*/

88
doc/doxygen/filtering.txt Normal file
View File

@@ -0,0 +1,88 @@
/*! \page filtering Using Filters
In this section, we demonstrate the use of a few of the STK filter classes. The Filter class provides functionality to implement a generalized digital filter of any type, similar to the \c filter function in Matlab. In this example, we create a Filter instance and initialize it with specific numerator and denominator coefficients. We then compute its impulse response for 20 samples.
\code
#include "Filter.h"
int main()
{
StkFrames output( 20 ); // initialize StkFrames to 20 elements (defaults: 1 channel, interleaved)
output[0] = 1.0;
std::vector<StkFloat> numerator( 5, 0.1 ); // create and initialize numerator coefficients
std::vector<StkFloat> denominator; // create empty denominator coefficients
denominator.push_back( 1.0 ); // populate our denomintor values
denominator.push_back( 0.3 );
denominator.push_back( -0.5 );
Filter filter( numerator, denominator );
filter.tick( output );
for ( unsigned int i=0; i<output.size(); i++ ) {
std::cout << "i = " << i << " : output = " << output[i] << std::endl;
}
return 0;
}
\endcode
The Filter class implements the standard difference equation
\code
a[0]*y[n] = b[0]*x[n] + ... + b[nb]*x[n-nb] - a[1]*y[n-1] - ... - a[na]*y[n-na],
\endcode
where "b" values are numerator coefficients and "a" values are denominator coefficients. Note that if the first denominator coefficient is not 1.0, the Filter class automatically normalizes all filter coefficients by that value. The coefficient values are passed to the Filter class via a C++ <a href="http://www.roguewave.com/support/docs/sourcepro/stdlibref/vector.html">vector</a>, a container object provided by the C++ Standard Library.
Most STK classes use more specific types of digital filters, such as the OneZero, OnePole, TwoPole, or BiQuad varieties. These classes inherit from the Filter class and provide specific functionality particular to their use, as well as functions to independently control individual coefficient values.
\section reson Resonances:
The STK BiQuad and TwoPole classes provide functionality for creating resonance filters. The following example demonstrates how to create a resonance centered at 440 Hz that is used to filter the output of a Noise generator.
\code
#include "BiQuad.h"
#include "Noise.h"
int main()
{
StkFrames output( 20 ); // initialize StkFrames to 20 elements (defaults: 1 channel, interleaved)
Noise noise;
BiQuad biquad;
biquad.setResonance( 440.0, 0.98, true ); // automatically normalize for unity peak gain
for ( unsigned int i=0; i<output.size(); i++ ) {
output[i] = biquad.tick( noise.tick() ); // single-sample computations
std::cout << "i = " << i << " : output = " << output[i] << std::endl;
}
return 0;
}
\endcode
By passing a boolian value of \c true as the third argument to the BiQuad::setResonance() function, the filter coefficients are automatically scaled to achieve unity gain at the resonance peak frequency. The previous code could be easily modified for "vector-based" calculations:
\code
#include "BiQuad.h"
#include "Noise.h"
int main()
{
StkFrames output( 20 ); // initialize StkFrames to 20 elements (defaults: 1 channel, interleaved)
Noise noise;
BiQuad biquad;
biquad.setResonance( 440.0, 0.98, true ); // automatically normalize for unity peak gain
biquad.tick( noise.tick( output ) ); // vector-based computations
for ( unsigned int i=0; i<output.size(); i++ ) {
std::cout << "i = " << i << " : output = " << output[i] << std::endl;
}
return 0;
}
\endcode
[<A HREF="realtime.html">Next tutorial</A>] &nbsp; [<A HREF="tutorial.html">Main tutorial page</A>]
*/

2
doc/doxygen/footer.html
View File

@@ -1,7 +1,7 @@
<HR>
<table>
<tr><td><A HREF="http://www-ccrma.stanford.edu/software/stk/"><I>The Synthesis ToolKit in C++ (STK)</I></A></td></tr>
<tr><td><A HREF="http://ccrma.stanford.edu/software/stk/"><I>The Synthesis ToolKit in C++ (STK)</I></A></td></tr>
<tr><td>&copy;1995-2004 Perry R. Cook and Gary P. Scavone. All Rights Reserved.</td></tr>
</table>

63
doc/doxygen/fundamentals.txt Normal file
View File

@@ -0,0 +1,63 @@
/*! \page fundamentals STK Fundamentals
The Synthesis ToolKit is implemented in the C++ programming language. STK does not attempt to provide a new programming environment or paradigm but rather provides a set of objects which can be used within a normal C++ programming framework. Therefore, it is expected that users of STK will have some familiarity with C/C++ programming concepts. That said, the STK classes do have some particular idiosyncrasies that we will mention here.
\section Signal Computations:
Audio and control signals throughout STK use a floating-point data type, <tt>StkFloat</tt>, the exact precision of which can be controlled via a typedef statement in Stk.h. By default, an StkFloat is a double-precision floating-point value. Thus, the ToolKit can use any normalization scheme desired. The base instruments and algorithms are implemented with a general audio sample dynamic maximum of +/-1.0.
In general, the computation and/or passing of values is performed on a "single-sample" basis. For example, the Noise class outputs random floating-point numbers in the range +/-1.0. The computation of such values occurs in the Noise::tick() function. The following program will generate 20 random floating-point (<tt>StkFloat</tt>) values in the range -1.0 to +1.0:
\code
#include "Noise.h"
int main()
{
StkFloat output;
Noise noise;
for ( unsigned int i=0; i<20; i++ ) {
output = noise.tick();
std::cout << "i = " << i << " : output = " << output << std::endl;
}
return 0;
}
\endcode
Nearly all STK classes implement <TT>tick()</TT> functions which take and/or return sample values. Within the <TT>tick()</TT> function, the fundamental sample calculations are performed for a given class. Most STK classes consume/generate a single sample per operation and their <TT>tick()</TT> method takes/returns each sample "by value". In addition, every class implementing a <TT>tick()</TT> function also provides one or more overloaded <TT>tick()</TT> functions which can be used for vectorized computations, as shown in the next example.
\code
#include "Noise.h"
int main()
{
StkFrames output(20); // initialize StkFrames to 20 elements (defaults: 1 channel, interleaved)
Noise noise;
noise.tick( output );
for ( unsigned int i=0; i<output.size(); i++ ) {
std::cout << "i = " << i << " : output = " << output[i] << std::endl;
}
return 0;
}
\endcode
In this way, it might be possible to achieve improved processing efficiency using vectorized computations. The StkFrames class is a new addition to the ToolKit to provide a general "mechanism" for handling and passing vectorized, multi-channel audio data. The StkFrames "type" provides functions to set and/or determine the number of audio channels and sample frames it holds, as well as the format (interleaved or non-interleaved) of its data.
\section STK Inheritance:
Nearly all STK classes inherit from the Stk abstract base class, which provides common functionality related to error reporting, sample rate control, and byte swapping. Several other base classes exist which roughly group many of the classes according to function as follows:
- Generator: source signal unit generator classes [Envelope, ADSR, Asymp, Noise, SubNoise, Modulate, SingWave]
- Filter: digital filtering classes [OneZero, OnePole, PoleZero, TwoZero, TwoPole, BiQuad, FormSwep, Delay, DelayL, DelayA]
- Function: input to output function mappings [Table, BowTable, JetTable, ReedTable]
- Instrmnt: sound synthesis algorithms, including physical, FM, modal, and particle models
- Effect: sound processing effect classes [Echo, Chorus, PitShift, PRCRev, JCRev, NRev]
- WvOut: audio file and streaming output classes [RtWvOut, TcpWvOut]
- WvIn: audio file and streaming input classes [WaveLoop, RtWvIn, TcpWvIn]
[<A HREF="hello.html">Next tutorial</A>] &nbsp; [<A HREF="tutorial.html">Main tutorial page</A>]
*/

61
doc/doxygen/hello.txt
View File

@@ -1,6 +1,6 @@
/*! \page hello Hello Sine!
We'll begin our introduction to the Synthesis ToolKit with a simple sine-wave oscillator program. STK does not provide a specific oscillator for sine waves. Instead, it provides a generic waveform oscillator class, WaveLoop, which can load a variety of common file types. In this example, we load a sine "table" from an STK RAW file (defined as monophonic, 16-bit, big-endian data). We use the class WvOut to write the result to a 16-bit, WAV formatted audio file.
We'll continue our introduction to the Synthesis ToolKit with a simple sine-wave oscillator program. STK does not provide a specific oscillator for sine waves. Instead, it provides a generic waveform oscillator class, WaveLoop, which can load a variety of common file types. In this example, we load a sine "table" from an STK RAW file (defined as monophonic, 16-bit, big-endian data). We use the class WvOut to write the result to a 16-bit, WAV formatted audio file.
\code
@@ -15,11 +15,11 @@ int main()
Stk::setSampleRate( 44100.0 );
// Define and load the sine wave file
WaveLoop *input = new WaveLoop( "rawwaves/sinewave.raw", TRUE );
WaveLoop* input = new WaveLoop( "rawwaves/sinewave.raw", true );
input->setFrequency( 440.0 );
// Define and open a 16-bit, one-channel WAV formatted output file
output = new WvOut( "hellosine.wav", 1, WvOut::WVOUT_WAV, Stk::STK_SINT16 );
WvOut* output = new WvOut( "hellosine.wav", 1, WvOut::WVOUT_WAV, Stk::STK_SINT16 );
// Run the oscillator for 40000 samples, writing to the output file
int i;
@@ -39,66 +39,17 @@ WaveLoop is a subclass of WvIn, which supports WAV, SND (AU), AIFF, MAT-file (Ma
The WvIn and WvOut classes are complementary, both supporting WAV, SND (AU), AIFF, MAT-file (Matlab), and RAW file formats with 8-, 16-, and 32-bit integer and 32- and 64-bit floating-point data types. However, WvOut does not perform data interpolation.
Nearly all STK classes implement <TT>tick()</TT> functions which take and/or return sample values. Within the <TT>tick()</TT> function, the fundamental sample calculations are performed for a given class. Most STK classes consume/generate a single sample per operation and their <TT>tick()</TT> method takes/returns each sample "by value". In addition, every class implementing a <TT>tick()</TT> function also provides an overloaded <TT>tick()</TT> function taking pointer and size arguments which can be used for vectorized computations.
The WvIn and WvOut classes support multi-channel sample frames. To distinguish single-sample frame operations from multi-channel frame operations, these classes also implement <TT>tickFrame()</TT> functions. When a <TT>tick()</TT> method is called for multi-channel data, frame averages are returned or the input sample is distributed across all channels of a sample frame.
Nearly all STK classes inherit from the Stk base class. Stk provides a static sample rate which is queried by subclasses as needed. Because many classes use the current sample rate value during instantiation, it is important that the desired value be set at the beginning of a program. The default STK sample rate is 22050 Hz.
Another primary concept that is somewhat obscurred in this example concerns the data format in which sample values are passed and received. Audio and control signals throughout STK use a floating-point data type, the exact precision of which can be controlled via the <TT>MY_FLOAT</TT> \#define statement in Stk.h. Thus, the ToolKit can use any normalization scheme desired. The base instruments and algorithms are implemented with a general audio sample dynamic maximum of +/-1.0, and the WvIn and WvOut classes and subclasses scale appropriately for DAC or soundfile input and output.
Nearly all STK classes inherit from the Stk base class. Stk provides a static sample rate which is queried by subclasses as needed. Because many classes use the current sample rate value during instantiation, it is important that the desired value be set at the beginning of a program. The default STK sample rate is 44100 Hz.
\section error Error Handling
The ToolKit has some basic C++ error handling functionality built in. Classes which access files and/or hardware are most prone to runtime errors. To properly "catch" such errors, the above example should be rewritten as shown below.
\code
// sineosc.cpp
#include "WaveLoop.h"
#include "WvOut.h"
int main()
{
// Set the global sample rate before creating class instances.
Stk::setSampleRate( 44100.0 );
WaveLoop *input = 0;
WvOut *output = 0;
try {
// Define and load the sine wave file
input = new WaveLoop( "rawwaves/sinewave.raw", TRUE );
// Define and open a 16-bit, one-channel WAV formatted output file
output = new WvOut( "hellosine.wav", 1, WvOut::WVOUT_WAV, Stk::STK_SINT16 );
}
catch ( StkError & ) {
goto cleanup;
}
input->setFrequency( 440.0 );
// Run the oscillator for 40000 samples, writing to the output file
for ( int i=0; i<40000; i++ ) {
try {
output->tick( input->tick() );
}
catch ( StkError & ) {
goto cleanup;
}
}
cleanup:
delete input;
delete output;
return 0;
}
\endcode
\include sineosc.cpp
In this particular case, we simply exit the program if an error occurs (an error message is automatically printed to stderr). A more refined program might attempt to recover from or fix a particular problem and, if successful, continue processing. See the \ref classes to determine which constructors and functions can throw an error.
[<A HREF="compile.html">Next tutorial</A>] &nbsp; [<A HREF="tutorial.html">Main tutorial page</A>]
[<A HREF="compile.html">Next tutorial</A>] &nbsp; [<A HREF="fundamentals.html">Main tutorial page</A>]
*/

6
doc/doxygen/index.txt
View File

@@ -2,9 +2,11 @@
<BODY BGCOLOR="white">
<center><h3>Perry R. Cook & Gary P. Scavone</h3></center>
\htmlonly
<h3><center><a href="http://www.cs.princeton.edu/~prc/">Perry R. Cook</a> & <a href="http://music.mcgill.ca/~gary/">Gary P. Scavone</a></center></h3>
\endhtmlonly
The <B>Synthesis ToolKit in C++ (STK)</B> is a set of open source audio signal processing and algorithmic synthesis classes written in C++. STK was designed to facilitate rapid development of music synthesis and audio processing software, with an emphasis on cross-platform functionality, realtime control, ease of use, and educational example code. The Synthesis ToolKit is extremely portable (it's mostly platform-independent C and C++ code), and it's completely user-extensible (all source included, no unusual libraries, and no hidden drivers). We like to think that this increases the chances that our programs will still work in another 5-10 years. In fact, the ToolKit has been working continuously for nearly 8 years now. STK currently runs with "realtime" support (audio and MIDI) on SGI (Irix), Linux, Macintosh OS X, and Windows computer platforms. Generic, non-realtime support has been tested under NeXTStep, Sun, and other platforms and should work with any standard C++ compiler.
The <B>Synthesis ToolKit in C++ (STK)</B> is a set of open source audio signal processing and algorithmic synthesis classes written in the C++ programming language. STK was designed to facilitate rapid development of music synthesis and audio processing software, with an emphasis on cross-platform functionality, realtime control, ease of use, and educational example code. The Synthesis ToolKit is extremely portable (it's mostly platform-independent C and C++ code), and it's completely user-extensible (all source included, no unusual libraries, and no hidden drivers). We like to think that this increases the chances that our programs will still work in another 5-10 years. In fact, the ToolKit has been working continuously for nearly 10 years now. STK currently runs with "realtime" support (audio and MIDI) on SGI (Irix), Linux, Macintosh OS X, and Windows computer platforms. Generic, non-realtime support has been tested under NeXTStep, Sun, and other platforms and should work with any standard C++ compiler.
- \ref information
- \ref classes

40
doc/doxygen/information.txt
View File

@@ -4,11 +4,11 @@
<UL>
<LI><A HREF="Papers/stkicmc99.pdf">ICMC99 Paper</A></LI>
<BR>
A somewhat recent paper by Perry and Gary about the Synthesis ToolKit in C++.
A not-so-recent paper by Perry and Gary about the Synthesis ToolKit in C++.
<P>
<LI><A HREF="Papers/STKsiggraph96.pdf">SIGGRAPH96 Paper</A></LI>
<BR>
A not-so-recent paper by Perry about the Synthesis ToolKit in C++.
A very-not-so-recent paper by Perry about the Synthesis ToolKit in C++.
<P>
<LI><A HREF="http://www.cs.princeton.edu/~prc/NewWork.html#STK">Perry's STK Web Page</A></LI>
<BR>
@@ -18,14 +18,14 @@ This is a link to Perry Cook's STK Web page. He has information about the \ref
<H4>What is the <I>Synthesis ToolKit</I>?</H4>
The Synthesis ToolKit in C++ (STK) is a set of open source audio signal processing and algorithmic synthesis classes written in C++. STK was designed to facilitate rapid development of music synthesis and audio processing software, with an emphasis on cross-platform functionality, realtime control, ease of use, and educational example code. The Synthesis ToolKit is extremely portable (it's mostly platform-independent C and C++ code), and it's completely user-extensible (all source included, no unusual libraries, and no hidden drivers). We like to think that this increases the chances that our programs will still work in another 5-10 years. In fact, the ToolKit has been working continuously for nearly 8 years now. STK currently runs with "realtime" support (audio and MIDI) on SGI (Irix), Linux, Macintosh OS X, and Windows computer platforms. Generic, non-realtime support has been tested under NeXTStep, Sun, and other platforms and should work with any standard C++ compiler.
The Synthesis ToolKit in C++ (STK) is a set of open source audio signal processing and algorithmic synthesis classes written in the C++ programming language. STK was designed to facilitate rapid development of music synthesis and audio processing software, with an emphasis on cross-platform functionality, realtime control, ease of use, and educational example code. The Synthesis ToolKit is extremely portable (it's mostly platform-independent C and C++ code), and it's completely user-extensible (all source included, no unusual libraries, and no hidden drivers). We like to think that this increases the chances that our programs will still work in another 5-10 years. In fact, the ToolKit has been working continuously for nearly 10 years now. STK currently runs with "realtime" support (audio and MIDI) on SGI (Irix), Linux, Macintosh OS X, and Windows computer platforms. Generic, non-realtime support has been tested under NeXTStep, Sun, and other platforms and should work with any standard C++ compiler.
The Synthesis ToolKit is free for non-commercial use. The only parts of the Synthesis ToolKit that are platform-dependent concern real-time audio and MIDI input and output, and that is taken care of with a few special classes. The interface for MIDI input and the simple <A HREF="http://dev.scriptics.com">Tcl/Tk</A> graphical user interfaces (GUIs) provided is the same, so it's easy to experiment in real time using either the GUIs or MIDI. The Synthesis ToolKit can generate simultaneous SND (AU), WAV, AIFF, and MAT-file output soundfile formats (as well as realtime sound output), so you can view your results using one of a large variety of sound/signal analysis tools already available (e.g. <A HREF="http://www-ccrma.stanford.edu/software/snd/">Snd</A>, Cool Edit, Matlab).
<H4>What the <I>Synthesis ToolKit</I> is not.</H4>
The Synthesis Toolkit is not one particular program. Rather, it is a set of C++ classes that you can use to create your own programs. A few example applications are provided to demonstrate some of the ways to use the classes. 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" graphical patching GUI, you probably don't want to use the ToolKit. Spending hundreds of hours making platform-dependent graphics code would go against one of the fundamental design goals of the ToolKit - platform independence.
The Synthesis Toolkit is not one particular program. Rather, it is a set of C++ classes that you can use to create your own programs. A few example applications are provided to demonstrate some of the ways to use the classes. 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. It is easy to embed STK classes inside a GUI environment but we have chosen to focus our energy on the audio signal processing issues. Spending hundreds of hours making platform-dependent graphical user interfaces would go against one of the fundamental design goals of the ToolKit - platform independence.
For those instances where a simple GUI with sliders and buttons is helpful, we use <A HREF="http://dev.scriptics.com">Tcl/Tk</A> (which is freely distributed for all the supported ToolKit platforms). A number of Tcl/Tk GUI scripts are distributed with the ToolKit release. For control, the Synthesis Toolkit uses raw MIDI (on supported platforms), and SKINI (Synthesis ToolKit Instrument Network Interface, a MIDI-like text message synthesis control format).
@@ -33,7 +33,7 @@ For those instances where a simple GUI with sliders and buttons is helpful, we u
Perry Cook began developing a pre-cursor to the Synthesis ToolKit (also called STK) under NeXTStep at the Center for Computer Research in Music and Acoustics (CCRMA) at Stanford University in the early-1990s. With his move to Princeton University in 1996, he ported everything to C++ on SGI hardware, added real-time capabilities, and greatly expanded the synthesis techniques available. With the help of Bill Putnam, Perry also made a port of STK to Windows95. Gary Scavone began using STK extensively in the summer of 1997 and completed a full port of STK to Linux early in 1998. He finished the fully compatable Windows port (using Direct Sound API) in June 1998. Numerous improvements and extensions have been made since then.
The Toolkit has been distributed continuously since 1996 via the <A HREF="http://www.music.princeton.edu/psk">Princeton Sound Kitchen</A>, <A HREF="http://www.cs.princeton.edu/~prc">Perry Cook's home page</A> at Princeton, <A HREF="http://www-ccrma.stanford.edu/~gary/">Gary Scavone's home page</A> at Stanford's Center for Computer Research in Music and Acoustics (CCRMA), and the <A HREF="http://www-ccrma.stanford.edu/software/stk">Synthesis ToolKit home page</A>. The ToolKit has been in included in various collections of software. Much of it has also been ported to MAX/MSP on Macintosh computers by Dan Trueman and Luke Dubois of Columbia University, and is distributed as <A HREF="http://music.columbia.edu/PeRColate">PeRColate</A>. Help on real-time sound and MIDI has been provided by Tim Stilson, Bill Putnam, and Gabriel Maldonado.
The Toolkit has been distributed continuously since 1996 via the <A HREF="http://www.music.princeton.edu/psk">Princeton Sound Kitchen</A>, <A HREF="http://www.cs.princeton.edu/~prc">Perry Cook's home page</A> at Princeton, <A HREF="http://www-ccrma.stanford.edu/~gary/">Gary Scavone's home page</A> at Stanford's Center for Computer Research in Music and Acoustics (CCRMA), and the <A HREF="http://www-ccrma.stanford.edu/software/stk">Synthesis ToolKit home page</A>. The ToolKit has been included in various collections of software. Much of it has also been ported to Max/MSP on Macintosh computers by Dan trueman and Luke Dubois of Columbia University, and is distributed as <A HREF="http://music.columbia.edu/PeRColate">PeRColate</A>. Help on real-time sound and MIDI has been provided over the years by Tim Stilson, Bill Putnam, and Gabriel Maldonado.
<H4>Legal and Ethical Notes</H4>
@@ -47,4 +47,32 @@ Some of the concepts are covered by various patents, some known to us and likely
STK is free and we do not guarantee anything. We've been hacking on this code for a while now and most of it seems to work pretty well. But, there surely are some bugs floating around. Sometimes things work fine on one computer platform but not so fine on another. FPU overflows and underflows cause <I>very</I> weird behavior which also depends on the particular CPU and OS. Let us know about bugs you find and we'll do our best to correct them.
*/
<H4>Perry's Notes From the Original Distribution of STK</H4>
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 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.
<ol>
<li>I needed to port many of the things I've done into something which is generic enough to port further to different machines.</li>
<li>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.)</li>
<li>The classic difficulties most people have in trying to implement physical models are:
<ul>
<li>They have trouble understanding the papers, and/or in turning the theory into practice.</li>
<li>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.</li>
</ul>
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.</li>
<li>I wanted to try some new stuff with modal synthesis, and implement some classic FM patches as well.</li>
<li>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.</li>
<li>More rationalizations to follow ...</li>
</ol>
*/

62
doc/doxygen/instruments.txt
View File

@@ -1,66 +1,8 @@
/*! \page instruments Instruments
The ToolKit comes with a wide variety of synthesis algorithms, all of which inherit from the Instrmnt class. In this example, we'll fire up an instance of the BeeThree FM synthesis class and show how it's frequency can be modified over time.
The ToolKit comes with a wide variety of synthesis algorithms, all of which inherit from the Instrmnt class. In this example, we'll fire up an instance of the BeeThree FM synthesis class and show how its frequency can be modified over time.
\code
// bethree.cpp
#include "BeeThree.h"
#include "RtWvOut.h"
int main()
{
// Set the global sample rate before creating class instances.
Stk::setSampleRate( 44100.0 );
Instrmnt *instrument = 0;
RtWvOut *output = 0;
MY_FLOAT frequency, amplitude, scaler;
long counter, i;
try {
// Define and load the BeeThree instrument
instrument = new BeeThree();
// Define and open the default realtime output device for one-channel playback
output = new RtWvOut(1);
}
catch (StkError &) {
goto cleanup;
}
scaler = 1.0;
frequency = 220.0;
amplitude = 0.5;
instrument->noteOn( frequency, amplitude );
// Play the instrument for 80000 samples, changing the frequency every 2000 samples
counter = 0;
while ( counter < 80000 ) {
for ( i=0; i<2000; i++ ) {
try {
output->tick( instrument->tick() );
}
catch (StkError &) {
goto cleanup;
}
}
counter += 2000;
scaler += 0.025;
instrument->setFrequency( frequency * scaler );
}
// Turn the instrument off with maximum decay envelope.
instrument->noteOff( 1.0 );
cleanup:
delete instrument;
delete output;
return 0;
}
\endcode
\include bethree.cpp
We have used an Instrmnt pointer when referencing the BeeThree instance above, so it would be simple to replace the BeeThree class with any other STK instrument class. It should be noted, however, that a few classes do not respond to the setFrequency() function (e.g., Shakers, Drummer).

8
doc/doxygen/links.txt
View File

@@ -1,6 +1,12 @@
/*! \page links Miscellaneous Links
- <A HREF="http://www-ccrma.stanford.edu/~gary/rtaudio/">The RtAudio WWW site</A>
- <A HREF="http://music.mcgill.ca/~gary/rtaudio/">The %RtAudio WWW site</A>
- <A HREF="http://music.mcgill.ca/~gary/rtmidi/">The %RtMidi WWW site</A>
- <A HREF="http://chuck.cs.princeton.edu/">ChucK: Concurrent, On-the-fly Audio Programming Language</A> using STK unit generators
- <A HREF="http://www.music.princeton.edu/paul/stkugens.tar.gz">Paul Lansky's port of STK to SuperCollider</A>
- <A HREF="http://kern.humdrum.net/">Kern Scores: A Library of Electronic Musical Scores</A> (with automatic conversion to SKINI format)

58
doc/doxygen/multichannel.txt
View File

@@ -8,63 +8,7 @@ Multi-channel support for realtime audio input and output is dependent on the au
The following example demonstrates the use of the WvOut class for creating a four channel, 16-bit AIFF formatted audio file. We will use four sinewaves of different frequencies for the first two seconds and then a single sinewave for the last two seconds.
\code
// foursine.cpp
#include "WaveLoop.h"
#include "WvOut.h"
int main()
{
// Set the global sample rate before creating class instances.
Stk::setSampleRate( 44100.0 );
int i, j;
WvOut *output = 0;
WaveLoop *inputs[4];
for ( i=0; i<4; i++ ) inputs[i] = 0;
// Define and load the sine waves
try {
for ( i=0; i<4; i++ ) {
inputs[i] = new WaveLoop( "rawwaves/sinewave.raw", TRUE );
inputs[i]->setFrequency( 220.0 * (i+1) );
}
}
catch (StkError &) {
goto cleanup;
}
// Define and open a 16-bit, four-channel AIFF formatted output file
try {
output = new WvOut( "foursine.aif", 4, WvOut::WVOUT_AIF, Stk::STK_SINT16 );
}
catch (StkError &) {
goto cleanup;
}
// Write two seconds of four sines to the output file
MY_FLOAT frame[4];
for ( j=0; j<88200; j++ ) {
for ( i=0; i<4; i++ )
frame[i] = inputs[i]->tick();
output->tickFrame( frame );
}
// Now write the first sine to all four channels for two seconds
for ( j=0; j<88200; j++ ) {
output->tick( inputs[0]->tick() );
}
cleanup:
for ( i=0; i<4; i++ ) delete inputs[i];
delete output;
return 0;
}
\endcode
\include foursine.cpp
[<A HREF="polyvoices.html">Next tutorial</A>] &nbsp; [<A HREF="tutorial.html">Main tutorial page</A>]
*/

112
doc/doxygen/polyvoices.txt
View File

@@ -1,122 +1,22 @@
/*! \page polyvoices Voice Management
The previous tutorial chapters were concerned only with monophonic ToolKit instrument playback and control. At this point, it should be relatively clear that one can instantiate multiple instruments and perhaps sum together their sounds or even direct their sounds to separate output channels. It is less clear how one might go about controlling a group of instruments. The Voicer class is designed to serve just this purpose.
The previous tutorial chapters were concerned only with monophonic ToolKit instrument playback and control. At this point, it should be relatively clear that one can instantiate multiple instruments and perhaps sum together their outputs or even direct their outputs to separate channels. It is less clear how one might go about controlling a group of instruments. The Voicer class is designed to serve just this purpose.
The STK Voicer class is a relatively simple voice manager. The user can dynamically add and delete instruments from its "control", with the option of controlling specific instruments via unique note tags and/or grouping sets of instruments via a "channel" number. All sounding instrument outputs are summed and returned via the <TT>tick()</TT> function. The Voicer class responds to noteOn, noteOff, setFrequency, pitchBend, and controlChange messages, automatically assigning incoming messages to the voices in its control. When all voices are sounding and a new noteOn is encountered, the Voicer interrupts the oldest sounding voice. The user is responsible for creating and deleting all instrument instances.
The STK Voicer class is a relatively simple voice manager. The user can dynamically add and delete instruments to/from its "control", with the option of controlling specific instruments via unique note tags and/or grouping sets of instruments via a "channel" number. All sounding instrument outputs are summed and returned via the <TT>tick()</TT> function. The Voicer class responds to noteOn, noteOff, setFrequency, pitchBend, and controlChange messages, automatically assigning incoming messages to the voices in its control. When all voices are sounding and a new noteOn is encountered, the Voicer interrupts the oldest sounding voice. The user is responsible for creating and deleting all instrument instances.
In the following example, we modify the <TT>controlbee.cpp</TT> program to make use of three BeeThree instruments, all controlled using a Voicer.
\code
// threebees.cpp
\include threebees.cpp
#include "BeeThree.h"
#include "RtWvOut.h"
#include "Messager.h"
#include "Voicer.h"
#include "SKINI.msg"
int main()
{
// Set the global sample rate before creating class instances.
Stk::setSampleRate( 44100.0 );
int i;
RtWvOut *output = 0;
Messager *messager = 0;
Voicer *voicer = 0;
bool done = FALSE;
Instrmnt *instrument[3];
for ( i=0; i<3; i++ ) instrument[i] = 0;
try {
// Define and load the BeeThree instruments
for ( i=0; i<3; i++ )
instrument[i] = new BeeThree();
// Define and open the default realtime output device for one-channel playback
output = new RtWvOut(1);
}
catch (StkError &) {
goto cleanup;
}
try {
// Create a Messager instance to read from a redirected SKINI scorefile.
messager = new Messager();
}
catch (StkError &) {
goto cleanup;
}
// Instantiate the voicer for a maximum of three voices.
voicer = new Voicer( 3 );
for ( i=0; i<3; i++ )
voicer->addInstrument( instrument[i] );
// Play the instrument until the end of the scorefile.
int nTicks, type;
MY_FLOAT byte2, byte3;
while (!done) {
// Look for new messages and return a delta time (in samples).
type = messager->nextMessage();
if (type < 0)
done = TRUE;
nTicks = messager->getDelta();
try {
for ( i=0; i<nTicks; i++ )
output->tick( voicer->tick() );
}
catch (StkError &) {
goto cleanup;
}
if ( type > 0 ) {
// Process the new control message.
byte2 = messager->getByteTwo();
byte3 = messager->getByteThree();
switch(type) {
case __SK_NoteOn_:
voicer->noteOn( byte2, byte3 );
break;
case __SK_NoteOff_:
voicer->noteOff( byte2, byte3 );
break;
case __SK_ControlChange_:
voicer->controlChange( (int) byte2, byte3 );
break;
case __SK_AfterTouch_:
voicer->controlChange( 128, byte2 );
break;
}
}
}
cleanup:
for ( i=0; i<3; i++ ) delete instrument[i];
delete output;
delete messager;
delete voicer;
return 0;
}
\endcode
Assuming the program is compiled as <TT>threebees</TT>, the three-voice SKINI scorefile <A HREF="tutorial/bachfugue.ski"><TT>bachfugue.ski</TT></A> (also located in the <tt>scores</tt> directory with the examples) could be redirected to the program as:
We have written this program to accept control messages from \c STDIN. Assuming the program is compiled as <TT>threebees</TT>, the three-voice SKINI scorefile <A HREF="tutorial/bachfugue.ski"><TT>bachfugue.ski</TT></A> (located in the <tt>scores</tt> directory with the examples) can be redirected to the program as:
\code
threebees < bachfugue.ski
threebees < scores/bachfugue.ski
\endcode
For more fun, surf to <A HREF="http://kern.humdrum.net/">Kern Scores</A> for a huge assortment of other scorefiles which can be downloaded in the SKINI format.
Another easy extension would be to use the <TT>STK_MIDI</TT> constructor argument to the Messager class and then play the instruments via a MIDI keyboard.
Another easy extension would be to add the \c Messager::startMidiInput() function to the program and then play the instruments via a MIDI keyboard.
[<A HREF="tutorial.html">Main tutorial page</A>]
*/

64
doc/doxygen/realtime.txt
View File

@@ -1,72 +1,28 @@
/*! \page realtime Realtime Audio
/*! \page realtime Realtime Audio (blocking)
In this section, we modify the <TT>sineosc.cpp</TT> program in order to send the output to the default audio playback device on your system.
In this section, we modify the <TT>sineosc.cpp</TT> program in order to send the output to the default audio playback device on your computer system.
\code
// rtsine.cpp
\include rtsine.cpp
#include "WaveLoop.h"
#include "RtWvOut.h"
int main()
{
// Set the global sample rate before creating class instances.
Stk::setSampleRate( 44100.0 );
WaveLoop *input = 0;
RtWvOut *output = 0;
try {
// Define and load the sine wave file
input = new WaveLoop( "rawwaves/sinewave.raw", TRUE );
// Define and open the default realtime output device for one-channel playback
output = new RtWvOut(1);
}
catch (StkError &) {
goto cleanup;
}
input->setFrequency(440.0);
// Play the oscillator for 40000 samples
int i;
for ( i=0; i<40000; i++ ) {
try {
output->tick(input->tick());
}
catch (StkError &) {
goto cleanup;
}
}
cleanup:
delete input;
delete output;
return 0;
}
\endcode
The class RtWvOut is a protected subclass of WvOut. A number of optional constructor arguments can be used to fine tune its performance for a given system.
The class RtWvOut is a protected subclass of WvOut. A number of optional constructor arguments can be used to fine tune its performance for a given system. RtWvOut provides a "single-sample" interface to the RtAudio class. Note that RtWvOut (as well as the RtWvIn and RtDuplex classes described below) make use of RtAudio's blocking input/output functionality. On systems which implement an inherently callback-based audio API, this blocking functionality will be less robust. An example of audio output using a callback scheme will be discussed in a subsequent tutorial section.
Though not used here, an RtWvIn class exists as well which can be used to read realtime audio data from an input device. See the <TT>record.cpp</TT> example program in the <TT>examples</TT> project for more information.
It is possible to use an instance of RtWvOut and an instance of RtWvIn to simultaneously read and write realtime audio to and from a hardware device or devices. However, it is recommended to instead use a single instance of RtDuplex to achieve this behavior, in that it guarantees better synchronization between the input and output data. See the <TT>effects</TT> project or the <TT>io.cpp</TT> example program in the <TT>examples</TT> project for more information.
It may be possible to use an instance of RtWvOut and an instance of RtWvIn to simultaneously read and write realtime audio to and from a hardware device or devices. However, it is recommended to instead use a single instance of RtDuplex to achieve this behavior, in that it guarantees better synchronization between the input and output data. See the <TT>effects</TT> project or the <TT>io.cpp</TT> example program in the <TT>examples</TT> project for more information.
When using any realtime STK class (RtAudio, RtWvOut, RtWvIn, RtDuplex, RtMidi, TcpWvIn, TcpWvOut, Socket, and Thread), it is necessary to specify an audio/MIDI API preprocessor definition and link with the appropriate libraries or frameworks. For example, the above program could be compiled on a Linux system using the GNU g++ compiler and the ALSA audio/MIDI API as follows (assuming all necessary files exist in the project directory):
When using any realtime STK class (RtAudio, RtWvOut, RtWvIn, RtDuplex, RtMidi, TcpWvIn, TcpWvOut, Socket, and Thread), it is necessary to specify an audio/MIDI API preprocessor definition and link with the appropriate libraries or frameworks. For example, the above program could be compiled on a Linux system using the GNU g++ compiler and the ALSA audio API as follows (assuming all necessary files exist in the project directory):
\code
g++ -Wall -D__LINUX_ALSA__ -D__LITTLE_ENDIAN__ -o rtsine Stk.cpp WvIn.cpp WaveLoop.cpp WvOut.cpp \
RtWvOut.cpp RtAudio.cpp rtsine.cpp -lpthread -lasound -lstk
RtWvOut.cpp RtAudio.cpp rtsine.cpp -lpthread -lasound
\endcode
On a Macintosh OS X system, the syntax would be:
\code
CC -D__MACOSX_CORE__ -o rtsine Stk.cpp WvIn.cpp WaveLoop.cpp WvOut.cpp RtWvOut.cpp RtAudio.cpp \
rtsine.cpp -lpthread -lstdc++ -lstk -framework CoreAudio -framework CoreMIDI -framework CoreFoundation
g++ -Wall -D__MACOSX_CORE__ -o rtsine Stk.cpp WvIn.cpp WaveLoop.cpp WvOut.cpp RtWvOut.cpp RtAudio.cpp \
rtsine.cpp -lpthread -framework CoreAudio -framework CoreMIDI -framework CoreFoundation
\endcode
[<A HREF="instruments.html">Next tutorial</A>] &nbsp; [<A HREF="tutorial.html">Main tutorial page</A>]
[<A HREF="crealtime.html">Next tutorial</A>] &nbsp; [<A HREF="tutorial.html">Main tutorial page</A>]
*/

92
doc/doxygen/skini.txt
View File

@@ -8,7 +8,7 @@ This describes the latest (version 1.1) implementation of SKINI for the Synthesi
A SKINI haiku.
\endcode
Profound thanks to Dan Trueman, Brad Garton, and Gary Scavone for input on this revision. Thanks also to MIDI, the NeXT MusicKit, ZIPI and all the creators and modifiers of these for good bases upon/from which to build and depart.
Profound thanks to Dan trueman, Brad Garton, and Gary Scavone for input on this revision. Thanks also to MIDI, the NeXT MusicKit, ZIPI and all the creators and modifiers of these for good bases upon/from which to build and depart.
\section compatibility MIDI Compatibility
@@ -16,7 +16,7 @@ SKINI was designed to be MIDI compatible wherever possible, and extend MIDI in i
Differences from MIDI, and motivations, include:
- Text-based messages are used, with meaningful names wherever possible. This allows any language or system capable of formatted printing to generate SKINI. Similarly, any system capable of reading in a string and turning delimited fields into strings, floats, and ints can consume SKINI for control. More importantly, humans can actually read, and even write if they want, SKINI files and streams. Use an editor and search/replace or macros to change a channel or control number. Load a SKINI score into a spread sheet to apply transformations to time, control parameters, MIDI velocities, etc. Put a monkey on a special typewriter and get your next great work. Life's too short to debug bit/nybble packed variable length mumble messages. Disk space gets cheaper, available bandwidth increases, music takes up so little space and bandwidth compared to video and grapics. Live a little.
- Text-based messages are used, with meaningful names wherever possible. This allows any language or system capable of formatted printing to generate SKINI. Similarly, any system capable of reading in a string and turning delimited fields into strings, floats, and ints can consume SKINI for control. More importantly, humans can actually read, and even write if they want, SKINI files and streams. Use an editor and search/replace or macros to change a channel or control number. Load a SKINI score into a spread sheet to apply transformations to time, control parameters, MIDI velocities, etc. Put a monkey on a special typewriter and get your next great work. Life's too short to debug bit/nybble packed variable length mumble messages. Disk space gets cheaper, available bandwidth increases, music takes up so little space and bandwidth compared to video and graphics. Live a little.
- Floating point numbers are used wherever possible. Note Numbers, Velocities, Controller Values, and Delta and Absolute Times are all represented and scanned as ASCII double-precision floats. MIDI byte values are preserved, so that incoming MIDI bytes from an interface can be put directly into SKINI messages. 60.0 or 60 is middle C, 127.0 or 127 is maximum velocity etc. But, unlike MIDI, 60.5 can cause a 50 cent sharp middle C to be played. As with MIDI byte values like velocity, use of the integer and SKINI-added fractional parts is up to the implementor of the algorithm being controlled by SKINI messages. But the extra precision is there to be used or ignored.
@@ -38,13 +38,13 @@ All fields other than type, time, and channel are optional, and the types and us
The other important file used by SKINI is SKINI.msg, which is a set of #defines to make C code more readable, and to allow reasonably quick re-mapping of control numbers, etc.. All of these defined symbols are assigned integer values. For Java, the #defines could be replaced by declaration and assignment statements, preserving the look and behavior of the rest of the code.
\section cfiles C Files Used To Implement SKINI
\section cfiles Files Used To Implement SKINI
SKINI.cpp is an object which can either open a SKINI file, and successively read and parse lines of text as SKINI strings, or accept strings from another object and parse them. The latter functionality would be used by a socket, pipe, or other connection receiving SKINI messages a line at a time, usually in real time, but not restricted to real time.
Skini.cpp is a C++ object which can either open a SKINI file and successively read and parse lines of text as SKINI strings, or accept strings from another object and parse them. The latter functionality would be used by a socket, pipe, or other connection receiving SKINI messages a line at a time, usually in real time, but not restricted to real time.
SKINI.msg should be included by anything wanting to use the SKINI.cpp object. This is not mandatory, but use of the __SK_blah_ symbols which are defined in the .msg file will help to ensure clarity and consistency when messages are added and changed.
SKINI.msg should be included by anything wanting to use the Skini.cpp object. This is not mandatory, but use of the __SK_blah_ symbols which are defined in the .msg file will help to ensure clarity and consistency when messages are added and changed.
SKINI.tbl is used only by the SKINI parser object (SKINI.cpp). In the file SKINI.tbl, an array of structures is declared and assigned values which instruct the parser as to what the message types are, and what the fields mean for those message types. This table is compiled and linked into applications using SKINI, but could be dynamically loaded and changed in a future version of SKINI.
SKINI.tbl is used only by the SKINI parser object (Skini.cpp). In the file SKINI.tbl, an array of structures is declared and assigned values which instruct the parser as to what the message types are, and what the fields mean for those message types. This table is compiled and linked into applications using SKINI, but could be dynamically loaded and changed in a future version of SKINI.
\section parser SKINI Messages and the SKINI Parser:
@@ -102,7 +102,7 @@ The parser isn't all that smart, but neither am I. Here are the basic rules gov
\section table The SKINI.tbl File and Message Parsing:
The SKINI.tbl file contains an array of structures which are accessed by the parser object SKINI.cpp. The struct is:
The SKINI.tbl file contains an array of structures which are accessed by the parser object Skini.cpp. The struct is:
\code
struct SKINISpec {
@@ -164,55 +164,53 @@ The StringDamping and StringDetune messages behave the same as the Volume messag
Here's a simple example of code which uses the SKINI object to read a SKINI file and control a single instrument.
\code
Skini score;
Skini::Message message;
instrument = new Mandolin(50.0);
score = new SKINI(argv[1]);
while(score->getType() > 0) {
tempDouble = score->getDelta();
if (tempDouble < 0) {
tempDouble = - tempDouble;
tempDouble = tempDouble - output.getTime();
if (tempDouble < 0) {
printf("Bad News Here!!! Backward Absolute Time Required.\n");
tempDouble = 0.0;
}
score.setFile( argv[1] );
while ( score.nextMessage( message ) != 0 ) {
tempDouble = message.time;
if (tempDouble < 0) {
tempDouble = - tempDouble;
tempDouble = tempDouble - output.getTime();
if (tempDouble < 0) {
printf("Bad News Here!!! Backward Absolute Time Required.\n");
tempDouble = 0.0;
}
tempLong = (long) (tempDouble * Stk::sampleRate());
for (i=0;i<tempLong;i++) {
output.tick(instrument->tick());
}
tempLong = (long) ( tempDouble * Stk::sampleRate() );
for ( i=0; i<tempLong; i++ ) {
output.tick( instrument->tick() );
}
tempDouble3 = message.floatValues[1] * NORM_MIDI;
if ( message.type == __SK_NoteOn_ ) {
if ( tempDouble3 == 0.0 ) {
tempDouble3 = 0.5;
instrument->noteOff( tempDouble3 );
}
tempDouble3 = score->getByteThree();
if (score->getType()== __SK_NoteOn_ ) {
tempDouble3 *= NORM_MIDI;
if (score->getByteThree() == 0) {
tempDouble3 = 0.5;
instrument->noteOff(tempDouble3);
}
else {
tempLong = (int) score->getByteTwo();
tempDouble2 = Midi2Pitch[tempLong];
instrument->noteOn(tempDouble2,tempDouble3);
}
else {
tempLong = message.intValues[0];
tempDouble2 = Midi2Pitch[tempLong];
instrument->noteOn( tempDouble2, tempDouble3 );
}
else if (score->getType() == __SK_NoteOff_) {
tempDouble3 *= NORM_MIDI;
instrument->noteOff(tempDouble3);
}
else if (score->getType() == __SK_ControlChange_) {
tempLong = score->getByteTwoInt();
instrument->controlChange(tempLong,temp3.0);
}
score->nextMessage();
}
else if ( message.type == __SK_NoteOff_ ) {
instrument->noteOff( tempDouble3 );
}
else if ( message.type == __SK_ControlChange_ ) {
tempLong = message.intValues[0];
instrument->controlChange( tempLong, tempDouble3 );
}
}
\endcode
When the score (SKINI object) object is created from the filename in argv[1], the first valid command line is read from the file and parsed.
When a SKINI score is passed to a Skini object using the Skini::setFile() function, valid messages are read from the file and returned using the Skini::nextMessage() function.
The score->getType() retrieves the messageType. If this is -1, there are no more valid messages in the file and the synthesis loop terminates. Otherwise, the message type is returned.
A Skini::Message structure contains all the information parsed from a single SKINI message. A returned message type of zero indicates either an invalid message or the end of a scorefile.
getDelta() retrieves the deltaTime until the current message should occur. If this is greater than 0, synthesis occurs until the deltaTime has elapsed. If deltaTime is less than zero, the time is interpreted as absolute time and the output device is queried as to what time it is now. That is used to form a deltaTime, and if it's positive we synthesize. If it's negative, we print an error and pretend this never happened and we hang around hoping to eventually catch up.
The "time" member of a Skini::Message is the deltaTime until the current message should occur. If this is greater than 0, synthesis occurs until the deltaTime has elapsed. If deltaTime is less than zero, the time is interpreted as absolute time and the output device is queried as to what time it is now. That is used to form a deltaTime, and if it's positive we synthesize. If it's negative, we print an error, pretend this never happened and we hang around hoping to eventually catch up.
The rest of the code sorts out message types NoteOn, NoteOff (including NoteOn with velocity 0), and ControlChange. The code implicitly takes into account the integer type of the control number, but all other data is treated as double float.
The last line reads and parses the next message in the file.
*/
*/

15
doc/doxygen/system.txt
View File

@@ -2,23 +2,24 @@
<B>General:</B>
<UL>
<LI>A MIDI interface to use MIDI input controls. (NOTE: This may be built into the soundcard on your computer.)</LI>
<LI>A MIDI interface to use MIDI input/output controls. (NOTE: This may be built into the soundcard on your computer.)</LI>
<LI><A HREF="http://dev.scriptics.com">Tcl/Tk</A> version 8.0 or higher to use the simple Tcl/Tk GUIs provided with the STK distribution (available free over the WWW for all supported realtime platforms).</LI>
</UL>
<B>Linux (specific):</B>
<UL>
<LI>A soundcard to use realtime audio input/output capabilities. In order to use the <I><B>effects</B></I> project, the soundcard and drivers must support full duplex mode.</LI>
<LI><A HREF="http://www.opensound.com">OSS</A> or <A HREF="http://www.alsa-project.org/">ALSA</A> device drivers for realtime sound output and MIDI input.</LI>
<LI><A HREF="http://www.alsa-project.org/">ALSA</A> device drivers and library for realtime sound and MIDI input/output. <A HREF="http://www.opensound.com">OSS</A> device drivers can be used for audio input/output, but MIDI support requires the ALSA library to compile.</LI>
</UL>
<B>Macintosh OS X (specific):</B>
<UL>
<LI>A C++ compiler does not ship by default with OS X. It is necessary to download the Developer Kit from the Apple WWW site in order to compile STK.</LI>
<LI><B>IMPORTANT:</B>The internal Macintosh audio hardware typically supports a sample rate of 44100 Hz only. Therefore, it is necessary to either specify this rate as a command-line option to the STK example programs or to change the default sample rate inside the Stk.h file before compilation. In addition, the RT_BUFFER_SIZE, specified in Stk.h, could be increased (to a higher power of two) for more robust performance.</LI>
<LI>The tcl/tk interpreter does not ship by default with OS X, but must be downloaded from the internet. The latest Tcl/Tk Aqua distribution (http://www.apple.com/downloads/macosx/unix_open_source/tcltk.html) has been successfully tested on a 10.2 system. The default installation will place a link to the wish interpretor at /usr/bin/wish.
<LI>A C++ compiler does install by default with OS X. It is necessary to download the Developer Kit from the Apple WWW site in order to compile STK or load it from the installation CD-ROM.</LI>
<LI><B>IMPORTANT:</B>The internal Macintosh audio hardware typically supports a sample rate of 44100 Hz only. The default STK sample rate is now 44100 Hz, but there may be programs which change that value before execution. Check the program code if you have sample rate conflicts. Many of the example project programs allow the sample rate to be specified via the command line.</LI>
<LI>If you experience frequent audio input/output "glitches", try increasing the RT_BUFFER_SIZE specified in Stk.h.</LI>
<LI>The tcl/tk interpreter does not ship by default with OS X, but must be downloaded from the internet. The latest Tcl/Tk Aqua distribution (http://www.apple.com/downloads/macosx/unix_open_source/tcltk.html) has been successfully tested on 10.2 and 10.3 systems. The default installation will place a link to the wish interpretor at /usr/bin/wish.
Initial tests have shown somewhat poor response between changes made in the tcl/tk script and the resulting audio updates. It is possible to connect a tcl/tk interface to an STK program via a socket connection. However, the tcl/tk interpreter does not appear to properly close the socket connection during disconnection. It is therefore necessary to type "Exit" in the STK program terminal window to properly exit the STK program.</LI>
It appears that socket support in Tcl/Tk uses the Nagle algorithm, which produces poor response between changes made in the tcl/tk script and the resulting audio updates. Note that this is only a problem when using a socket connection from a Tcl/Tk script.</LI>
</UL>
@@ -37,4 +38,4 @@ Initial tests have shown somewhat poor response between changes made in the tcl/
<P>
*/
*/

11
doc/doxygen/tutorial.txt
View File

@@ -1,23 +1,26 @@
/*! \page tutorial Tutorial
The Synthesis ToolKit is a set of C++ classes. In order to go beyond the simple example programs we provide, it is necessary to know some basics about programming in C or C++. STK's "target audience" includes people who:
The Synthesis ToolKit is a set of C++ classes. In order to go beyond the simple example programs we provide, it is necessary to know some basics about programming in C and C++. STK's "target audience" includes people who:
<UL>
<LI>want to create audio DSP and/or synthesis programs</LI>
<LI>want to save some time by using our unit generators and input/output routines</LI>
<LI>want to use our unit generators and input/output routines rather than code their own</LI>
<LI>want to learn about synthesis and processing algorithms</LI>
<LI>wish to teach real-time synthesis and processing, and wish to use some of our classes and examples</LI>
<LI>wish to teach real-time synthesis and processing and wish to use some of our classes and examples</LI>
</UL>
Most ToolKit programmers will likely end up writing a class or two for their own particular needs, but this task is typically simplified by making use of pre-existing STK classes (filters, oscillators, etc.).
The following tutorial chapters describe many of the fundamental ToolKit concepts and classes. All tutorial programs are included in the <TT>projects/examples</TT> directory.
-# \ref fundamentals
-# \ref hello
-# \ref compile
-# \ref filtering
-# \ref realtime
-# \ref crealtime
-# \ref instruments
-# \ref controlin
-# \ref multichannel
-# \ref polyvoices
*/
*/

53
doc/doxygen/usage.txt
View File

@@ -21,7 +21,7 @@ The top level distribution contains the following directories:
<LI> The <I><B>include</B></I> directory contains the header files for 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>rawwaves</B></I> directory contains various raw, monophonic, 16-bit, big-endian, 22050 Hz soundfiles used with the STK classes.</LI><P>
<LI> The <I><B>doc</B></I> directory contains documentation about STK.</LI><P>
@@ -37,13 +37,13 @@ This release of STK comes with four separate "project" directories:
<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>
<LI> The <I><B>examples</B></I> project contains several simple programs which demonstrate audio input/output, including the audio internet streaming classes, as well as most of the tutorial programs.</LI>
</OL>
\section compiling Compiling:
<UL>
<LI><B>Windows95/98/2000/XP:</B> Realtime support is available using either DirectSound or ASIO audio drivers. For DirectSound support, use the <TT>__WINDOWS_DS__</TT> preprocessor definition and link with the <TT>dsound.lib</TT>, <TT>winmm.lib</TT>, and <TT>Wsock32.lib</TT> libraries. For ASIO support, use the <TT>__WINDOWS_ASIO__</TT> preprocessor definition, include all the files in the <TT>src/asio/</TT> directory (i.e. <TT>asio.h,cpp</TT>, <TT>asiodrivers.h,cpp</TT>, ...), and link with the <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 (using DirectSound) 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 files 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>Windows95/98/2000/XP:</B> Realtime support is available using either DirectSound or ASIO audio drivers. For DirectSound support, use the <TT>__WINDOWS_DS__</TT> preprocessor definition and link with the <TT>dsound.lib</TT>, <TT>winmm.lib</TT>, and <TT>Wsock32.lib</TT> libraries. For ASIO support, use the <TT>__WINDOWS_ASIO__</TT> preprocessor definition, include all the files in the <TT>src/asio/</TT> directory (i.e. <TT>asio.h,cpp</TT>, <TT>asiodrivers.h,cpp</TT>, ...), and link with the <TT>winmm.lib</TT>, and <TT>Wsock32.lib</TT> libraries. In addition, the <TT>__LITTLE_ENDIAN__</TT> and <TT>__WINDOWS_MM__</TT> preprocessor definitions are necessary for all Windows systems (RtMidi uses the Windows MultiMedia MIDI API). A distribution of the release is available with precompiled binaries (using DirectSound) 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 files 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> DirectX support for NT is inadequate, so it is not possible to use STK under WindowsNT with realtime DirectX support. It may be possible to use STK under WindowsNT with realtime ASIO support, though this has not been tested.</LI>
@@ -53,11 +53,12 @@ Several options can be supplied to the <TT>configure</TT> script to customize th
<UL>
<LI><TT>--disable-realtime</TT> to only compile generic non-realtime classes</LI>
<LI><TT>--enable-debug</TT> to enable various debug output</LI>
<LI><TT>--enable-midiator</TT> to enable native MS-124W MIDI support (linux only)</LI>
<LI><TT>--with-alsa</TT> to choose native ALSA API support (linux only)</LI>
<LI><TT>--with-alsa</TT> to choose native ALSA API support (default, linux only)</LI>
<LI><TT>--with-jack</TT> to choose native JACK API support (linux only)</LI>
<LI><TT>--with-oss</TT> to choose native OSS audio API support (linux only, no native OSS MIDI support)</LI>
</UL>
<P>
In addition, it is possible to specify the location of the STK rawwaves and the STK include path as follows:
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:
\code
./configure RAWWAVE_PATH="/home/gary/rawwaves/"
./configure INCLUDE_PATH="/home/gary/include/"
@@ -68,13 +69,13 @@ For novice STK users, the default configuration should be adequate.
For those who wish to create their own system-specific <TT>Makefiles</TT>:
<UL>
<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. Special support exists under Linux for the MIDIator serial MIDI device, enabled using the <TT>__MIDIATOR__</TT> preprocessor definition (together with either the <TT>__LINUX_ALSA__</TT> or <TT>__LINUX_OSS__</TT> definitions). See the README-Linux file for further system configuration information.</LI>
<LI><B>Linux:</B> Realtime audio support is enabled with either the <TT>__LINUX_ALSA__</TT>, <TT>__LINUX_JACK__</TT>, and/or <TT>__LINUX_OSS__</TT> 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 <TT>__LINUX_ALSASEQ__</TT> preprocessor definition must be included for MIDI support. Note that native OSS MIDI support no longer exists in RtMidi. If the <TT>__LINUX_OSS__</TT> preprocessor definition is specified, only OSS audio support will be compiled and RtMidi will still be compiled using the ALSA API (assuming the <TT>__LINUX_ALSASEQ__</TT> definition is defined). For this reason, STK now requires the <TT>asound</TT> library for realtime support. Realtime programs must also link with the <TT>pthread</TT> library. In addition, the <TT>__LITTLE_ENDIAN__</TT> preprocessor definition is necessary if compiling on a little-endian system. See the README-Linux file for further system configuration information.</LI>
<LI><B>Macintosh OS X:</B> Realtime support is enabled with the <TT>__MACOSX_CORE__</TT> preprocessor definitions, which incorporates the CoreAudio audio/MIDI API. Realtime programs must also link with the <TT>pthread</TT> library and the <TT>CoreAudio</TT>, <TT>CoreMIDI</TT>, and <TT>CoreFoundation</TT> frameworks. See the README-MacOSX 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. STK 4.0 (and higher) is confirmed to compile using CC version 7.30. There may be problems with old compiler versions.</LI>
<LI><B>SGI:</B> Realtime audio and MIDI support is enabled with the <TT>__IRIX_AL__</TT> and <TT>__IRIX_MD__</TT> preprocessor definitions and linkage with the <TT>audio</TT>, <TT>md</TT>, and <TT>pthread</TT> libraries. STK 4.0 (and higher) is confirmed to compile using CC version 7.30. There may be problems with old compiler versions.</LI>
<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>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, Mutex, 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>
</UL>
@@ -132,16 +133,10 @@ 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 -ow myfile.wav
demo BeeThree -ow myfile.wav -if scores/bookert.ski
\endcode
or (on WindowsXX and/or Unix)
\code
demo BeeThree -ow 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.
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" (note that you may need to append <TT>./</TT> to the program name if your default shell setup is not set to look in the current directory). Typing <TT>demo</TT> without any arguments will provide a full program usage description.
\section rt Demo: Realtime Use
@@ -157,27 +152,22 @@ demo instrument flags
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>-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>-if \<file name\></I> for a SKINI formatted control file,</LI>
<LI><I>-ip</I> for realtime SKINI control input via piping,</LI>
<LI><I>-is <port></I> > for realtime SKINI control input via socketing (with an optional port number),</LI>
<LI><I>-im <file name></I> for MIDI control input</LI>
<LI><I>-s RATE</I> to specify a sample rate</LI>
<LI><I>-is \<port\></I> for realtime SKINI control input via socketing (with an optional port number),</LI>
<LI><I>-im \<port\></I> for MIDI control input (with optional port, -1 = virtual port where possible),</LI>
<LI><I>-s RATE</I> to specify a sample rate,</LI>
<LI><I>-n NUMBER</I> to specify multivoice polyphony</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.
The <i>-ip</i> and <i>-is</i> flags must be used when piping or socketing realtime SKINI control data to an STK program. The <i>-im</i> 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
demo BeeThree -or -if 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.
@@ -209,6 +199,7 @@ On all supported realtime platforms, you can direct realtime MIDI input to the S
demo Clarinet -or -im
\endcode
This will attempt to use the default MIDI port for input. An optional MIDI port number can be specified after the <TT>-im</TT> 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 (which other software applications can connect to) by specifying a port identifier of -1.
\section polyphony Polyphony: