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

Release 4.1 tarball

Browse Source
This commit is contained in:
Gary Scavone
2013-09-29 23:35:44 +02:00
committed by Stephen Sinclair
parent 71e5c027fb
commit f25eb5c3d7
269 changed files with 12509 additions and 45583 deletions
Download Patch File Download Diff File Expand all files Collapse all files

155
doc/html/tutorial.html
View File

@@ -1,155 +0,0 @@
<HTML>
<HEAD>
<TITLE>The Synthesis ToolKit in C++ (STK)</TITLE>
<LINK HREF="doxygen.css" REL="stylesheet" TYPE="text/css">
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<CENTER>
<img src="princeton.gif"> &nbsp; <img src="ccrma.gif"><P>
<a class="qindex" href="index.html">Home</a> &nbsp; <a class="qindex" href="information.html">Information</a> &nbsp; <a class="qindex" href="classes.html">Classes</a> &nbsp; <a class="qindex" href="download.html">Download</a> &nbsp; <a class="qindex" href="usage.html">Usage</a> &nbsp; <a class="qindex" href="maillist.html">Mail List</a> &nbsp; <a class="qindex" href="system.html">Requirements</a> &nbsp; <a class="qindex" href="tutorial.html">Tutorial</a></CENTER>
<HR>
<!-- Generated by Doxygen 1.2.8.1 -->
<a name="tutorial"><h2>Tutorial</h2></a>
<ul>
<li><a href="tutorial.html#intro">Introduction</a><li><a href="tutorial.html#start">Getting Started</a><li><a href="tutorial.html#compile">Compiling</a><li><a href="tutorial.html#rtvsnonrt">"Realtime" vs. "Non-Realtime"</a></ul>
<a name="intro"><h2>Introduction</h2></a>
<p>
First and foremost, the Synthesis ToolKit is a set of C++ classes. That means you need to know some basics about programming in C++ to make use of STK (beyond the example programs we provide). STK's "target audience" is people who: <ul>
<li>already know how to program in C and C++ <li>want to create audio DSP and/or synthesis programs <li>want to save some time by using our unit generators and input/output routines <li>know C, but want to learn about synthesis and processing algorithms <li>wish to teach real-time synthesis and processing, and wish to use some of our classes and examples </ul>
<p>
Most ToolKit programmers will likely end up writing a class or two for their own particular needs, but this task is typically simplified by making use of pre-existing STK classes (filters, oscillators, etc.).
<p>
<a name="start"><h2>Getting Started</h2></a>
<p>
We'll begin our introduction to the Synthesis ToolKit with a simple sine-wave oscillator program. STK doesn't provide a specific oscillator for sine waves. Instead, it provides a generic waveform oscillator class, <a class="el" href="classWaveLoop.html">WaveLoop</a>, which can load a variety of common file types. In this example, we load a sine "table" from an STK RAW file. The class <a class="el" href="classRtWvOut.html">RtWvOut</a> will send "realtime" samples to the audio output hardware on your computer.
<p>
<div class="fragment"><pre><font class="comment">// sineosc.cpp</font>
<font class="preprocessor">#include "WaveLoop.h"</font>
<font class="preprocessor">#include "RtWvOut.h"</font>
<font class="keywordtype">int</font> main()<font class="keyword"></font>
<font class="keyword"></font>{
<font class="comment">// Set the global sample rate before creating class instances.</font>
<a class="code" href="classStk.html#d1">Stk::setSampleRate</a>( 44100.0 );
<font class="comment">// Define and load the sine wave file</font>
<a class="code" href="classWaveLoop.html">WaveLoop</a> *input = <font class="keyword">new</font> WaveLoop(<font class="stringliteral">"sinewave.raw"</font>, TRUE);
input-&gt;<a class="code" href="classWaveLoop.html#a2">setFrequency</a>(440.0);
<font class="comment">// Define and open the default realtime output device for one-channel playback</font>
<a class="code" href="classRtWvOut.html">RtWvOut</a> *output = <font class="keyword">new</font> RtWvOut(1);
<font class="comment">// Play the oscillator for 40000 samples</font>
<font class="keywordflow">for</font> (<font class="keywordtype">int</font> i=0; i&lt;40000; i++) {
output-&gt;<a class="code" href="classRtWvOut.html#a6">tick</a>( input-&gt;<a class="code" href="classWvIn.html#a16">tick</a>() );
}
<font class="comment">// Clean up</font>
<font class="keyword">delete</font> input;
<font class="keyword">delete</font> output;
<font class="keywordflow">return</font> 0;
}</pre></div>
<p>
<a class="el" href="classWaveLoop.html">WaveLoop</a> is a subclass of <a class="el" href="classWvIn.html">WvIn</a>, 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. <a class="el" href="classWvIn.html">WvIn</a> provides interpolating, read once ("oneshot") functionality, as well as methods for setting the read rate and read position.
<p>
Nearly all STK classes implement tick() methods which take and/or return sample values. Within the tick() method, the fundamental sample calculations are performed for a given class. Most STK classes consume/generate a single sample per operation and their tick() method takes/returns each sample "by value". In addition, every class implementing a tick() method also provides an overloaded tick() function taking pointer and size arguments which can be used for vectorized computations.
<p>
The <a class="el" href="classWvIn.html">WvIn</a> and <a class="el" href="classWvOut.html">WvOut</a> classes support multi-channel sample frames. To distinguish single-sample frame operations from multi-channel frame operations, these classes also implement tickFrame() functions. When a tick() method is called for multi-channel data, frame averages are returned or the input sample is distributed across all channels of a sample frame.
<p>
Nearly all STK classes inherit from the <a class="el" href="classStk.html">Stk</a> base class. <a class="el" href="classStk.html">Stk</a> provides a static sample rate which is queried by subclasses as needed. Because many classes use the current sample rate value during instantiation, it is important that the desired value be set at the beginning of a program. The default STK sample rate is 22050 Hz.
<p>
Another primary concept that is somewhat obscurred in this example concerns the data format in which sample values are passed and received. Audio and control signals throughout STK use a floating-point data type, the exact precision of which can be controlled via the MY_FLOAT #define statement in Stk.h. Thus, the ToolKit can use any normalization scheme desired. The base instruments and algorithms are implemented with a general audio sample dynamic maximum of +/-1.0, and the <a class="el" href="classWvIn.html">WvIn</a> and <a class="el" href="classWvOut.html">WvOut</a> classes and subclasses scale appropriately for DAC or soundfile input and output.
<p>
Finally, STK has some basic C++ error handling functionality built in. Classes which access files and/or hardware are most prone to runtime errors. To properly "catch" such errors, the above example should be rewritten as shown below.
<p>
<div class="fragment"><pre><font class="comment">// sineosc.cpp</font>
<font class="preprocessor">#include "WaveLoop.h"</font>
<font class="preprocessor">#include "RtWvOut.h"</font>
<font class="keywordtype">int</font> main()<font class="keyword"></font>
<font class="keyword"></font>{
<font class="comment">// Set the global sample rate before creating class instances.</font>
<a class="code" href="classStk.html#d1">Stk::setSampleRate</a>( 44100.0 );
<a class="code" href="classWaveLoop.html">WaveLoop</a> *input = 0;
<a class="code" href="classRtWvOut.html">RtWvOut</a> *output = 0;
<font class="keywordflow">try</font> {
<font class="comment">// Define and load the sine wave file</font>
input = <font class="keyword">new</font> WaveLoop( <font class="stringliteral">"sinewave.raw"</font>, TRUE );
<font class="comment">// Define and open the default realtime output device for one-channel playback</font>
output = <font class="keyword">new</font> RtWvOut(1);
}
<font class="keywordflow">catch</font> (<a class="code" href="classStkError.html">StkError</a> &amp;) {
<font class="keywordflow">goto</font> cleanup;
}
input-&gt;<a class="code" href="classWaveLoop.html#a2">setFrequency</a>(440.0);
<font class="comment">// Play the oscillator for 40000 samples</font>
<font class="keywordflow">for</font> (<font class="keywordtype">int</font> i=0; i&lt;40000; i++) {
<font class="keywordflow">try</font> {
output-&gt;<a class="code" href="classRtWvOut.html#a6">tick</a>(input-&gt;<a class="code" href="classWvIn.html#a16">tick</a>());
}
<font class="keywordflow">catch</font> (<a class="code" href="classStkError.html">StkError</a> &amp;) {
<font class="keywordflow">goto</font> cleanup;
}
}
cleanup:
<font class="keyword">delete</font> input;
<font class="keyword">delete</font> output;
<font class="keywordflow">return</font> 0;
}</pre></div>
<p>
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.
<p>
<a name="compile"><h2>Compiling</h2></a>
<p>
<a name="compileLinux"><h3>Linux</h3></a>
<p>
In general, you will probably want to use a <code>Makefile</code> for your STK programs and projects. For this particular program, however, the following will suffice (on a linux system): <div class="fragment"><pre>g++ -Wall -D__LINUX_OSS__ -D__LITTLE_ENDIAN__ -o sineosc <a class="code" href="classStk.html">Stk</a>.cpp <a class="code" href="classWvIn.html">WvIn</a>.cpp <a class="code" href="classWaveLoop.html">WaveLoop</a>.cpp <a class="code" href="classWvOut.html">WvOut</a>.cpp <a class="code" href="classRtWvOut.html">RtWvOut</a>.cpp RtAudio.cpp sineosc.cpp -lpthread</pre></div>
<p>
This assumes you've set up a directory that includes the files <code>sineosc.cpp</code>, the rawwave file <code>sinewave.raw</code>, and the header and source files for the classes <a class="el" href="classStk.html">Stk</a>, <a class="el" href="classWvIn.html">WvIn</a>, <a class="el" href="classWaveLoop.html">WaveLoop</a>, <a class="el" href="classWvOut.html">WvOut</a>, <a class="el" href="classRtWvOut.html">RtWvOut</a>, and RtAudio. There are other, more convenient, means for structuring projects that will be discussed later.
<p>
Most linux systems currently come installed with the OSS audio hardware drivers. If your system instead has ALSA audio drivers installed and you wish to make use of native ALSA API calls, a link to the ALSA library must be specified in the above compile statement (<code>-lasound</code>) and the preprocessor definition should instead be <code>__LINUX_ALSA__</code>.
<p>
<a name="compileIrix"><h3>Irix</h3></a>
<p>
The irix (SGI) and linux operating systems are both flavors of unix and thus behave similarly. Making the same assumptions as in the linux case, the following compile statement should work: <div class="fragment"><pre>CC -Wall -D__IRIX_AL__ -o sineosc <a class="code" href="classStk.html">Stk</a>.cpp <a class="code" href="classWvIn.html">WvIn</a>.cpp <a class="code" href="classWaveLoop.html">WaveLoop</a>.cpp <a class="code" href="classWvOut.html">WvOut</a>.cpp <a class="code" href="classRtWvOut.html">RtWvOut</a>.cpp RtAudio.cpp sineosc.cpp -lpthread</pre></div>
<p>
<a name="compileWin"><h3>Windows</h3></a>
<p>
I have personally only worked with Visual C++ when compiling programs under windoze. I'll assume you've become familiar with Visual C+ and don't need a tutorial on its particular idiosyncrasies. In creating the VC++ project, add the <a class="el" href="classStk.html">Stk</a>, <a class="el" href="classWvIn.html">WvIn</a>, <a class="el" href="classWaveLoop.html">WaveLoop</a>, <a class="el" href="classWvOut.html">WvOut</a>, <a class="el" href="classRtWvOut.html">RtWvOut</a>, and RtAudio class files, as well as the <code>sineosc.cpp</code> and <code>sinewave.raw</code> files. You will also need to link to the DirectSound library (<code>dsound.lib</code>), select the multithreaded library, and provide the <code>__WINDOWS_DS__</code> and <code>__LITTLE_ENDIAN__</code> preprocessor definitions.
<p>
<a name="rtvsnonrt"><h2>"Realtime" vs. "Non-Realtime"</h2></a>
<p>
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) <em>dependent</em>. STK classes which require specific platform/OS support include RtAudio, <a class="el" href="classRtWvOut.html">RtWvOut</a>, <a class="el" href="classRtWvIn.html">RtWvIn</a>, <a class="el" href="classRtDuplex.html">RtDuplex</a>, <a class="el" href="classRtMidi.html">RtMidi</a>, <a class="el" href="classTcpWvIn.html">TcpWvIn</a>, <a class="el" href="classTcpWvOut.html">TcpWvOut</a>, <a class="el" href="classSocket.html">Socket</a>, and <a class="el" href="classThread.html">Thread</a>. These classes currently can only be compiled on Linux, Irix, and Windows (except Windows NT) systems using the <code>__LINUX_OSS__</code>, <code>__LINUX_ALSA__</code>, <code>__IRIX_AL__</code>, or <code>__WINDOWS_DS__</code> preprocessor definitions.
<p>
Without the "realtime" classes, it is still possible to read <a class="el" href="classSKINI.html">SKINI</a> scorefiles for control input and to read and write to/from a variety of audio file formats (WAV, SND, AIFF, MAT-file, and RAW). If compiling for a "little-endian" host processor, the <code>__LITTLE_ENDIAN__</code> preprocessor definition should be provided.
<p>
<a name="continued"><h2>To Be Continued ...</h2></a>
<p>
<HR>
<table>
<tr><td><A HREF="http://www-ccrma.stanford.edu/software/stk/"><I>The Synthesis ToolKit in C++ (STK)</I></A></td></tr>
<tr><td>&copy;1995-2002 Perry R. Cook and Gary P. Scavone. All Rights Reserved.</td></tr>
</table>
</BODY>
</HTML>