e1lama/stk
1
0
Fork 0
mirror of https://github.com/thestk/stk synced 2026-01-11 20:11:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

Version 4.2.1

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

2
doc/README-Linux.txt
View File

@@ -1,6 +1,6 @@
The Synthesis ToolKit in C++ (STK)
By Perry R. Cook and Gary P. Scavone, 1995-2004.
By Perry R. Cook and Gary P. Scavone, 1995-2005.
Please read the file README and INSTALL for more general STK information.

4
doc/README-MacOSX.txt
View File

@@ -1,12 +1,12 @@
The Synthesis ToolKit in C++ (STK)
By Perry R. Cook and Gary P. Scavone, 1995-2004.
By Perry R. Cook and Gary P. Scavone, 1995-2005.
Please read the file README and INSTALL for more general STK information.
Realtime support for Macintosh OS X uses the CoreAudio HAL API and is specified during compilation using the __MACOSX_CORE__ preprocessor definition.
It is necessary to install the OS X developer kit in order to compile STK. STK was successfully tested on OS X versions 10.2 and 10.3.
It is necessary to install the OS X developer kit in order to compile STK. STK was successfully tested on OS X versions 10.4.
The internal Macintosh audio hardware typically supports a sample rate of 44100 Hz only. The default STK sample rate is now 44100 Hz and all current example programs use this rate. However, it is possible to manually override this value in some programs from the command-line. The default sample rate is set in Stk.h. In addition, the RT_BUFFER_SIZE, specified in Stk.h, could be increased (to a higher power of two) for more robust performance.

2
doc/README-NeXT.txt
View File

@@ -1,6 +1,6 @@
The Synthesis ToolKit in C++ (STK)
By Perry R. Cook and Gary P. Scavone, 1995-2004.
By Perry R. Cook and Gary P. Scavone, 1995-2005.
Please read the file README and INSTALL for more general STK information.

2
doc/README-SGI.txt
View File

@@ -1,6 +1,6 @@
The Synthesis ToolKit in C++ (STK)
By Perry R. Cook and Gary P. Scavone, 1995-2004.
By Perry R. Cook and Gary P. Scavone, 1995-2005.
Please read the file README and INSTALL for more general STK information.

2
doc/README-Win.txt
View File

@@ -1,6 +1,6 @@
The Synthesis ToolKit in C++ (STK)
By Perry R. Cook and Gary P. Scavone, 1995-2004.
By Perry R. Cook and Gary P. Scavone, 1995-2005.
Please read the file README for more general STK information.

34
doc/ReleaseNotes.txt
View File

@@ -1,6 +1,38 @@
The Synthesis ToolKit in C++ (STK)
By Perry R. Cook and Gary P. Scavone, 1995-2004.
By Perry R. Cook and Gary P. Scavone, 1995-2005.
Future To Do:
- OSC server/client classes
- move various error checks, especially in tick() functions, into __DEBUG__ blocks?
- add WAVEFORMATEXTENSIBLE support to RtAudio
- add WAVEFORMATEXTENSIBLE support to WvIn/WvOut?
- better documentation
v4.2.1: (14 October 2005)
- greatly expanded StkFrames functionality (including interpolation and indexing by channel/frame)
- new Granulate granular synthesis class
- new Blit, BlitSaw, and BlitSquare bandlimited waveform classes (thanks to Robin Davies!)
- removed Table class ... all functionality (including interpolation) now in StkFrames and FileRead classes
- revised Socket class (now abstract) and added TcpServer, TcpClient, and UdpSocket subclasses
- added Stk::showWarnings() and Stk::printErrors() functions to dis/enable warning and error printouts
- extracted file I/O functionality to new FileRead and FileWrite classes
- revised WvIn / WvOut class structure (WvIn / WvOut now abstract and file I/O functionality in new FileWvIn / FileWvOut subclasses)
- new SineWave class which calculates its own static table of variable length (no rawwave dependency)
- new sinewave.raw file of length 1024 samples (used to be 256)
- TcpWvIn and TcpWvOut renamed InetWvIn and InetWvOut, with added support for UDP sockets
- fixed bug in WvOut tickFrame( const StkFrames &frames ) function
- fixed bug in demo.cpp when writing output soundfiles without realtime output
- added "binary" open flag to MidiFileIn class for Windows
- fixed oversized MAT-file header in WvOut.cpp
- fixed case statement bug in MidiFileIn.cpp for sysex
- added missing getDelay() function to DelayA.cpp
- fixed modDepth omission in Chorus.cpp
- fixed DC blocker initialization bug in Flute.cpp
- changed Filter class behavior so no default clearing of state when changing coefficients
- bug fixes to RtAudio, especially for Windows DirectSound and ASIO (thanks to Robin Davies)
- bug fixes to RtMidi, especially for Linux (thanks to Pedro Pedro Lopez-Cabanillas)
v4.2.0: (4 October 2004)
- simultaneous multiple audio APIs supported at compile time

43
doc/doxygen/Doxyfile
View File

