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

Release 4.3.0 tarball

Browse Source
This commit is contained in:
Gary Scavone
2013-09-29 23:41:50 +02:00
committed by Stephen Sinclair
parent 554a74374b
commit 1a8403e203
462 changed files with 4751 additions and 3397 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
doc/html/usage.html
View File

@@ -6,7 +6,7 @@
<BODY BGCOLOR="#FFFFFF">
<CENTER>
<img src="princeton.gif"> &nbsp; <img src="ccrma.gif"> &nbsp; <img src="mcgill.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="links.html">Links</a> &nbsp; <a class="qindex" href="tutorial.html">Tutorial</a></CENTER>
<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="links.html">Links</a> &nbsp; <a class="qindex" href="faq.html">FAQ</a> &nbsp; <a class="qindex" href="tutorial.html">Tutorial</a></CENTER>
<HR>
<!-- Generated by Doxygen 1.4.4 -->
<h1><a class="anchor" name="usage">Usage Documentation</a></h1><ul>
@@ -41,7 +41,7 @@ The <em><b>projects</b></em> directory contains various demo and example STK pro
This release of STK comes with four separate "project" directories:<p>
<ol>
<li>
The <em><b>demo</b></em> project is used to demonstrate nearly all of the STK instruments. The <em><b>demo</b></em> 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>
The <em><b>demo</b></em> project is used to demonstrate nearly all of the STK instruments. The <em><b>demo</b></em> program has been written to allow a variety of control input and sound data output options. <a class="el" href="classSimple.html">Simple</a> graphical user interfaces (GUIs) are also provided.<p>
<p>
</li>
<li>
@@ -53,13 +53,13 @@ The <em><b>ragamatic</b></em> project is just cool. Fire it up and be enlightene
<p>
</li>
<li>
The <em><b>examples</b></em> 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>
The <em><b>examples</b></em> 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>
<h2><a class="anchor" name="compiling">
Compiling:</a></h2>
<ul>
<li>
<b>Windows95/98/2000/XP:</b> Realtime support is available using either DirectSound or ASIO audio drivers. For DirectSound support, use the <code>__WINDOWS_DS__</code> preprocessor definition and link with the <code>dsound.lib</code>, <code>winmm.lib</code>, and <code>Wsock32.lib</code> libraries. For ASIO support, use the <code>__WINDOWS_ASIO__</code> preprocessor definition, include all the files in the <code>src/asio/</code> directory (i.e. <code>asio.h,cpp</code>, <code>asiodrivers.h,cpp</code>, ...), and link with the <code>winmm.lib</code>, and <code>Wsock32.lib</code> libraries. In addition, the <code>__LITTLE_ENDIAN__</code> and <code>__WINDOWS_MM__</code> preprocessor definitions are necessary for all Windows systems (<a class="el" href="classRtMidi.html">RtMidi</a> 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 <em><b>effects</b></em> 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.<p>
<b>Windows95/98/2000/XP:</b> Realtime support is available using either DirectSound or ASIO audio drivers. For DirectSound support, use the <code>__WINDOWS_DS__</code> preprocessor definition and link with the <code>dsound.lib</code>, <code>winmm.lib</code>, and <code>Wsock32.lib</code> libraries. For ASIO support, use the <code>__WINDOWS_ASIO__</code> preprocessor definition, include all the files in the <code>src/asio/</code> directory (i.e. <code>asio.h,cpp</code>, <code>asiodrivers.h,cpp</code>, ...), and link with the <code>winmm.lib</code>, and <code>Wsock32.lib</code> libraries. In addition, the <code>__LITTLE_ENDIAN__</code> and <code>__WINDOWS_MM__</code> preprocessor definitions are necessary for all Windows systems (<a class="el" href="classRtMidi.html">RtMidi</a> 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 <em><b>effects</b></em> 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.<p>
</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.<p>
@@ -74,9 +74,11 @@ Several options can be supplied to the <code>configure</code> script to customiz
<li>
<code>--with-alsa</code> to choose native ALSA API support (default, linux only) </li>
<li>
<code>--with-jack</code> to choose native JACK API support (linux only) </li>
<li>
<code>--with-oss</code> to choose native OSS audio API support (linux only, no native OSS MIDI support) </li>
<li>
<code>--with-jack</code> to choose native JACK API support (linux and Macintosh OS-X) </li>
<li>
<code>--with-core</code> 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: <div class="fragment"><pre class="fragment">./configure RAWWAVE_PATH=<span class="stringliteral">"/home/gary/rawwaves/"</span>
@@ -87,16 +89,13 @@ For novice STK users, the default configuration should be adequate. </li>
<p>
For those who wish to create their own system-specific <code>Makefiles</code>: <ul>
<li>
<b>Linux:</b> Realtime audio support is enabled with either the <code>__LINUX_ALSA__</code>, <code>__LINUX_JACK__</code>, and/or <code>__LINUX_OSS__</code> 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 <code>__LINUX_ALSASEQ__</code> preprocessor definition must be included for MIDI support. Note that native OSS MIDI support no longer exists in <a class="el" href="classRtMidi.html">RtMidi</a>. If the <code>__LINUX_OSS__</code> preprocessor definition is specified, only OSS audio support will be compiled and <a class="el" href="classRtMidi.html">RtMidi</a> will still be compiled using the ALSA API (assuming the <code>__LINUX_ALSASEQ__</code> definition is defined). For this reason, STK now requires the <code>asound</code> library for realtime support. Realtime programs must also link with the <code>pthread</code> library. In addition, the <code>__LITTLE_ENDIAN__</code> preprocessor definition is necessary if compiling on a little-endian system. See the README-Linux file for further system configuration information.<p>
<b>Linux:</b> Realtime audio support is enabled with either the <code>__LINUX_ALSA__</code>, <code>__UNIX_JACK__</code>, and/or <code>__LINUX_OSS__</code> 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 <code>__LINUX_ALSASEQ__</code> preprocessor definition must be included for MIDI support. Note that native OSS MIDI support no longer exists in <a class="el" href="classRtMidi.html">RtMidi</a>. If the <code>__LINUX_OSS__</code> preprocessor definition is specified, only OSS (version 4.0) audio support will be compiled and <a class="el" href="classRtMidi.html">RtMidi</a> will still be compiled using the ALSA API (assuming the <code>__LINUX_ALSASEQ__</code> definition is defined). For this reason, STK now requires the <code>asound</code> library for realtime support. Realtime programs must also link with the <code>pthread</code> library. In addition, the <code>__LITTLE_ENDIAN__</code> preprocessor definition is necessary if compiling on a little-endian system. See the README-Linux file for further system configuration information.<p>
</li>
<li>
<b>Macintosh OS X:</b> Realtime support is enabled with the <code>__MACOSX_CORE__</code> preprocessor definitions, which incorporates the CoreAudio audio/MIDI API. Realtime programs must also link with the <code>pthread</code> library and the <code>CoreAudio</code>, <code>CoreMIDI</code>, and <code>CoreFoundation</code> frameworks. See the README-MacOSX file for further system configuration information.<p>
<b>Macintosh OS X:</b> Realtime support is enabled with the <code>__MACOSX_CORE__</code> and <code>__UNIX_JACK__</code> preprocessor definitions, which incorporate the CoreAudio audio/MIDI API and/or the JACK API. Realtime programs must also link with the <code>pthread</code> library and the <code>CoreAudio</code>, <code>CoreMIDI</code>, and <code>CoreFoundation</code> frameworks (for Core Audio support) and/or the JACK library. See the README-MacOSX file for further system configuration information.<p>
</li>
<li>
<b>SGI:</b> Realtime audio and MIDI support is enabled with the <code>__IRIX_AL__</code> and <code>__IRIX_MD__</code> preprocessor definitions and linkage with the <code>audio</code>, <code>md</code>, and <code>pthread</code> libraries. STK 4.0 (and higher) is confirmed to compile using CC version 7.30. There may be problems with old compiler versions.<p>
</li>
<li>
<b>Generic (non-realtime):</b> Most STK classes are operating system <em>independent</em> 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 <code>__LITTLE_ENDIAN__</code> preprocessor definition to your compiler. The <em><b>demo</b></em> 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 <em>cannot</em> be used without realtime support: <a class="el" href="classRtAudio.html">RtAudio</a>, <a class="el" href="classRtWvIn.html">RtWvIn</a>, <a class="el" href="classRtWvOut.html">RtWvOut</a>, <a class="el" href="classRtDuplex.html">RtDuplex</a>, <a class="el" href="classRtMidi.html">RtMidi</a>, <a class="el" href="classSocket.html">Socket</a>, <a class="el" href="classThread.html">Thread</a>, <a class="el" href="classMutex.html">Mutex</a>, TcpWvIn, TcpWvOut. Because of this, it is not possible to compile the <em><b>effects</b></em>, <em><b>ragamatic</b></em>, and most of the <em><b>examples</b></em> projects for non-realtime use. </li>
<b>Generic (non-realtime):</b> Most STK classes are operating system <em>independent</em> 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 <code>__LITTLE_ENDIAN__</code> preprocessor definition to your compiler. The <em><b>demo</b></em> 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 <em>cannot</em> be used without realtime support: <a class="el" href="classRtAudio.html">RtAudio</a>, <a class="el" href="classRtWvIn.html">RtWvIn</a>, <a class="el" href="classRtWvOut.html">RtWvOut</a>, RtDuplex, <a class="el" href="classRtMidi.html">RtMidi</a>, <a class="el" href="classSocket.html">Socket</a>, <a class="el" href="classThread.html">Thread</a>, <a class="el" href="classMutex.html">Mutex</a>, TcpWvIn, TcpWvOut. Because of this, it is not possible to compile the <em><b>effects</b></em>, <em><b>ragamatic</b></em>, and most of the <em><b>examples</b></em> projects for non-realtime use. </li>
</ul>
<h2><a class="anchor" name="control">
Control Data:</a></h2>
@@ -112,7 +111,7 @@ Pipe realtime SKINI input messages to an executable (not possible under Windows9
Acquire realtime MIDI messages from a MIDI port on your computer. </li>
</ol>
<p>
<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 <a class="el" href="classMessager.html">Messager</a> class allows multiple simultaneous socket client connections, together with MIDI and/or piped input. The <em><b>Md2Skini</b></em> program (in the <em><b>demo</b></em> directory) is mostly obsolete but can be used to create SKINI scorefiles from realtime MIDI input.<h2><a class="anchor" name="voices">
<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 <a class="el" href="classMessager.html">Messager</a> class allows multiple simultaneous socket client connections, together with MIDI and/or piped input. The <em><b>Md2Skini</b></em> program (in the <em><b>demo</b></em> directory) is mostly obsolete but can be used to create SKINI scorefiles from realtime MIDI input.<h2><a class="anchor" name="voices">
Demo: STK Instruments</a></h2>
The <em><b>demo</b></em> project demonstrates the behavior of all the distributed STK instruments. The instruments available with this release include: <ul>
<li>
@@ -120,7 +119,7 @@ The <em><b>demo</b></em> project demonstrates the behavior of all the distribute
<li>
<a class="el" href="classBlowHole.html">BlowHole</a>: A clarinet physical model with one tonehole and one register vent </li>
<li>
<a class="el" href="classSaxofony.html">Saxofony</a>: A psuedo-conical bore reed instrument which sometimes sounds like a saxophone </li>
<a class="el" href="classSaxofony.html">Saxofony</a>: A psuedo-conical bore reed instrument that sometimes sounds like a saxophone </li>
<li>
<a class="el" href="classFlute.html">Flute</a>: Pretty good physical model of the flute </li>
<li>
@@ -178,7 +177,7 @@ In non-realtime mode, it is assumed that input control messages are provided fro
</pre></div><p>
from the <em><b>demo</b></em> directory will play the scorefile <em>bookert.ski</em> using the STK <a class="el" href="classBeeThree.html">BeeThree</a> instrument and write the resulting audio data to a WAV formatted soundfile called "myfile.wav" (note that you may need to append <code>./</code> to the program name if your default shell setup is not set to look in the current directory). Typing <code>demo</code> without any arguments will provide a full program usage description.<h2><a class="anchor" name="rt">
Demo: Realtime Use</a></h2>
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. <p>
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 <em><b>demo</b></em> program is invoked as:<p>
<div class="fragment"><pre class="fragment">demo instrument flags
</pre></div><p>
@@ -227,7 +226,7 @@ Realtime MIDI Control Input:</a></h2>
On all supported realtime platforms, you can direct realtime MIDI input to the STK <a class="el" href="classClarinet.html">Clarinet</a> by typing:<p>
<div class="fragment"><pre class="fragment">demo <a class="code" href="classClarinet.html">Clarinet</a> -or -im
</pre></div><p>
This will attempt to use the default MIDI port for input. An optional MIDI port number can be specified after the <code>-im</code> 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.<h2><a class="anchor" name="polyphony">
This will attempt to use the default MIDI port for input. An optional MIDI port number can be specified after the <code>-im</code> 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.<h2><a class="anchor" name="polyphony">
Polyphony:</a></h2>
The <em><b>demo</b></em> program supports an arbitrary number of voices via the <code>-n NUMBER</code> command-line flag and argument. For example, you can play eight <a class="el" href="classBeeThree.html">BeeThree</a> instruments with realtime output and control them from a MIDI device by typing:<p>
<div class="fragment"><pre class="fragment">demo <a class="code" href="classBeeThree.html">BeeThree</a> -n 8 -or -im
@@ -235,7 +234,7 @@ The <em><b>demo</b></em> program supports an arbitrary number of voices via the
<table>
<tr><td><A HREF="http://ccrma.stanford.edu/software/stk/"><I>The Synthesis ToolKit in C++ (STK)</I></A></td></tr>
<tr><td>&copy;1995-2005 Perry R. Cook and Gary P. Scavone. All Rights Reserved.</td></tr>
<tr><td>&copy;1995-2007 Perry R. Cook and Gary P. Scavone. All Rights Reserved.</td></tr>
</table>
</BODY>