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

Version 4.0

Browse Source
This commit is contained in:
Gary Scavone
2013-09-25 14:50:19 +02:00
committed by Stephen Sinclair
parent 3f126af4e5
commit 81475b04c5
473 changed files with 36355 additions and 28396 deletions
Download Patch File Download Diff File Expand all files Collapse all files

155
doc/doxygen/Doxyfile Normal file
View File

@@ -0,0 +1,155 @@
# Doxyfile 1.2.6
#---------------------------------------------------------------------------
# General configuration options
#---------------------------------------------------------------------------
PROJECT_NAME = STK
PROJECT_NUMBER =
OUTPUT_DIRECTORY = .
OUTPUT_LANGUAGE = English
EXTRACT_ALL = NO
EXTRACT_PRIVATE = NO
EXTRACT_STATIC = YES
HIDE_UNDOC_MEMBERS = YES
HIDE_UNDOC_CLASSES = YES
BRIEF_MEMBER_DESC = YES
REPEAT_BRIEF = YES
ALWAYS_DETAILED_SEC = NO
FULL_PATH_NAMES = NO
STRIP_FROM_PATH =
INTERNAL_DOCS = NO
CLASS_DIAGRAMS = YES
SOURCE_BROWSER = NO
INLINE_SOURCES = NO
STRIP_CODE_COMMENTS = YES
CASE_SENSE_NAMES = YES
HIDE_SCOPE_NAMES = NO
VERBATIM_HEADERS = YES
SHOW_INCLUDE_FILES = YES
JAVADOC_AUTOBRIEF = NO
INHERIT_DOCS = YES
INLINE_INFO = YES
SORT_MEMBER_DOCS = NO
DISTRIBUTE_GROUP_DOC = NO
TAB_SIZE = 8
ENABLED_SECTIONS =
GENERATE_TODOLIST = YES
GENERATE_TESTLIST = YES
GENERATE_BUGLIST = YES
ALIASES =
MAX_INITIALIZER_LINES = 30
OPTIMIZE_OUTPUT_FOR_C = NO
SHOW_USED_FILES = YES
#---------------------------------------------------------------------------
# configuration options related to warning and progress messages
#---------------------------------------------------------------------------
QUIET = NO
WARNINGS = YES
WARN_IF_UNDOCUMENTED = YES
WARN_FORMAT = "$file:$line: $text"
WARN_LOGFILE =
#---------------------------------------------------------------------------
# configuration options related to the input files
#---------------------------------------------------------------------------
INPUT = index.txt information.txt classes.txt download.txt usage.txt maillist.txt system.txt tutorial.txt skini.txt ../../include/
FILE_PATTERNS = *.h
RECURSIVE = NO
EXCLUDE =
EXCLUDE_PATTERNS =
EXAMPLE_PATH =
EXAMPLE_PATTERNS =
IMAGE_PATH =
INPUT_FILTER =
FILTER_SOURCE_FILES = NO
#---------------------------------------------------------------------------
# configuration options related to the alphabetical class index
#---------------------------------------------------------------------------
ALPHABETICAL_INDEX = NO
COLS_IN_ALPHA_INDEX = 5
IGNORE_PREFIX =
#---------------------------------------------------------------------------
# configuration options related to the HTML output
#---------------------------------------------------------------------------
GENERATE_HTML = YES
HTML_OUTPUT = ../html
HTML_HEADER = header.html
HTML_FOOTER = footer.html
HTML_STYLESHEET =
HTML_ALIGN_MEMBERS = YES
GENERATE_HTMLHELP = NO
GENERATE_CHI = NO
BINARY_TOC = NO
TOC_EXPAND = NO
DISABLE_INDEX = YES
ENUM_VALUES_PER_LINE = 4
GENERATE_TREEVIEW = NO
TREEVIEW_WIDTH = 250
#---------------------------------------------------------------------------
# configuration options related to the LaTeX output
#---------------------------------------------------------------------------
GENERATE_LATEX = YES
LATEX_OUTPUT = latex
COMPACT_LATEX = NO
PAPER_TYPE = letter
EXTRA_PACKAGES =
LATEX_HEADER = header.tex
PDF_HYPERLINKS = YES
USE_PDFLATEX = YES
LATEX_BATCHMODE = NO
#---------------------------------------------------------------------------
# configuration options related to the RTF output
#---------------------------------------------------------------------------
GENERATE_RTF = NO
RTF_OUTPUT = rtf
COMPACT_RTF = NO
RTF_HYPERLINKS = NO
RTF_STYLESHEET_FILE =
#---------------------------------------------------------------------------
# configuration options related to the man page output
#---------------------------------------------------------------------------
GENERATE_MAN = NO
MAN_OUTPUT = man
MAN_EXTENSION = .3
#---------------------------------------------------------------------------
# Configuration options related to the preprocessor
#---------------------------------------------------------------------------
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = NO
EXPAND_ONLY_PREDEF = NO
SEARCH_INCLUDES = YES
INCLUDE_PATH =
INCLUDE_FILE_PATTERNS =
PREDEFINED =
EXPAND_AS_DEFINED =
#---------------------------------------------------------------------------
# Configuration::addtions related to external references
#---------------------------------------------------------------------------
TAGFILES =
GENERATE_TAGFILE =
ALLEXTERNALS = NO
PERL_PATH = /usr/bin/perl
#---------------------------------------------------------------------------
# Configuration options related to the dot tool
#---------------------------------------------------------------------------
HAVE_DOT = NO
CLASS_GRAPH = YES
COLLABORATION_GRAPH = YES
INCLUDE_GRAPH = YES
INCLUDED_BY_GRAPH = YES
GRAPHICAL_HIERARCHY = YES
DOT_PATH =
MAX_DOT_GRAPH_WIDTH = 1024
MAX_DOT_GRAPH_HEIGHT = 1024
GENERATE_LEGEND = YES
DOT_CLEANUP = YES
#---------------------------------------------------------------------------
# Configuration::addtions related to the search engine
#---------------------------------------------------------------------------
SEARCHENGINE = NO
CGI_NAME = search.cgi
CGI_URL =
DOC_URL =
DOC_ABSPATH =
BIN_ABSPATH = /usr/local/bin/
EXT_DOC_PATHS =

10
doc/doxygen/classes.txt Normal file
View File

@@ -0,0 +1,10 @@
/*! \page classes Class Documentation
<UL>
<LI><a class="qindex" href="hierarchy.html">Class Hierarchy</a></LI>
<LI><a class="qindex" href="annotated.html">Class/Enum List</a></LI>
<LI><a class="qindex" href="files.html">File List</a></LI>
<LI><a class="qindex" href="functions.html">Compound Members</a></LI>
</UL>
*/

