mirror of
https://github.com/thestk/stk
synced 2026-02-02 07:46:14 +00:00
Merge 4.4.0 into releases
This commit is contained in:
Stephen Sinclair
@@ -1,6 +1,6 @@
|
||||
The Synthesis ToolKit in C++ (STK)
|
||||
|
||||
By Perry R. Cook and Gary P. Scavone, 1995-2007.
|
||||
By Perry R. Cook and Gary P. Scavone, 1995-2009.
|
||||
|
||||
Please read the file README and INSTALL for more general STK information.
|
||||
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
The Synthesis ToolKit in C++ (STK)
|
||||
|
||||
By Perry R. Cook and Gary P. Scavone, 1995-2007.
|
||||
By Perry R. Cook and Gary P. Scavone, 1995-2009.
|
||||
|
||||
Please read the file README and INSTALL for more general STK information.
|
||||
|
||||
The default realtime support for Macintosh OS X uses the CoreAudio HAL API and is specified during compilation using the __MACOSX_CORE__ preprocessor definition. There is also support for the JACK low-latency audio server using the __UNIX_JACK__ preprocessor definition.
|
||||
The default realtime support for Macintosh OS X uses the CoreAudio HAL API and is specified during compilation using the __MACOSX_CORE__ preprocessor definition. There is also support for the JACK audio server using the __UNIX_JACK__ 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.4.
|
||||
It is necessary to install the OS X developer kit in order to compile STK. STK was successfully tested on OS X versions 10.5.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
The Synthesis ToolKit in C++ (STK)
|
||||
|
||||
By Perry R. Cook and Gary P. Scavone, 1995-2007.
|
||||
By Perry R. Cook and Gary P. Scavone, 1995-2009.
|
||||
|
||||
Please read the file README and INSTALL for more general STK information.
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
The Synthesis ToolKit in C++ (STK)
|
||||
|
||||
By Perry R. Cook and Gary P. Scavone, 1995-2007.
|
||||
By Perry R. Cook and Gary P. Scavone, 1995-2009.
|
||||
|
||||
Please read the file README and INSTALL for more general STK information.
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
The Synthesis ToolKit in C++ (STK)
|
||||
|
||||
By Perry R. Cook and Gary P. Scavone, 1995-2007.
|
||||
By Perry R. Cook and Gary P. Scavone, 1995-2009.
|
||||
|
||||
Please read the file README for more general STK information.
|
||||
|
||||
|
||||
@@ -1,6 +1,20 @@
|
||||
The Synthesis ToolKit in C++ (STK)
|
||||
|
||||
By Perry R. Cook and Gary P. Scavone, 1995-2007.
|
||||
By Perry R. Cook and Gary P. Scavone, 1995-2009.
|
||||
|
||||
v4.4: (30 April 2009)
|
||||
- all classes embedded in the "stk" namespace (except RtAudio, RtMidi, and RtError)
|
||||
- class WaveLoop renamed FileLoop
|
||||
- significant efficiency improvements via code restructuring and inlining
|
||||
- some class source (.cpp) files deleted as part of inlining (Generator, Filter, Function, WvIn, WvOut, Effect, Instrmnt, BowTable, ReedTable, JetTable, Vector3D)
|
||||
- updates to RtAudio and RtMidi
|
||||
- previous "tickFrame()" functions renamed "tick" for more consistent API
|
||||
- more consistent and scalable approach to multichannel data and computations
|
||||
- multichannel support added to Granulate class
|
||||
- Filter class made abstract. New Iir and Fir classes made for non-order-specific filtering.
|
||||
- new TapDelay class
|
||||
- SubNoise class deleted (same as sub-sampled "ticking" of Noise class)
|
||||
|
||||
|
||||
v4.3.1: (7 December 2007)
|
||||
- further headerless file support in FileRead
|
||||
@@ -14,6 +28,7 @@ v4.3.0: (13 August 2007)
|
||||
- an official MIT-like license
|
||||
- new functionality to automatically update class data when the STK sample rate changes (partly implemented)
|
||||
- updates for new RtAudio version 4.0
|
||||
- removed RtDuplex class, users should use RtAudio directly with a callback function
|
||||
- bug fix in interpolate() function in Stk.h for non-interleaved data
|
||||
- fixes / improvements to the Granulate class
|
||||
- fix in Whistle when doing animation
|
||||
|
||||
1297
doc/doxygen/Doxyfile
1297
doc/doxygen/Doxyfile
File diff suppressed because it is too large
Load Diff
@@ -56,7 +56,7 @@ STK compiles with realtime support on the following flavors of the Unix operatin
|
||||
<TD>Macintosh OS X</TD>
|
||||
<TD>CoreAudio</TD>
|
||||
<TD>__MACOSX_CORE__</TD>
|
||||
<TD><TT>pthread, CoreAudio, CoreMIDI, CoreFoundation</TT></TD>
|
||||
<TD><TT>pthread, CoreAudio, CoreMidi, CoreFoundation</TT></TD>
|
||||
</TR>
|
||||
</TABLE>
|
||||
</CENTER>
|
||||
@@ -69,13 +69,11 @@ a particular program into a project directory. Taking the
|
||||
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 FileRead.cpp FileWrite.cpp WvIn.cpp FileWvIn.cpp WaveLoop.cpp WvOut.cpp FileWvOut.cpp sineosc.cpp
|
||||
\endcode
|
||||
for the classes Stk, FileRead, FileWrite, FileWvIn, FileLoop, 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 FileRead.cpp FileWrite.cpp FileWvIn.cpp FileLoop.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.
|
||||
|
||||
@@ -95,7 +93,7 @@ g++ -Wall -D__LITTLE_ENDIAN__ -I/usr/include/stk -o sineosc sineosc.cpp -lstk
|
||||
With the header files in a standard search path, it is possible to modify the <TT>\#include</TT> statements in the <TT>sineosc.cpp</TT> program as follows:
|
||||
|
||||
\code
|
||||
#include "stk/WaveLoop.h"
|
||||
#include "stk/FileLoop.h"
|
||||
#include "stk/FileWvOut.h"
|
||||
\endcode
|
||||
|
||||
@@ -117,7 +115,7 @@ 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
|
||||
FileLoop, 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>.
|
||||
|
||||
|
||||
@@ -19,9 +19,20 @@ NoteOff 1.000000 2 69.0 64.0
|
||||
|
||||
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. 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.
|
||||
The class stk::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 stk::Skini::Message types (MIDI
|
||||
messages are converted to the stk::Skini:Message format). The user
|
||||
then uses the stk::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
|
||||
stk::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 SKINI messages read from a SKINI file.
|
||||
In the following example, we'll modify the <TT>bethree.cpp</TT> program from the previous tutorial chapter and incorporate a stk::Messager class to allow control via SKINI messages read from a SKINI file.
|
||||
|
||||
\include controlbee.cpp
|
||||
|
||||
@@ -37,7 +48,7 @@ controlbee scores/bookert.ski
|
||||
|
||||
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 pipe, socket or MIDI connections. The Messager class provides Messager::startStdInput(), Messager::startSocketInput(), and Messager::startMidiInput() functions for this purpose.
|
||||
This example could also be easily extended to accept "realtime" control input messages via pipe, socket or MIDI connections. The stk::Messager class provides stk::Messager::startStdInput(), stk::Messager::startSocketInput(), and stk::Messager::startMidiInput() functions for this purpose.
|
||||
|
||||
[<A HREF="tutorial.html">Main tutorial page</A>] [<A HREF="multichannel.html">Next tutorial</A>]
|
||||
*/
|
||||
|
||||
@@ -11,8 +11,8 @@ 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).
|
||||
|
||||
The previous section described the use of the RtWvOut class for
|
||||
realtime audio output. The RtWvOut::tick() function writes data to a
|
||||
The previous section described the use of the stk::RtWvOut class for
|
||||
realtime audio output. The stk::RtWvOut::tick() function writes data to a
|
||||
large ring-buffer, from which data is periodically written to the
|
||||
computer's audio hardware via an underlying callback routine.
|
||||
|
||||
|
||||
@@ -1,16 +1,31 @@
|
||||
/*! \page download Download, Release Notes, and Bug Fixes
|
||||
|
||||
\section down Download Version 4.3.1 (7 December 2007):
|
||||
\section down Download Version 4.4.0 (30 April 2009):
|
||||
|
||||
<UL>
|
||||
<LI><A HREF="http://ccrma.stanford.edu/software/stk/release/stk-4.3.1.tar.gz">Source distribution</A></LI>
|
||||
<LI><A HREF="http://ccrma.stanford.edu/planetccrma/software/">Linux RPMs from Planet CCRMA</A></LI>
|
||||
<LI><A HREF="http://ccrma.stanford.edu/software/stk/release/stk-4.4.0.tar.gz">Source distribution</A></LI>
|
||||
</UL>
|
||||
|
||||
|
||||
\section notes Release Notes:
|
||||
|
||||
\subsection v4dot3dot0 Version 4.3.1
|
||||
\subsection v4dot4dot0 Version 4.4.0
|
||||
|
||||
<ul>
|
||||
<li>All classes embedded in the "stk" namespace (except RtAudio, RtMidi, and RtError).</li>
|
||||
<li>Class WaveLoop renamed FileLoop.</li>
|
||||
<li>Significant efficiency improvements via code restructuring and inlining.</li>
|
||||
<li>Some class source (.cpp) files deleted as part of inlining (Generator, Filter, Function, WvIn, WvOut, Effect, Instrmnt, BowTable, ReedTable, JetTable, Vector3D).</li>
|
||||
<li>Updates to RtAudio and RtMidi.</li>
|
||||
<li>Previous "tickFrame()" functions renamed "tick" for more consistent API.</li>
|
||||
<li>More consistent and scalable approach to multichannel data and computations.</li>
|
||||
<li>Multichannel support added to Granulate class.</li>
|
||||
<li>Filter class made abstract. New Iir and Fir classes made for non-order-specific filtering.</li>
|
||||
<li>New TapDelay class.</li>
|
||||
<li>SubNoise class deleted (same as sub-sampled "ticking" of Noise class).</li>
|
||||
</ul>
|
||||
|
||||
\subsection v4dot3dot1 Version 4.3.1
|
||||
|
||||
<ul>
|
||||
<li>Further headerless file support in FileRead.</li>
|
||||
@@ -20,13 +35,13 @@
|
||||
<li>Changes to channel assignment in demo.cpp.</li>
|
||||
</ul>
|
||||
|
||||
|
||||
\subsection v4dot3dot0 Version 4.3.0
|
||||
|
||||
<ul>
|
||||
<li>An official MIT-like license.</li>
|
||||
<li>New functionality to automatically update class data when the STK sample rate changes (partly implemented).</li>
|
||||
<li>Updates for new RtAudio version 4.0.</li>
|
||||
<li>Removed RtDuplex class, users should use RtAudio directly with a callback function.</li>
|
||||
<li>Bug fix in interpolate() function in Stk.h for non-interleaved data.</li>
|
||||
<li>Fixes / improvements to the Granulate class.</li>
|
||||
<li>Fix in Whistle when doing animation.</li>
|
||||
|
||||
@@ -2,8 +2,6 @@
|
||||
|
||||
- \ref license
|
||||
- \ref filerate
|
||||
- \ref computesample
|
||||
- \ref tickframe
|
||||
- \ref endianness
|
||||
- \ref xwindows
|
||||
|
||||
@@ -26,7 +24,7 @@ work with any standard C++ compiler.
|
||||
STK WWW site: http://ccrma.stanford.edu/software/stk/
|
||||
|
||||
The Synthesis ToolKit in C++ (STK)
|
||||
Copyright (c) 1995-2007 Perry R. Cook and Gary P. Scavone
|
||||
Copyright (c) 1995-2009 Perry R. Cook and Gary P. Scavone
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining
|
||||
a copy of this software and associated documentation files (the
|
||||
@@ -65,21 +63,13 @@ Stk::setSampleRate( sampleRate ); // set a new STK sample rate based o
|
||||
|
||||
With version 4.3 and higher of STK, the FileWvIn class will be notified of a sample rate change and it will automatically adjust its read rate accordingly. Previous versions of STK did not perform this change and thus, the read rate could end up being incorrect. If you do not want FileWvIn to perform this automatic adjustment, you can call the \c ignoreSampleRateChange() function for a given class instance.
|
||||
|
||||
\section tickframe What is the difference between the tick() and tickFrame() functions?
|
||||
|
||||
\e tickFrame() functions are provided in classes that can handle multi-channel data. A <i>sample frame</i> of audio data represents a single "slice" in time across many audio channels. The WvIn and WvOut subclasses are the primary classes in STK that currently implement the \e tickFrame() functions. \e tick() functions are used for monophonic classes. Note, however, that the WvIn and WvOut classes also implement \e tick() functions though their behavior is dependent on the number of channels you are working with. For example, if using the FileWvIn class with a monophonic soundfile, then there is no difference between the \e tick() and \e tickFrame() functions (aside from the format of their arguments). But if you have a multi-channel file open, then the single value returned from the tick() function is an average of all the samples in the multi-channel sample frame.
|
||||
|
||||
\section computesample Hey, why was the tick() function replaced by computeSample() in various STK classes?
|
||||
|
||||
C++ doesn't like overloaded virtual functions. All STK classes that implement a single-sample \e tick() function also provide an overloaded version that takes an StkFrames argument (for vectorized computations). Further, many STK classes inherit from abstract base classes (Instrmnt, Generator, ...) and it is most convenient to define functionality common to all subclasses (like the \e tick() function that takes an StkFrames argument) in only the base class. So, to get around the overloaded virtual function problem, STK now uses the \e computeSample() function as a non-overloaded virtual function that is implemented in all subclasses (it essentially replaces the \e tick() function). Note, however, that the overloaded \e tick() functions are still available to the user ... they are implemented in the base classes.
|
||||
|
||||
\section endianness Why does the sound I generated with STK sound like *&#@!?
|
||||
|
||||
If the resultant sound generated by an STK program sounds like noise (and you're not doing an MLS experiment), the problem is likely related to the byte "endianness" of your computer. By default, STK assumes "big endian" byte order. If you are working with STK classes on a PC (Windows or Linux), you \e must define the <TT>__LITTLE_ENDIAN__</TT> preprocessor definition \e before compiling. If after reading this you realize you need to make this change, do not forget to recompile all STK classes from scratch.
|
||||
|
||||
\section xwindows Why do I get a Tk display error message?
|
||||
|
||||
The following error will be printed to your terminal window if you attempt to start an STK tcl/tk interface without the X Server first running:
|
||||
The following error may be printed to your terminal window (depending on the version of the tcl/tk interpreter you are running) if you attempt to start an STK tcl/tk interface without the X Server first running:
|
||||
|
||||
\code
|
||||
Application initialization failed: this isn't a Tk applicationcouldn't connect to display ":0.0"
|
||||
|
||||
@@ -1,9 +1,10 @@
|
||||
/*! \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.
|
||||
In this section, we demonstrate the use of a few of the STK filter classes. The stk::Iir class provides functionality to implement a generalized infinite impulse response (IIR) digital filter, similar to the \c filter function in Matlab. In this example, we create an stk::Iir instance and initialize it with specific numerator and denominator coefficients. We then compute its impulse response for 20 samples.
|
||||
|
||||
\code
|
||||
#include "Filter.h"
|
||||
#include "Iir.h"
|
||||
using namespace stk;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -16,7 +17,7 @@ int main()
|
||||
denominator.push_back( 0.3 );
|
||||
denominator.push_back( -0.5 );
|
||||
|
||||
Filter filter( numerator, denominator );
|
||||
Iir filter( numerator, denominator );
|
||||
|
||||
filter.tick( output );
|
||||
for ( unsigned int i=0; i<output.size(); i++ ) {
|
||||
@@ -27,22 +28,23 @@ int main()
|
||||
}
|
||||
\endcode
|
||||
|
||||
The Filter class implements the standard difference equation
|
||||
The stk::Iir 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.
|
||||
where "b" values are numerator coefficients and "a" values are denominator coefficients. Note that if the first denominator coefficient is not 1.0, the Iir class automatically normalizes all filter coefficients by that value. The coefficient values are passed to the Iir 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.
|
||||
Most STK classes use more specific types of digital filters, such as the stk::OneZero, stk::OnePole, stk::TwoPole, or stk::BiQuad varieties. These classes inherit from the stk::Filter abstract base 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.
|
||||
The STK stk::BiQuad and stk::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 stk::Noise generator.
|
||||
|
||||
\code
|
||||
#include "BiQuad.h"
|
||||
#include "Noise.h"
|
||||
using namespace stk;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -61,11 +63,12 @@ int main()
|
||||
}
|
||||
\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:
|
||||
By passing a boolian value of \c true as the third argument to the stk::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"
|
||||
using namespace stk;
|
||||
|
||||
int main()
|
||||
{
|
||||
|
||||
@@ -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>©1995-2007 Perry R. Cook and Gary P. Scavone. All Rights Reserved.</td></tr>
|
||||
<tr><td>©1995-2009 Perry R. Cook and Gary P. Scavone. All Rights Reserved.</td></tr>
|
||||
</table>
|
||||
|
||||
</BODY>
|
||||
|
||||
@@ -1,15 +1,16 @@
|
||||
/*! \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 that 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.
|
||||
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 that 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. Starting with STK version 4.4, all STK classes except RtAudio, RtMidi, and RtError are defined within the stk namespace.
|
||||
|
||||
\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:
|
||||
In general, the computation and/or passing of values is performed on a "single-sample" basis. For example, the stk::Noise class outputs random floating-point numbers in the range +/-1.0. The computation of such values occurs in the stk::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"
|
||||
using namespace stk;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -29,6 +30,7 @@ Nearly all STK classes implement <TT>tick()</TT> functions that take and/or retu
|
||||
|
||||
\code
|
||||
#include "Noise.h"
|
||||
using namespace stk;
|
||||
|
||||
int main()
|
||||
{
|
||||
@@ -44,19 +46,19 @@ int main()
|
||||
}
|
||||
\endcode
|
||||
|
||||
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.
|
||||
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. 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 that roughly group many of the classes according to function as follows:
|
||||
|
||||
- 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 [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 data output classes [FileWvOut, RtWvOut, InetWvOut]
|
||||
- WvIn: audio data input classes [FileWvIn, WaveLoop, RtWvIn, InetWvIn]
|
||||
- stk::Generator: source signal unit generator classes [stk::Envelope, stk::ADSR, stk::Asymp, stk::Noise, stk::SubNoise, stk::Modulate, stk::SingWave, stk::SineWave, stk::Blit, stk::BlitSaw, stk::BlitSquare, stk::Granulate]
|
||||
- stk::Filter: digital filtering classes [stk::OneZero, stk::OnePole, stk::PoleZero, stk::TwoZero, stk::TwoPole, stk::BiQuad, stk::FormSwep, stk::Delay, stk::DelayL, stk::DelayA, stk::TapDelay]
|
||||
- stk::Function: input to output function mappings [stk::BowTable, stk::JetTable, stk::ReedTable]
|
||||
- stk::Instrmnt: sound synthesis algorithms, including physical, FM, modal, and particle models
|
||||
- stk::Effect: sound processing effect classes [stk::Echo, stk::Chorus, stk::PitShift, stk::PRCRev, stk::JCRev, stk::NRev]
|
||||
- stk::WvOut: audio data output classes [stk::FileWvOut, stk::RtWvOut, stk::InetWvOut]
|
||||
- stk::WvIn: audio data input classes [stk::FileWvIn, stk::FileLoop, stk::RtWvIn, stk::InetWvIn]
|
||||
|
||||
|
||||
[<A HREF="tutorial.html">Main tutorial page</A>] [<A HREF="hello.html">Next tutorial</A>]
|
||||
|
||||
@@ -3,24 +3,25 @@
|
||||
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
|
||||
oscillator class, stk::FileLoop, 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.
|
||||
stk::FileWvOut to write the result to a 16-bit, WAV formatted audio file.
|
||||
|
||||
\code
|
||||
|
||||
// sineosc.cpp
|
||||
|
||||
#include "WaveLoop.h"
|
||||
#include "FileLoop.h"
|
||||
#include "FileWvOut.h"
|
||||
using namespace stk;
|
||||
|
||||
int main()
|
||||
{
|
||||
// Set the global sample rate before creating class instances.
|
||||
Stk::setSampleRate( 44100.0 );
|
||||
|
||||
WaveLoop input;
|
||||
FileLoop input;
|
||||
FileWvOut output;
|
||||
|
||||
// Load the sine wave file.
|
||||
@@ -39,29 +40,37 @@ int main()
|
||||
}
|
||||
\endcode
|
||||
|
||||
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.
|
||||
stk::FileLoop is a subclass of stk::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.
|
||||
stk::FileWvIn provides interpolating, read-once ("oneshot")
|
||||
functionality, as well as methods for setting the read rate and read
|
||||
position.
|
||||
|
||||
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.
|
||||
stk::FileWvIn provides a "tick level" and interpolating interface to
|
||||
the stk::FileRead class. Likewise, stk::FileWvOut provides a "tick
|
||||
level" interface to the stk::FileWrite class. stk::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. stk::FileWvOut does not currently offer
|
||||
data interpolation functionality.
|
||||
|
||||
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.
|
||||
A number of STK parent classes, including stk::WvIn, stk::WvOut,
|
||||
stk::Instrmnt, stk::Generator, and stk::Effect, (and some or all of
|
||||
their subclasses) support multi-channel sample frames. If a
|
||||
single-sample version of the <TT>tick()</TT> function is called for
|
||||
these classes, a full sample frame is computed but only a single value
|
||||
is either input and/or output. For example, if the single-sample
|
||||
<TT>tick()</TT> function is called for subclasses of stk::WvOut, the
|
||||
sample argument is written to all channels in the one computed frame.
|
||||
For classes returning values, an optional \c channel argument
|
||||
specifies which channel value is returned from the computed frame (the
|
||||
default is always channel 0). To input and/or output multichannel data
|
||||
to these classes, the overloaded <TT>tick()</TT> functions taking
|
||||
StkFrames reference arguments should be used.
|
||||
|
||||
Nearly all STK classes inherit from the Stk base class. Stk provides
|
||||
a static sample rate that is queried by subclasses as needed.
|
||||
Nearly all STK classes inherit from the stk::Stk base class. Stk
|
||||
provides a static sample rate that 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.
|
||||
@@ -75,7 +84,11 @@ 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.
|
||||
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="fundamentals.html">Main tutorial page</A>] [<A HREF="compile.html">Next tutorial</A>]
|
||||
*/
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
/*! \mainpage <I>The Synthesis ToolKit in C++ (STK)</I>
|
||||
/*! \mainpage The Synthesis ToolKit in C++ (STK)
|
||||
|
||||
\htmlonly
|
||||
<BODY BGCOLOR="white">
|
||||
@@ -15,7 +15,7 @@ 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
|
||||
fact, the ToolKit has been working continuously for nearly 15 years
|
||||
now. STK currently runs with realtime support (audio and MIDI) on
|
||||
Linux, Macintosh OS X, and Windows computer platforms. Generic,
|
||||
non-realtime support has been tested under NeXTStep, Sun, and other
|
||||
|
||||
@@ -18,9 +18,9 @@ Here's a link to a book that includes an chapter on STK.
|
||||
|
||||
<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 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 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 15 years now. STK currently runs with realtime support (audio and MIDI) on 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).
|
||||
The Synthesis ToolKit is free. 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>
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
/*! \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 its frequency can be modified over time.
|
||||
The ToolKit comes with a wide variety of synthesis algorithms, all of which inherit from the stk::Instrmnt class. In this example, we'll fire up an instance of the stk::BeeThree FM synthesis class and show how its frequency can be modified over time.
|
||||
|
||||
\include bethree.cpp
|
||||
|
||||
@@ -10,7 +10,7 @@ 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 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.
|
||||
The noteOn() function initiates an instrument attack. Instruments that are continuously excited (e.g., stk::Clarinet, stk::BeeThree) will continue to sound until stopped with a noteOff(). Impulsively excited instrument sounds (e.g., stk::Plucked, stk::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.
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
/*! \page links Miscellaneous Links
|
||||
|
||||
- <A HREF="http://music.mcgill.ca/~gary/rtaudio/">The %RtAudio WWW site</A>
|
||||
- <A HREF="http://www.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://www.music.mcgill.ca/~gary/rtmidi/">The %RtMidi WWW site</A>
|
||||
|
||||
- <A HREF="http://ccrma.stanford.edu/~woony/software/stkx/">StkX: A Cocoa STK Framework for Mac OS X by Woon Seung Yeo</A>
|
||||
|
||||
|
||||
@@ -1,22 +1,25 @@
|
||||
/*! \page multichannel Multi-Channel I/O
|
||||
|
||||
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.
|
||||
The ToolKit stk::WvIn and stk::WvOut classes (and their subclasses) support multi-channel audio data input and output. Several other abstract base classes, such as stk::Instrmnt, stk::Generator, and stk::Effect, also support multi-channel computations though not all of their subclasses produce or take multi-channel data. 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 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).
|
||||
<TT>tick()</TT> function. For classes supporting multi-channel data,
|
||||
one must distinguish the <TT>tick()</TT> functions taking or producing
|
||||
single \c StkFloat arguments from those taking stk::StkFrames& arguments. If
|
||||
a single-sample version of the <TT>tick()</TT> function is called for
|
||||
these classes, a full sample frame is computed but only a single value
|
||||
is either input and/or output. For example, if the single-sample
|
||||
<TT>tick()</TT> function is called for subclasses of WvOut, the sample
|
||||
argument is written to all channels in the one computed frame. For
|
||||
classes returning values, an optional \c channel argument specifies
|
||||
which channel value is returned from the computed frame (the default
|
||||
is always channel 0). To input and/or output multichannel data to
|
||||
these classes, the overloaded <TT>tick()</TT> functions taking
|
||||
StkFrames reference arguments should be used.
|
||||
|
||||
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 FileWvOut class for
|
||||
The following example demonstrates the use of the stk::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.
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
/*! \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 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 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 stk::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 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.
|
||||
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 "group" number. All sounding instrument outputs are summed and returned via the <TT>tick()</TT> function. The stk::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 stk::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.
|
||||
In the following example, we modify the <TT>controlbee.cpp</TT> program to make use of three stk::BeeThree instruments, all controlled using a stk::Voicer.
|
||||
|
||||
\include threebees.cpp
|
||||
|
||||
@@ -16,7 +16,7 @@ threebees < scores/bachfugue.ski
|
||||
|
||||
For more fun, surf to <A HREF="http://kern.humdrum.net/">Kern Scores</A> for a huge assortment of other scorefiles that can be downloaded in the SKINI format.
|
||||
|
||||
Another easy extension would be to add the \c Messager::startMidiInput() function to the program and then play the instruments via a MIDI keyboard.
|
||||
Another easy extension would be to add the \c stk::Messager::startMidiInput() function to the program and then play the instruments via a MIDI keyboard.
|
||||
|
||||
[<A HREF="tutorial.html">Main tutorial page</A>]
|
||||
*/
|
||||
|
||||
@@ -2,36 +2,36 @@
|
||||
|
||||
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
|
||||
computer system. We also make use of the stk::SineWave class as a
|
||||
sine-wave oscillator. stk::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
|
||||
The class stk::RtWvOut is a protected subclass of stk::WvOut. A number of
|
||||
optional constructor arguments can be used to fine tune its
|
||||
performance for a given system. RtWvOut provides a "single-sample",
|
||||
blocking interface to the RtAudio class. Note that RtWvOut (as well
|
||||
as the RtWvIn class described below) makes use of RtAudio's callback
|
||||
performance for a given system. stk::RtWvOut provides a "single-sample",
|
||||
blocking interface to the RtAudio class. Note that stk::RtWvOut (as well
|
||||
as the stk::RtWvIn class described below) makes use of RtAudio's callback
|
||||
input/output functionality by creating a large ring-buffer into which
|
||||
data is written. These classes should not be used when low-latency
|
||||
and robust performance is necessary
|
||||
|
||||
Though not used here, an RtWvIn class exists as well that can be used
|
||||
Though not used here, an stk::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
|
||||
It may be possible to use an instance of stk::RtWvOut and an instance of
|
||||
stk::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 RtAudio to achieve this behavior, as described in the next section.
|
||||
See the <TT>effects</TT> project or the <TT>duplex.cpp</TT> example
|
||||
program in the <TT>examples</TT> project for more information.
|
||||
|
||||
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):
|
||||
When using any realtime STK class (RtAudio, stk::RtWvOut, stk::RtWvIn, RtMidi, stk::InetWvIn, stk::InetWvOut, stk::Socket, stk::UdpSocket, stk::TcpServer, stk::TcpClient, and stk::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 Generator.cpp SineWave.cpp WvOut.cpp \
|
||||
|
||||
@@ -15,10 +15,9 @@
|
||||
|
||||
<B>Macintosh OS X (specific):</B>
|
||||
<UL>
|
||||
<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 that 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>A C++ compiler is not installed 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>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.
|
||||
<LI>The tcl/tk interpreter does not ship by default with OS X and 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.
|
||||
|
||||
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>
|
||||
|
||||
@@ -32,11 +31,6 @@ It appears that socket support in Tcl/Tk uses the Nagle algorithm, which produce
|
||||
<LI>For compiling the source (if not already in your system): <UL><LI><A HREF="Misc/dsound.h">dsound.h</A> header file (DirectX 6.1) - put somewhere in your header search path</LI><LI><A HREF="Misc/dsound.lib">dsound.lib</A> library file (DirectX 6.1) - put somewhere in your library search path</LI></UL></LI>
|
||||
</UL>
|
||||
|
||||
<B>WindowsNT (specific):</B>
|
||||
<UL>
|
||||
<LI>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>
|
||||
</UL>
|
||||
|
||||
<P>
|
||||
|
||||
*/
|
||||
|
||||
@@ -45,8 +45,6 @@ This release of STK comes with four separate "project" directories:
|
||||
<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> 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++ .NET 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>
|
||||
|
||||
<LI><B>Unix Systems:</B> A GNU <TT>configure</TT> shell script is included in the distribution for unix-based systems. From the top-level distribution directory, type <TT>'./configure'</TT> and the script will create <TT>Makefiles</TT> in each project directory specific to the characteristics of the host computer. Then from within any given project directory (example <TT>demo</TT>), type <TT>'make'</TT> to compile the project. In addition, an STK library can be compiled from within the <TT>src</TT> directory.
|
||||
|
||||
Several options can be supplied to the <TT>configure</TT> script to customize the build behavior:
|
||||
|
||||
@@ -5,10 +5,7 @@ By Perry R. Cook and Gary P. Scavone, 1995-2007.
|
||||
STK Classes - See the HTML documentation in the html directory for complete information.
|
||||
|
||||
|
||||
.- Generator - (Modulate, Noise, SingWave, Envelope, SineWave, Blit, BlitSaw, BlitSquare, Granulate)
|
||||
| | |
|
||||
| SubNoise ADSR
|
||||
| Asymp
|
||||
.- Generator - (Modulate, Noise, SingWave, Envelope, ADSR, Asymp, SineWave, Blit, BlitSaw, BlitSquare, Granulate)
|
||||
|
|
||||
|- Function - (BowTable, JetTable, ReedTable)
|
||||
|
|
||||
@@ -16,14 +13,11 @@ STK Classes - See the HTML documentation in the html directory for complete info
|
||||
|
|
||||
|- WvIn - (FileWvIn, RtWvIn, InetWvIn)
|
||||
| |
|
||||
| WaveLoop
|
||||
| FileLoop
|
||||
|
|
||||
|- WvOut - (FileWvOut, RtWvOut, TcpWvOut)
|
||||
|
|
||||
|- Filter - (OnePole, OneZero, Delay, TwoPole, TwoZero, PoleZero, Biquad)
|
||||
| | |
|
||||
| DelayL FormSwep
|
||||
| DelayA
|
||||
|- Filter - (OnePole, OneZero, TwoPole, TwoZero, PoleZero, Biquad, FormSwep, Delay, DelayL, DelayA, TapDelay)
|
||||
|
|
||||
|- RtAudio, RtMidi, RtDuplex, Socket, Thread, Mutex
|
||||
| |
|
||||
@@ -68,34 +62,35 @@ Stk -| UdpSocket
|
||||
|
||||
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
|
||||
Sources: Generator.h Abstract base class for various source signal classes
|
||||
Function.h Abstract base class for various input/output mapping classes
|
||||
Envelope.cpp Linearly goes to target by rate
|
||||
ADSR.cpp ADSR flavor of Envelope
|
||||
ADSR.cpp ADSR 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
|
||||
WvIn.h Abstract base class for audio data input classes
|
||||
FileWvIn.cpp Audio file input interface class with interpolation
|
||||
WaveLoop.cpp Wavetable looping (subclass of FileWvIn)
|
||||
FileLoop.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: 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
|
||||
WvOut.h 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 (blocking)
|
||||
|
||||
Filters: Filter.cpp Filter master class
|
||||
Filters: Filter.h Filter master class
|
||||
Iir.h General infinite-impulse response filter
|
||||
Fir.h General finite-impulse response filter
|
||||
OneZero.cpp One zero filter
|
||||
OnePole.cpp One pole filter
|
||||
PoleZero.cpp One pole/one zero filter
|
||||
@@ -104,15 +99,16 @@ Filters: Filter.cpp Filter master class
|
||||
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)
|
||||
DelayL.cpp Linearly interpolating delay line
|
||||
DelayA.cpp Allpass interpolating delay line
|
||||
TapDelay.cpp Multi-tap non-interpolating delay line class
|
||||
|
||||
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.h Cubic jet non-linearity
|
||||
BowTabl.h x^(-3) Bow non-linearity
|
||||
ReedTabl.h One breakpoint saturating reed non-linearity
|
||||
|
||||
Derived: Modulate.cpp Periodic and random vibrato: WvIn, SubNoise, OnePole
|
||||
SingWave.cpp Looping wave table with randomness: Modulate, WaveLoop, Envelope
|
||||
Derived: Modulate.cpp Periodic and random vibrato: WvIn, Noise, OnePole
|
||||
SingWave.cpp Looping wave table with randomness: Modulate, FileLoop, Envelope
|
||||
|
||||
|
||||
********** INSTRUMENTS AND ALGORITHMS **************
|
||||
@@ -153,7 +149,7 @@ Shakers.cpp PhISM statistical model for shakers and real-world sound effects
|
||||
Mesh2D.cpp Two-dimensional, rectilinear digital waveguide mesh.
|
||||
Whistle.cpp Hybrid physical/spectral model of a police whistle.
|
||||
|
||||
Effect.cpp Effects Processor Base Class
|
||||
Effect.h Effects Processor Base Class
|
||||
JCRev.cpp Chowning Reverberator 3 series allpass units, 4 parallel combs, 2 stereo delays
|
||||
NRev.cpp Another famous CCRMA Reverb 8 allpass, 6 parallel comb filters
|
||||
PRCRev.cpp Dirt Cheap Reverb by Cook 2 allpass, 2 comb filters
|
||||
|
||||
175
doc/treesed.html
Normal file
175
doc/treesed.html
Normal file
@@ -0,0 +1,175 @@
|
||||
<html>
|
||||
<head>
|
||||
<title>Treesed Usage</title>
|
||||
</head>
|
||||
<body>
|
||||
<table border="0" width="660" cellpadding="0" cellspacing="0">
|
||||
<tbody><tr valign="top"><td width="165">
|
||||
|
||||
<h3>How to Use Treesed</h3>
|
||||
|
||||
Go to the directory where you want to search or make changes.
|
||||
|
||||
<p>
|
||||
There are two choices you can make when using treesed:
|
||||
</p><ol>
|
||||
<li>Do I just want to search for a text, or do I want to search for a
|
||||
text and replace it with something else?
|
||||
<br>
|
||||
If you are just searching you are using Treesed in "search mode", otherwise it is in
|
||||
"replace mode."
|
||||
</li><li>Do I want to search/replace only in files in my current directory,
|
||||
or should files in all subdirectories (and all directories below that)
|
||||
also be done?
|
||||
</li></ol>
|
||||
Some examples will make this clear.
|
||||
|
||||
<h4>Searching</h4>
|
||||
Say you are faced with the situation that the author of a slew of web-pages, Nathan Brazil, has left and has been succeeded by Mavra Chang. First, let us see which files are affected by this (what you type in is shown in <b><tt>bold</tt></b>):
|
||||
<blockquote>
|
||||
<pre>[localhost] <b>treesed "Nathan Brazil" -files *.html</b>
|
||||
search_pattern: Nathan\ Brazil
|
||||
replacement_pattern:
|
||||
|
||||
** Search mode
|
||||
|
||||
.
|
||||
midnight.html: 1 lines on: 2
|
||||
..
|
||||
well.html: 1 lines on: 3
|
||||
</pre>
|
||||
</blockquote>
|
||||
We notice the following:
|
||||
<ul>
|
||||
<li>The search text <tt>"Nathan Brazil"</tt> is enclosed in
|
||||
double-quotes (<tt>"</tt>).
|
||||
</li><li>You specify which files to search with <tt>-files</tt> followed by a
|
||||
list of file names--in this case <tt>*.html</tt>.
|
||||
</li><li>Treesed reports the search pattern ("pattern" is just a fancy word
|
||||
for "text") you specified (you can ignore
|
||||
that \).
|
||||
</li><li>Treesed reports an empty <tt>replacement_pattern</tt>. This is
|
||||
correct, because you haven't entered one.
|
||||
</li><li>It therefore deduces that is is in search mode.
|
||||
</li><li>It finds two files containing "Nathan Brazil", and reports on which
|
||||
lines of these files it found it; it does not show the lines themselves.
|
||||
</li></ul>
|
||||
Because you used <tt>-files</tt>, Treesed will search in the files you
|
||||
specify <i>in the current directory</i>. You can also search files in
|
||||
the current directory <i>and</i> all directories below it. However, in
|
||||
that case you can not specify which file names to use, all files will be
|
||||
searched:
|
||||
<blockquote>
|
||||
<pre>[localhost] <b>treesed "Nathan Brazil" -tree</b>
|
||||
search_pattern: Nathan\ Brazil
|
||||
replacement_pattern:
|
||||
|
||||
** Search mode
|
||||
|
||||
.
|
||||
midnight.html: 1 lines on: 2
|
||||
...
|
||||
well.html: 1 lines on: 3
|
||||
.
|
||||
new/echoes.html: 1 lines on: 2
|
||||
</pre>
|
||||
</blockquote>
|
||||
We notice the following:
|
||||
<ul>
|
||||
<li>Instead of <tt>-files</tt> we now see <tt>-tree</tt>.
|
||||
</li><li>We do not see a specification of file names.
|
||||
</li><li>Treesed finds an occurence of "Nathan Brazil" in the file
|
||||
<tt>echoes.html</tt> in the subdirectory <tt>new</tt>; it did not
|
||||
find this file in the previous example (as it shouldn't).
|
||||
</li></ul>
|
||||
|
||||
<h4>Replacing</h4>
|
||||
To replace a text you simply add the replacement text right after the
|
||||
search text:
|
||||
<blockquote>
|
||||
<pre>[localhost] <b>treesed "Nathan Brazil" "Mavra Change" -files *.html</b>
|
||||
search_pattern: Nathan\ Brazil
|
||||
replacement_pattern: Mavra Chang
|
||||
|
||||
** EDIT MODE!
|
||||
|
||||
.
|
||||
midnight.html: 1 lines on: 2
|
||||
|
||||
Replaced Nathan\ Brazil by Mavra Chang on 1 lines in midnight.html
|
||||
..
|
||||
well.html: 1 lines on: 3
|
||||
|
||||
Replaced Nathan\ Brazil by Mavra Chang on 1 lines in well.html
|
||||
</pre>
|
||||
</blockquote>
|
||||
We notice the following:
|
||||
<ul>
|
||||
<li>Right after the search text "Nathan Brazil" you specify the
|
||||
replacement text "Mavra Chang".
|
||||
</li><li>As a result, Treesed now reports a non-empty
|
||||
<tt>replacement_pattern</tt>.
|
||||
</li><li>Hence it concludes it is in "edit mode", which means replacment mode.
|
||||
</li><li>Treesed dutifully reports on which lines in which files it did the
|
||||
replacement.
|
||||
</li></ul>
|
||||
To replace a text in all files in the current directory and the ones
|
||||
below it, we do the following:
|
||||
<blockquote>
|
||||
<pre>[localhost] <b>treesed "Nathan Brazil" "Mavra Chang" -tree</b>
|
||||
search_pattern: Nathan\ Brazil
|
||||
replacement_pattern: Mavra Chang
|
||||
|
||||
** EDIT MODE!
|
||||
|
||||
.
|
||||
midnight.html: 1 lines on: 2
|
||||
|
||||
Replaced Nathan\ Brazil by Mavra Chang on 1 lines in midnight.html
|
||||
|
||||
....
|
||||
well.html: 1 lines on: 3
|
||||
|
||||
Replaced Nathan\ Brazil by Mavra Chang on 1 lines in well.html
|
||||
.
|
||||
new/echoes.html: 1 lines on: 2
|
||||
|
||||
Replaced Nathan\ Brazil by Mavra Chang on 1 lines in new/echoes.html
|
||||
</pre>
|
||||
</blockquote>
|
||||
and we get the expected results, including the replace in
|
||||
<tt>new/echoes.html</tt>.
|
||||
|
||||
<h4>Old Versions</h4>
|
||||
Treesed leaves behind quite a mess of old versions of the files it
|
||||
changed (only in change-mode, of course). These old files have the same
|
||||
name as the original file, with <tt>.ddddd</tt> appended to it. For
|
||||
example, if treesed makes a change to <tt>midnight.html</tt> it will
|
||||
leave the original version as something like
|
||||
<tt>midnight.html.26299</tt>. You'll have to remove these files lest
|
||||
your disk area clutters up. Here is a command that does that, <b>but
|
||||
beware!</b> This command removes all files in the current directory and
|
||||
all below it, that end in a period followed by one or more
|
||||
digits:
|
||||
<blockquote>
|
||||
<pre>find . -name "*.[0-9]*" -exec rm {} \;
|
||||
</pre>
|
||||
</blockquote>
|
||||
|
||||
It is interesting to note that if you use treesed again without cleaning
|
||||
up, you may get files like <tt>midnight.html.26299.27654</tt>. These
|
||||
will also be cleaned up by the above slightly dangerous command.
|
||||
|
||||
|
||||
<h3>About Treesed</h3>
|
||||
<tt>treesed</tt> is public domain software developed
|
||||
and designed by Rick Jansen from Sara, Amsterdam, Netherlands, January
|
||||
1996.
|
||||
|
||||
<p>
|
||||
|
||||
<h3>About This Document</h3>
|
||||
This usage document was created by the Division of Information Technology Services at The
|
||||
University of Western Ontario.
|
||||
|
||||
</body></html>
|
||||
Reference in New Issue
Block a user