@@ -1,11 +1,12 @@
# Doxyfile 1.3.6
# Doxyfile 1.4.4
#---------------------------------------------------------------------------
# Project related configuration options
#---------------------------------------------------------------------------
PROJECT_NAME = STK
PROJECT_NUMBER = 4.2.0
PROJECT_NUMBER = 4.2.1
OUTPUT_DIRECTORY = .
CREATE_SUBDIRS = NO
OUTPUT_LANGUAGE = English
USE_WINDOWS_ENCODING = NO
BRIEF_MEMBER_DESC = YES
@@ -15,12 +16,14 @@ ALWAYS_DETAILED_SEC = NO
INLINE_INHERITED_MEMB = NO
FULL_PATH_NAMES = NO
STRIP_FROM_PATH =
STRIP_FROM_INC_PATH =
SHORT_NAMES = NO
JAVADOC_AUTOBRIEF = NO
MULTILINE_CPP_IS_BRIEF = NO
DETAILS_AT_TOP = YES
INHERIT_DOCS = YES
INHERIT_DOCS = NO
DISTRIBUTE_GROUP_DOC = NO
SEPARATE_MEMBER_PAGES = NO
TAB_SIZE = 9
ALIASES =
OPTIMIZE_OUTPUT_FOR_C = NO
@@ -31,12 +34,13 @@ SUBGROUPING = YES
#---------------------------------------------------------------------------
EXTRACT_ALL = NO
EXTRACT_PRIVATE = NO
EXTRACT_STATIC = YES
EXTRACT_LOCAL_CLASSES = YES
EXTRACT_STATIC = NO
EXTRACT_LOCAL_CLASSES = NO
EXTRACT_LOCAL_METHODS = NO
HIDE_UNDOC_MEMBERS = YES
HIDE_UNDOC_CLASSES = YES
HIDE_FRIEND_COMPOUNDS = NO
HIDE_IN_BODY_DOCS = NO
HIDE_FRIEND_COMPOUNDS = YES
HIDE_IN_BODY_DOCS = YES
INTERNAL_DOCS = NO
CASE_SENSE_NAMES = YES
HIDE_SCOPE_NAMES = NO
@@ -52,6 +56,8 @@ GENERATE_DEPRECATEDLIST= YES
ENABLED_SECTIONS =
MAX_INITIALIZER_LINES = 30
SHOW_USED_FILES = YES
SHOW_DIRECTORIES = YES
FILE_VERSION_FILTER =
#---------------------------------------------------------------------------
# configuration options related to warning and progress messages
#---------------------------------------------------------------------------
@@ -59,6 +65,7 @@ QUIET = NO
WARNINGS = YES
WARN_IF_UNDOCUMENTED = YES
WARN_IF_DOC_ERROR = YES
WARN_NO_PARAMDOC = NO
WARN_FORMAT = "$file:$line: $text"
WARN_LOGFILE =
#---------------------------------------------------------------------------
@@ -69,7 +76,7 @@ INPUT = . \
FILE_PATTERNS = *.txt \
*.msg \
*.h
RECURSIVE = YES
RECURSIVE = NO
EXCLUDE = ../../src/asio
EXCLUDE_SYMLINKS = NO
EXCLUDE_PATTERNS =
@@ -78,20 +85,22 @@ EXAMPLE_PATTERNS =
EXAMPLE_RECURSIVE = NO
IMAGE_PATH =
INPUT_FILTER =
FILTER_PATTERNS =
FILTER_SOURCE_FILES = NO
#---------------------------------------------------------------------------
# configuration options related to source browsing
#---------------------------------------------------------------------------
SOURCE_BROWSER = YES
INLINE_SOURCES = YES
SOURCE_BROWSER = NO
INLINE_SOURCES = NO
STRIP_CODE_COMMENTS = YES
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION = YES
REFERENCED_BY_RELATION = NO
REFERENCES_RELATION = NO
USE_HTAGS = NO
VERBATIM_HEADERS = YES
#---------------------------------------------------------------------------
# configuration options related to the alphabetical class index
#---------------------------------------------------------------------------
ALPHABETICAL_INDEX = NO
ALPHABETICAL_INDEX = YES
COLS_IN_ALPHA_INDEX = 5
IGNORE_PREFIX =
#---------------------------------------------------------------------------
@@ -167,7 +176,7 @@ PERLMOD_MAKEVAR_PREFIX =
#---------------------------------------------------------------------------
# Configuration options related to the preprocessor
#---------------------------------------------------------------------------
ENABLE_PREPROCESSING = YES
ENABLE_PREPROCESSING = NO
MACRO_EXPANSION = NO
EXPAND_ONLY_PREDEF = NO
SEARCH_INCLUDES = YES
@@ -192,18 +201,22 @@ HIDE_UNDOC_RELATIONS = YES
HAVE_DOT = NO
CLASS_GRAPH = YES
COLLABORATION_GRAPH = YES
GROUP_GRAPHS = YES
UML_LOOK = NO
TEMPLATE_RELATIONS = NO
INCLUDE_GRAPH = YES
INCLUDED_BY_GRAPH = YES
CALL_GRAPH = NO
GRAPHICAL_HIERARCHY = YES
DIRECTORY_GRAPH = YES
DOT_IMAGE_FORMAT = png
DOT_PATH =
DOT_PATH = /sw/bin
DOTFILE_DIRS =
MAX_DOT_GRAPH_WIDTH = 1024
MAX_DOT_GRAPH_HEIGHT = 1024
MAX_DOT_GRAPH_DEPTH = 0
DOT_TRANSPARENT = NO
DOT_MULTI_TARGETS = NO
GENERATE_LEGEND = YES
DOT_CLEANUP = YES
#---------------------------------------------------------------------------

52
doc/doxygen/compile.txt
View File