115
doc/doxygen/download.txt Normal file
View File

@@ -0,0 +1,115 @@
/*! \page download Download and Release Notes
<B>Version 4.0, 30 April 2002</B><P>
<A HREF="Release/stk-4.0.tar.gz">STK Version 4.0: Source distribution</A> (1.64 MB tar/gzipped)<BR>
<A HREF="Release/stk-4.0.binaries.tar.gz">STK Version 4.0: Source distribution with precompiled windows binaries</A> (2.26 MB tar/gzipped)<BR>
<P>
\section notes Release Notes:
\subsection v4 Version 4.0
<UL>
<LI>New documentation and tutorial.</LI>
<LI>Several new instruments, including Saxofony, BlowBotl, and StifKarp.</LI>
<LI>New Stk base class, replacing Object class.</LI>
<LI>New Filter class structure and methods.</LI>
<LI>Extensive modifications to WvIn and WvOut class structures and methods.</LI>
<LI>Looping functionality moved to WaveLoop (subclass of WvIn).</LI>
<LI>Automatic file type detection in WvIn ... hosed WavWvIn, AifWvIn, RawWavIn, SndWavIn, and MatWvIn subclasses.</LI>
<LI>New file type specifier argument in WvOut ... hosed WavWvOut, AifWvOut, RawWavOut, SndWavOut, and MatWvOut subclasses.</LI>
<LI>Some simplifications of Messager class (was Controller).</LI>
<LI>New independent RtAudio class.</LI>
<LI>Extensive revisions in code and a significant number of API changes.</LI>
</UL>
\subsection v3dot2 Version 3.2
<UL>
<LI>New input control handling class (Controller)</LI>
<LI>Added AIFF file input/output support.</LI>
<LI>New C++ error handling capabilities.</LI>
<LI>New input/output internet streaming support (StrmWvIn/StrmWvOut).</LI>
<LI>Added native ALSA support for linux.</LI>
<LI>Added optional "device" argument to all "Rt" classes (audio and MIDI) and printout of devices when argument is invalid.</LI>
<LI>WvIn classes rewritten to support very big files (incremental load from disk).</LI>
<LI>Changed WvIn/WvOut classes to work with sample frame buffers.</LI>
<LI>Fixed looping and negative rate calculations in WvIn classes.</LI>
<LI>Fixed interpolation bug in RtWvIn.</LI>
<LI>Windoze RtAudio code rewritten (thank Dave!).</LI>
<LI>Simplified byte-swapping functions (in-place swapping).</LI>
<LI>"Stereo-ized" RagaMatic.</LI>
<LI>Miscellaneous renamings.</LI>
<LI>Probably a bunch more fixes that I've long since forgotten about.</LI>
</UL>
\subsection v3dot1 Version 3.1
<UL>
<LI>New RagaMatic project ... very cool!!!</LI>
<LI>Less clipping in the Shakers class.</LI>
<LI>Added "microphone position" to Mandolin in STKdemo.</LI>
<LI>Fixed MIDI system message exclusion under Irix.</LI>
<LI>Added a few bitmaps for the Shaker instruments.</LI>
<LI>Made destructors virtual for Reverb.h, WvIn.h and Simple.h.</LI>
<LI>Fixed bug setting delay length in DLineA when value too big.</LI>
<LI>Fixed bug in WinMM realtime code (RTSoundIO).</LI>
<LI>Added tick() method to BowTabl, JetTabl, and ReedTabl (same as lookup).</LI>
<LI>Switched to pthread API on SGI platforms.</LI>
<LI>Added some defines to Object.h for random number generation, FPU overflow checking, etc....</LI>
<LI>A few minor changes, some bug fixes ... can't remember all of them.</LI>
</UL>
\subsection v3 Version 3.0
<UL>
<LI>New #define flags for OS and realtime dependencies (this will probably cause problems for old personal STK code, but it was necessary to make future ports easier).</LI>
<LI>Expanded and cleaned the Shakers class.</LI>
<LI>New BowedBar algorithm/class.</LI>
<LI>Fixed Linux MIDI input bug.</LI>
<LI>Fixed MIDI status masking problem in Windows.</LI>
<LI>OS type defines now in Makefile.</LI>
<LI>New RAWWAVE_PATH define in Object.h.</LI>
<LI>Syntmono project pulled out to separate directory and cleaned up.</LI>
<LI>Socketing capabilities under Unix, as well as Windoze.</LI>
<LI>Multiple simultaneous socket client connections to STK servers now possible.</LI>
<LI>MD2SKINI now can merge MIDI and piped messages under Irix and Linux (for TCL->MD2SKINI->syntmono control).</LI>
<LI>Defined INT16 and INT32 types and fixed various WvIn and WvOut classes.</LI>
<LI>Updated MatWvIn and MatWvOut for new MAT-file documentation from Matlab.</LI>
<LI>New demo Tcl/Tk GUI (TclDemo.tcl).</LI>
<LI>Minor fixes to FM behavior.</LI>
<LI>Added record/duplex capabilities to RTSoundIO (Linux, SGI, and Windoze).</LI>
<LI>Fixed bugs in WavWvOut and MatWvOut header specifications.</LI>
<LI>Added RawWvOut class.</LI>
<LI>New WvIn class with RawWvIn, SndWvIn, WavWvIn, MatWvIn, and RTWvIn subclasses.</LI>
<LI>Removed RawWave, RawShot, RawInterp, and RawLoop classes (supplanted by RawWvIn).</LI>
<LI>Multi-channel data support in WvIn and WvOut classes using MY_MULTI data type (pointer to MY_FLOAT) and the methods mtick() and mlastOutput().</LI>
<LI>Now writing to primary buffer under Windoze when allowed by hardware.</LI>
<LI>Cleaned up Object.h a bit.</LI>
<LI>Pulled various utility and thread functions out of syntmono.cpp (to aid readability of the code).</LI>
</UL>
\subsection v2dot02 Version 2.02
<UL>
<LI>Created RawWave abstract class, with subclasses of RawLoop (looping rawwave oscillator), RawShot (non-looping, non-interpolating rawwave player ... used to be RawWvIn), and RawInterp (looping or non-looping, interpolating rawwave player ... used to be RawWave).</LI>
<LI>Modified DrumSynt to correctly handle sample rates different than 22050 Hz.</LI>
<LI>Modified syntmono parsing vs. tick routine so that some ticking occurs between each message. When multiple messages are waiting to be processed, the time between message updates is inversely proportional to the number of messages in the buffer.</LI>
<LI>Fixed DirectSound playback bug in WinXX distribution. Sound was being played at 8-bit, 22 kHz in all cases. Playback is now 16-bit and dependent on SRATE.</LI>
<LI>Fixed bug in MD2SKINI which prevented some NoteOff statements from being output.</LI>
<LI>This distribution includes an example STK project, mus151, which demonstrates a means for keeping a user's personal projects separate from the main distribution. This is highly recommended, in order to simplify upgrades to future STK releases.</LI>
</UL>
\subsection v2 Version 2
<UL>
<LI>Unification of the capabilities of STK across the various platforms. All of the previous SGI functionality has been ported to Linux and Windows, including realtime sound output and MIDI input.</LI>
<LI>MIDI input (with optional time-stamping) supported on SGI, Linux (OSS device drivers only), and Windows operating systems. Time stamping under IRIX and Windows is quantized to milliseconds and under Linux to hundredths of a second.</LI>
<LI>Various Sound Output Options - .wav, .snd, and .mat (Matlab MAT-file) soundfile outputs are supported on all operating systems. I hacked out the MAT-file structure, so you don't have to include any platform-specific libraries. Realtime sound output is provided as well, except under NeXTStep. </LI>
<LI>Multiple Reverberator Implementations - Reverb subclasses of JCRev and NRev (popular reverberator implementations from CCRMA) have been written. Perry's original reverb implementation still exists as PRCRev. All reverberators now take a T60 initializer argument.</LI>
<LI>MD2SKINI - A program which parses a MIDI input stream and spits out SKINI code. The output of MD2SKINI is typically piped into an STK instrument executable (eg. <FONT FACE="Geneva">MD2SKINI | syntmono Clarinet -r -i</FONT>). In addition, you can supply a filename argument to MD2SKINI and have it simultaneously record a SKINI score file for future reuse.
<LI>Modifications to <I>Object.h</I> for OS_TYPE compilation dependencies. <I>Makefile</I> automatically determines OS_TYPE when invoked (if you have the GNU makefile utilities installed on your system).
<LI>A single distribution for all platforms. The Unix and Windows versions have been merged into a single set of classes. Makefiles and Visual C++ workspace/project files are provided for compiling.
</UL>
*/

