diff --git a/INSTALL b/INSTALL index 00d0ea1..c290a1a 100644 --- a/INSTALL +++ b/INSTALL @@ -1,6 +1,6 @@ The Synthesis ToolKit in C++ (STK) -By Perry R. Cook and Gary P. Scavone, 1995-2005. +By Perry R. Cook and Gary P. Scavone, 1995-2007. The Synthesis ToolKit in C++ can be used in a variety of ways, depending on your particular needs. Some people just choose the classes they need for a particular project and copy those to their project directory. Others like to compile and link to a library of object files. STK was not designed with one particular style of use in mind. @@ -19,10 +19,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 (default, linux only) - --with-jack = choose native JACK server API support (linux only) --with-oss = choose native OSS API support (linux only) + --with-jack = choose native JACK server API support (linux and macintosh OS-X) + --with-core = choose OS-X Core Audio API (macintosh OS-X only) -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): +It is now possible to specify more than one audio API where supported. 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)/rawwaves/' ./configure INCLUDE_PATH='$(HOME)/include/' diff --git a/README b/README index 8a9fe9c..8e23fb8 100644 --- a/README +++ b/README @@ -1,6 +1,6 @@ The Synthesis ToolKit in C++ (STK) -By Perry R. Cook and Gary P. Scavone, 1995-2005. +By Perry R. Cook and Gary P. Scavone, 1995-2007. This distribution of the Synthesis ToolKit in C++ (STK) contains the following: @@ -17,61 +17,180 @@ 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 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 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 +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). +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). -The Synthesis Toolkit is not one particular program. Rather, it is a set of C++ classes that you can use to create your own programs. A few example applications are provided to demonstrate some of the ways to use the classes. If you have specific needs, you will probably have to either modify the example programs or write a new program altogether. Further, the example programs don't have a fancy GUI wrapper. If you feel the need to have a "drag and drop" graphical patching GUI, you probably don't want to use the ToolKit. Spending hundreds of hours making platform-dependent graphics code would go against one of the fundamental design goals of the ToolKit - platform independence. +The Synthesis Toolkit is not one particular program. Rather, it is a +set of C++ classes that you can use to create your own programs. A +few example applications are provided to demonstrate some of the ways +to use the classes. If you have specific needs, you will probably +have to either modify the example programs or write a new program +altogether. Further, the example programs don't have a fancy GUI +wrapper. If you feel the need to have a "drag and drop" graphical +patching GUI, you probably don't want to use the ToolKit. Spending +hundreds of hours making platform-dependent graphics code would go +against one of the fundamental design goals of the ToolKit - platform +independence. -For those instances where a simple GUI with sliders and buttons is helpful, we use Tcl/Tk (http://dev.scriptics.com) which is freely distributed for all the supported ToolKit platforms. A number of Tcl/Tk GUI scripts are distributed with the ToolKit release. For control, the Synthesis Toolkit uses raw MIDI (on supported platforms), and SKINI (Synthesis ToolKit Instrument Network Interface, a MIDI-like text message synthesis control format). +For those instances where a simple GUI with sliders and buttons is +helpful, we use Tcl/Tk (http://dev.scriptics.com) which is freely +distributed for all the supported ToolKit platforms. A number of +Tcl/Tk GUI scripts are distributed with the ToolKit release. For +control, the Synthesis Toolkit uses raw MIDI (on supported platforms), +and SKINI (Synthesis ToolKit Instrument Network Interface, a MIDI-like +text message synthesis control format). 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. +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 (AND NOT SO NEW): -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. +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 that accept StkFrames arguments. +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 that 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. +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, 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! +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. +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, the configure script generates a Makefile in the src directory that will accomplish that (Linux, SGI, and Macintosh OS X only). +For those who wish to make a library from the core STK classes, the +configure script generates a Makefile in the src directory that will +accomplish that (Linux, SGI, and Macintosh OS X only). 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 the mail list. +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: -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. +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. +If you make a million dollars with it, it would be nice if you would +share. 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. +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. +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. + +LICENSE: + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +Any person wishing to distribute modifications to the Software is +asked to send the modifications to the original developer so that they +can be incorporated into the canonical version. This is, however, not +a binding provision of this license. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR +ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF +CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. FURTHER READING: -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. +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 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. +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. diff --git a/STK_TODO.txt b/STK_TODO.txt new file mode 100644 index 0000000..9bcc5e0 --- /dev/null +++ b/STK_TODO.txt @@ -0,0 +1,25 @@ +Ongoing STK "to do" list: + +- OSC server/client classes + +- move various error checks, especially in tick() functions, into __DEBUG__ blocks + +- more information reported in __DEBUG__ blocks + +- add funcionality for sample rate in MAT-file support + +- develop a good solution for multi-channel support in Instrumnt class (and others) + +- add WAVEFORMATEXTENSIBLE support to WvIn/WvOut? + +- port Blotar and Ublotar classes from PeRColate + +- consider further sample rate change updates in classes? + +- more documentation + + +To see differences: +------------------- + +diff -B -C2 -P -u original_src_dir new_src_dir > difffile.txt diff --git a/configure.ac b/configure.ac index f3c9e4e..5c35b0f 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.2.1, gary@music.mcgill.ca, stk) +AC_INIT(STK, 4.3, 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 projects/examples/libMakefile) @@ -69,12 +69,12 @@ if test $realtime = yes; then 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 + AC_ARG_WITH(jack, [ --with-jack = choose JACK server support (linux only)], [AC_SUBST( sound_api, [-D__UNIX_JACK__] ) AC_MSG_RESULT(using JACK)] , ) + if [test $sound_api = -D__UNIX_JACK__;] then TEMP_LIBS=$LIBS AC_CHECK_LIB(jack, jack_client_new, , AC_MSG_ERROR(JACK support requires the jack library!)) LIBS="`pkg-config --cflags --libs jack` $TEMP_LIBS -lasound" - audio_apis="-D__LINUX_JACK__ $audio_apis" + audio_apis="-D__UNIX_JACK__ $audio_apis" fi # Look for Alsa flag @@ -96,19 +96,33 @@ if test $realtime = yes; then fi ;; - *-sgi*) - 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!) ) - ;; - *-apple*) - # Check for CoreAudio and CoreMIDI framework - AC_CHECK_HEADERS(CoreAudio/CoreAudio.h CoreMIDI/CoreMIDI.h CoreServices/CoreServices.h, - [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"] ) + AC_SUBST( sound_api, [_NO_API_] ) + + # Look for JACK flag + AC_ARG_WITH(jack, [ --with-jack = choose JACK server support (unix only)], [AC_SUBST( sound_api, [-D__UNIX_JACK__] ) AC_MSG_RESULT(using JACK)], ) + if [test $sound_api = -D__UNIX_JACK__;] then + AC_CHECK_LIB(jack, jack_client_new, , AC_MSG_ERROR(JACK support requires the jack library!)) + audio_apis="-D__UNIX_JACK__" + fi + + # Look for Core flag + AC_ARG_WITH(core, [ --with-core = choose CoreAudio API support (mac only)], [AC_SUBST( sound_api, [-D__MACOSX_CORE__] ) AC_MSG_RESULT(using CoreAudio)], ) + if test $sound_api = -D__MACOSX_CORE__; then + AC_CHECK_HEADER(CoreAudio/CoreAudio.h, [], [AC_MSG_ERROR(CoreAudio header files not found!)] ) + AC_SUBST( frameworks, ["-framework CoreAudio -framework CoreFoundation -framework CoreMidi"] ) + audio_apis="-D__MACOSX_CORE__ $audio_apis" + fi + + # If no audio api flags specified, use CoreAudio + if [test $sound_api = _NO_API_;] then + AC_SUBST( sound_api, [-D__MACOSX_CORE__] ) + AC_MSG_RESULT(using CoreAudio) + AC_CHECK_HEADER(CoreAudio/CoreAudio.h, + [AC_SUBST( audio_apis, [-D__MACOSX_CORE__] )], + [AC_MSG_ERROR(CoreAudio header files not found!)] ) + AC_SUBST( frameworks, ["-framework CoreAudio -framework CoreFoundation -framework CoreMidi"] ) + fi ;; *) diff --git a/doc/README-Linux.txt b/doc/README-Linux.txt index 99fddaf..89da290 100644 --- a/doc/README-Linux.txt +++ b/doc/README-Linux.txt @@ -1,12 +1,10 @@ The Synthesis ToolKit in C++ (STK) -By Perry R. Cook and Gary P. Scavone, 1995-2005. +By Perry R. Cook and Gary P. Scavone, 1995-2007. Please read the file README and INSTALL for more general STK information. -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. - -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. +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 version 4.0 and higher only) APIs. One or more APIs are selected during compilation using the __LINUX_ALSA__, __UNIX_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. 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. diff --git a/doc/README-MacOSX.txt b/doc/README-MacOSX.txt index 1830b6d..e07de5e 100644 --- a/doc/README-MacOSX.txt +++ b/doc/README-MacOSX.txt @@ -1,10 +1,10 @@ The Synthesis ToolKit in C++ (STK) -By Perry R. Cook and Gary P. Scavone, 1995-2005. +By Perry R. Cook and Gary P. Scavone, 1995-2007. 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. +The default realtime support for Macintosh OS X uses the CoreAudio HAL API and is specified during compilation using the __MACOSX_CORE__ preprocessor definition. There is also support for the JACK low-latency audio server using the __UNIX_JACK__ preprocessor definition. It is necessary to install the OS X developer kit in order to compile STK. STK was successfully tested on OS X versions 10.4. diff --git a/doc/README-NeXT.txt b/doc/README-NeXT.txt index e9d59b1..16c651e 100644 --- a/doc/README-NeXT.txt +++ b/doc/README-NeXT.txt @@ -1,6 +1,6 @@ The Synthesis ToolKit in C++ (STK) -By Perry R. Cook and Gary P. Scavone, 1995-2005. +By Perry R. Cook and Gary P. Scavone, 1995-2007. Please read the file README and INSTALL for more general STK information. diff --git a/doc/README-SGI.txt b/doc/README-SGI.txt index febe80f..7ec2ad7 100644 --- a/doc/README-SGI.txt +++ b/doc/README-SGI.txt @@ -1,12 +1,12 @@ The Synthesis ToolKit in C++ (STK) -By Perry R. Cook and Gary P. Scavone, 1995-2005. +By Perry R. Cook and Gary P. Scavone, 1995-2007. Please read the file README and INSTALL for more general STK information. The project Makefiles are created by configure. If you have trouble running "make", try invoking "gmake" (for GNU make). If that doesn't work, try to download the GNU Makefile utilities from the Internet. -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. +With STK version 4.3, realtime support for IRIX has been discontinued due to the inability to test it. If you need realtime support on an SGI, go back to version 4.2.1. 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. diff --git a/doc/README-Win.txt b/doc/README-Win.txt index 5d78d14..4f1e03e 100644 --- a/doc/README-Win.txt +++ b/doc/README-Win.txt @@ -1,13 +1,13 @@ The Synthesis ToolKit in C++ (STK) -By Perry R. Cook and Gary P. Scavone, 1995-2005. +By Perry R. Cook and Gary P. Scavone, 1995-2007. Please read the file README for more general STK information. DirectX and WindowsNT Issues: ----------------------------- -STK is currently distributed with Visual C++ 6.0 project and workspace files. It has been tested using both Visual C++ 6.0 and Visual C++ .NET. +STK is currently distributed with Visual C++ .NET project and workspace files. It no longer compiles with Visual C++ 6.0. I gave up attempting to fix all the problems created by such a bad compiler. This version of STK has been tested using Visual C++ .NET. IMPORTANT VC++ NOTE: When compiling "release" versions of STK programs, link to the release multithreaded library. When compiling "debug" versions, link to the debug multithreaded library. Compiler errors will result otherwise. Also, the Microsoft folk are up to their old habits of trying to change standards. The .NET compiler will complain about cerr for some reason. @@ -17,7 +17,7 @@ When using the DirectSound API for audio input, latency is typically pretty horr 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": +Visual C++ 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" (this was for VC 6.0 ... things have changed with the newer versions of the VC compiler): 1. Under General: Set "Output files:" to (this will put the executable in the main project directory. diff --git a/doc/ReleaseNotes.txt b/doc/ReleaseNotes.txt index ed4439d..c946a58 100644 --- a/doc/ReleaseNotes.txt +++ b/doc/ReleaseNotes.txt @@ -1,13 +1,22 @@ The Synthesis ToolKit in C++ (STK) -By Perry R. Cook and Gary P. Scavone, 1995-2005. +By Perry R. Cook and Gary P. Scavone, 1995-2007. + +v4.3.0: (13 August 2007) +- an official MIT-like license +- new functionality to automatically update class data when the STK sample rate changes (partly implemented) +- updates for new RtAudio version 4.0 +- bug fix in interpolate() function in Stk.h for non-interleaved data +- fixes / improvements to the Granulate class +- fix in Whistle when doing animation +- fixes in BlitSquare for frequency, harmonics, and dc offset +- updates to Makefiles for non-realtime compile +- fix in demo.cpp for voice channel assignment +- updated versions of RtMidi and RtAudio +- updated ASIO files for MinGW compiler +- new FAQ in documentation +- MAT-file bug fix in FileRead class -Future To Do: -- OSC server/client classes -- move various error checks, especially in tick() functions, into __DEBUG__ blocks? -- add WAVEFORMATEXTENSIBLE support to RtAudio -- add WAVEFORMATEXTENSIBLE support to WvIn/WvOut? -- better documentation v4.2.1: (14 October 2005) - greatly expanded StkFrames functionality (including interpolation and indexing by channel/frame) diff --git a/doc/doxygen/Doxyfile b/doc/doxygen/Doxyfile index 795a16e..9d51253 100644 --- a/doc/doxygen/Doxyfile +++ b/doc/doxygen/Doxyfile @@ -4,7 +4,7 @@ # Project related configuration options #--------------------------------------------------------------------------- PROJECT_NAME = STK -PROJECT_NUMBER = 4.2.1 +PROJECT_NUMBER = 4.3 OUTPUT_DIRECTORY = . CREATE_SUBDIRS = NO OUTPUT_LANGUAGE = English diff --git a/doc/doxygen/compile.txt b/doc/doxygen/compile.txt index ff153aa..ce5c05b 100644 --- a/doc/doxygen/compile.txt +++ b/doc/doxygen/compile.txt @@ -1,6 +1,6 @@ /*! \page compile Compiling -The Synthesis ToolKit can be used in a variety of ways, depending on your particular needs. Some people choose the classes they need for a particular project and copy those to their working directory. Others create Makefiles which compile project-specific class objects from common src and include directories. And still others like to compile and link to a common library of object files. STK was not designed with one particular style of use in mind. +The Synthesis ToolKit can be used in a variety of ways, depending on your particular needs. Some people choose the classes they need for a particular project and copy those to their working directory. Others create Makefiles that compile project-specific class objects from common src and include directories. And still others like to compile and link to a common library of object files. STK was not designed with one particular style of use in mind. \section rtvsnonrt "Realtime" vs. "Non-Realtime" @@ -9,11 +9,11 @@ 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 +and operating-system (OS) dependent. STK classes that require specific platform/OS support include RtAudio, RtWvOut, RtWvIn, RtDuplex, RtMidi, InetWvIn, InetWvOut, Socket, UdpSocket, TcpServer, TcpClient, Thread, and Mutex. These classes currently can only be -compiled on Linux, Irix, Macintosh OS X, and Windows systems. +compiled on Linux, 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 @@ -42,15 +42,15 @@ STK compiles with realtime support on the following flavors of the Unix operatin Linux - Jack (audio only, use ALSA for MIDI support) - __LINUX_JACK__, __LINUX_ALSASEQ__, __LITTLE_ENDIAN__ + OSS (version 4.0 only, use ALSA for MIDI support) + __LINUX_OSS__, __LINUX_ALSASEQ__, __LITTLE_ENDIAN__ asound, pthread - Linux - OSS (audio only, use ALSA for MIDI support) - __LINUX_OSS__, __LINUX_ALSASEQ__, __LITTLE_ENDIAN__ - asound, pthread + Linux and Macintosh OS-X + Jack (audio only, use ALSA for MIDI support) + __UNIX_JACK__, __LINUX_ALSASEQ__, __LITTLE_ENDIAN__ + asound, pthread, jack Macintosh OS X @@ -58,12 +58,6 @@ STK compiles with realtime support on the following flavors of the Unix operatin __MACOSX_CORE__ pthread, CoreAudio, CoreMIDI, CoreFoundation - - Irix - AL - __IRIX_AL__, __IRIX_MD__ - audio, pthread - @@ -85,7 +79,7 @@ g++ -Wall -D__LITTLE_ENDIAN__ -o sineosc Stk.cpp FileRead.cpp FileWrite.cpp WvIn 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. +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) that 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: @@ -114,11 +108,11 @@ g++ -Wall -D__LITTLE_ENDIAN__ -o sineosc sineosc.cpp -lstk \section compileWin Windows: -STK has been tested on Windows platforms using the Visual C++ compiler +STK has been tested on Windows platforms using the Visual .NET compiler only. It is assumed here that you're familiar with Visual C++ and its -particular idiosyncrasies. +particular idiosyncrasies. STK won't compile in Visual C++ 6.0 any more. -The approach when using Visual C++ is to build a project which +The approach when using Visual C++ is to build a project that 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 diff --git a/doc/doxygen/crealtime.txt b/doc/doxygen/crealtime.txt index 02d4ec4..e0aa5aa 100644 --- a/doc/doxygen/crealtime.txt +++ b/doc/doxygen/crealtime.txt @@ -1,26 +1,74 @@ /*! \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). -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). +The previous section described the use of the RtWvOut class for +realtime audio output. The RtWvOut::tick() function writes data to a +large ring-buffer, from which data is periodically written to the +computer's audio hardware via an underlying callback routine. \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). +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 \c bufferFrames 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. +We also provide the audio system controller with a pointer to our +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. +Our callback routine is the \c tick() function. Function arguments +include pointers to the audio input and output data buffers, the +buffer size (in frames), a stream time argument, a status argument to +test for over/underruns, and the data pointer passed in the +openStream() 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 nBufferFrames 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. +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. +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. +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 that 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. [Main tutorial page]   [Next tutorial] */ diff --git a/doc/doxygen/download.txt b/doc/doxygen/download.txt index 9ba6a6d..0986d23 100644 --- a/doc/doxygen/download.txt +++ b/doc/doxygen/download.txt @@ -1,16 +1,34 @@ /*! \page download Download, Release Notes, and Bug Fixes -\section down Download Version 4.2.1 (14 October 2005): +\section down Download Version 4.3.0 (13 August 2007): \section notes Release Notes: +\subsection v4dot3dot0 Version 4.3.0 + + + \subsection v4dot2dot1 Version 4.2.1