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 3.2

Browse Source
This commit is contained in:
Gary Scavone
2013-09-25 14:47:10 +02:00
committed by Stephen Sinclair
parent 4b6500d3de
commit 3f126af4e5
443 changed files with 11772 additions and 8060 deletions
Download Patch File Download Diff File Expand all files Collapse all files

156
doc/Hierarchy.txt Normal file
View File

@@ -0,0 +1,156 @@
STK: A ToolKit of Audio Synthesis Classes and Instruments in C++
Version 3.2
By Perry R. Cook, 1995-2000
and Gary P. Scavone, 1997-2000.
STK Classes, Version 3.2
Please read README.txt for more information.
<--------Building Blocks---------->|<----------------Instruments------------------>
SourcSink Filters Reverb Non-Lin Modal & FM Physical Sampling PhISM
Formant
Object-----------------------------------Instrmnt----------.
| | | | | | |
Envelope| Filter Reverb BowTabl | .----------------------------------------.
| | | | JetTabl | | | | | | | | |
ADSR | OneZero PRCRev ReedTabl| Modal4 | FM4Op---.| | | | Shakers
| OnePole JCRev | | | | || | | |
._____| TwoZero NRev .____| ModalBar| FM4Alg3 || Plucked Sampler |
| | TwoPole | | | || Clarinet | |
Noise | DCBlock LipFilt | HeavyMtl|| Brass SamplFlt|
| | BiQuad | || Flute | |
SubNoise| DlineL .____| .____|| Bowed Moog1 |
| DLineA | | || BowedBar |
| DLineN VoicForm FM4Alg4 || BlowHole |
| FormSwep | ||____. |
| PoleZero PercFlut| | |
.____| FIR | Plucked2 |
| | .____| | .____|
TablLook| | | Mandolin |
| FM4Alg5 | DrumSynt
|____. | |
| | Rhodey |
| WvIn Wurley |
._____| | TubeBell |
| | WavWvIn .____|
Modulatr| SndWvIn | |
| RawWvIn FM4Alg6 |
._____| MatWvIn | |
| | AifWvIn FMVoices|
SingWave| StrmWvIn |
| .____|
._____|_____. |
| | | FM4Alg8
VoicMang| WvOut |
| | BeeThree
| WavWvOut
._____| SndWvOut
| | RawWvOut
RtMidi | MatWvOut
| AifWvOut
._____| RtWvOut
| StrmWvOut
RtAudio
********** INSTRUMENTS AND ALGORITHMS **************
Each Class will be listed either with all UGs it uses,
or the <<Algorithm>> of which it is a flavor.
All inherit from Instrmnt, which inherits from Object.
Plucked.cpp Basic Plucked String DLineA,OneZero,OnePole,Noise
Plucked2.cpp Not So Basic Pluck DLineL,DlineA,OneZero
Mandolin.cpp My Own Mandolin <<flavor of Plucked2>>
Bowed.cpp Not Hideous Bowed String DlineL,BowTabl,OnePole,BiQuad,RawWave,ADSR
Brass.cpp Not So Bad Brass Inst. DLineA,LipFilt,DCBlock,ADSR,RawWvIn
Clarinet.cpp Pretty Good Clarinet DLineL,ReedTabl,OneZero,Envelope,Noise,RawWvIn
BlowHole.cpp Clarinet w/ tone/reghole DLineL,ReedTabl,OneZero,Envelope,Noise,RawWvIn,PoleZero
Flute.cpp Pretty Good Flute JetTabl,DLineL,OnePole,DCBlock,Noise,ADSR,RawWvIn
BowedBar.cpp Pretty Good Bowed Bar DLineN,BowTabl,ADSR,BiQuad
Modal4.cpp 4 Resonances Envelope,RawWvIn,RawWvIn,BiQuad,OnePole
ModalBar.cpp Various presets <<flavor of MODAL4>>
FM4Op.cpp 4 Operator FM Master ADSR,RawWvIn,TwoZero
FM4Alg3.cpp 3 Cascade w/ FB Mod. <<flavor of FM4OP>>
FM4Alg4.cpp Like Alg3 but diff. <<flavor of FM4OP>>
FM4Alg5.cpp 2 Parallel Simple FMs <<flavor of FM4OP>>
FM4Alg6.cpp 3 Carr. with 1 Mod. <<flavor of FM4OP>>
FM4Alg8.cpp 4 Osc. Additive <<flavor of FM4OP>>
HeavyMtl.cpp Distorted Synth <<flavor of FM4Alg3>>
PercFlut.cpp Perc. Flute <<flavor of FM4Alg4>>
Rhodey.cpp Rhodes-Like Elec. Piano <<flavor of FM4Alg5>>
Wurley.cpp Wurlitz. Elec. Piano <<flavor of FM4Alg5>>
TubeBell.cpp Classic FM Bell <<flavor of FM4Alg5>>
FMVoices.cpp 3-Formant Voice Synth. <<flavor of FM4Alg6>>
BeeThree.cpp Cheezy Organ for Paul <<flavor of FM4Alg8>>
Sampler.cpp Sampling Synth. 4 each ADSR, RawWvIn (att), RawWvIn (loop), OnePole
SamplFlt.cpp Sampler with Swept Filter <<flavor of Sampler>>
Moog1.cpp Swept filter flavor of <<flavor of SamplFlt>>
VoicForm.cpp Source/Filter Voice Envelope,Noise,SingWave,FormSwep,OnePole,OneZero
DrumSynt.cpp Drum Synthesizer bunch of RawWvIn, and OnePole
Shakers.cpp Stochastic Event Models
*********** BASIC UNIT GENERATORS **************
Master Object: Object.cpp For compatibility with Objective C
Source&Sink: Envelope.cpp Linearly Goes to Target by Rate, + noteOn/Off
ADSR.cpp ADSR Flavor of Envelope
Noise.cpp Random Number Generator
SubNoise.cpp Random Numbers each N samples
Inputs: TablLook.cpp Lookup Table (assumes given data in big-endian format)
WvIn.cpp Input Master Class (Looping, One-Shot,
Interpolating, Non-Interpolating)
RawWvIn.cpp STK Raw-file Input
SndWvIn.cpp .snd Input Class
WavWvIn.cpp .wav Input Class
MatWvIn.cpp Matlab MAT-file Input Class
AifWvIn.cpp AIFF Input Class
RtWvIn.cpp Realtime Input Class
StrmWvIn.cpp Audio Streaming (socket server) Input Class
Outputs: WvOut.cpp Output Master Class
RawWvOut.cpp STK Raw-file Output Class
SndWvOut.cpp .snd Output Class
WavWvOut.cpp .wav Output Class
MatWvOut.cpp Matlab MaT-file Output Class
AifWvOut.cpp AIFF Output Class
RtWvOut.cpp Realtime Output Class
StrmWvOut.cpp Audio Streaming (socket client) Output Class
Duplex: RtDuplex.cpp Realtime Input/Output Class
MIDI: RtMidi.cpp MIDI I/O Class
Audio I/O: RtAudio.cpp Multi-OS Audio I/O Routines
Filters: Filter.cpp Filter Master Class
OneZero.cpp One Zero Filter
OnePole.cpp One Pole Filter
PoleZero.cpp One Pole/One Zero Filter
DCBlock.cpp DC Blocking 1Pole/1Zero Filter
TwoZero.cpp Two Zero Filter
TwoPole.cpp Two Pole Filter
BiQuad.cpp 2Pole/2Zero Filter
FormSwep.cpp Sweepable 2Pole filter, go to target by rate
DLineL.cpp Linearly Interpolating Delay Line
DLineA.cpp AllPass Interpolating Delay Line
DLineN.cpp Non Interpolating Delay Line
Reverb: Reverb.cpp Reverb Master Class
PRCRev.cpp 2 series allpass units, 2 parallel comb filters
JCRev.cpp 3 series allpass units, 4 parallel comb filters
NRev.cpp 6 parallel comb filters, 3 series allpass units, ...
NonLin&Lookup: JetTabl.cpp Cubic Jet NonLinearity
BowTabl.cpp 1/x^3-like Bow NonLinearity
ReedTabl.cpp 1 break point Reed NonLinearity
LipFilt.cpp Pressure Controlled BiQuad with NonLin
Derived: Modulatr.cpp Per. and Rnd. Vibrato: RawWave, SubNoise, OnePole
SingWave.cpp Looping Wavetable with: Modulatr, Envelope
Control: Controller.cpp Pipe, Socket, and MIDI control message handling