@@ -5,9 +5,21 @@ 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, Thread, and Mutex. These classes currently can only be compiled on Linux, Irix, Macintosh OS X, and Windows systems.
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, InetWvIn, InetWvOut, Socket, UdpSocket, TcpServer,
TcpClient, 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.
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.
\section unix Unix Systems:
@@ -28,6 +40,12 @@ STK compiles with realtime support on the following flavors of the Unix operatin
<TD>__LINUX_ALSA__, __LINUX_ALSASEQ__, __LITTLE_ENDIAN__</TD>
<TD><TT>asound, pthread</TT></TD>
</TR>
<TR>
<TD>Linux</TD>
<TD>Jack (audio only, use ALSA for MIDI support)</TD>
<TD>__LINUX_JACK__, __LINUX_ALSASEQ__, __LITTLE_ENDIAN__</TD>
<TD><TT>asound, pthread</TT></TD>
</TR>
<TR>
<TD>Linux</TD>
<TD>OSS (audio only, use ALSA for MIDI support)</TD>
@@ -51,9 +69,18 @@ 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 little-endian system, such as a PC running Linux, 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, FileRead, FileWrite, WvIn, FileWvIn, WaveLoop,
WvOut, and FileWvOut. 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
g++ -Wall -D__LITTLE_ENDIAN__ -o sineosc Stk.cpp FileRead.cpp FileWrite.cpp WvIn.cpp FileWvIn.cpp WaveLoop.cpp WvOut.cpp FileWvOut.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.
@@ -75,7 +102,7 @@ With the header files in a standard search path, it is possible to modify the <T
\code
#include "stk/WaveLoop.h"
#include "stk/WvOut.h"
#include "stk/FileWvOut.h"
\endcode
and then compile without an explicit include path argument to the compiler:
@@ -87,13 +114,22 @@ g++ -Wall -D__LITTLE_ENDIAN__ -o sineosc sineosc.cpp -lstk
\section compileWin Windows:
STK has been tested on Windows platforms using the Visual C++ compiler only. It is assumed here that you're familiar with Visual C++ and its particular idiosyncrasies.
STK has been tested on Windows platforms using the Visual C++ compiler
only. It is assumed here that you're familiar with Visual C++ and its
particular idiosyncrasies.
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>.
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, FileRead, FileWrite, WvIn, FileWvIn,
WaveLoop, WvOut, and FileWvOut 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>, <TT>__WINDOWS_DS__</TT>, and <TT>__WINDOWS_MM__</TT> preprocessor definitions.
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="filtering.html">Next tutorial</A>] &nbsp; [<A HREF="tutorial.html">Main tutorial page</A>]
[<A HREF="tutorial.html">Main tutorial page</A>] &nbsp; [<A HREF="filtering.html">Next tutorial</A>]
*/

2
doc/doxygen/control.txt
View File

@@ -39,5 +39,5 @@ Only a few basic SKINI message type case statements are included in this example
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>]
[<A HREF="tutorial.html">Main tutorial page</A>] &nbsp; [<A HREF="multichannel.html">Next tutorial</A>]
*/

4
doc/doxygen/crealtime.txt
View File

@@ -16,11 +16,11 @@ The \c main() function blocks at the std::cin.get() call until the user hits the
\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.
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>]
[<A HREF="tutorial.html">Main tutorial page</A>] &nbsp; [<A HREF="instruments.html">Next tutorial</A>]
*/

37
doc/doxygen/download.txt
View File

@@ -1,15 +1,42 @@
/*! \page download Download and Release Notes
/*! \page download Download, Release Notes, and Bug Fixes
\section down Download Version 4.2.1 (14 October 2005):
<B>Version 4.2.0, 4 October 2004</B><P>
<UL>
<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>
<LI><A HREF="http://ccrma.stanford.edu/software/stk/release/stk-4.2.1.tar.gz">Source distribution</A></LI>
<LI><A HREF="http://ccrma.stanford.edu/software/stk/release/stk-4.2.1.binaries.tar.gz">Source with precompiled Windows binaries</A></LI>
<LI><A HREF="http://ccrma.stanford.edu/planetccrma/software/">Linux RPMs from Planet CCRMA</A></LI>
</UL>
\section notes Release Notes:
\subsection v4dot2dot1 Version 4.2.1
<ul>
<li>Greatly expanded StkFrames functionality (including interpolation and indexing by channel/frame).</li>
<li>New Blit, BlitSaw, and BlitSquare bandlimited waveform classes (thanks to Robin Davies!).</li>
<li>New Granulate granular synthesis class.</li>
<li>Removed Table class ... all functionality (including interpolation) now in StkFrames and FileRead classes.</li>
<li>Revised Socket class (now abstract) and added TcpServer, TcpClient, and UdpSocket subclasses.</li>
<li>Added Stk::showWarnings() and Stk::printErrors() functions to dis/enable warning and error printouts.</li>
<li>Extracted file I/O functionality to FileRead and FileWrite classes.</li>
<li>Revised WvIn / WvOut class structure (WvIn / WvOut now abstract and file I/O functionality in new FileWvIn / FileWvOut subclasses).</li>
<li>New SineWave class which calculates its own static table of variable length (no rawwave dependency).</li>
<li>New sinewave.raw file of length 1024 samples (used to be 256).</li>
<li>TcpWvIn and TcpWvOut renamed InetWvIn and InetWvOut, with added support for UDP sockets.</li>
<li>Fixed bug in WvOut tickFrame( const StkFrames &frames ) function.</li>
<li>Fixed bug in demo.cpp when writing output soundfiles without realtime output.</li>
<li>Added "binary" open flag to MidiFileIn class for Windows.</li>
<li>Fixed oversized MAT-file header in WvOut.cpp</li>
<li>Fixed case statement bug in MidiFileIn.cpp for sysex.</li>
<li>Added missing getDelay() function to DelayA.cpp.</li>
<li>Fixed modDepth omission in Chorus.cpp.</li>
<li>Fixed DC blocker initialization bug in Flute.cpp.</li>
<li>Changed Filter class behavior so no default clearing of state when changing coefficients.</li>
<li>Fixes to RtAudio, especially for Windows DirectSound and ASIO (thanks to Robin Davies).</li>
</ul>
\subsection v4dot2dot0 Version 4.2.0
<ul>

8
doc/doxygen/filtering.txt
View File

@@ -7,7 +7,7 @@ In this section, we demonstrate the use of a few of the STK filter classes. The
int main()
{
StkFrames output( 20 ); // initialize StkFrames to 20 elements (defaults: 1 channel, interleaved)
StkFrames output( 20, 1 ); // initialize StkFrames to 20 frames and 1 channel (default: interleaved)
output[0] = 1.0;
std::vector<StkFloat> numerator( 5, 0.1 ); // create and initialize numerator coefficients
@@ -46,7 +46,7 @@ The STK BiQuad and TwoPole classes provide functionality for creating resonance
int main()
{
StkFrames output( 20 ); // initialize StkFrames to 20 elements (defaults: 1 channel, interleaved)
StkFrames output( 20, 1 ); // initialize StkFrames to 20 frames and 1 channel (default: interleaved)
Noise noise;
BiQuad biquad;
@@ -69,7 +69,7 @@ By passing a boolian value of \c true as the third argument to the BiQuad::setRe
int main()
{
StkFrames output( 20 ); // initialize StkFrames to 20 elements (defaults: 1 channel, interleaved)
StkFrames output( 20, 1 ); // initialize StkFrames to 20 frames and 1 channel (default: interleaved)
Noise noise;
BiQuad biquad;
@@ -84,5 +84,5 @@ int main()
}
\endcode
[<A HREF="realtime.html">Next tutorial</A>] &nbsp; [<A HREF="tutorial.html">Main tutorial page</A>]
[<A HREF="tutorial.html">Main tutorial page</A>] &nbsp; [<A HREF="realtime.html">Next tutorial</A>]
*/