9
doc/doxygen/footer.html Normal file
View File

@@ -0,0 +1,9 @@
<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>

10
doc/doxygen/header.html Normal file
View File

@@ -0,0 +1,10 @@
<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>

31
doc/doxygen/header.tex Normal file
View File

@@ -0,0 +1,31 @@
\documentclass[letter]{book}
\usepackage{makeidx}
\usepackage{fancyhdr}
\usepackage{graphicx}
\usepackage{float}
\usepackage{alltt}
\usepackage{doxygen}
\usepackage{hyperref}
\makeindex
\setcounter{tocdepth}{1}
\setlength{\footrulewidth}{0.4pt}
\begin{document}
\begin{titlepage}
\vspace*{7cm}
\begin{center}
{\Large User Manual}\\
\vspace*{0.5cm}
{\Large The Synthesis ToolKit in C++}\\
\vspace*{1cm}
{\large by Perry R. Cook and Gary P. Scavone}\\
\vspace*{0.5cm}
{\small \copyright 1995--2002}\\
\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}}
\tableofcontents
\clearemptydoublepage
\pagenumbering{arabic}

BIN
doc/doxygen/images/ccrma.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.1 KiB

BIN
doc/doxygen/images/princeton.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.3 KiB

15
doc/doxygen/index.txt Normal file
View File

@@ -0,0 +1,15 @@
/*! \mainpage <I>The Synthesis ToolKit in C++ (STK)</I>
<BODY BGCOLOR="white">
The <B>Synthesis ToolKit in C++ (STK)</B> is a set of audio signal processing and synthesis classes and algorithms written in C++. You can use these classes to create programs that make sounds with a variety of synthesis techniques. This is not a terribly novel concept, except that the Synthesis ToolKit is extremely portable (it's mostly platform-independent C and C++ code), and it's completely user-extensible (no libraries, no hidden drivers, and all source code is included). 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 8 years now. STK currently runs with "realtime" support (audio and MIDI) on SGI (Irix), Linux, 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
- \ref download
- \ref usage
- \ref maillist
- \ref system
- \ref tutorial
*/

50
doc/doxygen/information.txt Normal file
View File

@@ -0,0 +1,50 @@
/*! \page information General Information
<H3>References</H3>
<UL>
<LI><A HREF="Papers/stkicmc99.pdf">ICMC99 Paper</A></LI>
<BR>
A somewhat recent paper by Perry and Gary about the Synthesis ToolKit in C++.
<P>
<LI><A HREF="Papers/STKsiggraph96.pdf">SIGGRAPH96 Paper</A></LI>
<BR>
A not-so-recent paper by Perry about the Synthesis ToolKit in C++.
<P>
<LI><A HREF="http://www.cs.princeton.edu/~prc/NewWork.html#STK">Perry's STK Web Page</A></LI>
<BR>
This is a link to Perry Cook's STK Web page. He has information about the \ref skini, the protocol used to control STK instruments, as well as a lot of other cool stuff.
</UL>
<H4>What is the <I>Synthesis ToolKit</I>?</H4>
The Synthesis ToolKit in C++ (STK) is a set of audio signal processing and synthesis classes and algorithms written in C++. You can use these classes to create programs that make sounds with a variety of synthesis techniques. This is not a terribly novel concept, except that the Synthesis ToolKit is extremely portable (it's mostly platform-independent C and C++ code), and it's completely user-extensible (no libraries, no hidden drivers, and all source code is included). 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 8 years now. STK currently runs with "realtime" support (audio and MIDI) on SGI (Irix), Linux, 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).
<H4>What the <I>Synthesis ToolKit</I> is not.</H4>
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. If you feel the need to have a "drag and drop" graphical patching GUI, you probably don't want to use the ToolKit. Spending hundreds of hours making platform-dependent graphics code 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).
<H4>A brief history of the <I>Synthesis ToolKit in C++.</I></H4>
Perry Cook began developing a pre-cursor to the Synthesis ToolKit (also called STK) under NeXTStep at the Center for Computer Research in Music and Acoustics (CCRMA) at Stanford University in the early-1990s. With his move to Princeton University in 1996, he ported everything to C++ on SGI hardware, added real-time capabilities, and greatly expanded the synthesis techniques available. With the help of Bill Putnam, Perry also made a port of STK to Windows95. Gary Scavone began using STK extensively in the summer of 1997 and completed a full port of STK to Linux early in 1998. He finished the fully compatable Windows port (using Direct Sound API) in June 1998. Numerous improvements and extensions have been made since then.
The Toolkit has been distributed continuously since 1996 via the <A HREF="http://www.music.princeton.edu/psk">Princeton Sound Kitchen</A>, <A HREF="http://www.cs.princeton.edu/~prc">Perry Cook's home page</A> at Princeton, <A HREF="http://www-ccrma.stanford.edu/~gary/">Gary Scavone's home page</A> at Stanford's Center for Computer Research in Music and Acoustics (CCRMA), and the <A HREF="http://www-ccrma.stanford.edu/software/stk">Synthesis ToolKit home page</A>. The ToolKit has been in included in various collections of software. Much of it has also been ported to MAX/MSP on Macintosh computers by Dan Trueman and Luke Dubois of Columbia University, and is distributed as <A HREF="http://music.columbia.edu/PeRColate">PeRColate</A>. Help on real-time sound and MIDI has been provided by Tim 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>
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.
<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.
*/