28
doc/README-Linux.txt Normal file
View File

@@ -0,0 +1,28 @@
STK: A ToolKit of Audio Synthesis Classes and Instruments in C++
Version 3.2
By Perry R. Cook, 1995-2000
and Gary P. Scavone, 1997-2000.
Please read the file README.txt for more general STK information.
STK for Linux is currently using either the Open Sound System (OSS) or the Advanced Linux Sound Architecture (ALSA) sound and MIDI APIs. The free version of OSS works as well (and in some cases better than the commercial OSS version ... such as with my Maestro 2e chipset). In general, the ALSA drivers seem to perform well though we have had some problems with them at CCRMA. You can read more about ALSA at http://www.alsa-project.org/. ALSA is open source and holds great promise for audio under Linux. Select (uncomment) the proper API #define statement in Object.h.
STK should compile without much trouble under Linux ... afterall, it is primarily developed on Linux platforms. Since all Linux distributions typically include the GNU makefile utilities, you should be able to use the default Makefile. Typing "make" will initiate the compilation process.
MIDIATOR SERIAL PORT MIDI SUPPORT:
STK now has special support for the MIDIator serial port MIDI interface. This is of primary interest to us laptop users, whose computers usually don't have a gameport. If you want to buy one of these devices, make sure you get the MS-124w model (www.midiator.com). For it to work in STK, make sure you uncomment the MIDIATOR define statement in Object.h. This support currently only works within the OSS API framework, though I should be able to get it to work with ALSA in the future as well.
There are a few things that need to be done on your system to get the MIDIator working. Add the following lines to your bootup sequence in /etc/rc.d/rc.local:
setserial /dev/ttyS0 baud_base 57600
setserial /dev/ttyS0 divisor 1
You may need to specify the full path to the setserial function, depending on how your PATH variable is set up. Also, you may need to modify the permissions of /dev/ttyS0 (chmod a+rwx). And finally, the MIDIator should be set for "single addresssed" mode (the S/A switch on S and the A/B switch on A), which puts identical output on all 4 MIDI output ports. It is possible to use the MIDIator in a "multi-port" mode, though I'm not currently supporting that in STK.
NOTE REGARDING PTHREADS:
There haven't been any problems with threads since the old days of RedHat Linux 5.0. STK uses the MIT pthreads API.