2
doc/doxygen/footer.html
View File

@@ -2,7 +2,7 @@
<table>
<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>
<tr><td>&copy;1995-2005 Perry R. Cook and Gary P. Scavone. All Rights Reserved.</td></tr>
</table>
</BODY>

16
doc/doxygen/fundamentals.txt
View File

@@ -25,14 +25,14 @@ int main()
}
\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.
Nearly all STK classes implement <TT>tick()</TT> functions that 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)
StkFrames output(20, 1); // initialize StkFrames to 20 frames and 1 channel (default: interleaved)
Noise noise;
noise.tick( output );
@@ -44,20 +44,20 @@ int main()
}
\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.
In this way, it might be possible to achieve improved processing efficiency using vectorized computations. The StkFrames class is a relatively 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. Further, the StkFrames class provides data interpolation and subscripting functionality by frame/channel values.
\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]
- Generator: source signal unit generator classes [Envelope, ADSR, Asymp, Noise, SubNoise, Modulate, SingWave, SineWave Blit, BlitSaw, BlitSquare, Granulate]
- Filter: digital filtering classes [OneZero, OnePole, PoleZero, TwoZero, TwoPole, BiQuad, FormSwep, Delay, DelayL, DelayA]
- Function: input to output function mappings [Table, BowTable, JetTable, ReedTable]
- Function: input to output function mappings [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]
- WvOut: audio data output classes [FileWvOut, RtWvOut, InetWvOut]
- WvIn: audio data input classes [FileWvIn, WaveLoop, RtWvIn, InetWvIn]
[<A HREF="hello.html">Next tutorial</A>] &nbsp; [<A HREF="tutorial.html">Main tutorial page</A>]
[<A HREF="tutorial.html">Main tutorial page</A>] &nbsp; [<A HREF="hello.html">Next tutorial</A>]
*/

68
doc/doxygen/hello.txt
View File

@@ -1,55 +1,81 @@
/*! \page hello Hello Sine!
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.
We'll continue our introduction to the Synthesis ToolKit with a simple
sine-wave oscillator program. STK provides two different classes for
sine-wave generation. We will first look at a generic waveform
oscillator class, WaveLoop, that 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
FileWvOut to write the result to a 16-bit, WAV formatted audio file.
\code
// sineosc.cpp
#include "WaveLoop.h"
#include "WvOut.h"
#include "FileWvOut.h"
int main()
{
// Set the global sample rate before creating class instances.
Stk::setSampleRate( 44100.0 );
// Define and load the sine wave file
WaveLoop* input = new WaveLoop( "rawwaves/sinewave.raw", true );
input->setFrequency( 440.0 );
WaveLoop input;
FileWvOut output;
// Define and open a 16-bit, one-channel WAV formatted output file
WvOut* output = new WvOut( "hellosine.wav", 1, WvOut::WVOUT_WAV, Stk::STK_SINT16 );
// Load the sine wave file.
input.openFile( "rawwaves/sinewave.raw", true );
// Open a 16-bit, one-channel WAV formatted output file
output.openFile( "hellosine.wav", 1, FileWrite::FILE_WAV, Stk::STK_SINT16 );
input.setFrequency( 440.0 );
// Run the oscillator for 40000 samples, writing to the output file
int i;
for ( i=0; i<40000; i++ ) {
output->tick( input->tick() );
}
// Clean up
delete input;
delete output;
for ( int i=0; i<40000; i++ )
output.tick( input.tick() );
return 0;
}
\endcode
WaveLoop is a subclass of WvIn, which supports 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. WvIn provides interpolating, read once ("oneshot") functionality, as well as methods for setting the read rate and read position.
WaveLoop is a subclass of FileWvIn, which supports 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. FileWvIn
provides interpolating, read-once ("oneshot") functionality, as well
as methods for setting the read rate and read position.
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.
FileWvIn provides a "tick level" and interpolating interface to the
FileRead class. Likewise, FileWvOut provides a "tick level" interface
to the FileWrite class. FileRead and FileWrite both support 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.
FileWvOut does not currently offer data interpolation functionality.
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.
The WvIn and WvOut parent classes and all subclasses 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 44100 Hz.
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.
The ToolKit has some basic C++ error handling functionality built in.
Classes that 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.
\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="fundamentals.html">Main tutorial page</A>]
[<A HREF="fundamentals.html">Main tutorial page</A>] &nbsp; [<A HREF="compile.html">Next tutorial</A>]
*/

19
doc/doxygen/index.txt
View File