12
doc/doxygen/maillist.txt Normal file
View File

@@ -0,0 +1,12 @@
/*! \page maillist The Mail List
An <A HREF="mailto:stk-request@ccrma.stanford.edu">STK</A> mailing list has been set up to facilitate communication among STK users. Subscribing to this list is your best way of keeping on top of new releases, bug fixes, and various user developments.
<P>
To join send a message to <A HREF="mailto:stk-request@ccrma.stanford.edu">&lt;stk-request@ccrma.stanford.edu&gt;</A>
with the contents: <TT>subscribe</TT>
<P>
To be removed from the list send a message to <A HREF="mailto:stk-request@ccrma.stanford.edu">&lt;stk-request@ccrma.stanford.edu&gt;</A>
with the contents: <TT>unsubscribe</TT>
*/

218
doc/doxygen/skini.txt Normal file
View File

@@ -0,0 +1,218 @@
/*! \page skini Synthesis toolKit Instrument Network Interface (SKINI)
This describes the latest (version 1.1) implementation of SKINI for the Synthesis Toolkit in C++ (STK) by Perry R. Cook.
\code
Too good to be true?
Have control and read it too?
A SKINI haiku.
\endcode
Profound thanks to Dan Trueman, Brad Garton, and Gary Scavone for input on this revision. Thanks also to MIDI, the NeXT MusicKit, ZIPI and all the creators and modifiers of these for good bases upon/from which to build and depart.
\section compatibility MIDI Compatibility
SKINI was designed to be MIDI compatible wherever possible, and extend MIDI in incremental, then maybe profound ways.
Differences from MIDI, and motivations, include:
- Text-based messages are used, with meaningful names wherever possible. This allows any language or system capable of formatted printing to generate SKINI. Similarly, any system capable of reading in a string and turning delimited fields into strings, floats, and ints can consume SKINI for control. More importantly, humans can actually read, and even write if they want, SKINI files and streams. Use an editor and search/replace or macros to change a channel or control number. Load a SKINI score into a spread sheet to apply transformations to time, control parameters, MIDI velocities, etc. Put a monkey on a special typewriter and get your next great work. Life's too short to debug bit/nybble packed variable length mumble messages. Disk space gets cheaper, available bandwidth increases, music takes up so little space and bandwidth compared to video and grapics. Live a little.
- Floating point numbers are used wherever possible. Note Numbers, Velocities, Controller Values, and Delta and Absolute Times are all represented and scanned as ASCII double-precision floats. MIDI byte values are preserved, so that incoming MIDI bytes from an interface can be put directly into SKINI messages. 60.0 or 60 is middle C, 127.0 or 127 is maximum velocity etc. But, unlike MIDI, 60.5 can cause a 50cent sharp middle C to be played. As with MIDI byte values like velocity, use of the integer and SKINI-added fractional parts is up to the implementor of the algorithm being controlled by SKINI messages. But the extra precision is there to be used or ignored.
\section why Why SKINI?
SKINI was designed to be extensable and hackable for a number of applications: imbedded synthesis in a game or VR simulation, scoring and mixing tasks, real-time and non-real time applications which could benefit from controllable sound synthesis, JAVA controlled synthesis, or eventually maybe JAVA synthesis, etc. SKINI is not intended to be "the mother of scorefiles," but since the entire system is based on text representations of names, floats, and ints, converters from one scorefile language to SKINI, or back, should be easily created.
I am basically a bottom-up designer with an awareness of top-down design ideas, so SKINI above all reflects the needs of my particular research and creative projects as they have arisen and developed. SKINI 1.1 represents a profound advance beyond versions 0.8 and 0.9 (the first versions), future SKINI's might reflect some changes. Compatibility with prior scorefiles will be attempted, but there aren't that many scorefiles out there yet.
\section messages SKINI Messages
A basic SKINI message is a line of text. There are only three required fields, the message type (an ASCII name), the time (either delta or absolute), and the channel number. Don't freak out and think that this is MIDI channel 0-15 (which is supported), because the channel number is scanned as a long int. Channels could be socket numbers, machine IDs, serial numbers, or even unique tags for each event in a synthesis. Other fields might be used, as specified in the SKINI.tbl file. This is described in more detail later.
Fields in a SKINI line are delimited by spaces, commas, or tabs. The SKINI parser only operates on a line at a time, so a newline means the message is over. Multiple messages are NOT allowed directly on a single line (by use of the ; for example in C). This could be supported, but it isn't in version 1.1.
Message types include standard MIDI types like NoteOn, NoteOff, ControlChange, etc. MIDI extension message types (messages which look better than MIDI but actually get turned into MIDI-like messages) include LipTension, StringDamping, etc. Non-MIDI message types include SetPath (sets a path for file use later), and OpenReadFile (for streaming, mixing, and applying effects to soundfiles along with synthesis, for example). Other non-MIDI message types include Trilling, HammerOn, etc. (these translate to gestures, behaviors, and contexts for use by intellegent players and instruments using SKINI). Where possible I will still use these as MIDI extension messages, so foot switches, etc. can be used to control them in real time.
All fields other than type, time, and channel are optional, and the types and useage of the additional fields is defined in the file SKINI.tbl.
The other important file used by SKINI is SKINI.msg, which is a set of #defines to make C code more readable, and to allow reasonably quick re-mapping of control numbers, etc.. All of these defined symbols are assigned integer values. For Java, the #defines could be replaced by declaration and assignment statements, preserving the look and behavior of the rest of the code.
\section cfiles C Files Used To Implement SKINI
SKINI.cpp is an object which can either open a SKINI file, and successively read and parse lines of text as SKINI strings, or accept strings from another object and parse them. The latter functionality would be used by a socket, pipe, or other connection receiving SKINI messages a line at a time, usually in real time, but not restricted to real time.
SKINI.msg should be included by anything wanting to use the SKINI.cpp object. This is not mandatory, but use of the __SK_blah_ symbols which are defined in the .msg file will help to ensure clarity and consistency when messages are added and changed.
SKINI.tbl is used only by the SKINI parser object (SKINI.cpp). In the file SKINI.tbl, an array of structures is declared and assigned values which instruct the parser as to what the message types are, and what the fields mean for those message types. This table is compiled and linked into applications using SKINI, but could be dynamically loaded and changed in a future version of SKINI.
\section parser SKINI Messages and the SKINI Parser:
The parser isn't all that smart, but neither am I. Here are the basic rules governing a valid SKINI message:
- If the first (non-delimiter ... see below) character in a SKINI string is '/' that line is treated as a comment and echoed to stdout.
- If there are no characters on a line, that line is treated as blank and echoed to stdout. Tabs and spaces are treated as non-characters.
- Spaces, commas, and tabs delimit the fields in a SKINI message line. (We might allow for multiple messages per line later using the semicolon, but probably not. A series of lines with deltaTimes of 0.0 denotes simultaneous events. For read-ability, multiple messages per line doesn't help much, so it's unlikely to be supported later).
- The first field must be a SKINI message name (like NoteOn). These might become case-insensitive in future versions, so don't plan on exciting clever overloading of names (like noTeOn being different from NoTeON). There can be a number of leading spaces or tabs, but don't exceed 32 or so.
- The second field must be a time specification in seconds. A time field can be either delta-time (most common and the only one supported in version 0.8), or absolute time. Absolute time messages have an '=' appended to the beginning of the floating point number with no space. So 0.10000 means delta time of 100 ms, while =0.10000 means absolute time of 100 ms. Absolute time messages make most sense in score files, but could also be used for (loose) synchronization in a real-time context. Real-time messages should be time-ordered AND time-correct. That is, if you've sent 100 total delta-time messages of 1.0 seconds, and then send an absolute time message of =90.0 seconds, or if you send two absolute time messages of =100.0 and =90.0 in that order, things will get really fouled up. The SKINI parser doesn't know about time, however. The WvOut device is the master time keeper in the Synthesis Toolkit, so it should be queried to see if absolute time messages are making sense. There's an example of how to do that later in this document. Absolute times are returned by the parser as negative numbers (since negative deltaTimes are not allowed).
- The third field must be an integer channel number. Don't go crazy and think that this is just MIDI channel 0-15 (which is supported). The channel number is scanned as a long int. Channels 0-15 are in general to be treated as MIDI channels. After that it's wide open. Channels could be socket numbers, machine IDs, serial numbers, or even unique tags for each event in a synthesis. A -1 channel can be used as don't care, omni, or other functions depending on your needs and taste.
- All remaining fields are specified in the SKINI.tbl file. In general, there are maximum two more fields, which are either SK_INT (long), SK_DBL (double float), or SK_STR (string). The latter is the mechanism by which more arguments can be specified on the line, but the object using SKINI must take that string apart (retrived by using getRemainderString()) and scan it. Any excess fields are stashed in remainderString.
\section file A Short SKINI File:
\code
/* Howdy!!! Welcome to SKINI, by P. Cook 1999
NoteOn 0.000082 2 55 82
NoteOff 1.000000 2 55 0
NoteOn 0.000082 2 69 82
StringDetune 0.100000 2 10
StringDetune 0.100000 2 30
StringDetune 0.100000 2 50
NoteOn 0.000000 2 69 82
StringDetune 0.100000 2 40
StringDetune 0.100000 2 22
StringDetune 0.100000 2 12
//
StringDamping 0.000100 2 0.0
NoteOn 0.000082 2 55 82
NoteOn 0.200000 2 62 82
NoteOn 0.100000 2 71 82
NoteOn 0.200000 2 79 82
NoteOff 1.000000 2 55 82
NoteOff 0.000000 2 62 82
NoteOff 0.000000 2 71 82
NoteOff 0.000000 2 79 82
StringDamping =4.000000 2 0.0
NoteOn 0.000082 2 55 82
NoteOn 0.200000 2 62 82
NoteOn 0.100000 2 71 82
NoteOn 0.200000 2 79 82
NoteOff 1.000000 2 55 82
NoteOff 0.000000 2 62 82
NoteOff 0.000000 2 71 82
NoteOff 0.000000 2 79 82
\endcode
\section table The SKINI.tbl File and Message Parsing:
The SKINI.tbl file contains an array of structures which are accessed by the parser object SKINI.cpp. The struct is:
\code
struct SKINISpec {
char messageString[32];
long type;
long data2;
long data3;
};
\endcode
so an assignment of one of these structs looks like:
\code
MessageStr$ ,type, data2, data3,
\endcode
<TT>type</TT> is the message type sent back from the SKINI line parser.
<TT>data<n></TT> is either:
- NOPE : field not used, specifically, there aren't going to be any more fields on this line. So if there is is NOPE in data2, data3 won't even be checked.
- SK_INT : byte (actually scanned as 32 bit signed long int). If it's a MIDI data field which is required to be an integer, like a controller number, it's 0-127. Otherwise, get creative with SK_INTs.
- SK_DBL : double precision floating point. SKINI uses these in the MIDI context for note numbers with micro tuning, velocities, controller values, etc.
- SK_STR : only valid in final field. This allows (nearly) arbitrary message types to be supported by simply scanning the string to EndOfLine and then passing it to a more intellegent handler. For example, MIDI SYSEX (system exclusive) messages of up to 256 bytes can be read as space-delimited integers into the 1K SK_STR buffer. Longer bulk dumps, soundfiles, etc. should be handled as a new message type pointing to a FileName, Socket, or something else stored in the SK_STR field, or as a new type of multi-line message.
Here's a couple of lines from the SKINI.tbl file
\code
{"NoteOff" , __SK_NoteOff_, SK_DBL, SK_DBL},
{"NoteOn" , __SK_NoteOn_, SK_DBL, SK_DBL},
{"ControlChange" , __SK_ControlChange_, SK_INT, SK_DBL},
{"Volume" , __SK_ControlChange_, __SK_Volume_ , SK_DBL},
{"StringDamping" , __SK_ControlChange_, __SK_StringDamping_, SK_DBL},
{"StringDetune" , __SK_ControlChange_, __SK_StringDetune_, SK_DBL},
\endcode
The first three are basic MIDI messages. The first two would cause the parser, after recognizing a match of the string "NoteOff" or "NoteOn", to set the message type to 128 or 144 (__SK_NoteOff_ and __SK_NoteOn_ are #defined in the file SKINI.msg to be the MIDI byte value, without channel, of the actual MIDI messages for NoteOn and NoteOff). The parser would then set the time or delta time (this is always done and is therefore not described in the SKINI Message Struct). The next two fields would be scanned as double-precision floats and assigned to the byteTwo and byteThree variables of the SKINI parser. The remainder of the line is stashed in the remainderString variable.
The ControlChange spec is basically the same as NoteOn and NoteOff, but the second data byte is set to an integer (for checking later as to what MIDI control is being changed).
The Volume spec is a MIDI Extension message, which behaves like a ControlChange message with the controller number set explicitly to the value for MIDI Volume (7). Thus the following two lines would accomplish the same changing of MIDI volume on channel 2:
\code
ControlChange 0.000000 2 7 64.1
Volume 0.000000 2 64.1
\endcode
I like the 2nd line better, thus my motivation for SKINI in the first place.
The StringDamping and StringDetune messages behave the same as the Volume message, but use Control Numbers which aren't specifically nailed-down in MIDI. Note that these Control Numbers are carried around as long ints, so we're not limited to 0-127. If, however, you want to use a MIDI controller to play an instrument, using controller numbers in the 0-127 range might make sense.
\section using Using SKINI:
Here's a simple example of code which uses the SKINI object to read a SKINI file and control a single instrument.
\code
instrument = new Mandolin(50.0);
score = new SKINI(argv[1]);
while(score->getType() > 0) {
tempDouble = score->getDelta();
if (tempDouble < 0) {
tempDouble = - tempDouble;
tempDouble = tempDouble - output.getTime();
if (tempDouble < 0) {
printf("Bad News Here!!! Backward Absolute Time Required.\n");
tempDouble = 0.0;
}
}
tempLong = (long) (tempDouble * Stk::sampleRate());
for (i=0;i<tempLong;i++) {
output.tick(instrument->tick());
}
tempDouble3 = score->getByteThree();
if (score->getType()== __SK_NoteOn_ ) {
tempDouble3 *= NORM_MIDI;
if (score->getByteThree() == 0) {
tempDouble3 = 0.5;
instrument->noteOff(tempDouble3);
}
else {
tempLong = (int) score->getByteTwo();
tempDouble2 = Midi2Pitch[tempLong];
instrument->noteOn(tempDouble2,tempDouble3);
}
}
else if (score->getType() == __SK_NoteOff_) {
tempDouble3 *= NORM_MIDI;
instrument->noteOff(tempDouble3);
}
else if (score->getType() == __SK_ControlChange_) {
tempLong = score->getByteTwoInt();
instrument->controlChange(tempLong,temp3.0);
}
score->nextMessage();
}
\endcode
When the score (SKINI object) object is created from the filename in argv[1], the first valid command line is read from the file and parsed.
The score->getType() retrieves the messageType. If this is -1, there are no more valid messages in the file and the synthesis loop terminates. Otherwise, the message type is returned.
getDelta() retrieves the deltaTime until the current message should occur. If this is greater than 0, synthesis occurs until the deltaTime has elapsed. If deltaTime is less than zero, the time is interpreted as absolute time and the output device is queried as to what time it is now. That is used to form a deltaTime, and if it's positive we synthesize. If it's negative, we print an error and pretend this never happened and we hang around hoping to eventually catch up.
The rest of the code sorts out message types NoteOn, NoteOff (including NoteOn with velocity 0), and ControlChange. The code implicitly takes into account the integer type of the control number, but all other data is treated as double float.
The last line reads and parses the next message in the file.
*/

