From a6381b9d3819ea7b029306191e350fcd98aca88f Mon Sep 17 00:00:00 2001 From: Gary Scavone Date: Tue, 24 Mar 2009 23:02:14 -0400 Subject: [PATCH] Version 4.2.0 --- INSTALL | 10 +- README | 57 +- configure.ac | 29 +- doc/Hierarchy.txt | 35 +- doc/README-Linux.txt | 15 +- doc/README-MacOSX.txt | 9 +- doc/README-SGI.txt | 2 + doc/README-Win.txt | 6 +- doc/ReleaseNotes.txt | 24 +- doc/SKINI.txt | 111 +- doc/doxygen/Doxyfile | 16 +- doc/doxygen/compile.txt | 28 +- doc/doxygen/control.txt | 113 +- doc/doxygen/crealtime.txt | 26 + doc/doxygen/download.txt | 42 +- doc/doxygen/filtering.txt | 88 + doc/doxygen/footer.html | 2 +- doc/doxygen/fundamentals.txt | 63 + doc/doxygen/hello.txt | 61 +- doc/doxygen/index.txt | 6 +- doc/doxygen/information.txt | 40 +- doc/doxygen/instruments.txt | 62 +- doc/doxygen/links.txt | 8 +- doc/doxygen/multichannel.txt | 58 +- doc/doxygen/polyvoices.txt | 112 +- doc/doxygen/realtime.txt | 64 +- doc/doxygen/skini.txt | 92 +- doc/doxygen/system.txt | 15 +- doc/doxygen/tutorial.txt | 11 +- doc/doxygen/usage.txt | 53 +- include/ADSR.h | 51 +- include/Asymp.h | 84 + include/BandedWG.h | 84 +- include/BeeThree.h | 25 +- include/BiQuad.h | 39 +- include/BlowBotl.h | 57 +- include/BlowHole.h | 75 +- include/BowTabl.h | 62 - include/BowTable.h | 67 + include/Bowed.h | 60 +- include/Brass.h | 59 +- include/Chorus.h | 56 +- include/Clarinet.h | 59 +- include/Delay.h | 59 +- include/DelayA.h | 46 +- include/DelayL.h | 42 +- include/Drummer.h | 45 +- include/Echo.h | 51 +- include/Effect.h | 67 + include/Envelope.h | 42 +- include/FM.h | 71 +- include/FMVoices.h | 35 +- include/Filter.h | 81 +- include/Flute.h | 79 +- include/FormSwep.h | 57 +- include/Function.h | 52 + include/Generator.h | 51 + include/HevyMetl.h | 25 +- include/Instrmnt.h | 38 +- include/JCRev.h | 43 +- include/JetTabl.h | 44 - include/JetTable.h | 49 + include/Mandolin.h | 43 +- include/Mesh2D.h | 70 +- include/Messager.h | 215 +- include/MidiFileIn.h | 131 ++ include/Modal.h | 74 +- include/ModalBar.h | 19 +- include/Modulate.h | 46 +- include/Moog.h | 41 +- include/Mutex.h | 70 + include/NRev.h | 41 +- include/Noise.h | 30 +- include/OnePole.h | 34 +- include/OneZero.h | 34 +- include/PRCRev.h | 39 +- include/PercFlut.h | 27 +- include/Phonemes.h | 23 +- include/PitShift.h | 45 +- include/PluckTwo.h | 63 +- include/Plucked.h | 42 +- include/PoleZero.h | 36 +- include/{ReedTabl.h => ReedTable.h} | 43 +- include/Resonate.h | 44 +- include/Reverb.h | 58 - include/Rhodey.h | 27 +- include/RtAudio.h | 58 +- include/RtDuplex.h | 68 +- include/RtError.h | 2 +- include/RtMidi.h | 310 ++- include/RtWvIn.h | 46 +- include/RtWvOut.h | 47 +- include/SKINI.h | 127 -- include/SKINI.msg | 23 +- include/SKINI.tbl | 176 +- include/Sampler.h | 49 +- include/Saxofony.h | 63 +- include/Shakers.h | 93 +- include/Simple.h | 47 +- include/SingWave.h | 58 +- include/Sitar.h | 48 +- include/Skini.h | 117 + include/Socket.h | 19 +- include/Sphere.h | 43 +- include/StifKarp.h | 65 +- include/Stk.h | 184 +- include/SubNoise.h | 24 +- include/Table.h | 41 +- include/TcpWvIn.h | 70 +- include/TcpWvOut.h | 46 +- include/Thread.h | 87 +- include/TubeBell.h | 25 +- include/TwoPole.h | 33 +- include/TwoZero.h | 33 +- include/Vector3D.h | 35 +- include/VoicForm.h | 55 +- include/Voicer.h | 76 +- include/WaveLoop.h | 38 +- include/Whistle.h | 69 +- include/Wurley.h | 27 +- include/WvIn.h | 127 +- include/WvOut.h | 89 +- projects/demo/Drums | 1 + projects/demo/Makefile.in | 25 +- projects/demo/Md2Skini.cpp | 431 ++-- projects/demo/Md2Skini.dsp | 20 +- projects/demo/Modal | 1 + projects/demo/Modal.bat | 2 +- projects/demo/Physical | 1 + projects/demo/Physical.bat | 2 +- projects/demo/Shakers | 1 + projects/demo/StkDemo | 1 + projects/demo/StkDemo.bat | 2 +- projects/demo/Voice | 1 + projects/demo/Voice.bat | 2 +- projects/demo/demo.cpp | 365 +-- projects/demo/demo.dsp | 64 +- projects/demo/tcl/Demo.tcl | 2 +- projects/demo/utilities.cpp | 63 +- projects/demo/utilities.h | 2 +- projects/effects/Effects | 1 + projects/effects/Effects.bat | 2 +- projects/effects/Makefile.in | 16 +- projects/effects/effects.cpp | 368 +-- projects/effects/effects.dsp | 44 +- projects/effects/tcl/Effects.tcl | 8 +- projects/examples/Makefile.in | 33 +- projects/examples/bethree.cpp | 106 +- projects/examples/bethree.dsp | 18 +- projects/examples/controlbee.cpp | 204 +- projects/examples/controlbee.dsp | 16 +- projects/examples/crtsine.cpp | 78 + projects/examples/crtsine.dsp | 134 ++ projects/examples/examples.dsw | 12 + projects/examples/foursine.cpp | 4 +- projects/examples/foursine.dsp | 14 +- projects/examples/io.cpp | 32 +- projects/examples/io.dsp | 4 +- projects/examples/libMakefile.in | 9 +- projects/examples/midifiles/bwv772.mid | Bin 0 -> 4569 bytes projects/examples/midifiles/jesu.mid | Bin 0 -> 17539 bytes projects/examples/midifiles/tango.mid | Bin 0 -> 12274 bytes projects/examples/play.cpp | 97 +- projects/examples/play.dsp | 4 +- projects/examples/playsmf.cpp | 122 + projects/examples/record.cpp | 15 +- projects/examples/record.dsp | 4 +- projects/examples/rtsine.cpp | 16 +- projects/examples/rtsine.dsp | 10 +- projects/examples/sine.cpp | 8 +- projects/examples/sine.dsp | 4 +- projects/examples/sineosc.cpp | 2 +- projects/examples/sineosc.dsp | 4 +- projects/examples/tcpIn.cpp | 13 +- projects/examples/tcpIn.dsp | 8 +- projects/examples/tcpOut.cpp | 2 +- projects/examples/tcpOut.dsp | 4 +- projects/examples/threebees.cpp | 204 +- projects/examples/threebees.dsp | 18 +- projects/ragamatic/Drone.cpp | 95 +- projects/ragamatic/Drone.h | 42 +- projects/ragamatic/Makefile.in | 12 +- projects/ragamatic/Raga | 1 + projects/ragamatic/Raga.bat | 2 +- projects/ragamatic/Tabla.cpp | 137 +- projects/ragamatic/Tabla.h | 39 +- projects/ragamatic/VoicDrum.cpp | 136 +- projects/ragamatic/VoicDrum.h | 39 +- projects/ragamatic/ragamat.cpp | 518 +++-- projects/ragamatic/ragamat.dsp | 44 +- src/ADSR.cpp | 191 +- src/Asymp.cpp | 115 + src/BandedWG.cpp | 394 ++-- src/BeeThree.cpp | 83 +- src/BiQuad.cpp | 92 +- src/BlowBotl.cpp | 131 +- src/BlowHole.cpp | 247 +- src/BowTabl.cpp | 63 - src/BowTable.cpp | 60 + src/Bowed.cpp | 183 +- src/Brass.cpp | 162 +- src/Chorus.cpp | 98 +- src/Clarinet.cpp | 138 +- src/Delay.cpp | 179 +- src/DelayA.cpp | 127 +- src/DelayL.cpp | 118 +- src/Drummer.cpp | 127 +- src/Echo.cpp | 72 +- src/Effect.cpp | 99 + src/Envelope.cpp | 97 +- src/FM.cpp | 176 +- src/FMVoices.cpp | 179 +- src/Filter.cpp | 261 ++- src/Flute.cpp | 201 +- src/FormSwep.cpp | 132 +- src/Function.cpp | 58 + src/Generator.cpp | 57 + src/HevyMetl.cpp | 92 +- src/Instrmnt.cpp | 53 +- src/JCRev.cpp | 134 +- src/JetTabl.cpp | 53 - src/JetTable.cpp | 49 + src/Makefile.in | 15 +- src/Mandolin.cpp | 153 +- src/Mesh2D.cpp | 316 +-- src/Messager.cpp | 702 +++--- src/MidiFileIn.cpp | 359 +++ src/Modal.cpp | 214 +- src/ModalBar.cpp | 99 +- src/Modulate.cpp | 56 +- src/Moog.cpp | 141 +- src/Mutex.cpp | 100 + src/NRev.cpp | 101 +- src/Noise.cpp | 29 +- src/OnePole.cpp | 69 +- src/OneZero.cpp | 68 +- src/PRCRev.cpp | 85 +- src/PercFlut.cpp | 93 +- src/Phonemes.cpp | 49 +- src/PitShift.cpp | 114 +- src/PluckTwo.cpp | 127 +- src/Plucked.cpp | 112 +- src/PoleZero.cpp | 73 +- src/{ReedTabl.cpp => ReedTable.cpp} | 49 +- src/Resonate.cpp | 127 +- src/Reverb.cpp | 60 - src/Rhodey.cpp | 87 +- src/RtAudio.cpp | 1433 +++++++----- src/RtDuplex.cpp | 122 +- src/RtMidi.cpp | 2844 +++++++++++++++--------- src/RtWvIn.cpp | 65 +- src/RtWvOut.cpp | 144 +- src/SKINI.cpp | 350 --- src/Sampler.cpp | 45 +- src/Saxofony.cpp | 179 +- src/Shakers.cpp | 1368 ++++++------ src/Simple.cpp | 105 +- src/SingWave.cpp | 105 +- src/Sitar.cpp | 112 +- src/Skini.cpp | 212 ++ src/Socket.cpp | 109 +- src/Sphere.cpp | 79 +- src/StifKarp.cpp | 216 +- src/Stk.cpp | 107 +- src/SubNoise.cpp | 28 +- src/Table.cpp | 82 +- src/TcpWvIn.cpp | 281 +-- src/TcpWvOut.cpp | 236 +- src/Thread.cpp | 127 +- src/TubeBell.cpp | 81 +- src/TwoPole.cpp | 65 +- src/TwoZero.cpp | 69 +- src/Vector3D.cpp | 52 +- src/VoicForm.cpp | 186 +- src/Voicer.cpp | 254 ++- src/WaveLoop.cpp | 108 +- src/Whistle.cpp | 252 ++- src/Wurley.cpp | 93 +- src/WvIn.cpp | 801 +++---- src/WvOut.cpp | 700 +++--- src/asio/asiolist.cpp | 8 +- 281 files changed, 17152 insertions(+), 12000 deletions(-) create mode 100644 doc/doxygen/crealtime.txt create mode 100644 doc/doxygen/filtering.txt create mode 100644 doc/doxygen/fundamentals.txt create mode 100644 include/Asymp.h delete mode 100644 include/BowTabl.h create mode 100644 include/BowTable.h create mode 100644 include/Effect.h create mode 100644 include/Function.h create mode 100644 include/Generator.h delete mode 100644 include/JetTabl.h create mode 100644 include/JetTable.h create mode 100644 include/MidiFileIn.h create mode 100644 include/Mutex.h rename include/{ReedTabl.h => ReedTable.h} (55%) delete mode 100644 include/Reverb.h delete mode 100644 include/SKINI.h create mode 100644 include/Skini.h create mode 100755 projects/demo/Drums create mode 100755 projects/demo/Modal create mode 100755 projects/demo/Physical create mode 100755 projects/demo/Shakers create mode 100755 projects/demo/StkDemo create mode 100755 projects/demo/Voice create mode 100755 projects/effects/Effects create mode 100644 projects/examples/crtsine.cpp create mode 100755 projects/examples/crtsine.dsp create mode 100644 projects/examples/midifiles/bwv772.mid create mode 100644 projects/examples/midifiles/jesu.mid create mode 100644 projects/examples/midifiles/tango.mid create mode 100644 projects/examples/playsmf.cpp create mode 100755 projects/ragamatic/Raga create mode 100644 src/Asymp.cpp delete mode 100644 src/BowTabl.cpp create mode 100644 src/BowTable.cpp create mode 100644 src/Effect.cpp create mode 100644 src/Function.cpp create mode 100644 src/Generator.cpp delete mode 100644 src/JetTabl.cpp create mode 100644 src/JetTable.cpp create mode 100644 src/MidiFileIn.cpp create mode 100644 src/Mutex.cpp rename src/{ReedTabl.cpp => ReedTable.cpp} (51%) delete mode 100644 src/Reverb.cpp delete mode 100644 src/SKINI.cpp create mode 100644 src/Skini.cpp diff --git a/INSTALL b/INSTALL index 8c67f9e..09e49aa 100644 --- a/INSTALL +++ b/INSTALL @@ -6,7 +6,7 @@ The Synthesis ToolKit in C++ can be used in a variety of ways, depending on your To configure and compile (on Unix systems): -1. Unpack the STK distribution (tar -xzf stk-4.x.tar.gz). +1. Unpack the STK distribution (tar -xzf stk-4.x.x.tar.gz). 2. From within the directory containing this file, run configure: ./configure @@ -18,11 +18,11 @@ Several options can be passed to configure, including: --disable-realtime = only compile generic non-realtime classes --enable-debug = enable various debug output - --with-alsa = choose native ALSA API support (linux only) + --with-alsa = choose native ALSA API support (default, linux only) --with-jack = choose native JACK server API support (linux only) - --enable-midiator = enable native MS-124W MIDI support (linux only) + --with-oss = choose native OSS API support (linux only) -At the moment, it is not possible to specify more than one Linux audio API, though this will change in the next release. Typing "./configure --help" will display all the available options. In addition, it is possible to specify the RAWWAVES and INCLUDE paths to configure as (ex. to set to /home/gary/rawwaves and /home/gary/include): +It is now possible to specify more than one Linux audio API. Note however that the ALSA library is required in order to compile the RtMidi class, even if the "--with-oss" option is provided (only the OSS audio API will be used, not the OSS MIDI API). Typing "./configure --help" will display all the available options. In addition, it is possible to specify the RAWWAVES and INCLUDE paths to configure as (ex. to set to /home/gary/rawwaves and /home/gary/include): ./configure RAWWAVE_PATH="/home/gary/rawwaves/" ./configure INCLUDE_PATH="/home/gary/include/" @@ -33,7 +33,7 @@ If you wish to use a different compiler than that selected by configure, specify ./configure CXX=CC -In addition, a linux RPM is available from the STK WWW site (http://www-ccrma.stanford.edu/software/stk/). +In addition, a linux RPM is available from the Planet CCRMA WWW site (http://ccrma.stanford.edu/planetccrma/software/). For Windows Users: diff --git a/README b/README index a8a494c..75f3a64 100644 --- a/README +++ b/README @@ -8,7 +8,7 @@ include: STK class header files src: STK class source files rawwaves: STK audio files (1-channel, 16-bit, big-endian) doc: STK documentation -projects: example STK programs +projects: example STK projects and programs Please read the Legal and Ethical notes near the bottom of this document. @@ -17,7 +17,7 @@ For compiling and installing STK, see the INSTALL file in this directory. OVERVIEW: -The Synthesis ToolKit in C++ (STK) is a set of open source audio signal processing and algorithmic synthesis classes written in C++. STK was designed to facilitate rapid development of music synthesis and audio processing software, with an emphasis on cross-platform functionality, realtime control, ease of use, and educational example code. The Synthesis ToolKit is extremely portable (it's mostly platform-independent C and C++ code), and it's completely user-extensible (all source included, no unusual libraries, and no hidden drivers). We like to think that this increases the chances that our programs will still work in another 5-10 years. In fact, the ToolKit has been working continuously for nearly 8 years now. STK currently runs with "realtime" support (audio and MIDI) on SGI (Irix), Linux, Macintosh OS X, and Windows computer platforms. Generic, non-realtime support has been tested under NeXTStep, Sun, and other platforms and should work with any standard C++ compiler. +The Synthesis ToolKit in C++ (STK) is a set of open source audio signal processing and algorithmic synthesis classes written in the C++ programming language. STK was designed to facilitate rapid development of music synthesis and audio processing software, with an emphasis on cross-platform functionality, realtime control, ease of use, and educational example code. The Synthesis ToolKit is extremely portable (it's mostly platform-independent C and C++ code), and it's completely user-extensible (all source included, no unusual libraries, and no hidden drivers). We like to think that this increases the chances that our programs will still work in another 5-10 years. In fact, the ToolKit has been working continuously for nearly 10 years now. STK currently runs with "realtime" support (audio and MIDI) on SGI (Irix), Linux, Macintosh OS X, and Windows computer platforms. Generic, non-realtime support has been tested under NeXTStep, Sun, and other platforms and should work with any standard C++ compiler. The Synthesis ToolKit 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 Tcl/Tk 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. Snd, Cool Edit, Matlab). @@ -31,13 +31,15 @@ SYSTEM REQUIREMENTS: See the individual README's (eg. README-linux) in the /doc directory for platform specific information and system requirements. In general, you will use the configure script to create Makefiles on 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: +WHAT'S NEW (AND NOT SO NEW): -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 Release Notes to see what has changed since the last release. +Despite being available in one form or another since 1996, we still consider STK to be alpha software. We attempt to maintain backward compatability but changes are sometimes made in an effort to improve the overall design or performance of the software. Please read the Release Notes to see what has changed since the last release. + +A new StkFrames class has been created to facilitate the handling and passing of multichannel, vectorized audio data. All STK classes have been updated to include tick() functions which accept StkFrames arguments. The control message handling scheme has been simplified greatly through the use of the Messager 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! +Realtime audio input capabilities were added to STK with release 3.0, though the behavior of such is very hardware dependent. Under Linux, Macintosh OS-X, 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. @@ -46,7 +48,7 @@ For those who wish to make a library from the core STK classes, the configure sc 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. +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 the mail list. LEGAL AND ETHICAL: @@ -62,53 +64,30 @@ The good news is that large hunks of the techniques used here are public domain. FURTHER READING: -For complete documentation on this ToolKit, the classes, etc., see the doc directory of the distribution or surf to http://www-ccrma.stanford.edu/software/stk/. Also check the platform specific README's for specific system requirements. +For complete documentation on this ToolKit, the classes, etc., see the doc directory of the distribution or surf to http://ccrma.stanford.edu/software/stk/. 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. +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 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. +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.) +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: +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. + 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. + 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. + 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. +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. +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 . . . diff --git a/configure.ac b/configure.ac index 83767de..99f1f7b 100644 --- a/configure.ac +++ b/configure.ac @@ -1,5 +1,5 @@ # Process this file with autoconf to produce a configure script. -AC_INIT(STK, 4.1.2, gary@ccrma.stanford.edu, stk) +AC_INIT(STK, 4.2.0, gary@music.mcgill.ca, stk) AC_CONFIG_SRCDIR(src/Stk.cpp) AC_CONFIG_FILES(src/Makefile projects/demo/Makefile projects/effects/Makefile projects/ragamatic/Makefile projects/examples/Makefile) @@ -48,12 +48,12 @@ fi AC_MSG_CHECKING(whether to compile debug version) AC_ARG_ENABLE(debug, [ --enable-debug = enable various debug output], - [AC_SUBST( debug, [-D_STK_DEBUG_] ) AC_SUBST( cflags, [-g] ) AC_SUBST( object_path, [Debug] ) AC_MSG_RESULT(yes)], - [AC_SUBST( debug, [] ) AC_SUBST( cflags, [-O2] ) AC_SUBST( object_path, [Release] ) AC_MSG_RESULT(no)]) + [AC_SUBST( debug, ["-D_STK_DEBUG_ -D__RTAUDIO_DEBUG__"] ) AC_SUBST( cflags, ["-g -O2"] ) AC_SUBST( object_path, [Debug] ) AC_MSG_RESULT(yes)], + [AC_SUBST( debug, [] ) AC_SUBST( cflags, [-O3] ) AC_SUBST( object_path, [Release] ) AC_MSG_RESULT(no)]) # Check compiler and use -Wall if gnu. if test $GXX = "yes" ; then - AC_SUBST( warn, ["-Wall -g"] ) + AC_SUBST( warn, ["-Wall -g -Woverloaded-virtual -D__GXX__"] ) fi if test $realtime = yes; then @@ -64,20 +64,22 @@ if test $realtime = yes; then *-*-linux*) AC_SUBST( sound_api, [_NO_API_] ) + # Look for ALSA library because we need it for RtMidi + AC_CHECK_LIB(asound, snd_pcm_open, , AC_MSG_ERROR(STK in Linux requires the ALSA asound library for RtMidi!)) + audio_apis="-D__LINUX_ALSASEQ__" + # Look for Jack flag AC_ARG_WITH(jack, [ --with-jack = choose JACK server support (linux only)], [AC_SUBST( sound_api, [-D__LINUX_JACK__] ) AC_MSG_RESULT(using JACK)] , ) if [test $sound_api = -D__LINUX_JACK__;] then TEMP_LIBS=$LIBS AC_CHECK_LIB(jack, jack_client_new, , AC_MSG_ERROR(JACK support requires the jack library!)) - AC_CHECK_LIB(asound, snd_pcm_open, , AC_MSG_ERROR(ALSA support requires the asound library!)) LIBS="`pkg-config --cflags --libs jack` $TEMP_LIBS -lasound" - audio_apis="-D__LINUX_JACK__" + audio_apis="-D__LINUX_JACK__ $audio_apis" fi # Look for Alsa flag AC_ARG_WITH(alsa, [ --with-alsa = choose native ALSA API support (linux only)], [AC_SUBST( sound_api, [-D__LINUX_ALSA__] ) AC_MSG_RESULT(using ALSA)], ) if test $sound_api = -D__LINUX_ALSA__; then - AC_CHECK_LIB(asound, snd_pcm_open, , AC_MSG_ERROR(ALSA support requires the asound library!)) audio_apis="-D__LINUX_ALSA__ $audio_apis" fi @@ -87,18 +89,15 @@ if test $realtime = yes; then audio_apis="-D__LINUX_OSS__ $audio_apis" fi - # If no audio api flags specified, use OSS + # If no audio api flags specified, use ALSA if [test $sound_api = _NO_API_;] then - AC_SUBST( sound_api, [-D__LINUX_OSS__] ) - AC_MSG_RESULT(using OSS) - AC_SUBST( audio_apis, [-D__LINUX_OSS__] ) + AC_MSG_RESULT(using ALSA) + audio_apis="-D__LINUX_ALSA__ $audio_apis" fi - - AC_ARG_ENABLE(midiator, [ --enable-midiator = enable native MS-124W MIDI support (linux only)], [AC_SUBST( midiator, [-D__MIDIATOR__] )], [AC_SUBST( midiator, [] )]) ;; *-sgi*) - AC_SUBST( audio_apis, ["-D__IRIX_AL__ -LANG:std -w"] ) + AC_SUBST( audio_apis, ["-D__IRIX_AL__ -D__IRIX_MD__ -LANG:std -w"] ) AC_MSG_RESULT(using IRIX AL) AC_CHECK_LIB(audio, alOpenPort, , AC_MSG_ERROR(IRIX audio support requires the audio library!) ) AC_CHECK_LIB(md, mdOpenInPort, , AC_MSG_ERROR(IRIX MIDI support requires the md library!) ) @@ -110,8 +109,6 @@ if test $realtime = yes; then [AC_SUBST( audio_apis, [-D__MACOSX_CORE__] )], [AC_MSG_ERROR(CoreAudio and/or CoreMIDI header files not found!)] ) AC_SUBST( frameworks, ["-framework CoreAudio -framework CoreMIDI -framework CoreFoundation"] ) - # Explicitly link with c++ library. - AC_CHECK_LIB(stdc++, printf, , AC_MSG_ERROR(Stk requires the C++ library!) ) ;; *) diff --git a/doc/Hierarchy.txt b/doc/Hierarchy.txt index 7952a3e..6a1f52a 100644 --- a/doc/Hierarchy.txt +++ b/doc/Hierarchy.txt @@ -4,11 +4,13 @@ By Perry R. Cook and Gary P. Scavone, 1995-2004. STK Classes - See the HTML documentation in the html directory for complete information. - .- Envelope - ADSR + + .- Generator - (Modulate, Noise, SingWave, Envelope) + | | | + | SubNoise ADSR + | Asymp | - |- Noise - SubNoise - | - |- Table + |- Function - (Table, BowTable, JetTable, ReedTable) | |- WvIn - (WaveLoop, RtWvIn, TcpWvIn) | @@ -19,24 +21,14 @@ STK Classes - See the HTML documentation in the html directory for complete info | DelayL FormSwep | DelayA | - |- Echo, Chorus, PitShift - | - |- RtAudio, RtMidi, Socket, Thread + |- RtAudio, RtMidi, RtDuplex, Socket, Thread, Mutex Stk -| - |- Reverb - (PRCRev, JCRev, NRev) + |- Effect - (Echo, Chorus, PitShift, PRCRev, JCRev, NRev) | - |- Modulate - | - |- SingWave - | - |- Voicer + |- Voicer, Message, Skini, MidiFileIn, Phonemes, Sphere, Vector3D | |- Messager | - |- SKINI - | - |- ReedTabl, JetTabl, BowTabl - | | .- FM - (HevyMetl, PercFlut, Rhodey, Wurley, TubeBell, BeeThree, FMVoices) | | | |- Modal - ModalBar @@ -66,8 +58,11 @@ Stk -| Master Class: Stk.cpp Sample rate, byte-swapping, error handling functionality -Sources: Envelope.cpp Linearly Goes to Target by Rate +Sources: Generator.cpp Abstract Base Class for Various Source Signal Classes + Function.cpp Abstract Base Class for Various Input/Output Mapping Classes + Envelope.cpp Linearly Goes to Target by Rate ADSR.cpp ADSR Flavor of Envelope + Asymp.cpp Exponentially Approaches Target Noise.cpp Random Number Generator SubNoise.cpp Random Numbers each N samples Table.cpp Lookup Table (assumes given data in big-endian format) @@ -140,7 +135,7 @@ Shakers.cpp PhISM statistical model for shakers and real-world sound effects Mesh2D.cpp Two-dimensional, rectilinear digital waveguide mesh. Whistle.cpp Hybrid physical/spectral model of a police whistle. -Reverb.cpp Reverberator Effects Processor Master Class for reverberators +Effect.cpp Effects Processor Base Class JCRev.cpp Chowning Reverberator 3 series allpass units, 4 parallel combs, 2 stereo delays NRev.cpp Another famous CCRMA Reverb 8 allpass, 6 parallel comb filters PRCRev.cpp Dirt Cheap Reverb by Cook 2 allpass, 2 comb filters @@ -160,7 +155,7 @@ demo.cpp Demonstration program for most synthesis algorithms effects.cpp Effects demonstration program ragamatic.cpp Nirvana just waiting to happen -SKINI.cpp SKINI file/message parser object +Skini.cpp SKINI file/message parser object SKINI.msg #defines for often used and universal MIDI/SKINI symbols SKINI.tbl Table of SKINI messages diff --git a/doc/README-Linux.txt b/doc/README-Linux.txt index 6c53ea2..8f64655 100644 --- a/doc/README-Linux.txt +++ b/doc/README-Linux.txt @@ -4,20 +4,15 @@ By Perry R. Cook and Gary P. Scavone, 1995-2004. Please read the file README and INSTALL for more general STK information. -Realtime support 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 also seem to perform well. You can read more about ALSA at http://www.alsa-project.org/. ALSA is open source and holds great promise for audio under Linux. The API is selected during compilation using either the __LINUX_ALSA__ or __LINUX_OSS__ definitions. The configure script uses the OSS API by default. The ALSA API can be selected by passing the "--with-alsa" option to configure. +Realtime audio support for Linux currently includes the Advanced Linux Sound Architecture (ALSA), the JACK low-latency audio server, and/or Open Sound System (OSS) APIs. One or more APIs are selected during compilation using the __LINUX_ALSA__, __LINUX_JACK__, and/or __LINUX_OSS__ definitions. Because the ALSA library is now integrated into the standard Linux kernel, it is the default audio/MIDI API with STK versions 4.2 and higher. The __LINUX_ALSASEQ__ definition is required to compile RtMidi with ALSA sequencer support. Native OSS MIDI support no longer exists in RtMidi. If the __LINUX_OSS__ preprocessor definition is specified, only OSS audio support will be compiled and RtMidi will still be compiled using the ALSA API. For this reason, STK now requires the asound library for realtime support. Realtime programs must also link with the pthread library. The OSS audio API can be selected by passing the "--with-oss" option to configure. -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. +The free version of OSS generally 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 also seem to perform well. You can read more about ALSA at http://www.alsa-project.org/. ALSA is open source and holds great promise for audio under Linux. + +STK should compile without much trouble under Linux. 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, you must provide the __MIDIATOR__ definition during compilation (in addition to either __LINUX_ALSA__ or __LINUX_OSS__) or pass the "--enable-midiator" option to configure. - -There are a few things that need to be done on your system to get the MIDIator working. Assuming you wish to attach the MIDIator to serial port 0, 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. +MIDIator support has been removed from RtMidi with STK versions 4.2 and higher. If you really need it, you can contact us to get an old distribution. NOTE REGARDING PTHREADS: diff --git a/doc/README-MacOSX.txt b/doc/README-MacOSX.txt index 9856452..70431e3 100644 --- a/doc/README-MacOSX.txt +++ b/doc/README-MacOSX.txt @@ -6,17 +6,16 @@ Please read the file README and INSTALL for more general STK information. Realtime support for Macintosh OS X uses the CoreAudio HAL API and is specified during compilation using the __MACOSX_CORE__ preprocessor definition. -It is necessary to download the OS X developer kit in order to compile STK. STK was successfully tested on OS X version 10.2. +It is necessary to install the OS X developer kit in order to compile STK. STK was successfully tested on OS X versions 10.2 and 10.3. -The internal Macintosh audio hardware typically supports a sample rate of 44100 Hz only. Therefore, it is necessary to either specify this rate as a command-line option to the STK example programs or to change the default sample rate inside the Stk.h file before compilation. In addition, the RT_BUFFER_SIZE, specified in Stk.h, could be increased (to a higher power of two) for more robust performance. +The internal Macintosh audio hardware typically supports a sample rate of 44100 Hz only. The default STK sample rate is now 44100 Hz and all current example programs use this rate. However, it is possible to manually override this value in some programs from the command-line. The default sample rate is set in Stk.h. In addition, the RT_BUFFER_SIZE, specified in Stk.h, could be increased (to a higher power of two) for more robust performance. There is a potential conflict between the STK Delay class and a Delay() function declared in OSUtils.h (which is included via ). In general, this conflict can be avoided via the use of a namespace (an explicit Delay::Delay declaration), though this made the Windows Visual C++ compiler barf. If you use STK classes within a project that includes the OSUtils.h file, you will likely need to make changes in STK classes that use the Delay class. Tcl/Tk on OS X: -The tcl/tk interpreter does not ship by default with OS X, but must be downloaded from the internet. The latest Tcl/Tk Aqua distribution (http://www.apple.com/downloads/macosx/unix_open_source/tcltk.html) has been successfully tested on a 10.2 system. The default installation will place a link to the wish interpretor at /usr/bin/wish. +The tcl/tk interpreter does not ship by default with OS X, but must be downloaded from the internet. The latest Tcl/Tk Aqua distribution (http://www.apple.com/downloads/macosx/unix_open_source/tcltk.html) has been successfully tested on 10.2 and 10.3 systems. The default installation will place a link to the wish interpretor at /usr/bin/wish. -Initial tests have shown somewhat poor response between changes made in the tcl/tk script and the resulting audio updates. +It appears that socket support in Tcl/Tk on OS X uses the Nagle algorithm, which produces poor response between changes made in the tcl/tk script and the resulting audio updates. Note that this is only a problem when using a socket connection from a Tcl/Tk script. -It is possible to connect a tcl/tk interface to an STK program via a socket connection. However, the tcl/tk interpreter does not appear to properly close the socket connection during disconnection. It is therefore necessary to type "Exit" in the STK program terminal window to properly exit the STK program. diff --git a/doc/README-SGI.txt b/doc/README-SGI.txt index 5be5d16..003a932 100644 --- a/doc/README-SGI.txt +++ b/doc/README-SGI.txt @@ -8,6 +8,8 @@ The project Makefiles are created by configure. If you have trouble running "ma 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. Release 4.0 of STK is confirmed to compile (with various warnings) using CC version 7.30. +The __IRIX_AL__ and __IRIX_MD__ preprocessor definitions are required for realtime audio and MIDI support. + 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! diff --git a/doc/README-Win.txt b/doc/README-Win.txt index b03e66b..db38b3c 100644 --- a/doc/README-Win.txt +++ b/doc/README-Win.txt @@ -15,7 +15,7 @@ Both the DirectSound and Steinberg ASIO audio APIs are supported for realtime au When using the DirectSound API for audio input, latency is typically pretty horrendous (should we be surprised?). Also, there is a slight 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 or XP or use an ASIO driver. I stopped supporting the WinMM audio output code with release 3.2. -Realtime MIDI input is supported using the winmm.lib API. +Realtime MIDI input/output is supported by RtMidi using the winmm.lib API and requires the __WINDOWS_MM__ preprocessor definition. 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 for a project, 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": @@ -27,7 +27,7 @@ Visual C++ 6.0 workspaces have been created for the various STK projects. Every 4. Under C/C++ > Preprocessor: Add "../../include" directory to the "extra include" field. -5. Under C/C++ > Preprocessor: Add "__WINDOWS_DS__" to the definitions field. +5. Under C/C++ > Preprocessor: Add "__WINDOWS_DS__", "__WINDOWS_MM__", and "__LITTLE_ENDIAN__ to the definitions field. 6. Add all the necessary files to the project. @@ -49,7 +49,7 @@ WINDOWS 95/98: PLAY SKINI SCOREFILES IN REALTIME: - demo Clarinet -or < scores/streetsf.ski + demo Clarinet -or -if scores/streetsf.ski USE TCL/TK GUIs FOR REALTIME CONTROL: diff --git a/doc/ReleaseNotes.txt b/doc/ReleaseNotes.txt index 84f1f0d..41590de 100644 --- a/doc/ReleaseNotes.txt +++ b/doc/ReleaseNotes.txt @@ -2,6 +2,28 @@ The Synthesis ToolKit in C++ (STK) By Perry R. Cook and Gary P. Scavone, 1995-2004. +v4.2.0: (4 October 2004) +- simultaneous multiple audio APIs supported at compile time +- fixed hidden overloaded virtual functions +- new Asymp exponential envelope class +- various changes to better conform to standard C++ programming practices +- MY_FLOAT type converted to StkFloat and changed throughout (use treesed utility to search/replace in old files) +- most example programs rewritten to use an audio callback paradigm (which works better in OS-X) +- new StkFrames class for vectorized multichannel data and associated new tick() functions making use of StkFrames +- new RtMidi class with MIDI output capabilities (API changes) +- new MidiFileIn class for reading MIDI files +- revised Filter classes to use std::vectors for coefficients (API changes) +- revised Messager class (now queues messages for retrieval) (API changes) +- new abstract parent Effect class for various effects +- added setT60 function to all reverbs +- new abstract parent Generator class for various signal sources +- new abstract parent Function class for tables and various non-linear functions +- Skini class completely rewritten (simplified) using the C++ STL (API changes) +- WvOut classes now clip to -1.0 to +1.0 and report out of range +- new Mutex class +- turned Nagle algorithm off by default in Socket class +- error reporting standardized in all classes + v4.1.3: (22 March 2004) - bug fix in RtAudio for Windows DirectSound output only support @@ -108,7 +130,7 @@ v3.0: (10 October 1999) - 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() +- multi-channel data support in WvIn and WvOut classes using MY_MULTI data type (pointer to StkFloat) 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) diff --git a/doc/SKINI.txt b/doc/SKINI.txt index d52dd02..d42c731 100644 --- a/doc/SKINI.txt +++ b/doc/SKINI.txt @@ -10,7 +10,7 @@ for the Synthesis Toolkit in C++ by Perry R. Cook. * A SKINI Haiku. * ********************************* -Profound thanks to Dan Trueman, Brad Garton, and +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 @@ -120,7 +120,7 @@ upon/from which to build and depart. 4) C Files Used To Implement SKINI - SKINI.cpp is an object which can either open a SKINI file, and + 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 @@ -128,11 +128,11 @@ upon/from which to build and depart. 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_ + 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). + 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. @@ -240,7 +240,7 @@ upon/from which to build and depart. 7) The SKINI.tbl File, How Messages are Parsed: The SKINI.tbl file contains an array of structures which - are accessed by the parser object SKINI.cpp. The struct is: + are accessed by the parser object Skini.cpp. The struct is: struct SKINISpec { char messageString[32]; long type; @@ -322,70 +322,67 @@ upon/from which to build and depart. 8) Objects using SKINI - Here's a simple example of code which uses the SKINI object + Here's a simple example of code which uses the Skini object to read a SKINI file and control a single instrument. + Skini score; + Skini::Message message; 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; - } + score.setFile( argv[1] ); + while ( score.nextMessage( message ) != 0 ) { + tempDouble = message.time; + 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;itick()); + } + tempLong = (long) ( tempDouble * Stk::sampleRate() ); + for ( i=0; itick() ); + } + + tempDouble3 = message.floatValues[1] * NORM_MIDI; + if ( message.type == __SK_NoteOn_ ) { + if ( tempDouble3 == 0.0 ) { + tempDouble3 = 0.5; + instrument->noteOff( tempDouble3 ); } - 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 { + tempLong = message.intValues[0]; + 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(); + } + else if ( message.type == __SK_NoteOff_ ) { + instrument->noteOff( tempDouble3 ); + } + else if ( message.type == __SK_ControlChange_ ) { + tempLong = message.intValues[0]; + instrument->controlChange( tempLong, tempDouble3 ); + } } - 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. + When a SKINI score is passed to a Skini object using the + Skini::setFile() function, valid messages are read from + the file and returned using the Skini::nextMessage() function. - 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. + A Skini::Message structure contains all the information parsed + from a single SKINI message. A returned message type of zero + indicates either an invalid message or the end of a scorefile. - 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 "time" member of a Skini::Message is 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, 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. diff --git a/doc/doxygen/Doxyfile b/doc/doxygen/Doxyfile index c829856..f4b1c07 100644 --- a/doc/doxygen/Doxyfile +++ b/doc/doxygen/Doxyfile @@ -4,7 +4,7 @@ # Project related configuration options #--------------------------------------------------------------------------- PROJECT_NAME = STK -PROJECT_NUMBER = +PROJECT_NUMBER = 4.2.0 OUTPUT_DIRECTORY = . OUTPUT_LANGUAGE = English USE_WINDOWS_ENCODING = NO @@ -18,10 +18,10 @@ STRIP_FROM_PATH = SHORT_NAMES = NO JAVADOC_AUTOBRIEF = NO MULTILINE_CPP_IS_BRIEF = NO -DETAILS_AT_TOP = NO +DETAILS_AT_TOP = YES INHERIT_DOCS = YES DISTRIBUTE_GROUP_DOC = NO -TAB_SIZE = 8 +TAB_SIZE = 9 ALIASES = OPTIMIZE_OUTPUT_FOR_C = NO OPTIMIZE_OUTPUT_JAVA = NO @@ -67,13 +67,13 @@ WARN_LOGFILE = INPUT = . \ ../../include FILE_PATTERNS = *.txt \ - *.h \ - *.cpp + *.msg \ + *.h RECURSIVE = YES EXCLUDE = ../../src/asio EXCLUDE_SYMLINKS = NO EXCLUDE_PATTERNS = -EXAMPLE_PATH = +EXAMPLE_PATH = ../../projects/examples EXAMPLE_PATTERNS = EXAMPLE_RECURSIVE = NO IMAGE_PATH = @@ -83,7 +83,7 @@ FILTER_SOURCE_FILES = NO # configuration options related to source browsing #--------------------------------------------------------------------------- SOURCE_BROWSER = YES -INLINE_SOURCES = NO +INLINE_SOURCES = YES STRIP_CODE_COMMENTS = YES REFERENCED_BY_RELATION = YES REFERENCES_RELATION = YES @@ -117,7 +117,7 @@ TREEVIEW_WIDTH = 250 #--------------------------------------------------------------------------- # configuration options related to the LaTeX output #--------------------------------------------------------------------------- -GENERATE_LATEX = YES +GENERATE_LATEX = NO LATEX_OUTPUT = latex LATEX_CMD_NAME = latex MAKEINDEX_CMD_NAME = makeindex diff --git a/doc/doxygen/compile.txt b/doc/doxygen/compile.txt index 32777d0..8eccfa1 100644 --- a/doc/doxygen/compile.txt +++ b/doc/doxygen/compile.txt @@ -5,7 +5,7 @@ The Synthesis ToolKit can be used in a variety of ways, depending on your partic \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) dependent. 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, Macintosh OS X, and Windows systems using the __LINUX_OSS__, __LINUX_ALSA__, __IRIX_AL__, __MACOSX_CORE__, __WINDOWS_DS__, or __WINDOWS_ASIO__ preprocessor definitions. +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) dependent. STK classes which require specific platform/OS support include RtAudio, RtWvOut, RtWvIn, RtDuplex, RtMidi, TcpWvIn, TcpWvOut, Socket, Thread, and Mutex. These classes currently can only be compiled on Linux, Irix, Macintosh OS X, and Windows systems. Without the "realtime" classes, it is still possible to read SKINI scorefiles for control input and to read and write to/from a variety of audio file formats (WAV, SND, AIFF, MAT-file, and RAW). If compiling for a "little-endian" host processor, the __LITTLE_ENDIAN__ preprocessor definition should be provided. @@ -25,25 +25,25 @@ STK compiles with realtime support on the following flavors of the Unix operatin Linux ALSA - __LINUX_ALSA__, __LITTLE_ENDIAN__ + __LINUX_ALSA__, __LINUX_ALSASEQ__, __LITTLE_ENDIAN__ asound, pthread Linux - OSS - __LINUX_OSS__, __LITTLE_ENDIAN__ - pthread + OSS (audio only, use ALSA for MIDI support) + __LINUX_OSS__, __LINUX_ALSASEQ__, __LITTLE_ENDIAN__ + asound, pthread Macintosh OS X CoreAudio __MACOSX_CORE__ - pthread, stdc++, CoreAudio, CoreMIDI, CoreFoundation + pthread, CoreAudio, CoreMIDI, CoreFoundation Irix AL - __IRIX_AL__ + __IRIX_AL__, __IRIX_MD__ audio, pthread @@ -51,21 +51,21 @@ STK compiles with realtime support on the following flavors of the Unix operatin The available C++ compilers on any of these systems can vary. -One approach in using STK is to simply copy the class files needed for a particular program into a project directory. Taking the sineosc.cpp example from the previous tutorial chapter, it would be necessary to set up a directory that includes the files sineosc.cpp, the rawwave file sinewave.raw in a subdirectory called rawwaves, and the header and source files for the classes Stk, WvIn, WaveLoop, and WvOut. The program could then be compiled on a Linux system using the GNU g++ compiler as follows: +One approach in using STK is to simply copy the class files needed for a particular program into a project directory. Taking the sineosc.cpp example from the previous tutorial chapter, it would be necessary to set up a directory that includes the files sineosc.cpp, the rawwave file sinewave.raw in a subdirectory called rawwaves, and the header and source files for the classes Stk, WvIn, WaveLoop, and WvOut. The program could then be compiled on a little-endian system, such as a PC running Linux, using the GNU g++ compiler as follows: \code g++ -Wall -D__LITTLE_ENDIAN__ -o sineosc Stk.cpp WvIn.cpp WaveLoop.cpp WvOut.cpp sineosc.cpp \endcode Note that the sineosc.cpp example does not make use of realtime audio or MIDI input/output classes. For programs using any of the STK realtime classes mentioned above, it is necessary to specify an audio/MIDI API preprocessor definition and link with the appropriate libraries or frameworks. -When working with a number of different projects that make use of ToolKit classes, the above approach can become cumbersome (especially when trying to synchronize with new STK releases). Most of the STK projects (e.g., demo, effects, ...) contain Makefiles (built by the configure script) which compile project-specific class objects from the distribution src and include directories. This approach makes it relatively easy when upgrading to a new STK release (by making path substitutions in the Makefile or by moving the projects to a similar relative path within the new STK source tree). A Makefile is provided in the projects/examples directory for compiling all the tutorial programs, as well as other example programs. To compile the sineosc.cpp program, for example, one need only type make sineosc from within the projects/examples directory. Note that this particular Makefile depends on a static library, as described in the next section. +When working with a number of different projects that make use of ToolKit classes, the above approach can become cumbersome (especially when trying to synchronize with new STK releases). Most of the STK projects (e.g., demo, effects, ...) contain Makefiles (built by the configure script) which compile project-specific class objects from the distribution src and include directories. This approach makes it relatively easy when upgrading to a new STK release (by making path substitutions in the Makefile or by moving the projects to a similar relative path within the new STK source tree). A Makefile is provided in the projects/examples directory for compiling all the tutorial programs, as well as other example programs. To compile the sineosc.cpp program, for example, one need only type make sineosc from within the projects/examples directory. \subsection library Library Use: -The STK distribution provides a Makefile that can be used on Unix systems to build a static library. After unpacking the distribution (tar -xzf stk-4.x.tar.gz), run the configure script by typing ./configure from the top level distribution directory (see the INSTALL file in the same directory for more information). Then from within the src directory, type make. After a successful build, you may wish to move the library (libstk.a) and the contents of the include directory to standard library and include search paths on your system. For example, the linux RPM distribution of STK puts the library in /usr/lib/ and the STK header files in /usr/include/stk/. +The STK distribution provides a Makefile that can be used on Unix systems to build a static library. After unpacking the distribution (tar -xzf stk-4.x.x.tar.gz), run the configure script by typing ./configure from the top level distribution directory (see the INSTALL file in the same directory for more information). Then from within the src directory, type make. After a successful build, you may wish to move the library (libstk.a) and the contents of the include directory to standard library and include search paths on your system. For example, the linux RPM distribution of STK puts the library in /usr/lib/ and the STK header files in /usr/include/stk/. -Assuming the library is located in a standard search path and the header files are located in /usr/include/stk/, the sineosc.cpp example from the previous tutorial chapter can be compiled on a Linux system using the GNU g++ compiler as follows: +Assuming the library is located in a standard search path and the header files are located in /usr/include/stk/, the sineosc.cpp example from the previous tutorial chapter can be compiled on a little-endian system using the GNU g++ compiler as follows: \code g++ -Wall -D__LITTLE_ENDIAN__ -I/usr/include/stk -o sineosc sineosc.cpp -lstk @@ -91,9 +91,9 @@ STK has been tested on Windows platforms using the Visual C++ compiler only. It The approach when using Visual C++ is to build a project which includes the necessary ToolKit files from the distribution src and include directories. For the example program from the previous tutorial chapter, create a VC++ console application project, add the Stk, WvIn, WaveLoop, and WvOut class files, as well as sineosc.cpp, and make sure the sinewave.raw file is in the subdirectory rawwaves. -For programs using any of the STK realtime classes mentioned above, it is necessary to link with the DirectSound (dsound.lib), winmm.lib, and Wsock32.lib libraries, select the multithreaded library, and provide the __LITTLE_ENDIAN__ and __WINDOWS_DS__ preprocessor definitions. +For programs using any of the STK realtime classes mentioned above, it is necessary to link with the DirectSound (dsound.lib), winmm.lib, and Wsock32.lib libraries, select the multithreaded library, and provide the __LITTLE_ENDIAN__, __WINDOWS_DS__, and __WINDOWS_MM__ preprocessor definitions. -For Steinberg ASIO support, use the __WINDOWS_ASIO__ preprocessor definition, include all the files in the src/asio/ directory (i.e., asio.h,cpp, asiodrivers.h,cpp, ...), and link with the winmm.lib, and Wsock32.lib libraries. +For Steinberg ASIO support, use the __WINDOWS_ASIO__ preprocessor definition (and the __WINDOWS_MM__ definition for RtMidi support), include all the files in the src/asio/ directory (i.e., asio.h,cpp, asiodrivers.h,cpp, ...), and link with the winmm.lib, and Wsock32.lib libraries. -[Next tutorial]   [Main tutorial page] +[Next tutorial]   [Main tutorial page] */ diff --git a/doc/doxygen/control.txt b/doc/doxygen/control.txt index 17d6b81..5b963f3 100644 --- a/doc/doxygen/control.txt +++ b/doc/doxygen/control.txt @@ -17,114 +17,27 @@ StringDetune 0.100000 2 12.0 NoteOff 1.000000 2 69.0 64.0 \endcode -MIDI messages (with the exception of Sysex) are easily represented within the SKINI protocol. +MIDI messages are easily represented within the SKINI protocol. -The class Messager can be used to acquire and parse MIDI messages from a MIDI device and SKINI messages from STDIN and socket connections. Many of the example programs included with the ToolKit distribution use a Messager instance to accept control input from the accompanying tcl/tk graphical user interfaces, from external MIDI devices, or from SKINI scorefiles. +The class Messager can be used to acquire and parse MIDI messages from a MIDI device and SKINI messages from STDIN and socket connections. Incoming messages are acquired asynchronously and saved to an internal message queue of Skini::Message types (MIDI messages are converted to the Skini:Message format). The user then uses the Messager:popMessage() function to retrieve incoming control messages. This function does not block, instead returning a message type of zero when no more messages are in the queue. Many of the example programs included with the ToolKit distribution use a Messager instance to accept control input from the accompanying tcl/tk graphical user interfaces, from external MIDI devices, or from SKINI scorefiles. -In the following example, we'll modify the bethree.cpp program from the previous tutorial chapter and incorporate a Messager class to allow control via a SKINI scorefile. +In the following example, we'll modify the bethree.cpp program from the previous tutorial chapter and incorporate a Messager class to allow control via SKINI messages read from a SKINI file. + +\include controlbee.cpp + +A realtime control message will usually have a delta time of zero, in which case it is processed as soon as possible. Non-realtime messages, normally from a scorefile, will usually have non-zero delta times. The scheme used in this example is designed to work for both scorefile and realtime input types. When no message is available from the queue, the instrument is "ticked" for DELTA_CONTROL_TICKS and then the queue is checked again. The value of DELTA_CONTROL_TICKS roughly defines the program "control rate" in a realtime context, though multiple available messages in the queue are processed in immediate succession when their delta time values are zero. + +The \c processMessage() function centralizes the handling of control messages. Other control update schemes can be implemented, perhaps using a separate thread or in the \c main() function, and this function should work in any context. + +Assuming the program is compiled as controlbee and the SKINI scorefile bookert.ski is in the scores directory, the program can be run as: \code -// controlbee.cpp - -#include "BeeThree.h" -#include "RtWvOut.h" -#include "Messager.h" -#include "SKINI.msg" -#include - -int main() -{ - // Set the global sample rate before creating class instances. - Stk::setSampleRate( 44100.0 ); - - Instrmnt *instrument = 0; - RtWvOut *output = 0; - Messager *messager = 0; - bool done = FALSE; - - try { - // Define and load the BeeThree instrument - instrument = new BeeThree(); - - // Define and open the default realtime output device for one-channel playback - output = new RtWvOut(1); - } - catch (StkError &) { - goto cleanup; - } - - try { - // Create a Messager instance to read from a redirected SKINI scorefile. - messager = new Messager(); - } - catch (StkError &) { - goto cleanup; - } - - // Play the instrument until the end of the scorefile. - int i, nTicks, type; - MY_FLOAT byte2, byte3, frequency; - while (!done) { - - // Look for new messages and return a delta time (in samples). - type = messager->nextMessage(); - if (type < 0) - done = TRUE; - - nTicks = messager->getDelta(); - try { - for ( i=0; itick( instrument->tick() ); - } - catch (StkError &) { - goto cleanup; - } - - if ( type > 0 ) { - // Process the new control message. - byte2 = messager->getByteTwo(); - byte3 = messager->getByteThree(); - - switch(type) { - - case __SK_NoteOn_: - frequency = (MY_FLOAT) 220.0 * pow( 2.0, (byte2 - 57.0) / 12.0 ); - instrument->noteOn( frequency, byte3 * ONE_OVER_128 ); - break; - - case __SK_NoteOff_: - instrument->noteOff( byte3 * ONE_OVER_128 ); - break; - - case __SK_ControlChange_: - instrument->controlChange( (int) byte2, byte3 ); - break; - - case __SK_AfterTouch_: - instrument->controlChange( 128, byte2 ); - break; - } - } - } - - cleanup: - delete instrument; - delete output; - delete messager; - - return 0; -} -\endcode - -Assuming the program is compiled as controlbee and the SKINI scorefile bookert.ski is in the scores directory, the scorefile could be redirected to the program as: - -\code -controlbee < scores/bookert.ski +controlbee scores/bookert.ski \endcode Only a few basic SKINI message type case statements are included in this example. It is easy to extend the program to support a much more elaborate set of instrument control parameters. -This example could also be easily extended to accept "realtime" control input messages via STDIN, socket, or MIDI connections. The Messager class constructor takes an optional argument consisting of a bitmask of the following options: STK_PIPE, STK_SOCKET, and/or STK_MIDI. +This example could also be easily extended to accept "realtime" control input messages via pipe, socket or MIDI connections. The Messager class provides Messager::startStdInput(), Messager::startSocketInput(), and Messager::startMidiInput() functions for this purpose. [Next tutorial]   [Main tutorial page] */ diff --git a/doc/doxygen/crealtime.txt b/doc/doxygen/crealtime.txt new file mode 100644 index 0000000..af70513 --- /dev/null +++ b/doc/doxygen/crealtime.txt @@ -0,0 +1,26 @@ +/*! \page crealtime Realtime Audio (callback) + +The previous section described the use of the RtWvOut class for realtime audio output. The RtWvOut::tick() function periodically pauses program execution in order to send a buffer of audio data to the computer's audio hardware (referred to as blocking functionality). These pauses will effectively limit a program's computations to the correct number of samples per second, which is defined by the sample rate of the hardware. + +An alternative scheme for audio input/output is to define a specific function in which audio computations are performed and to let the audio system call this function when more input/output data can be accepted by the hardware (referred to as a callback scheme). In this section, we show how the previous rtsine.cpp program can be modified to work in a callback scenario. There is no "single-sample" interface for this functionality. The callback function will be invoked automatically by the audio system controller (RtAudio) when new data is needed and it is necessary to compute a full audio buffer of samples at that time (see \ref callback for further information). + +\include crtsine.cpp + +The sinusoidal oscillator is created as before. The instantiation of RtAudio requires quite a few more parameters, including output/input device and channel specifiers, the data format, and the desired buffer length (in frames). In this example, we request a single output channel using the default output device, zero channels of input, the RtAudio data format which corresponds to an StkFloat, and the RT_BUFFER_SIZE defined in Stk.h. The last argument is an API-dependent buffering parameter (see RtAudio for further information). + +After the digital-to-analog converter (dac) and oscillator are successfully created, it is necessary to provide the audio system controller with a pointer to our callback function. The RtAudio::setStreamCallback() function takes a pointer to the callback function and an optional pointer to data that will be made available in the callback. In this example, we need to pass only the pointer to the oscillator. In more complex programs, it is typically necessary to put all shared data in a struct (see the next tutorial program for an example) or make use of global variables. + +Our callback routine is the \c tick() function. %Function arguments include a pointer to the audio data buffer, the buffer size (in frames), and the data pointer passed to the RtAudio::setStreamCallback() function (if it exists). It is necessary to cast these pointers to their corresponding data types before use. Our tick() routine simply "ticks" the oscillator for \c bufferSize counts and writes the result into the audio data buffer before returning. + +The \c main() function blocks at the std::cin.get() call until the user hits the "enter" key, after which the audio controller is shut down and program execution ends. + +\section callback Blocking vs. Callbacks + +Prior to version 4.2.0, all STK example projects and programs used blocking audio input/output functionality (typically with the RtWvIn, RtWvOut, or RtDuplex classes). In many instances, a blocking scheme results in a clearer and more straight forward program structure. Within a graphical user interface (GUI) programming context, however, callback routines are often more natural. + +The RtAudio class provides both blocking and callback routines for all supported audio APIs. It should be noted that it is easy to embed blocking calls within a thread to create "callback-like" functionality. In fact, this is what RtAudio does for those audio APIs which are naturally based on blocking routines (Linux ALSA and OSS, SGI Irix, and Windows DirectSound). It is much more difficult to make an inherently callback-based system work like a blocking scheme. RtAudio attempts to do this with the Linux JACK, Macintosh OS-X CoreAudio, and Windows ASIO APIs, but the result is not fully robust (audio over/underruns are more likely to occur). + +In order to allow all STK programs to function with equal proficiency on all supported computer platforms, a decision was made to modify the example projects to use audio callback routines. The result is a more complicated code structure, which is unfortunate given that we generally strive to make STK code as clear as possible for educational purposes. This was especially an issue with the demo program because it is designed to function in both realtime and non-realtime contexts. The use of global variables has been avoided by defining data structures to hold all variables which must be accessible to the callback routine and other functions. Alternative schemes for making control updates could be designed depending on particular program needs and constraints. + +[Next tutorial]   [Main tutorial page] +*/ diff --git a/doc/doxygen/download.txt b/doc/doxygen/download.txt index fb448f6..751de48 100644 --- a/doc/doxygen/download.txt +++ b/doc/doxygen/download.txt @@ -1,15 +1,39 @@ /*! \page download Download and Release Notes -Version 4.1.3, 22 March 2004

+Version 4.2.0, 4 October 2004

\section notes Release Notes: +\subsection v4dot2dot0 Version 4.2.0 + +
    +
  • Simultaneous multiple audio APIs supported at compile time.
    • +
  • Various changes to better conform to standard C++ programming practices.
    • +
  • Fixed hidden overloaded virtual functions.
    • +
  • New Asymp exponential envelope class.
    • +
  • MY_FLOAT type converted to StkFloat and changed throughout (use \c treesed utility to search/replace in old files).
    • +
  • Most example programs rewritten to use an audio callback paradigm (which works better in OS-X).
    • +
  • New StkFrames class for vectorized multichannel data and associated new tick() functions making use of StkFrames.
    • +
  • New RtMidi class with MIDI output capabilities (API changes).
    • +
  • New MidiFileIn class for reading MIDI files.
    • +
  • Revised Filter classes to use std::vectors for coefficients (API changes).
    • +
  • Revised Messager class (API changes).
    • +
  • New abstract parent Effect class for various effects.
    • +
  • New abstract parent Generator class for various signal sources.
    • +
  • New abstract parent Function class for tables and various non-linear functions.
    • +
  • Skini class completely rewritten (simplified) using the C++ STL (API changes).
    • +
  • WvOut classes now clip to -1.0 to +1.0 and report out of range.
    • +
  • New Mutex class.
    • +
  • Turned Nagle algorithm off by default in Socket class.
    • +
  • Error reporting standardized in all classes.
    • +
+ \subsection v4dot1dot3 Version 4.1.3
    @@ -30,7 +54,7 @@
  • Update to the contentsAt() method of Delay class.
  • WAV file fixes (8-bit) in WvIn and WvOut classes.
  • Configure script changes.
    • -
  • Updated include statements and appended "std::" as necessary throughout for compatibility with gcc 3.
    • +
  • Updated \ include statements and appended "std::" as necessary throughout for compatibility with gcc 3.
\subsection v4dot1dot1 Version 4.1.1 @@ -138,7 +162,7 @@
  • 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().
    • +
  • Multi-channel data support in WvIn and WvOut classes using MY_MULTI data type (pointer to StkFloat) 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).
    • @@ -160,11 +184,11 @@
    • 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.
    • 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.
      • -
    • 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.
      • +
    • 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.
    • 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.
      • -
    • 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. MD2SKINI | syntmono Clarinet -r -i). In addition, you can supply a filename argument to MD2SKINI and have it simultaneously record a SKINI score file for future reuse. -
    • Modifications to Object.h for OS_TYPE compilation dependencies. Makefile automatically determines OS_TYPE when invoked (if you have the GNU makefile utilities installed on your system). -
    • 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. +
    • 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. MD2SKINI | syntmono Clarinet -r -i). In addition, you can supply a filename argument to MD2SKINI and have it simultaneously record a SKINI score file for future reuse.
      • +
    • Modifications to Object.h for OS_TYPE compilation dependencies. Makefile automatically determines OS_TYPE when invoked (if you have the GNU makefile utilities installed on your system).
      • +
    • 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.
    */ diff --git a/doc/doxygen/filtering.txt b/doc/doxygen/filtering.txt new file mode 100644 index 0000000..3c24ec8 --- /dev/null +++ b/doc/doxygen/filtering.txt @@ -0,0 +1,88 @@ +/*! \page filtering Using Filters + +In this section, we demonstrate the use of a few of the STK filter classes. The Filter class provides functionality to implement a generalized digital filter of any type, similar to the \c filter function in Matlab. In this example, we create a Filter instance and initialize it with specific numerator and denominator coefficients. We then compute its impulse response for 20 samples. + +\code +#include "Filter.h" + +int main() +{ + StkFrames output( 20 ); // initialize StkFrames to 20 elements (defaults: 1 channel, interleaved) + output[0] = 1.0; + + std::vector numerator( 5, 0.1 ); // create and initialize numerator coefficients + std::vector denominator; // create empty denominator coefficients + denominator.push_back( 1.0 ); // populate our denomintor values + denominator.push_back( 0.3 ); + denominator.push_back( -0.5 ); + + Filter filter( numerator, denominator ); + + filter.tick( output ); + for ( unsigned int i=0; ivector, a container object provided by the C++ Standard Library. + +Most STK classes use more specific types of digital filters, such as the OneZero, OnePole, TwoPole, or BiQuad varieties. These classes inherit from the Filter class and provide specific functionality particular to their use, as well as functions to independently control individual coefficient values. + +\section reson Resonances: + +The STK BiQuad and TwoPole classes provide functionality for creating resonance filters. The following example demonstrates how to create a resonance centered at 440 Hz that is used to filter the output of a Noise generator. + +\code +#include "BiQuad.h" +#include "Noise.h" + +int main() +{ + StkFrames output( 20 ); // initialize StkFrames to 20 elements (defaults: 1 channel, interleaved) + Noise noise; + + BiQuad biquad; + biquad.setResonance( 440.0, 0.98, true ); // automatically normalize for unity peak gain + + for ( unsigned int i=0; iNext tutorial]   [Main tutorial page] +*/ diff --git a/doc/doxygen/footer.html b/doc/doxygen/footer.html index 5f091b7..132c535 100644 --- a/doc/doxygen/footer.html +++ b/doc/doxygen/footer.html @@ -1,7 +1,7 @@
    - +
    The Synthesis ToolKit in C++ (STK)
    The Synthesis ToolKit in C++ (STK)
    ©1995-2004 Perry R. Cook and Gary P. Scavone. All Rights Reserved.
    diff --git a/doc/doxygen/fundamentals.txt b/doc/doxygen/fundamentals.txt new file mode 100644 index 0000000..669e97d --- /dev/null +++ b/doc/doxygen/fundamentals.txt @@ -0,0 +1,63 @@ +/*! \page fundamentals STK Fundamentals + +The Synthesis ToolKit is implemented in the C++ programming language. STK does not attempt to provide a new programming environment or paradigm but rather provides a set of objects which can be used within a normal C++ programming framework. Therefore, it is expected that users of STK will have some familiarity with C/C++ programming concepts. That said, the STK classes do have some particular idiosyncrasies that we will mention here. + +\section Signal Computations: + +Audio and control signals throughout STK use a floating-point data type, StkFloat, the exact precision of which can be controlled via a typedef statement in Stk.h. By default, an StkFloat is a double-precision floating-point value. 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. + +In general, the computation and/or passing of values is performed on a "single-sample" basis. For example, the Noise class outputs random floating-point numbers in the range +/-1.0. The computation of such values occurs in the Noise::tick() function. The following program will generate 20 random floating-point (StkFloat) values in the range -1.0 to +1.0: + +\code +#include "Noise.h" + +int main() +{ + StkFloat output; + Noise noise; + + for ( unsigned int i=0; i<20; i++ ) { + output = noise.tick(); + std::cout << "i = " << i << " : output = " << output << std::endl; + } + + return 0; +} +\endcode + +Nearly all STK classes implement tick() functions which take and/or return sample values. Within the tick() function, 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() function also provides one or more overloaded tick() functions which can be used for vectorized computations, as shown in the next example. + +\code +#include "Noise.h" + +int main() +{ + StkFrames output(20); // initialize StkFrames to 20 elements (defaults: 1 channel, interleaved) + Noise noise; + + noise.tick( output ); + for ( unsigned int i=0; iNext tutorial]   [Main tutorial page] +*/ diff --git a/doc/doxygen/hello.txt b/doc/doxygen/hello.txt index fed12eb..31096c0 100644 --- a/doc/doxygen/hello.txt +++ b/doc/doxygen/hello.txt @@ -1,6 +1,6 @@ /*! \page hello Hello Sine! -We'll begin our introduction to the Synthesis ToolKit with a simple sine-wave oscillator program. STK does not 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 (defined as monophonic, 16-bit, big-endian data). We use the class WvOut to write the result to a 16-bit, WAV formatted audio file. +We'll continue our introduction to the Synthesis ToolKit with a simple sine-wave oscillator program. STK does not 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 (defined as monophonic, 16-bit, big-endian data). We use the class WvOut to write the result to a 16-bit, WAV formatted audio file. \code @@ -15,11 +15,11 @@ int main() Stk::setSampleRate( 44100.0 ); // Define and load the sine wave file - WaveLoop *input = new WaveLoop( "rawwaves/sinewave.raw", TRUE ); + WaveLoop* input = new WaveLoop( "rawwaves/sinewave.raw", true ); input->setFrequency( 440.0 ); // Define and open a 16-bit, one-channel WAV formatted output file - output = new WvOut( "hellosine.wav", 1, WvOut::WVOUT_WAV, Stk::STK_SINT16 ); + WvOut* output = new WvOut( "hellosine.wav", 1, WvOut::WVOUT_WAV, Stk::STK_SINT16 ); // Run the oscillator for 40000 samples, writing to the output file int i; @@ -39,66 +39,17 @@ WaveLoop is a subclass of WvIn, which supports WAV, SND (AU), AIFF, MAT-file (Ma The WvIn and WvOut classes are complementary, both supporting 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. However, WvOut does not perform data interpolation. -Nearly all STK classes implement tick() functions which take and/or return sample values. Within the tick() function, 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() function 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. +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 44100 Hz. \section error Error Handling The ToolKit 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 "WvOut.h" - -int main() -{ - // Set the global sample rate before creating class instances. - Stk::setSampleRate( 44100.0 ); - - WaveLoop *input = 0; - WvOut *output = 0; - - try { - // Define and load the sine wave file - input = new WaveLoop( "rawwaves/sinewave.raw", TRUE ); - - // Define and open a 16-bit, one-channel WAV formatted output file - output = new WvOut( "hellosine.wav", 1, WvOut::WVOUT_WAV, Stk::STK_SINT16 ); - } - catch ( StkError & ) { - goto cleanup; - } - - input->setFrequency( 440.0 ); - - // Run the oscillator for 40000 samples, writing to the output file - for ( int i=0; i<40000; i++ ) { - - try { - output->tick( input->tick() ); - } - catch ( StkError & ) { - goto cleanup; - } - - } - - cleanup: - delete input; - delete output; - - return 0; -} -\endcode +\include sineosc.cpp 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. See the \ref classes to determine which constructors and functions can throw an error. -[Next tutorial]   [Main tutorial page] +[Next tutorial]   [Main tutorial page] */ diff --git a/doc/doxygen/index.txt b/doc/doxygen/index.txt index 63bdde7..2dfbf38 100644 --- a/doc/doxygen/index.txt +++ b/doc/doxygen/index.txt @@ -2,9 +2,11 @@ -

    Perry R. Cook & Gary P. Scavone

    +\htmlonly +

    Perry R. Cook & Gary P. Scavone

    +\endhtmlonly -The Synthesis ToolKit in C++ (STK) is a set of open source audio signal processing and algorithmic synthesis classes written in C++. STK was designed to facilitate rapid development of music synthesis and audio processing software, with an emphasis on cross-platform functionality, realtime control, ease of use, and educational example code. The Synthesis ToolKit is extremely portable (it's mostly platform-independent C and C++ code), and it's completely user-extensible (all source included, no unusual libraries, and no hidden drivers). We like to think that this increases the chances that our programs will still work in another 5-10 years. In fact, the ToolKit has been working continuously for nearly 8 years now. STK currently runs with "realtime" support (audio and MIDI) on SGI (Irix), Linux, Macintosh OS X, and Windows computer platforms. Generic, non-realtime support has been tested under NeXTStep, Sun, and other platforms and should work with any standard C++ compiler. +The Synthesis ToolKit in C++ (STK) is a set of open source audio signal processing and algorithmic synthesis classes written in the C++ programming language. STK was designed to facilitate rapid development of music synthesis and audio processing software, with an emphasis on cross-platform functionality, realtime control, ease of use, and educational example code. The Synthesis ToolKit is extremely portable (it's mostly platform-independent C and C++ code), and it's completely user-extensible (all source included, no unusual libraries, and no hidden drivers). We like to think that this increases the chances that our programs will still work in another 5-10 years. In fact, the ToolKit has been working continuously for nearly 10 years now. STK currently runs with "realtime" support (audio and MIDI) on SGI (Irix), Linux, Macintosh OS X, and Windows computer platforms. Generic, non-realtime support has been tested under NeXTStep, Sun, and other platforms and should work with any standard C++ compiler. - \ref information - \ref classes diff --git a/doc/doxygen/information.txt b/doc/doxygen/information.txt index d28da38..cda37ed 100644 --- a/doc/doxygen/information.txt +++ b/doc/doxygen/information.txt @@ -4,11 +4,11 @@