@@ -1,12 +1,25 @@
/*! \mainpage <I>The Synthesis ToolKit in C++ (STK)</I>
<BODY BGCOLOR="white">
\htmlonly
<BODY BGCOLOR="white">
<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 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 <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 about 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

39
doc/doxygen/information.txt
View File

@@ -2,17 +2,17 @@
<H3>References</H3>
<UL>
<LI><A HREF="Papers/stkicmc99.pdf">ICMC99 Paper</A></LI>
<LI><A HREF="papers/stkupdate.pdf">ICMC2005 Paper</A></LI>
<BR>
A paper by Gary and Perry detailing recent updates to the Synthesis ToolKit in C++.
<P>
<LI><A HREF="papers/stkicmc99.pdf">ICMC99 Paper</A></LI>
<BR>
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>
<LI>Book Chapter: <A HREF="http://www.akpeters.com/product.asp?ProdCode=1047">Audio Anecdotes</A></LI>
<BR>
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>
This is a link to Perry Cook's STK Web page. He has information about the \ref skini, the protocol used to control STK instruments, as well as a lot of other cool stuff.
Here's a link to a book that includes an chapter on STK.
</UL>
@@ -31,9 +31,30 @@ For those instances where a simple GUI with sliders and buttons is helpful, we u
<H4>A brief history of the <I>Synthesis ToolKit in C++.</I></H4>
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.
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 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.
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.music.mcgill.ca/~gary/">Gary
Scavone's home page</A> at McGill University, and the <A HREF="http://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>

10
doc/doxygen/instruments.txt
View File

@@ -4,12 +4,16 @@ The ToolKit comes with a wide variety of synthesis algorithms, all of which inhe
\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).
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).
The noteOn() function initiates an instrument attack. Instruments which are continuously excited (e.g., Clarinet, BeeThree) will continue to sound until stopped with a noteOff(). Impulsively excited instrument sounds (e.g., Plucked, Wurley) typically decay within a few seconds time, requiring subsequent noteOn() messages for re-attack.
The noteOn() function initiates an instrument attack. Instruments that are continuously excited (e.g., Clarinet, BeeThree) will continue to sound until stopped with a noteOff(). Impulsively excited instrument sounds (e.g., Plucked, Wurley) typically decay within a few seconds time, requiring subsequent noteOn() messages for re-attack.
Instrument parameters can be precisely controlled as demonstrated above. A more flexible approach to instrument control, allowing arbitrary scorefile or realtime updates, is described in the next tutorial chapter.
[<A HREF="controlin.html">Next tutorial</A>] &nbsp; [<A HREF="tutorial.html">Main tutorial page</A>]
[<A HREF="tutorial.html">Main tutorial page</A>] &nbsp; [<A HREF="controlin.html">Next tutorial</A>]
*/

19
doc/doxygen/multichannel.txt
View File

@@ -2,13 +2,26 @@
The ToolKit WvIn and WvOut classes (and their subclasses) support multi-channel audio data input and output. A set of interleaved audio samples representing a single time "slice" is referred to as a <I>sample frame</I>. At a sample rate of 44.1 kHz, a four-channel audio stream will have 44100 sample frames per second and a total of 176400 individual samples per second.
Most STK classes process single-sample data streams via their <TT>tick()</TT> function. In order to distinguish single-sample and sample frame calculations, the WvIn and WvOut classes implement both <TT>tick()</TT> and <TT>tickFrame()</TT> functions. The <TT>tickFrame()</TT> functions take or return a pointer to an array of audio data representing one or more sample frames. For single-channel streams, the <TT>tick()</TT> and <TT>tickFrame()</TT> functions produce equivalent results. When <TT>tick()</TT> is called for a multi-channel stream, however, the function either returns a sample frame average (WvIn) or writes a single sample argument to all channels (WvOut).
Most STK classes process single-sample data streams via their
<TT>tick()</TT> function. In order to distinguish single-sample and
sample frame calculations, the WvIn and WvOut classes implement both
<TT>tick()</TT> and <TT>tickFrame()</TT> functions. The
<TT>tickFrame()</TT> functions take or return a reference to an StkFrames object
representing one or more sample frames. For single-channel
streams, the <TT>tick()</TT> and <TT>tickFrame()</TT> functions
produce equivalent results. When <TT>tick()</TT> is called for a
multi-channel stream, however, the function either returns a sample
frame average (WvIn) or writes a single sample argument to all
channels (WvOut).
Multi-channel support for realtime audio input and output is dependent on the audio device(s) available on your system.
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.
The following example demonstrates the use of the FileWvOut 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.
\include foursine.cpp
[<A HREF="polyvoices.html">Next tutorial</A>] &nbsp; [<A HREF="tutorial.html">Main tutorial page</A>]
[<A HREF="tutorial.html">Main tutorial page</A>] &nbsp; [<A HREF="polyvoices.html">Next tutorial</A>]
*/

29
doc/doxygen/realtime.txt
View File

@@ -1,28 +1,43 @@
/*! \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 computer 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. We also make use of the SineWave class as a
sine-wave oscillator. SineWave computes an internal, static sine-wave
table when its first instance is created. Subsequent instances make
use of the same table. The default table length, specified in
SineWave.h, is 2048 samples.
\include rtsine.cpp
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.
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 that implement an
inherently callback-based audio API (Linux Jack, Windows ASIO, OS-X
CoreAudio), 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.
Though not used here, an RtWvIn class exists as well that 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 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 API as follows (assuming all necessary files exist in the project directory):
When using any realtime STK class (RtAudio, RtWvOut, RtWvIn, RtDuplex, RtMidi, InetWvIn, InetWvOut, Socket, UdpSocket, TcpServer, TcpClient, 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 \
g++ -Wall -D__LINUX_ALSA__ -D__LITTLE_ENDIAN__ -o rtsine Stk.cpp Generator.cpp SineWave.cpp WvOut.cpp \
RtWvOut.cpp RtAudio.cpp rtsine.cpp -lpthread -lasound
\endcode
On a Macintosh OS X system, the syntax would be:
\code
g++ -Wall -D__MACOSX_CORE__ -o rtsine Stk.cpp WvIn.cpp WaveLoop.cpp WvOut.cpp RtWvOut.cpp RtAudio.cpp \
g++ -Wall -D__MACOSX_CORE__ -o rtsine Stk.cpp Generator.cpp SineWave.cpp WvOut.cpp RtWvOut.cpp RtAudio.cpp \
rtsine.cpp -lpthread -framework CoreAudio -framework CoreMIDI -framework CoreFoundation
\endcode
[<A HREF="crealtime.html">Next tutorial</A>] &nbsp; [<A HREF="tutorial.html">Main tutorial page</A>]
[<A HREF="tutorial.html">Main tutorial page</A>] &nbsp; [<A HREF="crealtime.html">Next tutorial</A>]
*/