14
doc/README-NeXT.txt Normal file
View File

@@ -0,0 +1,14 @@
STK: A ToolKit of Audio Synthesis Classes and Instruments in C++
Version 3.2
By Perry R. Cook, 1995-2000
and Gary P. Scavone, 1997-2000.
Please read the file README.txt for more general STK information.
STK has always worked under NeXTStep without realtime audio or MIDI support. In general, STK should compile in this way using any generic C++ compiler. C++ exception handling was added to STK with release 3.2. I have had some difficulty testing this release under NeXTStep because our NeXTStep compilers at CCRMA are very old. We tried a newer version of gcc-2.7.2.2 and that mostly worked, though it died trying to compile the BowedBar class. Also, I was unable to locate the correct header for the random() function.
In summary, I _think_ STK will compile under NeXTStep with a fairly recent compiler, but you may have to do a little work to make it happen. If you do succeed, please let us know.
Just for clarification, "realtime" support and the use of the __STK_REALTIME_ define statement includes audio and MIDI input/output routines, as well as socket and thread routines for realtime message acquisition (Controller) and internet audio streaming (StrmWvIn, StrmWvOut).

15
doc/README-SGI.txt Normal file
View File

@@ -0,0 +1,15 @@
STK: A ToolKit of Audio Synthesis Classes and Instruments in C++
Version 3.2
By Perry R. Cook, 1995-2000
and Gary P. Scavone, 1997-2000.
Please read the file README.txt for more general STK information.
It seems that SGI systems are not distributed with the GNU Makefile utilities. The default Make utility has very limited functionality, so your safest bet is to download the GNU Makefile utilities from the Internet and use STK's default Makefile. If this is not possible, try using Makefile.sgi (make -f Makefile.sgi).
Another issue that has crept up with this release is proper compiler support for C++ error handling. If you experience problems, you probably don't have a recent version of the C++ compiler. Otherwise, STK should compile and run on SGI platforms without any problems.
NOTE REGARDING PTHREADS:
Since release 3.1, STK has used the pthread API under Irix. It appears that pthread functionality is standard on SGI, so this change shouldn't cause any problems. If I'm wrong, let me know!