29
doc/doxygen/system.txt Normal file
View File

@@ -0,0 +1,29 @@
/*! \page system System Requirements
<B>General</B>
<UL>
<LI>A MIDI interface to use MIDI input controls. (NOTE: This may be built into the soundcard on your computer.)</LI>
<LI><A HREF="http://dev.scriptics.com">Tcl/Tk</A> version 8.0 or higher to use the simple Tcl/Tk GUIs provided with the STK distribution (available free over the WWW for all supported realtime platforms).</LI>
</UL>
<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.opensound.com">OSS</A> or <A HREF="http://www.alsa-project.org/">ALSA</A> device drivers for realtime sound output and MIDI input.</LI>
</UL>
<B>Windows95/98/2000/XP (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.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>For compiling the source (if not already in your system): <UL><LI><A HREF="Misc/dsound.h">dsound.h</A> header file (DirectX 6.1) - put somewhere in your header search path</LI><LI><A HREF="Misc/dsound.lib">dsound.lib</A> library file (DirectX 6.1) - put somewhere in your library search path</LI></UL></LI>
</UL>
<B>WindowsNT (specific)</B>
<UL>
<LI>STK is no longer supported under WindowsNT because DirectX support for NT is minimal. Unless DirectX 5.0 or higher becomes available for NT, STK won't work.</LI>
</UL>
<P>
*/