50
doc/doxygen/skini.txt
View File

@@ -28,23 +28,25 @@ I am basically a bottom-up designer with an awareness of top-down design ideas,
\section messages SKINI Messages
A basic SKINI message is a line of text. There are only three required fields, the message type (an ASCII name), the time (either delta or absolute), and the channel number. Don't freak out and think that this is MIDI channel 0-15 (which is supported), because the channel number is scanned as a long int. Channels could be socket numbers, machine IDs, serial numbers, or even unique tags for each event in a synthesis. Other fields might be used, as specified in the SKINI.tbl file. This is described in more detail later.
A basic SKINI message is a line of text. There are only three required fields, the message type (an ASCII name), the time (either delta or absolute), and the channel number. Don't freak out and think that this is MIDI channel 0-15 (which is supported), because the channel number is scanned as a long int. Channels could be socket numbers, machine IDs, serial numbers, or even unique tags for each event in a synthesis. Other fields might be used, as specified in the \c SKINI.tbl file. This is described in more detail later.
Fields in a SKINI line are delimited by spaces, commas, or tabs. The SKINI parser only operates on a line at a time, so a newline means the message is over. Multiple messages are NOT allowed directly on a single line (by use of the ; for example in C). This could be supported, but it isn't in version 1.1.
Message types include standard MIDI types like NoteOn, NoteOff, ControlChange, etc. MIDI extension message types (messages which look better than MIDI but actually get turned into MIDI-like messages) include LipTension, StringDamping, etc. Non-MIDI message types include SetPath (sets a path for file use later), and OpenReadFile (for streaming, mixing, and applying effects to soundfiles along with synthesis, for example). Other non-MIDI message types include Trilling, HammerOn, etc. (these translate to gestures, behaviors, and contexts for use by intellegent players and instruments using SKINI). Where possible I will still use these as MIDI extension messages, so foot switches, etc. can be used to control them in real time.
Message types include standard MIDI types like NoteOn, NoteOff, ControlChange, etc. MIDI extension message types (messages which look better than MIDI but actually get turned into MIDI-like messages) include LipTension, StringDamping, etc. Non-MIDI message types include SetPath (sets a path for file use later), and OpenReadFile (for streaming, mixing, and applying effects to soundfiles along with synthesis, for example). Other non-MIDI message types include Trilling, HammerOn, etc. (these translate to gestures, behaviors, and contexts for use by intelligent players and instruments using SKINI). Where possible I will still use these as MIDI extension messages, so foot switches, etc. can be used to control them in real time.
All fields other than type, time, and channel are optional, and the types and useage of the additional fields is defined in the file SKINI.tbl.
All fields other than type, time, and channel are optional, and the
types and useage of the additional fields is defined in the file \c
SKINI.tbl.
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.
The other important file used by SKINI is \c 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 Files Used To Implement SKINI
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 is a C++ class 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.
\c SKINI.msg should be included by anything wanting to use the Skini 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.
\c SKINI.tbl is used only by the Skini parser object (Skini.cpp). In the file \c 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:
@@ -52,8 +54,6 @@ The parser isn't all that smart, but neither am I. Here are the basic rules gov
- If the first (non-delimiter ... see below) character in a SKINI string is '/' that line is treated as a comment and echoed to stdout.
- If there are no characters on a line, that line is treated as blank and echoed to stdout. Tabs and spaces are treated as non-characters.
- Spaces, commas, and tabs delimit the fields in a SKINI message line. (We might allow for multiple messages per line later using the semicolon, but probably not. A series of lines with deltaTimes of 0.0 denotes simultaneous events. For read-ability, multiple messages per line doesn't help much, so it's unlikely to be supported later).
- The first field must be a SKINI message name (like NoteOn). These might become case-insensitive in future versions, so don't plan on exciting clever overloading of names (like noTeOn being different from NoTeON). There can be a number of leading spaces or tabs, but don't exceed 32 or so.
@@ -62,7 +62,7 @@ The parser isn't all that smart, but neither am I. Here are the basic rules gov
- The third field must be an integer channel number. Don't go crazy and think that this is just MIDI channel 0-15 (which is supported). The channel number is scanned as a long int. Channels 0-15 are in general to be treated as MIDI channels. After that it's wide open. Channels could be socket numbers, machine IDs, serial numbers, or even unique tags for each event in a synthesis. A -1 channel can be used as don't care, omni, or other functions depending on your needs and taste.
- All remaining fields are specified in the SKINI.tbl file. In general, there are maximum two more fields, which are either SK_INT (long), SK_DBL (double float), or SK_STR (string). The latter is the mechanism by which more arguments can be specified on the line, but the object using SKINI must take that string apart (retrived by using getRemainderString()) and scan it. Any excess fields are stashed in remainderString.
- All remaining fields are specified in the \c SKINI.tbl file. In general, there are maximum two more fields, which are either SK_INT (long), SK_DBL (double float), or SK_STR (string). The latter is the mechanism by which more arguments can be specified on the line, but the object using SKINI must take that string apart (retrived by using getRemainderString()) and scan it. Any excess fields are stashed in remainderString.
\section file A Short SKINI File:
@@ -80,7 +80,7 @@ The parser isn't all that smart, but neither am I. Here are the basic rules gov
StringDetune 0.100000 2 22
StringDetune 0.100000 2 12
//
StringDamping 0.000100 2 0.0
StringDamping 0.000100 2 0.0
NoteOn 0.000082 2 55 82
NoteOn 0.200000 2 62 82
NoteOn 0.100000 2 71 82
@@ -89,7 +89,7 @@ The parser isn't all that smart, but neither am I. Here are the basic rules gov
NoteOff 0.000000 2 62 82
NoteOff 0.000000 2 71 82
NoteOff 0.000000 2 79 82
StringDamping =4.000000 2 0.0
StringDamping =4.000000 2 0.0
NoteOn 0.000082 2 55 82
NoteOn 0.200000 2 62 82
NoteOn 0.100000 2 71 82
@@ -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 \c SKINI.tbl file contains an array of structures which are accessed by the parser object Skini.cpp. The struct is:
\code
struct SKINISpec {
@@ -129,9 +129,21 @@ so an assignment of one of these structs looks like:
- SK_DBL : double precision floating point. SKINI uses these in the MIDI context for note numbers with micro tuning, velocities, controller values, etc.
- SK_STR : only valid in final field. This allows (nearly) arbitrary message types to be supported by simply scanning the string to EndOfLine and then passing it to a more intellegent handler. For example, MIDI SYSEX (system exclusive) messages of up to 256 bytes can be read as space-delimited integers into the 1K SK_STR buffer. Longer bulk dumps, soundfiles, etc. should be handled as a new message type pointing to a FileName, Socket, or something else stored in the SK_STR field, or as a new type of multi-line message.
- SK_STR : only valid in final field. This allows (nearly) arbitrary message types to be supported by simply scanning the string to EOL (End Of Line) and then passing it to a more intelligent handler. For example, MIDI SYSEX (system exclusive) messages can be read as space-delimited integers into the SK_STR buffer. Longer bulk dumps, soundfiles, etc. should be handled as a new message type pointing to a FileName, Socket, or something else stored in the SK_STR field, or as a new type of multi-line message.
Here's a couple of lines from the SKINI.tbl file
Each individual SKINI message is parsed and saved to a Skini::Message structure of the form:
\code
struct Message {
long type; /*!< The message type, as defined in SKINI.msg. */
long channel; /*!< The message channel (not limited to 16!). */
StkFloat time; /*!< The message time stamp in seconds (delta or absolute). */
std::vector<StkFloat> floatValues; /*!< The message values read as floats (values are type-specific). */
std::vector<long> intValues; /*!< The message values read as ints (number and values are type-specific). */
std::string remainder; /*!< Any remaining message data, read as ascii text. */
};
\endcode
Here's a couple of lines from the \c SKINI.tbl file
\code
{"NoteOff" , __SK_NoteOff_, SK_DBL, SK_DBL},
@@ -144,7 +156,7 @@ Here's a couple of lines from the SKINI.tbl file
{"StringDetune" , __SK_ControlChange_, __SK_StringDetune_, SK_DBL},
\endcode
The first three are basic MIDI messages. The first two would cause the parser, after recognizing a match of the string "NoteOff" or "NoteOn", to set the message type to 128 or 144 (__SK_NoteOff_ and __SK_NoteOn_ are #defined in the file SKINI.msg to be the MIDI byte value, without channel, of the actual MIDI messages for NoteOn and NoteOff). The parser would then set the time or delta time (this is always done and is therefore not described in the SKINI Message Struct). The next two fields would be scanned as double-precision floats and assigned to the byteTwo and byteThree variables of the SKINI parser. The remainder of the line is stashed in the remainderString variable.
The first three are basic MIDI messages. The first two would cause the parser, after recognizing a match of the string "NoteOff" or "NoteOn", to set the message type to 128 or 144 (__SK_NoteOff_ and __SK_NoteOn_ are #defined in the file \c SKINI.msg to be the MIDI byte value, without channel, of the actual MIDI messages for NoteOn and NoteOff). The parser would then set the time or delta time (this is always done and is therefore not described in the SKINI Message Struct). The next two fields would be scanned either as double-precision \c floats or as <tt>long ints</tt>, depending on the format specified in \c SKINI.tbl, and saved to the corresponding C++ vector variables in the Skini::Message structure (either \c floatValues or \c intValues). Floating-point values are also cast to <tt>ints</tt> (and vice-versa) and stored to their respective variables. For example, an expected integer value of 64 will also be saved as 64.0 in the corresponding \c floatValues variable of the Skini::Message structure. The remainder of the line is stashed in the remainderString variable.
The ControlChange spec is basically the same as NoteOn and NoteOff, but the second data byte is set to an integer (for checking later as to what MIDI control is being changed).
@@ -155,13 +167,13 @@ The Volume spec is a MIDI Extension message, which behaves like a ControlChange
Volume 0.000000 2 64.1
\endcode
I like the 2nd line better, thus my motivation for SKINI in the first place.
I like the second line better, thus my motivation for SKINI in the first place.
The StringDamping and StringDetune messages behave the same as the Volume message, but use Control Numbers which aren't specifically nailed-down in MIDI. Note that these Control Numbers are carried around as long ints, so we're not limited to 0-127. If, however, you want to use a MIDI controller to play an instrument, using controller numbers in the 0-127 range might make sense.
\section using Using SKINI:
Here's a simple example of code which uses the SKINI object to read a SKINI file and control a single instrument.
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;
@@ -207,8 +219,6 @@ Here's a simple example of code which uses the SKINI object to read a SKINI file
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.
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.
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.

92
doc/Hierarchy.txt → doc/hierarchy.txt
View File

@@ -1,20 +1,24 @@
STK: A ToolKit of Audio Synthesis Classes and Instruments in C++
By Perry R. Cook and Gary P. Scavone, 1995-2004.
By Perry R. Cook and Gary P. Scavone, 1995-2005.
STK Classes - See the HTML documentation in the html directory for complete information.
.- Generator - (Modulate, Noise, SingWave, Envelope)
.- Generator - (Modulate, Noise, SingWave, Envelope, SineWave, Blit, BlitSaw, BlitSquare, Granulate)
| | |
| SubNoise ADSR
| Asymp
|
|- Function - (Table, BowTable, JetTable, ReedTable)
|- Function - (BowTable, JetTable, ReedTable)
|
|- WvIn - (WaveLoop, RtWvIn, TcpWvIn)
|- FileRead, FileWrite
|
|- WvOut - (RtWvOut, TcpWvOut)
|- WvIn - (FileWvIn, RtWvIn, InetWvIn)
| |
| WaveLoop
|
|- WvOut - (FileWvOut, RtWvOut, TcpWvOut)
|
|- Filter - (OnePole, OneZero, Delay, TwoPole, TwoZero, PoleZero, Biquad)
| | |
@@ -22,7 +26,13 @@ STK Classes - See the HTML documentation in the html directory for complete info
| DelayA
|
|- RtAudio, RtMidi, RtDuplex, Socket, Thread, Mutex
Stk -|
| |
Stk -| UdpSocket
| TcpServer
| TcpClient
|
|- StkFrames
|
|- Effect - (Echo, Chorus, PitShift, PRCRev, JCRev, NRev)
|
|- Voicer, Message, Skini, MidiFileIn, Phonemes, Sphere, Vector3D
@@ -58,42 +68,50 @@ Stk -|
Master Class: Stk.cpp Sample rate, byte-swapping, error handling functionality
Sources: Generator.cpp Abstract Base Class for Various Source Signal Classes
Function.cpp Abstract Base Class for Various Input/Output Mapping Classes
Envelope.cpp Linearly Goes to Target by Rate
ADSR.cpp ADSR Flavor of Envelope
Asymp.cpp Exponentially Approaches Target
Noise.cpp Random Number Generator
SubNoise.cpp Random Numbers each N samples
Table.cpp Lookup Table (assumes given data in big-endian format)
WvIn.cpp Data Input Class (interpolating) for RAW, WAV, SND (AU), AIFF, MAT-file files
WaveLoop.cpp Wavetable looping (subclass of WvIn)
RtWvIn.cpp Realtime Audio Input Class (subclass of WvIn)
TcpWvIn.cpp Audio Streaming (socket server) Input Class (subclass of WvIn)
Sources: Generator.cpp Abstract base class for various source signal classes
Function.cpp Abstract base class for various input/output mapping classes
Envelope.cpp Linearly goes to target by rate
ADSR.cpp ADSR flavor of Envelope
Asymp.cpp Exponentially approaches target
Noise.cpp Random number generator
SubNoise.cpp Random numbers each N samples
SineWave.cpp Sinusoidal oscillator with internally computed static table
Blit.cpp Bandlimited impulse train
BlitSaw.cpp Bandlimited sawtooth generator
BlitSquare.cpp Bandlimited square wave generator
Granulate.cpp Granular synthesis class that processes a monophonic audio file
FileRead.cpp Audio file input class (no internal data storage) for RAW, WAV, SND (AU), AIFF, MAT-file files
WvIn.cpp Abstract base class for audio data input classes
FileWvIn.cpp Audio file input interface class with interpolation
WaveLoop.cpp Wavetable looping (subclass of FileWvIn)
RtWvIn.cpp Realtime audio input class (subclass of WvIn)
InetWvIn.cpp Audio streaming (socket server) input class (subclass of WvIn)
Sinks: WvOut.cpp Output Master Class for RAW, WAV, SND (AU), AIFF, MAT-file files
RtWvOut.cpp Realtime Audio Output Class (subclass of WvOut)
TcpWvOut.cpp Audio Streaming (socket client) Output Class (subclass of WvOut)
Sinks: FileWrite.cpp Audio file output class (no internal data storage) for RAW, WAV, SND (AU), AIFF, MAT-file files
WvOut.cpp Abstract base class for audio data output classes
FileWvOut.cpp Audio file output interface class to FileWrite
RtWvOut.cpp Realtime audio output class (subclass of WvOut)
InetWvOut.cpp Audio streaming (socket client) output class (subclass of WvOut)
Duplex: RtDuplex.cpp Synchronous Realtime Audio Input/Output Class
Duplex: RtDuplex.cpp Synchronous realtime audio input/output class (blocking)
Filters: Filter.cpp Filter Master Class
OneZero.cpp One Zero Filter
OnePole.cpp One Pole Filter
PoleZero.cpp One Pole/One Zero Filter
TwoZero.cpp Two Zero Filter
TwoPole.cpp Two Pole Filter
BiQuad.cpp Two Pole/Two Zero Filter
FormSwep.cpp Sweepable BiQuad Filter (goes to target by rate)
Delay.cpp Non-Interpolating Delay Line Class
DelayL.cpp Linearly Interpolating Delay Line (subclass of Delay)
DelayA.cpp Allpass Interpolating Delay Line (subclass of Delay)
Filters: Filter.cpp Filter master class
OneZero.cpp One zero filter
OnePole.cpp One pole filter
PoleZero.cpp One pole/one zero filter
TwoZero.cpp Two zero filter
TwoPole.cpp Two pole filter
BiQuad.cpp Two pole/two zero filter
FormSwep.cpp Sweepable biquad filter (goes to target by rate)
Delay.cpp Non-interpolating delay line class
DelayL.cpp Linearly interpolating delay line (subclass of Delay)
DelayA.cpp Allpass interpolating delay line (subclass of Delay)
Non-Linear: JetTabl.cpp Cubic Jet Non-Linearity
BowTabl.cpp x^(-3) Bow Non-Linearity
ReedTabl.cpp One Breakpoint Saturating Reed Non-Linearity
Non-Linear: JetTabl.cpp Cubic jet non-linearity
BowTabl.cpp x^(-3) Bow non-linearity
ReedTabl.cpp One breakpoint saturating reed non-linearity
Derived: Modulate.cpp Periodic and Random Vibrato: WvIn, SubNoise, OnePole
Derived: Modulate.cpp Periodic and random vibrato: WvIn, SubNoise, OnePole
SingWave.cpp Looping wave table with randomness: Modulate, WaveLoop, Envelope