69
doc/README-Win.txt Normal file
View File

@@ -0,0 +1,69 @@
STK: A ToolKit of Audio Synthesis Classes and Instruments in C++
Version 3.2
By Perry R. Cook, 1995-2000
and Gary P. Scavone, 1997-2000.
Please read the file README.txt for more general STK information.
DirectX and WindowsNT Issues:
-----------------------------
STK is currently distributed with Visual C++ 6.0 project and workspace files.
The STK realtime sound input capabilities under Windoze are only supported using the DirectSoundCapture API. The latency is pretty horrendous, but what do you expect? Also, there is a chance you don't have DirectSoundCapture support on your computer. If not, you should download the DirectX 6.0 (or higher) runtime libraries from Microsoft's WWW site (http://www.microsoft.com/directx/download.asp) in order to run the pre-compiled STK executables for Windoze. The last time I checked, there was no DirectSoundCapture support for WindowsNT ... you'll have to switch to Windows 2000. I stopped supporting the WinMM audio output code with this release. So, if you wish to compile STK under WindowsNT (without realtime audio input support), you'll have to download an older version of STK, uncomment the __WINMM_API_ flag (and comment out the __WINDS_API flag) in Object.h and recompile the source code.
Realtime sound output under Windoze is supported using the DirectSound (dsound.lib) API. All new versions of Win95/98/NT come with the DirectSound library, but early versions did not. If you have trouble running the distributed executables, then you probably don't have DirectSound installed on your system. You can download the necessary DirectSound stuff from Microsoft's WWW pages (http://www.microsoft.com/directx/download.asp).
Realtime MIDI input is supported using the winmm.lib API.
Visual C++ 6.0 workspaces have been created for the various STK projects. Everything has already been configured for you. The intermediate .obj files will be written to either the "Release" or "Debug" directories, but the executable files will be written to the main project directories (where they need to be for proper execution). If you should somehow lose or hose the VC++ workspace file (STK.dsw), then you will have to do a LOT of configuring to recreate it ... it's probably easier just to download the distribution again from our WWW sites. Anyway, for your benefit and mine, here is a list of things that need to be added to the various "Project Settings":
1. Under General: Set "Output files:" to <blank> (this will put the executable in the main project directory.
2. Under C/C++ > Code Generation: Set "Use run-time library:" to Multithreaded (use "debug" versions for the debug configuration).
3. Under Link > General: Add winmm.lib, dsound.lib, and Wsock32.lib to the end of the Object/library modules list.
4. Under C/C++ > Preprocessor: Add "../../include" directory to the "extra include" field.
5. Add all the necessary files to the project.
Remember that items 1-3 above need to be done for each project and for each configuration. There might be an easy way to make global changes, but I couldn't figure it out.
To use the Tcl/Tk GUIs, you will have to install Tcl/Tk. I got version 8.0 and it works very well (and installed easily). The distribution is available on the WWW and is free.
In order for socketing to work, it is necessary to have the TCP protocol installed on your computer. This can be done from the "Network" control panel.
Finally, to use it all -
PLAY SKINI SCOREFILES IN REALTIME:
syntmono Clarinet -or < scores/streetsf.ski
USE TCL/TK GUIs FOR REALTIME CONTROL:
1. Open a DOS console window and start syntmono (eg. syntmono Clarinet -or -is).
2. Double click on a Tcl/Tk file in TCLSpecs (eg. TCLPhys.tcl) from the Windows Explorer to start the GUI. Select the "communications" menu item and "Socket" and make the connection.
3. Start moving the sliders to control the instrument.
USE REALTIME MIDI INPUT FOR CONTROL:
1. Open a DOS console window and start syntmono with MIDI input (eg. syntmono Clarinet -or -im).
This assumes you already have MIDI setup correctly for your computer.
WINDOWS NT ONLY:
Realtime piping seems to work under WindowsNT in much the same way as on Unix platforms. Thus, it is possible to pipe realtime control data to syntmono under WindowsNT as well.
WINDOWS 2000:
I don't have Windows 2000 and I doubt I'll get it anytime soon. However, we briefly tested release 3.2 of STK on Perry's Win2000 machine and it worked fine. There is an advantage in using Windows 2000 over 95/98 in that piping works, just as under unix. Also, the scheduler in Win2000 seems to be much better, so socketed messages don't get clumped together like they do in Win 95/98. Since 2000 is supposed to ship with DirectX 7.0, the DirectSoundCapture functionality should work as well.

128
doc/README.txt Normal file
View File

@@ -0,0 +1,128 @@
STK: A ToolKit of Audio Synthesis Classes and Instruments in C++
Version 3.2
By Perry R. Cook, 1995-2000
and Gary P. Scavone, 1997-2000.
Please read the Legal and Ethical notes near the bottom of this document.
OVERVIEW:
STK is a set of audio signal processing C++ classes and instruments for music synthesis. You can use these classes to create programs which make cool sounds using a variety of synthesis techniques. This is not a terribly novel concept, except that STK is very portable (it's mostly platform-independent C and C++ code) AND it's completely user-extensible. So, the code you write using STK actually has some chance of working in another 5-10 years. 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, but should work with any standard C++ compiler. STK is free for non-commercial use. The only parts of STK that are platform-dependent concern real-time sound, MIDI, and control input and output ... but we've taken care of that for you. The interface for MIDI input and the simple Tcl/Tk graphical user interfaces (GUIs) provided is the same, so it's easy to voice and experiment in real time using either the GUIs or MIDI.
STK isn't one particular program. Rather, STK is a set of C++ classes that you can use to create your own programs. We've provided a few example applications that demonstrate some of the ways that you could use these classes. But 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" GUI, you probably don't want to use STK. Spending hundreds of hours making platform-dependent GUI code would go against one of the fundamental design goals of STK - platform independence. STK can generate simultaneous .snd, .wav, .aif, and .mat output soundfile formats (as well as realtime sound output), so you can view your results using one of the numerous sound/signal analysis tools already available over the WWW (e.g. Snd, Cool Edit, Matlab). For those instances where a simple GUI with sliders and buttons is helpful, we use Tcl/Tk (which is freely distributed for all the STK supported platforms). A number of Tcl/Tk GUI scripts are distributed with the STK release.
SYSTEM REQUIREMENTS:
See the individual README's (eg. README-linux) for platform specific information and system requirements. In general, you will use either the provided Makefiles (Unix platforms) or the VC++ workspace files to compile the example programs. To use the Tcl/Tk GUIs, you will need Tcl/Tk version 8.0 or higher.
WHAT'S NEW:
STK has undergone several key revisions, changes, and additions since its last release. Despite being available in one form or another since 1996, we still consider STK to be alpha software. Thus, backward compatability has not been a priority. Please read the ReleaseNotes to see what has changed since the last release.
The control message handling scheme has been simplified greatly with release 3.2 through the use of the Controller class. It is now possible to have access to simultaneous piped, socketed, and/or MIDI input control messages. In most cases, this should eliminate the use of the MD2SKINI program.
Realtime audio input capabilities were added to STK with release 3.0, though the behavior of such is very hardware dependent. Under Linux and Irix, audio input and output are possible with very low latency. Using the Windoze DirectSound API, minimum dependable output sound latency seems to be around 20 milliseconds or so, while input sound latency is on the order of a hundred milliseconds or more!
As mentioned above, it is possible to record the audio ouput of an STK program to .snd, .wav, .raw, .aif, and .mat (Matlab MAT-file) output file types. Though somewhat obsolete, the program MD2SKINI can be used to write SKINI scorefiles from realtime MIDI input. Finally, STK should compile with non-realtime functionality on any platform with a generic C++ compiler.
For those who wish to make a library from the core STK classes, there is a Makefile in the src directory that will accomplish that (Linux and SGI only).
GETTING STARTED:
A number of example "projects" are provided with this distribution. The effects directory contains a program that demonstrates realtime duplex mode (simultaneous audio input and output) operation, as well as several simple delay-line based effects algorithms. RagaMatic is a totally cool application for achieving inner peace. The examples directory contains several simple programs which demonstrate audio input/output, as well as the use of the audio internet streaming classes. The syntmono directory offers a program for monophonic STK instrument playback and manipulation. Syntmono is used to demonstrate most of the current STK instruments. Control data (in the form of MIDI or SKINI messages) is acquired by syntmono through pipe, socket, or MIDI connections. Tcl/Tk GUIs are provided which output SKINI formatted messages. A variety of SKINI scorefiles are distributed with STK and can be found in the "scores" directory of the syntmono project. MD2SKINI is an executable (currently compiles from the syntmono project) which takes raw MIDI input, converts it to SKINI format, and outputs the result to stdout or any socket host and port ID.
Unless you downloaded the distribution with precompiled Windoze binaries, it is necessary to first compile the sources. Under Linux or Irix, simply typing "make" in any of the particular project directories will begin the compilation process. If your Unix system does not have the GNU Makefile utilities, you will have to use one of the platform specific Makefiles (eg. make -f Makefile.sgi). To compile the projects under Windoze, you should use the VC++ 6.0 project files provided with the STK distribution.
SYNTMONO:
Syntmono is used to demonstrate most of the current STK instruments. Syntmono can take realtime control input via MIDI and/or SKINI format via pipes or sockets, or it can be fed SKINI scorefile (non-realtime) input. Syntmono can output data in realtime, .wav, .snd, .aif, .mat (Matlab MAT-file), and/or .raw formats. Assuming you have successfully compiled the syntmono executable, a scorefile can be redirected to syntmono and the output heard in realtime in the following way:
syntmono Clarinet -or < scores/streetsf.ski
The "-or" flag specifies the realtime output option. Typing syntmono without arguments will provide a brief description of the instruments possible and the various input/output option flags. Tcl/Tk GUIs are provided in the "tcl" directory of each project, though you will have to install Tcl/Tk version 8.0 or higher on your system to use them (older versions of Tcl/Tk under Linux seem to be more forgiving than under IRIX). Realtime SKINI control data can be piped to syntmono from a Tcl/Tk GUI on Unix platforms and WinNT in the following way:
wish < TCLSpecs/TCLPhys.tcl | syntmono Clarinet -or -ip
The "-ip" flag specifies piped realtime input. It is not possible to use realtime pipes under Windoze95/98, so socket communication must be used instead. For socket communication, it is necessary to first start the syntmono socket server using the "-is" flag (socketed realtime input). For the time being, a default (hardwired) socket port of 2001 is being used by syntmono. After syntmono is running (and waiting for a socket client connection), a Tcl/Tk GUI can be started. When using the GUI, it is necessary to invoke the "communications" menu item and select "socket" to establish the connection. The same procedure is also possible on Unix platforms. Finally, realtime MIDI control input can be used to control syntmono by typing:
syntmono Clarinet -or -im
The "-im" flag specifies realtime MIDI input. It is possible to use piped, socketed, and/or MIDI control input simultaneously.
DISCLAIMER:
You probably already guessed this, but just to be sure, we don't guarantee anything works. :-) It's free ... what do you expect? If you find a bug, please let us know and we'll try to correct it. You can also make suggestions, but again, no guarantees. Send email to prc@cs.princeton.edu and gary@ccrma.stanford.edu.
LEGAL AND ETHICAL:
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.
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'll not state what's freely useable here, but we'll try to note within the various classes where certain things are likely to be protected by patents.
FURTHER READING:
For more documentation on this ToolKit, the classes, etc., read the file Hierarchy.txt and the individual class definitions. Also check the platform specific README's for specific system requirements.
PERRY'S NOTES FROM THE ORIGINAL DISTRIBUTION:
This whole world was created with no particular hardware in mind. These examples are intended to be tutorial in nature, as a platform for the continuation of my research, and as a possible starting point for a software synthesis system. The basic motivation was to create the necessary unit generators to do the synthesis, processing, and control that I want to do and teach about. Little thought for optimization was given (see Object.cpp), and therefore improvements, especially speed enhancements, should be possible with these classes. It was written with some basic concepts in mind about how to let compilers optimize.
Your question at this point might be, "But Perry, with CMix, CMusic, CSound, CShells, CMonkeys, etc. already cluttering the landscape, why a new set of stupid C functions for music synthesis and processing?" The answers lie below.
1) I needed to port many of the things I've done
into something which is generic enough to port
further to different machines.
2) I really plan to document this stuff, so that
you don't have to be me to figure out what's
going on. (I'll probably be sorry I said this
in a couple of years, when even I can't figure
out what I was thinking.)
3) The classic difficulties most people have in
trying to implement physical models are:
A) They have trouble understanding the papers,
and/or in turning the theory into practice.
B) The Physical Model instruments are a pain to get
to oscillate, and coming up with stable and
meaningful parameter values is required to
get the models to work at all.
This set of C++ unit generators and instruments
might help to diminish the scores of emails I
get asking what to do with those block diagrams
I put in my papers.
4) I wanted to try some new stuff with modal synthesis,
and implement some classic FM patches as well.
5) I wanted to reimplement, and newly implement
more of the intelligent and physical performer
models I've talked about in some of my papers.
But I wanted to do it in a portable way, and in
such a way that I can hook up modules quickly.
I also wanted to make these instruments connectable
to such player objects, so folks like Brad Garton
who really think a lot about the players can connect
them to my instruments, a lot about which I think.
6) More rationalizations to follow . . .