149
doc/doxygen/tutorial.txt Normal file
View File

@@ -0,0 +1,149 @@
/*! \page tutorial Tutorial
- \ref intro
- \ref start
- \ref compile
- \ref rtvsnonrt
\section intro Introduction
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>
<LI>want to create audio DSP and/or synthesis programs</LI>
<LI>want to save some time by using our unit generators and input/output routines</LI>
<LI>know C, but want to learn about synthesis and processing algorithms</LI>
<LI>wish to teach real-time synthesis and processing, and wish to use some of our classes and examples</LI>
</UL>
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.).
\section start Getting Started
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, WaveLoop, which can load a variety of common file types. In this example, we load a sine "table" from an STK RAW file. The class RtWvOut will send "realtime" samples to the audio output hardware on your computer.
\code
// sineosc.cpp
#include "WaveLoop.h"
#include "RtWvOut.h"
int main()
{
// Set the global sample rate before creating class instances.
Stk::setSampleRate( 44100.0 );
// Define and load the sine wave file
WaveLoop *input = new WaveLoop("sinewave.raw", TRUE);
input->setFrequency(440.0);
// Define and open the default realtime output device for one-channel playback
RtWvOut *output = new RtWvOut(1);
// Play the oscillator for 40000 samples
for (int i=0; i<40000; i++) {
output->tick( input->tick() );
}
// Clean up
delete input;
delete output;
return 0;
}
\endcode
WaveLoop is a subclass of WvIn, which supports WAV, SND (AU), AIFF, MAT-file (Matlab), and RAW file formats with 8-, 16-, and 32-bit integer and 32- and 64-bit floating-point data types. WvIn provides interpolating, read once ("oneshot") functionality, as well as methods for setting the read rate and read position.
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.
The WvIn and WvOut classes support multi-channel sample frames. To distinguish single-sample frame operations from multi-channel frame operations, these classes also implement 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.
Nearly all STK classes inherit from the Stk base class. Stk provides a static sample rate which is queried by subclasses as needed. Because many classes use the current sample rate value during instantiation, it is important that the desired value be set at the beginning of a program. The default STK sample rate is 22050 Hz.
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 WvIn and WvOut classes and subclasses scale appropriately for DAC or soundfile input and output.
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.
\code
// sineosc.cpp
#include "WaveLoop.h"
#include "RtWvOut.h"
int main()
{
// Set the global sample rate before creating class instances.
Stk::setSampleRate( 44100.0 );
WaveLoop *input = 0;
RtWvOut *output = 0;
try {
// Define and load the sine wave file
input = new WaveLoop( "sinewave.raw", TRUE );
// Define and open the default realtime output device for one-channel playback
output = new RtWvOut(1);
}
catch (StkError &) {
goto cleanup;
}
input->setFrequency(440.0);
// Play the oscillator for 40000 samples
for (int i=0; i<40000; i++) {
try {
output->tick(input->tick());
}
catch (StkError &) {
goto cleanup;
}
}
cleanup:
delete input;
delete output;
return 0;
}
\endcode
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.
\section compile Compiling
\subsection compileLinux Linux
In general, you will probably want to use a <TT>Makefile</TT> for your STK programs and projects. For this particular program, however, the following will suffice (on a linux system):
\code
g++ -Wall -D__LINUX_OSS__ -D__LITTLE_ENDIAN__ -o sineosc Stk.cpp WvIn.cpp WaveLoop.cpp WvOut.cpp RtWvOut.cpp RtAudio.cpp sineosc.cpp -lpthread
\endcode
This assumes you've set up a directory that includes the files <TT>sineosc.cpp</TT>, the rawwave file <TT>sinewave.raw</TT>, and the header and source files for the classes Stk, WvIn, WaveLoop, WvOut, RtWvOut, and RtAudio. There are other, more convenient, means for structuring projects that will be discussed later.
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 (<TT>-lasound</TT>) and the preprocessor definition should instead be <TT>__LINUX_ALSA__</TT>.
\subsection compileIrix Irix
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:
\code
CC -Wall -D__IRIX_AL__ -o sineosc Stk.cpp WvIn.cpp WaveLoop.cpp WvOut.cpp RtWvOut.cpp RtAudio.cpp sineosc.cpp -lpthread
\endcode
\subsection compileWin Windows
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 Stk, WvIn, WaveLoop, WvOut, RtWvOut, and RtAudio class files, as well as the <TT>sineosc.cpp</TT> and <TT>sinewave.raw</TT> files. You will also need to link to the DirectSound library (<TT>dsound.lib</TT>), select the multithreaded library, and provide the <TT>__WINDOWS_DS__</TT> and <TT>__LITTLE_ENDIAN__</TT> preprocessor definitions.
\section rtvsnonrt "Realtime" vs. "Non-Realtime"
Most of the Synthesis ToolKit classes are platform independent. That means that they should compile on any reasonably current C++ compiler. The functionality needed for realtime audio and MIDI input/output, as well as realtime control message acquistion, is inherently platform and operating-system (OS) <I>dependent</I>. STK classes which require specific platform/OS support include RtAudio, RtWvOut, RtWvIn, RtDuplex, RtMidi, TcpWvIn, TcpWvOut, Socket, and Thread. These classes currently can only be compiled on Linux, Irix, and Windows (except Windows NT) systems using the <TT>__LINUX_OSS__</TT>, <TT>__LINUX_ALSA__</TT>, <TT>__IRIX_AL__</TT>, or <TT>__WINDOWS_DS__</TT> preprocessor definitions.
Without the "realtime" classes, it is still possible to read SKINI scorefiles for control input and to read and write to/from a variety of audio file formats (WAV, SND, AIFF, MAT-file, and RAW). If compiling for a "little-endian" host processor, the <TT>__LITTLE_ENDIAN__</TT> preprocessor definition should be provided.
\section continued To Be Continued ...
*/

