mirror of
https://github.com/thestk/stk
synced 2026-01-11 20:11:52 +00:00
Version 4.3.0
This commit is contained in:
Gary Scavone
committed by
Stephen Sinclair
Stephen Sinclair
parent
2cbce2d8bd
commit
27d9b79dc7
@@ -4,7 +4,7 @@
|
||||
# Project related configuration options
|
||||
#---------------------------------------------------------------------------
|
||||
PROJECT_NAME = STK
|
||||
PROJECT_NUMBER = 4.2.1
|
||||
PROJECT_NUMBER = 4.3
|
||||
OUTPUT_DIRECTORY = .
|
||||
CREATE_SUBDIRS = NO
|
||||
OUTPUT_LANGUAGE = English
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
/*! \page compile Compiling
|
||||
|
||||
The Synthesis ToolKit can be used in a variety of ways, depending on your particular needs. Some people choose the classes they need for a particular project and copy those to their working directory. Others create <TT>Makefiles</TT> which compile project-specific class objects from common <TT>src</TT> and <TT>include</TT> directories. And still others like to compile and link to a common library of object files. STK was not designed with one particular style of use in mind.
|
||||
The Synthesis ToolKit can be used in a variety of ways, depending on your particular needs. Some people choose the classes they need for a particular project and copy those to their working directory. Others create <TT>Makefiles</TT> that compile project-specific class objects from common <TT>src</TT> and <TT>include</TT> directories. And still others like to compile and link to a common library of object files. STK was not designed with one particular style of use in mind.
|
||||
|
||||
|
||||
\section rtvsnonrt "Realtime" vs. "Non-Realtime"
|
||||
@@ -9,11 +9,11 @@ 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
|
||||
and operating-system (OS) <I>dependent</I>. STK classes that 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.
|
||||
compiled on Linux, 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
|
||||
@@ -42,15 +42,15 @@ STK compiles with realtime support on the following flavors of the Unix operatin
|
||||
</TR>
|
||||
<TR>
|
||||
<TD>Linux</TD>
|
||||
<TD>Jack (audio only, use ALSA for MIDI support)</TD>
|
||||
<TD>__LINUX_JACK__, __LINUX_ALSASEQ__, __LITTLE_ENDIAN__</TD>
|
||||
<TD>OSS (version 4.0 only, use ALSA for MIDI support)</TD>
|
||||
<TD>__LINUX_OSS__, __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>
|
||||
<TD>__LINUX_OSS__, __LINUX_ALSASEQ__, __LITTLE_ENDIAN__</TD>
|
||||
<TD><TT>asound, pthread</TT></TD>
|
||||
<TD>Linux and Macintosh OS-X</TD>
|
||||
<TD>Jack (audio only, use ALSA for MIDI support)</TD>
|
||||
<TD>__UNIX_JACK__, __LINUX_ALSASEQ__, __LITTLE_ENDIAN__</TD>
|
||||
<TD><TT>asound, pthread, jack</TT></TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD>Macintosh OS X</TD>
|
||||
@@ -58,12 +58,6 @@ STK compiles with realtime support on the following flavors of the Unix operatin
|
||||
<TD>__MACOSX_CORE__</TD>
|
||||
<TD><TT>pthread, CoreAudio, CoreMIDI, CoreFoundation</TT></TD>
|
||||
</TR>
|
||||
<TR>
|
||||
<TD>Irix</TD>
|
||||
<TD>AL</TD>
|
||||
<TD>__IRIX_AL__, __IRIX_MD__</TD>
|
||||
<TD><TT>audio, pthread</TT></TD>
|
||||
</TR>
|
||||
</TABLE>
|
||||
</CENTER>
|
||||
|
||||
@@ -85,7 +79,7 @@ g++ -Wall -D__LITTLE_ENDIAN__ -o sineosc Stk.cpp FileRead.cpp FileWrite.cpp WvIn
|
||||
|
||||
Note that the <TT>sineosc.cpp</TT> example does not make use of realtime audio or MIDI input/output classes. For programs using any of the STK realtime classes mentioned above, it is necessary to specify an audio/MIDI API preprocessor definition and link with the appropriate libraries or frameworks.
|
||||
|
||||
When working with a number of different projects that make use of ToolKit classes, the above approach can become cumbersome (especially when trying to synchronize with new STK releases). Most of the STK projects (e.g., demo, effects, ...) contain <TT>Makefiles</TT> (built by the configure script) which compile project-specific class objects from the distribution <TT>src</TT> and <TT>include</TT> directories. This approach makes it relatively easy when upgrading to a new STK release (by making path substitutions in the <TT>Makefile</TT> or by moving the projects to a similar relative path within the new STK source tree). A <TT>Makefile</TT> is provided in the <TT>projects/examples</TT> directory for compiling all the tutorial programs, as well as other example programs. To compile the <TT>sineosc.cpp</TT> program, for example, one need only type <TT>make sineosc</TT> from within the <TT>projects/examples</TT> directory.
|
||||
When working with a number of different projects that make use of ToolKit classes, the above approach can become cumbersome (especially when trying to synchronize with new STK releases). Most of the STK projects (e.g., demo, effects, ...) contain <TT>Makefiles</TT> (built by the configure script) that compile project-specific class objects from the distribution <TT>src</TT> and <TT>include</TT> directories. This approach makes it relatively easy when upgrading to a new STK release (by making path substitutions in the <TT>Makefile</TT> or by moving the projects to a similar relative path within the new STK source tree). A <TT>Makefile</TT> is provided in the <TT>projects/examples</TT> directory for compiling all the tutorial programs, as well as other example programs. To compile the <TT>sineosc.cpp</TT> program, for example, one need only type <TT>make sineosc</TT> from within the <TT>projects/examples</TT> directory.
|
||||
|
||||
|
||||
\subsection library Library Use:
|
||||
@@ -114,11 +108,11 @@ 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
|
||||
STK has been tested on Windows platforms using the Visual .NET compiler
|
||||
only. It is assumed here that you're familiar with Visual C++ and its
|
||||
particular idiosyncrasies.
|
||||
particular idiosyncrasies. STK won't compile in Visual C++ 6.0 any more.
|
||||
|
||||
The approach when using Visual C++ is to build a project which
|
||||
The approach when using Visual C++ is to build a project that
|
||||
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
|
||||
|
||||
@@ -1,26 +1,74 @@
|
||||
/*! \page crealtime Realtime Audio (callback)
|
||||
|
||||
The previous section described the use of the RtWvOut class for realtime audio output. The RtWvOut::tick() function periodically pauses program execution in order to send a buffer of audio data to the computer's audio hardware (referred to as blocking functionality). These pauses will effectively limit a program's computations to the correct number of samples per second, which is defined by the sample rate of the hardware.
|
||||
An alternative scheme for audio input/output is to define a specific
|
||||
function in which audio computations are performed and to let the
|
||||
audio system call this function when more input/output data can be
|
||||
accepted by the hardware (referred to as a callback scheme). In this
|
||||
section, we show how the previous <TT>rtsine.cpp</TT> program can be
|
||||
modified to work in a callback scenario. There is no "single-sample"
|
||||
interface for this functionality. The callback function will be
|
||||
invoked automatically by the audio system controller (RtAudio) when
|
||||
new data is needed and it is necessary to compute a full audio buffer
|
||||
of samples at that time (see \ref callback for further information).
|
||||
|
||||
An alternative scheme for audio input/output is to define a specific function in which audio computations are performed and to let the audio system call this function when more input/output data can be accepted by the hardware (referred to as a callback scheme). In this section, we show how the previous <TT>rtsine.cpp</TT> program can be modified to work in a callback scenario. There is no "single-sample" interface for this functionality. The callback function will be invoked automatically by the audio system controller (RtAudio) when new data is needed and it is necessary to compute a full audio buffer of samples at that time (see \ref callback for further information).
|
||||
The previous section described the use of the RtWvOut class for
|
||||
realtime audio output. The 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.
|
||||
|
||||
\include crtsine.cpp
|
||||
|
||||
The sinusoidal oscillator is created as before. The instantiation of RtAudio requires quite a few more parameters, including output/input device and channel specifiers, the data format, and the desired buffer length (in frames). In this example, we request a single output channel using the default output device, zero channels of input, the RtAudio data format which corresponds to an <tt>StkFloat</tt>, and the RT_BUFFER_SIZE defined in Stk.h. The last argument is an API-dependent buffering parameter (see RtAudio for further information).
|
||||
The sinusoidal oscillator is created as before. The instantiation of
|
||||
RtAudio requires quite a few more parameters, including output/input
|
||||
device and channel specifiers, the data format, and the desired buffer
|
||||
length (in frames). In this example, we request a single output
|
||||
channel using the default output device, zero channels of input, the
|
||||
RtAudio data format which corresponds to an <tt>StkFloat</tt>, and the
|
||||
RT_BUFFER_SIZE defined in Stk.h. The \c bufferFrames argument is an
|
||||
API-dependent buffering parameter (see RtAudio for further
|
||||
information).
|
||||
|
||||
After the digital-to-analog converter (dac) and oscillator are successfully created, it is necessary to provide the audio system controller with a pointer to our callback function. The RtAudio::setStreamCallback() function takes a pointer to the callback function and an optional pointer to data that will be made available in the callback. In this example, we need to pass only the pointer to the oscillator. In more complex programs, it is typically necessary to put all shared data in a <tt>struct</tt> (see the next tutorial program for an example) or make use of global variables.
|
||||
We also provide the audio system controller with a pointer to our
|
||||
callback function and an optional pointer to data that will be made
|
||||
available in the callback. In this example, we need to pass only the
|
||||
pointer to the oscillator. In more complex programs, it is typically
|
||||
necessary to put all shared data in a <tt>struct</tt> (see the next
|
||||
tutorial program for an example) or make use of global variables.
|
||||
|
||||
Our callback routine is the \c tick() function. %Function arguments include a pointer to the audio data buffer, the buffer size (in frames), and the data pointer passed to the RtAudio::setStreamCallback() function (if it exists). It is necessary to cast these pointers to their corresponding data types before use. Our tick() routine simply "ticks" the oscillator for \c bufferSize counts and writes the result into the audio data buffer before returning.
|
||||
Our callback routine is the \c tick() function. Function arguments
|
||||
include pointers to the audio input and output data buffers, the
|
||||
buffer size (in frames), a stream time argument, a status argument to
|
||||
test for over/underruns, and the data pointer passed in the
|
||||
openStream() function (if it exists). It is necessary to cast these
|
||||
pointers to their corresponding data types before use. Our tick()
|
||||
routine simply "ticks" the oscillator for \c nBufferFrames counts and
|
||||
writes the result into the audio data buffer before returning.
|
||||
|
||||
The \c main() function blocks at the std::cin.get() call until the user hits the "enter" key, after which the audio controller is shut down and program execution ends.
|
||||
The \c main() function blocks at the std::cin.get() call until the
|
||||
user hits the "enter" key, after which the audio controller is shut
|
||||
down and program execution ends.
|
||||
|
||||
\section callback Blocking vs. Callbacks
|
||||
|
||||
Prior to version 4.2.0, all STK example projects and programs used blocking audio input/output functionality (typically with the RtWvIn, RtWvOut, or RtDuplex classes). In many instances, a blocking scheme results in a clearer and more straight-forward program structure. Within a graphical user interface (GUI) programming context, however, callback routines are often more natural.
|
||||
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.
|
||||
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 that 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="tutorial.html">Main tutorial page</A>] [<A HREF="instruments.html">Next tutorial</A>]
|
||||
*/
|
||||
|
||||
@@ -1,16 +1,34 @@
|
||||
/*! \page download Download, Release Notes, and Bug Fixes
|
||||
|
||||
\section down Download Version 4.2.1 (14 October 2005):
|
||||
\section down Download Version 4.3.0 (13 August 2007):
|
||||
|
||||
<UL>
|
||||
<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/software/stk/release/stk-4.3.0.tar.gz">Source distribution</A></LI>
|
||||
<LI><A HREF="http://ccrma.stanford.edu/software/stk/release/stk-4.3.0.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 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>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>
|
||||
<li>Fixes in BlitSquare for frequency, harmonics, and dc offset.</li>
|
||||
<li>Updates to Makefiles for non-realtime compile.</li>
|
||||
<li>Fix in demo.cpp for voice channel assignment.</li>
|
||||
<li>Updated versions of RtMidi and RtAudio.</li>
|
||||
<li>Updated ASIO files for MinGW compiler.</li>
|
||||
<li>New FAQ in documentation.</li>
|
||||
<li>MAT-file bug fix in FileRead class.</li>
|
||||
</ul>
|
||||
|
||||
\subsection v4dot2dot1 Version 4.2.1
|
||||
|
||||
<ul>
|
||||
|
||||
72
doc/doxygen/faq.txt
Normal file
72
doc/doxygen/faq.txt
Normal file
@@ -0,0 +1,72 @@
|
||||
/*! \page faq Frequently Asked Questions
|
||||
|
||||
- \ref license
|
||||
- \ref filerate
|
||||
- \ref computesample
|
||||
- \ref tickframe
|
||||
- \ref endianness
|
||||
- \ref xwindows
|
||||
|
||||
\section license Does STK have a license?
|
||||
|
||||
Yes, we finally made something official for release 4.3.0. It is listed in the Stk class and a few other places in the distribution, but I'll repeat it here for clarity:
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining
|
||||
a copy of this software and associated documentation files (the
|
||||
"Software"), to deal in the Software without restriction, including
|
||||
without limitation the rights to use, copy, modify, merge, publish,
|
||||
distribute, sublicense, and/or sell copies of the Software, and to
|
||||
permit persons to whom the Software is furnished to do so, subject to
|
||||
the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be
|
||||
included in all copies or substantial portions of the Software.
|
||||
|
||||
Any person wishing to distribute modifications to the Software is
|
||||
asked to send the modifications to the original developer so that they
|
||||
can be incorporated into the canonical version. This is, however, not
|
||||
a binding provision of this license.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
||||
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
||||
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
||||
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
||||
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
||||
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
||||
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
|
||||
\section filerate Why is my file sample rate wrong?
|
||||
|
||||
When the FileWvIn class loads a soundfile, it automatically sets its internal read increment based on the soundfile rate and the current STK sample rate. For example, if the current STK sample rate is 44100 Hz and the soundfile rate is 22050 Hz, the read increment, or rate, will be set to 0.5 and the file will be interpolated so that is sounds correct at 44100 Hz. For most cases, this works fine. However, consider the following example:
|
||||
|
||||
\code
|
||||
FileWvIn input( "infile" ); // read an input soundfile
|
||||
StkFloat sampleRate = input.getFileRate();
|
||||
Stk::setSampleRate( sampleRate ); // set a new STK sample rate based on the file rate
|
||||
\endcode
|
||||
|
||||
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:
|
||||
|
||||
\code
|
||||
Application initialization failed: this isn't a Tk applicationcouldn't connect to display ":0.0"
|
||||
\endcode
|
||||
|
||||
Simply start your X server and then try the command again.
|
||||
|
||||
*/
|
||||
@@ -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-2005 Perry R. Cook and Gary P. Scavone. All Rights Reserved.</td></tr>
|
||||
<tr><td>©1995-2007 Perry R. Cook and Gary P. Scavone. All Rights Reserved.</td></tr>
|
||||
</table>
|
||||
|
||||
</BODY>
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
/*! \page fundamentals STK Fundamentals
|
||||
|
||||
The Synthesis ToolKit is implemented in the C++ programming language. STK does not attempt to provide a new programming environment or paradigm but rather provides a set of objects which can be used within a normal C++ programming framework. Therefore, it is expected that users of STK will have some familiarity with C/C++ programming concepts. That said, the STK classes do have some particular idiosyncrasies that we will mention here.
|
||||
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.
|
||||
|
||||
\section Signal Computations:
|
||||
|
||||
@@ -25,7 +25,7 @@ int main()
|
||||
}
|
||||
\endcode
|
||||
|
||||
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.
|
||||
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 that can be used for vectorized computations, as shown in the next example.
|
||||
|
||||
\code
|
||||
#include "Noise.h"
|
||||
@@ -48,7 +48,7 @@ In this way, it might be possible to achieve improved processing efficiency usin
|
||||
|
||||
\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:
|
||||
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]
|
||||
|
||||
@@ -6,5 +6,5 @@
|
||||
<BODY BGCOLOR="#FFFFFF">
|
||||
<CENTER>
|
||||
<img src="princeton.gif"> <img src="ccrma.gif"> <img src="mcgill.gif"><P>
|
||||
<a class="qindex" href="index.html">Home</a> <a class="qindex" href="information.html">Information</a> <a class="qindex" href="classes.html">Classes</a> <a class="qindex" href="download.html">Download</a> <a class="qindex" href="usage.html">Usage</a> <a class="qindex" href="maillist.html">Mail List</a> <a class="qindex" href="system.html">Requirements</a> <a class="qindex" href="links.html">Links</a> <a class="qindex" href="tutorial.html">Tutorial</a></CENTER>
|
||||
<a class="qindex" href="index.html">Home</a> <a class="qindex" href="information.html">Information</a> <a class="qindex" href="classes.html">Classes</a> <a class="qindex" href="download.html">Download</a> <a class="qindex" href="usage.html">Usage</a> <a class="qindex" href="maillist.html">Mail List</a> <a class="qindex" href="system.html">Requirements</a> <a class="qindex" href="links.html">Links</a> <a class="qindex" href="faq.html">FAQ</a> <a class="qindex" href="tutorial.html">Tutorial</a></CENTER>
|
||||
<HR>
|
||||
|
||||
@@ -19,13 +19,13 @@
|
||||
\vspace*{1cm}
|
||||
{\large by Perry R. Cook and Gary P. Scavone}\\
|
||||
\vspace*{0.5cm}
|
||||
{\small \copyright 1995--2002}\\
|
||||
{\small \copyright 1995--2007}\\
|
||||
\end{center}
|
||||
\end{titlepage}
|
||||
\clearemptydoublepage
|
||||
\pagenumbering{roman}
|
||||
\rfoot[\fancyplain{}{\bfseries\scriptsize The Synthesis ToolKit in C++ by Perry R. Cook and Gary P. Scavone, \copyright~1995--2002}]{}
|
||||
\lfoot[]{\fancyplain{}{\bfseries\scriptsize The Synthesis ToolKit in C++ by Perry R. Cook and Gary P. Scavone, \copyright~1995--2002}}
|
||||
\rfoot[\fancyplain{}{\bfseries\scriptsize The Synthesis ToolKit in C++ by Perry R. Cook and Gary P. Scavone, \copyright~1995--2007}]{}
|
||||
\lfoot[]{\fancyplain{}{\bfseries\scriptsize The Synthesis ToolKit in C++ by Perry R. Cook and Gary P. Scavone, \copyright~1995--2007}}
|
||||
\tableofcontents
|
||||
\clearemptydoublepage
|
||||
\pagenumbering{arabic}
|
||||
|
||||
@@ -61,7 +61,7 @@ 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.
|
||||
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.
|
||||
|
||||
@@ -16,10 +16,10 @@ 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.
|
||||
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.
|
||||
|
||||
- \ref information
|
||||
- \ref classes
|
||||
@@ -28,6 +28,7 @@ other platforms and should work with any standard C++ compiler.
|
||||
- \ref maillist
|
||||
- \ref system
|
||||
- \ref links
|
||||
- \ref faq
|
||||
- \ref tutorial
|
||||
|
||||
*/
|
||||
|
||||
@@ -18,7 +18,7 @@ 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 SGI (Irix), Linux, Macintosh OS X, and Windows computer platforms. Generic, non-realtime support has been tested under NeXTStep, Sun, and other platforms and should work with any standard C++ compiler.
|
||||
The Synthesis ToolKit in C++ (STK) is a set of open source audio signal processing and algorithmic synthesis classes written in the C++ programming language. STK was designed to facilitate rapid development of music synthesis and audio processing software, with an emphasis on cross-platform functionality, realtime control, ease of use, and educational example code. The Synthesis ToolKit is extremely portable (it's mostly platform-independent C and C++ code), and it's completely user-extensible (all source included, no unusual libraries, and no hidden drivers). We like to think that this increases the chances that our programs will still work in another 5-10 years. In fact, the ToolKit has been working continuously for nearly 10 years now. STK currently runs with realtime support (audio and MIDI) on 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).
|
||||
|
||||
@@ -27,7 +27,7 @@ The Synthesis ToolKit is free for non-commercial use. The only parts of the Syn
|
||||
|
||||
The Synthesis Toolkit is not one particular program. Rather, it is a set of C++ classes that you can use to create your own programs. A few example applications are provided to demonstrate some of the ways to use the classes. If you have specific needs, you will probably have to either modify the example programs or write a new program altogether. Further, the example programs don't have a fancy GUI wrapper. It is easy to embed STK classes inside a GUI environment but we have chosen to focus our energy on the audio signal processing issues. Spending hundreds of hours making platform-dependent graphical user interfaces would go against one of the fundamental design goals of the ToolKit - platform independence.
|
||||
|
||||
For those instances where a simple GUI with sliders and buttons is helpful, we use <A HREF="http://dev.scriptics.com">Tcl/Tk</A> (which is freely distributed for all the supported ToolKit platforms). A number of Tcl/Tk GUI scripts are distributed with the ToolKit release. For control, the Synthesis Toolkit uses raw MIDI (on supported platforms), and SKINI (Synthesis ToolKit Instrument Network Interface, a MIDI-like text message synthesis control format).
|
||||
For those instances where a simple GUI with sliders and buttons is helpful, we use <A HREF="http://dev.scriptics.com">Tcl/Tk</A> (that is freely distributed for all the supported ToolKit platforms). A number of Tcl/Tk GUI scripts are distributed with the ToolKit release. For control, the Synthesis Toolkit uses raw MIDI (on supported platforms), and SKINI (Synthesis ToolKit Instrument Network Interface, a MIDI-like text message synthesis control format).
|
||||
|
||||
<H4>A brief history of the <I>Synthesis ToolKit in C++.</I></H4>
|
||||
|
||||
@@ -58,15 +58,49 @@ Stilson, Bill Putnam, and Gabriel Maldonado.
|
||||
|
||||
<H4>Legal and Ethical Notes</H4>
|
||||
|
||||
This software was designed and created to be made publicly available for free, primarily for academic purposes, so if you use it, pass it on with this documentation, and for free. If you make a million dollars with it, give us some. If you make compositions with it, put us in the program notes.
|
||||
<P>
|
||||
This software was designed and created to be made publicly available
|
||||
for free, primarily for academic purposes, so if you use it, pass it
|
||||
on with this documentation, and for free. If you make a million
|
||||
dollars with it, it would be nice if you would share. If you make
|
||||
compositions with it, put us in the program notes.
|
||||
|
||||
Some of the concepts are covered by various patents, some known to us and likely others which are unknown. Many of the ones known to us are administered by the Stanford Office of Technology and Licensing. The good news is that large hunks of the techniques used here are public domain. To avoid subtle legal issues, we will not state what's freely useable here, but we will try to note within the various classes where certain things are likely to be protected by patents.
|
||||
Some of the concepts are covered by various patents, some known to us
|
||||
and likely others that are unknown. Many of the ones known to us are
|
||||
administered by the Stanford Office of Technology and Licensing. The
|
||||
good news is that large hunks of the techniques used here are public
|
||||
domain. To avoid subtle legal issues, we will not state what's freely
|
||||
useable here, but we will try to note within the various classes where
|
||||
certain things are likely to be protected by patents.
|
||||
|
||||
<H4>License</H4>
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining
|
||||
a copy of this software and associated documentation files (the
|
||||
"Software"), to deal in the Software without restriction, including
|
||||
without limitation the rights to use, copy, modify, merge, publish,
|
||||
distribute, sublicense, and/or sell copies of the Software, and to
|
||||
permit persons to whom the Software is furnished to do so, subject to
|
||||
the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be
|
||||
included in all copies or substantial portions of the Software.
|
||||
|
||||
Any person wishing to distribute modifications to the Software is
|
||||
asked to send the modifications to the original developer so that they
|
||||
can be incorporated into the canonical version. This is, however, not
|
||||
a binding provision of this license.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
||||
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
||||
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
||||
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
|
||||
ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
|
||||
CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
||||
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
|
||||
<H4>Disclaimer</H4>
|
||||
|
||||
STK is free and we do not guarantee anything. We've been hacking on this code for a while now and most of it seems to work pretty well. But, there surely are some bugs floating around. Sometimes things work fine on one computer platform but not so fine on another. FPU overflows and underflows cause <I>very</I> weird behavior which also depends on the particular CPU and OS. Let us know about bugs you find and we'll do our best to correct them.
|
||||
STK is free and we do not guarantee anything. We've been hacking on this code for a while now and most of it seems to work pretty well. But, there surely are some bugs floating around. Sometimes things work fine on one computer platform but not so fine on another. FPU overflows and underflows cause <I>very</I> weird behavior that also depends on the particular CPU and OS. Let us know about bugs you find and we'll do our best to correct them.
|
||||
|
||||
<H4>Perry's Notes From the Original Distribution of STK</H4>
|
||||
|
||||
@@ -75,7 +109,7 @@ This whole world was created with no particular hardware in mind. These example
|
||||
Your question at this point might be, "But Perry, with CMix, CMusic, CSound, CShells, CMonkeys, etc. already cluttering the landscape, why a new set of stupid C functions for music synthesis and processing?" The answers lie below.
|
||||
|
||||
<ol>
|
||||
<li>I needed to port many of the things I've done into something which is generic enough to port further to different machines.</li>
|
||||
<li>I needed to port many of the things I've done into something that is generic enough to port further to different machines.</li>
|
||||
|
||||
<li>I really plan to document this stuff, so that you don't have to be me to figure out what's going on. (I'll probably be sorry I said this in a couple of years, when even I can't figure out what I was thinking.)</li>
|
||||
|
||||
|
||||
@@ -4,6 +4,10 @@
|
||||
|
||||
- <A HREF="http://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>
|
||||
|
||||
- <A HREF="http://sourceforge.net/projects/mobilestk">Mobile STK: A port of STK for mobile devices by Georg Essl and Michael Rohs</A>
|
||||
|
||||
- <A HREF="http://chuck.cs.princeton.edu/">ChucK: Concurrent, On-the-fly Audio Programming Language</A> using STK unit generators
|
||||
|
||||
- <A HREF="http://www.music.princeton.edu/paul/stkugens.tar.gz">Paul Lansky's port of STK to SuperCollider</A>
|
||||
|
||||
@@ -14,7 +14,7 @@ We have written this program to accept control messages from \c STDIN. Assuming
|
||||
threebees < scores/bachfugue.ski
|
||||
\endcode
|
||||
|
||||
For more fun, surf to <A HREF="http://kern.humdrum.net/">Kern Scores</A> for a huge assortment of other scorefiles which can be downloaded in the SKINI format.
|
||||
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.
|
||||
|
||||
|
||||
@@ -12,18 +12,24 @@ SineWave.h, is 2048 samples.
|
||||
|
||||
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.
|
||||
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
|
||||
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 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.
|
||||
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 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):
|
||||
|
||||
|
||||
@@ -9,13 +9,14 @@
|
||||
<B>Linux (specific):</B>
|
||||
<UL>
|
||||
<LI>A soundcard to use realtime audio input/output capabilities. In order to use the <I><B>effects</B></I> project, the soundcard and drivers must support full duplex mode.</LI>
|
||||
<LI><A HREF="http://www.alsa-project.org/">ALSA</A> device drivers and library for realtime sound and MIDI input/output. <A HREF="http://www.opensound.com">OSS</A> device drivers can be used for audio input/output, but MIDI support requires the ALSA library to compile.</LI>
|
||||
<LI><A HREF="http://www.alsa-project.org/">ALSA</A> device drivers and library for realtime sound and MIDI input/output.</LI>
|
||||
<LI><A HREF="http://www.opensound.com">OSS</A> device drivers (version 4.0 and higher only) can be used for audio input/output, but MIDI support requires the ALSA library to compile.</LI>
|
||||
</UL>
|
||||
|
||||
<B>Macintosh OS X (specific):</B>
|
||||
<UL>
|
||||
<LI>A C++ compiler does install by default with OS X. It is necessary to download the Developer Kit from the Apple WWW site in order to compile STK or load it from the installation CD-ROM.</LI>
|
||||
<LI><B>IMPORTANT:</B>The internal Macintosh audio hardware typically supports a sample rate of 44100 Hz only. The default STK sample rate is now 44100 Hz, but there may be programs which change that value before execution. Check the program code if you have sample rate conflicts. Many of the example project programs allow the sample rate to be specified via the command line.</LI>
|
||||
<LI><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>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.
|
||||
|
||||
@@ -27,7 +28,7 @@ It appears that socket support in Tcl/Tk uses the Nagle algorithm, which produce
|
||||
<UL>
|
||||
<LI>A soundcard to use realtime audio input/output capabilities. In order to use the <I><B>effects</B></I> project, the soundcard and drivers must support full duplex mode.</LI>
|
||||
<LI><A HREF="http://www.microsoft.com/directx/">DirectX</A> 5.0 (or higher) runtime libraries to use the precompiled binaries.</LI>
|
||||
<LI>Visual C++ 6.0 for compiling (though a precompiled distribution is available).</LI>
|
||||
<LI>Visual C++ .NET for compiling (though a precompiled distribution is available).</LI>
|
||||
<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>
|
||||
|
||||
|
||||
@@ -31,19 +31,19 @@ The top level distribution contains the following directories:
|
||||
This release of STK comes with four separate "project" directories:
|
||||
|
||||
<OL>
|
||||
<LI> The <I><B>demo</B></I> project is used to demonstrate nearly all of the STK instruments. The <I><B>demo</B></I> program has been written to allow a variety of control input and sound data output options. %Simple graphical user interfaces (GUIs) are also provided.<P></LI>
|
||||
<LI> The <I><B>demo</B></I> project is used to demonstrate nearly all of the STK instruments. The <I><B>demo</B></I> program has been written to allow a variety of control input and sound data output options. Simple graphical user interfaces (GUIs) are also provided.<P></LI>
|
||||
|
||||
<LI> The <I><B>effects</B></I> project demonstrates realtime duplex mode (simultaneous audio input and output) operation, when available, as well as various delay-line based effects algorithms.<P></LI>
|
||||
|
||||
<LI> The <I><B>ragamatic</B></I> project is just cool. Fire it up and be enlightened.<P></LI>
|
||||
|
||||
<LI> The <I><B>examples</B></I> project contains several simple programs which demonstrate audio input/output, including the audio internet streaming classes, as well as most of the tutorial programs.</LI>
|
||||
<LI> The <I><B>examples</B></I> project contains several simple programs that demonstrate audio input/output, including the audio internet streaming classes, as well as most of the tutorial programs.</LI>
|
||||
</OL>
|
||||
|
||||
\section compiling Compiling:
|
||||
|
||||
<UL>
|
||||
<LI><B>Windows95/98/2000/XP:</B> Realtime support is available using either DirectSound or ASIO audio drivers. For DirectSound support, use the <TT>__WINDOWS_DS__</TT> preprocessor definition and link with the <TT>dsound.lib</TT>, <TT>winmm.lib</TT>, and <TT>Wsock32.lib</TT> libraries. For ASIO support, use the <TT>__WINDOWS_ASIO__</TT> preprocessor definition, include all the files in the <TT>src/asio/</TT> directory (i.e. <TT>asio.h,cpp</TT>, <TT>asiodrivers.h,cpp</TT>, ...), and link with the <TT>winmm.lib</TT>, and <TT>Wsock32.lib</TT> libraries. In addition, the <TT>__LITTLE_ENDIAN__</TT> and <TT>__WINDOWS_MM__</TT> preprocessor definitions are necessary for all Windows systems (RtMidi uses the Windows MultiMedia MIDI API). A distribution of the release is available with precompiled binaries (using DirectSound) for all the projects. In order for these binaries to function properly, your system must have the DirectX 5.0 (or higher) runtime libraries installed (available from <A HREF="http://www.microsoft.com/directx/">Microsoft</A>). Further, the <I><B>effects</B></I> project requires that your soundcard and drivers provide full duplex mode capabilities. Visual C++ 6.0 project files are provided in each project directory as well should you wish to compile your own binaries. It is important to link with the non-debug libraries when compiling "release" program versions and debug libraries when compiling "debug" program versions.</LI>
|
||||
<LI><B>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>
|
||||
|
||||
@@ -54,8 +54,9 @@ Several options can be supplied to the <TT>configure</TT> script to customize th
|
||||
<LI><TT>--disable-realtime</TT> to only compile generic non-realtime classes</LI>
|
||||
<LI><TT>--enable-debug</TT> to enable various debug output</LI>
|
||||
<LI><TT>--with-alsa</TT> to choose native ALSA API support (default, linux only)</LI>
|
||||
<LI><TT>--with-jack</TT> to choose native JACK API support (linux only)</LI>
|
||||
<LI><TT>--with-oss</TT> to choose native OSS audio API support (linux only, no native OSS MIDI support)</LI>
|
||||
<LI><TT>--with-jack</TT> to choose native JACK API support (linux and Macintosh OS-X)</LI>
|
||||
<LI><TT>--with-core</TT> to choose Core Audio API support (Macintosh OS-X)</LI>
|
||||
</UL>
|
||||
<P>
|
||||
Note that it is possible to specify as many of the "--with-" options as desired to compile multi-API support. In addition, it is possible to specify the location of the STK rawwaves and the STK include path as follows:
|
||||
@@ -69,11 +70,9 @@ For novice STK users, the default configuration should be adequate.
|
||||
|
||||
For those who wish to create their own system-specific <TT>Makefiles</TT>:
|
||||
<UL>
|
||||
<LI><B>Linux:</B> Realtime audio support is enabled with either the <TT>__LINUX_ALSA__</TT>, <TT>__LINUX_JACK__</TT>, and/or <TT>__LINUX_OSS__</TT> preprocessor definitions, which are used to select the underlying audio system API(s). Because the ALSA library is now integrated into the standard Linux kernel, it is the default audio/MIDI API with STK versions 4.2 and higher. The <TT>__LINUX_ALSASEQ__</TT> preprocessor definition must be included for MIDI support. Note that native OSS MIDI support no longer exists in RtMidi. If the <TT>__LINUX_OSS__</TT> preprocessor definition is specified, only OSS audio support will be compiled and RtMidi will still be compiled using the ALSA API (assuming the <TT>__LINUX_ALSASEQ__</TT> definition is defined). For this reason, STK now requires the <TT>asound</TT> library for realtime support. Realtime programs must also link with the <TT>pthread</TT> library. In addition, the <TT>__LITTLE_ENDIAN__</TT> preprocessor definition is necessary if compiling on a little-endian system. See the README-Linux file for further system configuration information.</LI>
|
||||
<LI><B>Linux:</B> Realtime audio support is enabled with either the <TT>__LINUX_ALSA__</TT>, <TT>__UNIX_JACK__</TT>, and/or <TT>__LINUX_OSS__</TT> preprocessor definitions, which are used to select the underlying audio system API(s). Because the ALSA library is now integrated into the standard Linux kernel, it is the default audio/MIDI API with STK versions 4.2 and higher. The <TT>__LINUX_ALSASEQ__</TT> preprocessor definition must be included for MIDI support. Note that native OSS MIDI support no longer exists in RtMidi. If the <TT>__LINUX_OSS__</TT> preprocessor definition is specified, only OSS (version 4.0) audio support will be compiled and RtMidi will still be compiled using the ALSA API (assuming the <TT>__LINUX_ALSASEQ__</TT> definition is defined). For this reason, STK now requires the <TT>asound</TT> library for realtime support. Realtime programs must also link with the <TT>pthread</TT> library. In addition, the <TT>__LITTLE_ENDIAN__</TT> preprocessor definition is necessary if compiling on a little-endian system. See the README-Linux file for further system configuration information.</LI>
|
||||
|
||||
<LI><B>Macintosh OS X:</B> Realtime support is enabled with the <TT>__MACOSX_CORE__</TT> preprocessor definitions, which incorporates the CoreAudio audio/MIDI API. Realtime programs must also link with the <TT>pthread</TT> library and the <TT>CoreAudio</TT>, <TT>CoreMIDI</TT>, and <TT>CoreFoundation</TT> frameworks. See the README-MacOSX file for further system configuration information.</LI>
|
||||
|
||||
<LI><B>SGI:</B> Realtime audio and MIDI support is enabled with the <TT>__IRIX_AL__</TT> and <TT>__IRIX_MD__</TT> preprocessor definitions and linkage with the <TT>audio</TT>, <TT>md</TT>, and <TT>pthread</TT> libraries. STK 4.0 (and higher) is confirmed to compile using CC version 7.30. There may be problems with old compiler versions.</LI>
|
||||
<LI><B>Macintosh OS X:</B> Realtime support is enabled with the <TT>__MACOSX_CORE__</TT> and <TT>__UNIX_JACK__</TT> preprocessor definitions, which incorporate the CoreAudio audio/MIDI API and/or the JACK API. Realtime programs must also link with the <TT>pthread</TT> library and the <TT>CoreAudio</TT>, <TT>CoreMIDI</TT>, and <TT>CoreFoundation</TT> frameworks (for Core Audio support) and/or the JACK library. See the README-MacOSX file for further system configuration information.</LI>
|
||||
|
||||
<LI><B>Generic (non-realtime):</B> Most STK classes are operating system <I>independent</I> and can be compiled using any current C++ compiler. STK assumes big-endian host byte order by default, so if your system is little-endian (i.e. Intel processor), you must provide the <TT>__LITTLE_ENDIAN__</TT> preprocessor definition to your compiler. The <I><B>demo</B></I> project will compile without realtime support, allowing the use of SKINI scorefiles for input control and output to a variety of soundfile formats. The following classes <I>cannot</I> be used without realtime support: RtAudio, RtWvIn, RtWvOut, RtDuplex, RtMidi, Socket, Thread, Mutex, TcpWvIn, TcpWvOut. Because of this, it is not possible to compile the <I><B>effects</B></I>, <I><B>ragamatic</B></I>, and most of the <I><B>examples</B></I> projects for non-realtime use.</LI>
|
||||
</UL>
|
||||
@@ -90,7 +89,7 @@ All STK programs in this distribution take input control data in the form of <A
|
||||
<LI>Acquire realtime MIDI messages from a MIDI port on your computer.</LI>
|
||||
</OL>
|
||||
|
||||
<A HREF="http://dev.scriptics.com">Tcl/Tk</A> graphical user interfaces (GUI) are provided with this distribution which can generate realtime SKINI messages. Note that the Messager class allows multiple simultaneous socket client connections, together with MIDI and/or piped input. The <I><B>Md2Skini</B></I> program (in the <I><B>demo</B></I> directory) is mostly obsolete but can be used to create SKINI scorefiles from realtime MIDI input.
|
||||
<A HREF="http://dev.scriptics.com">Tcl/Tk</A> graphical user interfaces (GUI) are provided with this distribution that can generate realtime SKINI messages. Note that the Messager class allows multiple simultaneous socket client connections, together with MIDI and/or piped input. The <I><B>Md2Skini</B></I> program (in the <I><B>demo</B></I> directory) is mostly obsolete but can be used to create SKINI scorefiles from realtime MIDI input.
|
||||
|
||||
|
||||
\section voices Demo: STK Instruments
|
||||
@@ -99,7 +98,7 @@ The <I><B>demo</B></I> project demonstrates the behavior of all the distributed
|
||||
<UL>
|
||||
<LI>Clarinet: Pretty good physical model of the clarinet</LI>
|
||||
<LI>BlowHole: A clarinet physical model with one tonehole and one register vent</LI>
|
||||
<LI>Saxofony: A psuedo-conical bore reed instrument which sometimes sounds like a saxophone</LI>
|
||||
<LI>Saxofony: A psuedo-conical bore reed instrument that sometimes sounds like a saxophone</LI>
|
||||
<LI>Flute: Pretty good physical model of the flute</LI>
|
||||
<LI>Brass: Not so bad physical model of a brass instrument</LI>
|
||||
<LI>BlowBotl: A basic helmholtz resonator and air jet model</LI>
|
||||
@@ -141,7 +140,7 @@ from the <I><B>demo</B></I> directory will play the scorefile <I>bookert.ski</I>
|
||||
|
||||
\section rt Demo: Realtime Use
|
||||
|
||||
STK realtime audio and MIDI input/output and realtime SKINI control input via socketing support is provided for Linux, SGI, Mac OS X, and Windows95/98/2000/XP operating systems. STK realtime SKINI control input via piping is possible under Linux, SGI, Mac OS X, and Windows2000/XP only.
|
||||
STK realtime audio and MIDI input/output and realtime SKINI control input via socketing support is provided for Linux, Mac OS-X, and Windows95/98/2000/XP operating systems. STK realtime SKINI control input via piping is possible under Linux, Mac OS X, and Windows2000/XP only.
|
||||
<P>
|
||||
Control input and audio output options are typically specified as command-line arguments to STK programs. For example, the <I><B>demo</B></I> program is invoked as:
|
||||
|
||||
@@ -199,7 +198,7 @@ On all supported realtime platforms, you can direct realtime MIDI input to the S
|
||||
demo Clarinet -or -im
|
||||
\endcode
|
||||
|
||||
This will attempt to use the default MIDI port for input. An optional MIDI port number can be specified after the <TT>-im</TT> flag. Valid MIDI ports are numbered from 0 (default) and higher. On Linux and Macintosh OS-X systems, it is possible to open a virtual MIDI input port (which other software applications can connect to) by specifying a port identifier of -1.
|
||||
This will attempt to use the default MIDI port for input. An optional MIDI port number can be specified after the <TT>-im</TT> flag. Valid MIDI ports are numbered from 0 (default) and higher. On Linux and Macintosh OS-X systems, it is possible to open a virtual MIDI input port (that other software applications can connect to) by specifying a port identifier of -1.
|
||||
|
||||
\section polyphony Polyphony:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user