90
doc/ReleaseNotes.txt Normal file
View File

@@ -0,0 +1,90 @@
STK: A ToolKit of Audio Synthesis Classes and Instruments in C++
Release 3.2
By Perry R. Cook, 1995-2000
and Gary P. Scavone, 1997-2000
v3.2: (13 November 2000)
- new control handling class (Controller)
- added AIFF file input/output support
- stklib.a Makefile in src directory
- added C++ error handling capabilities
- added input/output internet streaming support (StrmWvIn/StrmWvOut)
- added native ALSA support for linux
- added optional "device" argument to all "Rt" classes (audio and MIDI) and printout of devices when argument is invalid
- WvIn classes rewritten to support very big files (incremental load from disk)
- changed WvIn/WvOut classes to work with sample frame buffers
- fixed looping and negative rate calculations in WvIn classes
- fixed interpolation bug in RtWvIn
- windoze RtAudio code rewritten (thanks Dave!)
- simplified byte-swapping functions (in-place swapping)
- new FIR filter class (thanks Julius!)
- "stereo-ized" RagaMatic
- probably a bunch more fixes that I've long since forgotten about
v3.1: (13 March 2000)
- new RagaMatic project!!!
- added "microphone position" to Mandolin in STKdemo
- fixed MIDI system message exclusion under Irix
- added a few bitmaps for the Shaker instruments
- made destructors virtual for Reverb.h, WvIn.h and Simple.h
- fixed bug setting delay length in DLineA when value too big
- fixed bug in WinMM realtime code (RTSoundIO)
- added tick() method to BowTabl, JetTabl, and ReedTabl (same as lookup)
- switched to pthread API on SGI platforms
- added some defines to Object.h for random number generation, FPU overflow checking, etc...
- a lot of minor changes, some bug fixes ... can't remember all of them
v3.0: (10 October 1999)
- new #define flags for OS and realtime dependencies (this will probably cause problems for most everyone, but it was necessary to make future ports easier)
- fixed Linux MIDI input bug
- fixed MIDI status masking problem in Windows
- OS type defines now in Makefile
- new RAWWAVE_PATH define in Object.h
- syntmono pulled out to separate directory and cleaned up
- socketing capabilities under Unix, as well as Windoze
- multiple simultaneous socket client connections to STK servers now possible
- MD2SKINI now can merge MIDI and piped messages under Irix and Linux (for TCL->MD2SKINI->syntmono control)
- defined INT16 and INT32 types and fixed various WvIn and WvOut classes
- updated MatWvIn and MatWvOut for new MAT-file documentation from Matlab
- new demo GUI
- minor fixes to FM behavior
- added record/duplex capabilities to RTSoundIO (Linux, SGI, and Windoze)
- fixed bugs in WavWvOut and MatWvOut header specifications
- added RawWvOut class
- new WvIn class with RawWvIn, SndWvIn, WavWvIn, MatWvIn, and RTWvIn subclasses
- removed RawWave, RawShot, RawInterp, and RawLoop classes (supplanted by RawWvIn)
- multi-channel data support in WvIn and WvOut classes using MY_MULTI data type (pointer to MY_FLOAT) and the methods mtick() and mlastOutput()
- now writing to primary buffer under Windoze when allowed by hardware
- cleaned up Object.h a bit
- pulled various utility and thread functions out of syntmono.cpp (to aid readability of the code)
v2.02: (16 November 1998)
- 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).
- modified DrumSynt to correctly handle sample rates different than 22050 Hz.
- 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.
- fixed DirectSound playback bug in Win distribution. Sound was being played at 8-bit, 22 kHz in all cases. Playback is now 16-bit and dependent on SRATE.
- fixed bug in MD2SKINI which prevented some NoteOff statements from being output.
v2.01: (27 July 1998)
- Corrected extraneous ^M line return characters that were incompatible with SGI.
v2.0: (20 July 1998)
- The first true release by Gary, with unified capabilities across SGI, Linux, and Win platforms. See WWW pages (http://www-ccrma.stanford.edu/CCRMA/Software/STK/) for more info.
v1.1:
- More linux support and other changes that happened so long ago that I can't remember anymore. Never officially released.
v1.0:
- Linux support added with the help of Tim Stilson. Never officially released.
v0.8:
- One of (if not THE) original distributions for SGI, NeXTStep, and basic Win support. I think this came out in 1996.

395
doc/SKINI11.txt Normal file
View File

@@ -0,0 +1,395 @@
This describes the 1.1 implementation of SKINI,
updated for the 2.x release of STK:
Synthesis toolKit Instrument Network Interface
for the Synthesis Toolkit in C++ by Perry R. Cook
and Gary Scavone, 1999.
*********************************
* Too good to be true? *
* Have control and read it too? *
* A SKINI Haiku. *
*********************************
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.
1) 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.
2) 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. SKINI11 represents a profound advance beyond SKINI08
and SKINI09 (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.
3) 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
SKINI11.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.
NonMIDI 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 NonMIDI 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
SKINI11.tbl.
The other important file used by SKINI is SKINI11.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.
4) C Files Used To Implement SKINI11
SKINI11.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.
SKINI11.msg should be included by anything wanting to use the
SKINI11.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.
SKINI11.tbl is used only by the SKINI parser object (SKINI11.cpp).
In the file SKINI11.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.
5) 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:
a) If the first (non-delimiter (see c)) character in a SKINI
string is '/' that line is treated as a comment and echoed
to stdout.
b) 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.
c) 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 Readability, multiple messages per line doesn't help much,
so it's unlikely to be supported later).
d) The first field must be a SKINI message name. (like NoteOn).
These might become case-insensitive in SKINI11+, 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.
e) The second field must be a time specification in seconds.
For real-time applications, this field can be 0.0. A time
field can be either delta-time (most common and the only one
supported in SKINI0.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
100ms., 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 SKINI1.1 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).
f) 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.
g) All remaining fields are specified in the SKINI11.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.
6) A Short SKINI File:
/* Howdy!!! Welcome to SKINI11, 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
7) The SKINI11.tbl File, How Messages are Parsed
The SKINI11.tbl file contains an array of structures which
are accessed by the parser object SKINI11.cpp. The struct is:
struct SKINISpec { char messageString[32];
long type;
long data2;
long data3;
};
so an assignment of one of these structs looks like:
MessageStr$ ,type, data2, data3,
type is the message type sent back from the SKINI line parser.
data<n> 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
256bytes 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 SKINI11.tbl file
{"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},
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 SKINI11.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:
ControlChange 0.000000 2 7 64.1
Volume 0.000000 2 64.1
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.
8) Objects using SKINI
Here's a simple example of code which uses the SKINI object
to read a SKINI file and control a single instrument.
instrument = new Mandolin(50.0);
score = new SKINI11(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 * SRATE);
for (i=0;i<tempLong;i++) {
output.tick(instrument->tick());
}
tempDouble3 = score->getByteThree();
if (score->getType()== __SK_NoteOn_ ) {
tempDouble3 *= NORM_7;
if (score->getByteThree() == 0) {
tempDouble3 = 0.5;
instrument->noteOff(tempDouble3);
}
else {
tempLong = (int) score->getByteTwo();
tempDouble2 = __MIDI_To_Pitch[tempLong];
instrument->noteOn(tempDouble2,tempDouble3);
}
}
else if (score->getType() == __SK_NoteOff_) {
tempDouble3 *= NORM_7;
instrument->noteOff(tempDouble3);
}
else if (score->getType() == __SK_ControlChange_) {
tempLong = score->getByteTwoInt();
instrument->controlChange(tempLong,temp3.0);
}
score->nextMessage();
}
When the score (SKINI11 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.