183
doc/doxygen/usage.txt Normal file
View File

@@ -0,0 +1,183 @@
/*! \page usage Usage Documentation
- \ref directory
- \ref compiling
- \ref control
- \ref instruments
- \ref nort
- \ref rt
- \ref tcl
- \ref midi
<HR>
\section directory Directory Structure:
The top level distribution contains the following directories:
<UL>
<LI> The <I><B>src</B></I> directory contains the source .cpp files for almost all the STK unit generator and algorithm classes.</LI><P>
<LI> The <I><B>include</B></I> directory contains the header files for almost all the STK unit generator and algorithm classes.</LI><P>
<LI> The <I><B>rawwaves</B></I> directory contains various raw, monophonic, 16-bit, big-endian soundfiles used with the STK classes.</LI><P>
<LI> The <I><B>doc</B></I> directory contains documentation about STK.</LI><P>
<LI> The <I><B>projects</B></I> directory contains various demo and example STK programs.</LI><P>
</UL>
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>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, as well as the use of the audio internet streaming classes.</LI>
</OL>
\section compiling Compiling:
<UL>
<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, 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>
<LI><B>Linux:</B> Realtime support is enabled with either the <TT>__LINUX_OSS__</TT> or <TT>__LINUX_ALSA__</TT> preprocessor definitions, which are used to select the underlying audio/MIDI system API. Realtime programs must also link with the <TT>pthread</TT> library. When using the ALSA API, it is also necessary to link with the <TT>asound</TT> library. In addition, the <TT>__LITTLE_ENDIAN__</TT> preprocessor definition is necessary if compiling on a little-endian system. Assuming your system has the <A HREF="http://gnu.cetcol.net.co/">GNU</A> Makefile utilities installed, typing <TT>make</TT> within a particular project directory will initiate the compilation process. The <TT>Makefile</TT> will have to be modified to change the default audio/MIDI system API and for big-endian processors. Special support exists under Linux for the MIDIator serial MIDI device, enabled using the __MIDIATOR__ preprocessor definition (together with either the __LINUX_ALSA__ or __LINUX_OSS__ definitions). See the README-Linux file for further system configuration information.</LI>
<LI><B>SGI:</B> Realtime support is enabled with the <TT>__IRIX_AL__</TT> preprocessor definition and linkage with the <TT>audio</TT>, <TT>md</TT>, and <TT>pthread</TT> libraries. If your system has the <A HREF="http://gnu.cetcol.net.co/">GNU</A> Makefile utilities installed, typing <TT>make</TT> (or <TT>gmake</TT>) within a particular project directory will initiate the compilation process. If your system does not have the GNU Makefile utilities, you should first try to download and install them. If this is not possible, a generic Makefile is provided with the <I><B>demo</B></I> project (Makefile.sgi). It can be invoked by typing <TT>make -f Makefile.sgi</TT> within that project directory. STK 4.0 is confirmed to compile using CC version 7.30. There may be problems with old compiler versions.</LI>
<LI><B>Windows95/98/2000/XP:</B> Realtime support is enabled with the <TT>__WINDOWS_DS__</TT> preprocessor definition and linkage with the <TT>dsound.lib</TT>, <TT>winmm.lib</TT>, and <TT>Wsock32.lib</TT> libraries. In addition, the <TT>__LITTLE_ENDIAN__</TT> preprocessor definition is necessary for all Windows systems. A distribution of the release is available with precompiled binaries 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 file 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> I've given up trying to make things work under NT. You'll have to switch to Windows 2000 (which does seem to work).</LI>
</UL>
\section control Control Data:
All STK programs in this distribution take input control data in the form of <A HREF="skini.html">SKINI</A> or MIDI messages only. The Messager class unifies the various means of acquiring control data under a single, easy to use set of functions. The way that SKINI messages can be sent to the programs is dependent upon the operating system in use, as well as whether the program is running in realtime or not. In general, it is possible to:
<OL>
<LI>Redirect or pipe SKINI scorefiles to an executable.</LI>
<LI>Pipe realtime SKINI input messages to an executable (not possible under Windows95/98).</LI>
<LI>Socket realtime SKINI input messages to an executable.</LI>
<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.
\section instruments Demo: STK Instruments
The <I><B>demo</B></I> project demonstrates the behavior of all the distributed STK instruments. The instruments available with this release include:
<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>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>
<LI>Bowed: Not hideous physical model of a bowed string instrument</LI>
<LI>Plucked: Yer basic plucked string physical model</LI>
<LI>StifKarp: A simple plucked, stiff string physical model</LI>
<LI>Sitar: A simple sitar/plucked string physical model</LI>
<LI>Mandolin: Two-string mandolin physical model</LI>
<LI>Rhodey: Rhodes-like electric piano FM synthesis model</LI>
<LI>Wurley: Wurlitzer-like electric piano FM synthesis model</LI>
<LI>TubeBell: FM synthesis model</LI>
<LI>HevyMetl: Distorted synthesizer FM synthesis model</LI>
<LI>PercFlut: Percussive flute-like FM synthesis model</LI>
<LI>BeeThree: Cheezy organ FM synthesis model</LI>
<LI>Moog: Swept filter sampler</LI>
<LI>FMVoices: Three-formant FM voice synthesis</LI>
<LI>Resonate: Noise through a BiQuad filter</LI>
<LI>Drummer: Sampling synthesis</LI>
<LI>BandedWG: Banded waveguide meta-object for bowed bars, tibetan bowls, etc.</LI>
<LI>Shakers: Various stochastic event models of shaker instruments</LI>
<LI>ModalBar: Various four-resonance presets (marimba, vibraphone, etc...)</LI>
<LI>Mesh2D: Two-dimensional, rectilinear digital waveguide mesh</LI>
</UL>
\section nort Demo: Non-Realtime Use
See the information above with respect to compiling STK for non-realtime use.
In non-realtime mode, it is assumed that input control messages are provided from a SKINI scorefile and that audio output is written to a soundfile (.snd, .wav, .aif, .mat, .raw). A number of SKINI scorefiles are provided in the <I>scores</I> directory of the <I><B>demo</B></I> project. Assuming a successful compilation of the <I><B>demo</B></I> program, typing:
\code
cat scores/bookert.ski | demo BeeThree -w myfile.wav
\endcode
or (on WindowsXX and/or Unix)
\code
demo BeeThree -w myfile.wav < scores\bookert.ski
\endcode
from the <I><B>demo</B></I> directory will play the scorefile <I>bookert.ski</I> using the STK BeeThree instrument and write the resulting audio data to a WAV formatted soundfile called "myfile.wav". Typing <TT>demo</TT> without any arguments will provide a full program usage description.
\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, and Windows95/98/2000/XP operating systems. STK realtime SKINI control input via piping is possible under Linux, SGI, 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:
\code
demo instrument flags
\endcode
where instruments include those described above and flags can be any or all of:
<UL>
<LI><I>-or</I> for realtime audio output,</LI>
<LI><I>-ow <file name></I> for WAV soundfile output,</LI>
<LI><I>-os <file name></I> for SND (AU) soundfile output,</LI>
<LI><I>-om <file name></I> for MAT-file output,</LI>
<LI><I>-ip</I> or <I>-is</I> for realtime SKINI control input via piping or socketing, respectively,</LI>
<LI><I>-im <file name></I> for MIDI control input</LI>
</UL>
The <-ip> and <-is> flags must be used when piping or socketing realtime SKINI control data to an STK program. The <-im> flag must be used to read MIDI control input from your MIDI port. Note that you can use all three input types simultaneously.
Assuming a successful compilation of the <I><B>demo</B></I> program, typing:
\code
cat scores/bookert.ski | demo BeeThree -or
\endcode
or (on WindowsXX and/or Unix)
\code
demo BeeThree -or < scores\bookert.ski
\endcode
from the <I><B>demo</B></I> directory will play the scorefile <I>bookert.ski</I> using the STK BeeThree instrument and stream the resulting audio data in realtime to the audio output channel of your computer. Typing <TT>demo</TT> without any arguments will provide a full program usage description.
\section tcl Realtime Control Input using Tcl/Tk Graphical User Interfaces:
There are a number of <A HREF="http://dev.scriptics.com">Tcl/Tk</A> GUIs supplied with the STK projects. These scripts require Tcl/Tk version 8.0 or later, which can be downloaded for free over the WWW. On Unix and Windows2000/XP platforms, you can run the various executable scripts (e.g. StkDemo.bat) provided with each project to start everything up (you may need to symbolically link the wish80 executable to the name <I>wish</I>). The PhysicalDemo script just implements the following command-line sequence:
\code
wish < tcl/Physical.tcl | demo Clarinet -or -ip
\endcode
On WindowsXX and Unix platforms, the following operations are necessary to establish a socket connection between the Tcl/Tk GUI and the STK program:
<OL>
<LI>Open a DOS shell and start the STK program with the <I>-is</I> flag (ex. <I><B>demo Clarinet -or -is</B></I>).</LI>
<LI>Open the Tcl/Tk GUI (e.g. tcl/Physical.tcl) by double-clicking on it, or type <TT>wish < tcl/Physical.tcl</TT> in another DOS shell.</LI>
<LI>Establish the socket connection by selecting <I>Socket</I> under the Communications menu item in the Tcl/Tk GUI.</LI>
</OL>
Note that it is possible to specify a hostname when establishing the socket connection from the socket client. Thus, the STK socket server program and the Tcl/Tk GUI need not necessarily reside on the same computer.
\section midi Realtime MIDI Control Input:
On all supported realtime platforms, you can direct realtime MIDI input to the STK Clarinet by typing:
\code
demo Clarinet -or -im
\endcode
*/