/*! \mainpage The RtAudio Tutorial
OS: | Audio API: | C++ Class: | Preprocessor Definition: | Library or Framework: | Example Compiler Statement: |
Linux | ALSA | RtApiAlsa | __LINUX_ALSA__ | asound, pthread | g++ -Wall -D__LINUX_ALSA__ -o probe probe.cpp RtAudio.cpp -lasound -lpthread |
Linux | Jack Audio Server | RtApiJack | __LINUX_JACK__ | jack, pthread | g++ -Wall -D__LINUX_JACK__ -o probe probe.cpp RtAudio.cpp `pkg-config --cflags --libs jack` -lpthread |
Linux | OSS | RtApiOss | __LINUX_OSS__ | pthread | g++ -Wall -D__LINUX_OSS__ -o probe probe.cpp RtAudio.cpp -lpthread |
Macintosh OS X | CoreAudio | RtApiCore | __MACOSX_CORE__ | pthread, stdc++, CoreAudio | g++ -Wall -D__MACOSX_CORE__ -o probe probe.cpp RtAudio.cpp -framework CoreAudio -lpthread |
Irix | AL | RtApiAl | __IRIX_AL__ | audio, pthread | CC -Wall -D__IRIX_AL__ -o probe probe.cpp RtAudio.cpp -laudio -lpthread |
Windows | Direct Sound | RtApiDs | __WINDOWS_DS__ | dsound.lib (ver. 5.0 or higher), multithreaded | compiler specific |
Windows | ASIO | RtApiAsio | __WINDOWS_ASIO__ | various ASIO header and source files | compiler specific |
The example compiler statements above could be used to compile the probe.cpp example file, assuming that probe.cpp, RtAudio.h, RtError.h, and RtAudio.cpp all exist in the same directory.
\section debug Debugging
If you are having problems getting RtAudio to run on your system, try passing the preprocessor definition __RTAUDIO_DEBUG__ to the compiler (or uncomment the definition at the bottom of RtAudio.h). A variety of warning messages will be displayed which may help in determining the problem. Also try using the programs included in the test directory. The program info displays the queried capabilities of all hardware devices found.
\section apinotes API Notes
RtAudio is designed to provide a common API across the various supported operating systems and audio libraries. Despite that, some issues should be mentioned with regard to each.
\subsection linux Linux:
RtAudio for Linux was developed under Redhat distributions 7.0 - Fedora. Three different audio APIs are supported on Linux platforms: OSS, ALSA, and Jack. The OSS API has existed for at least 6 years and the Linux kernel is distributed with free versions of OSS audio drivers. Therefore, a generic Linux system is most likely to have OSS support (though the availability and quality of OSS drivers for new hardware is decreasing). The ALSA API, although relatively new, is now part of the Linux development kernel and offers significantly better functionality than the OSS API. RtAudio provides support for the 1.0 and higher versions of ALSA. Jack, which is still in development, is a low-latency audio server, written primarily for the GNU/Linux operating system. It can connect a number of different applications to an audio device, as well as allow them to share audio between themselves. Input/output latency on the order of 15 milliseconds can typically be achieved using any of the Linux APIs by fine-tuning the RtAudio buffer parameters (without kernel modifications). Latencies on the order of 5 milliseconds or less can be achieved using a low-latency kernel patch and increasing FIFO scheduling priority. The pthread library, which is used for callback functionality, is a standard component of all Linux distributions.
The ALSA library includes OSS emulation support. That means that you can run programs compiled for the OSS API even when using the ALSA drivers and library. It should be noted however that OSS emulation under ALSA is not perfect. Specifically, channel number queries seem to consistently produce invalid results. While OSS emulation is successful for the majority of RtAudio tests, it is recommended that the native ALSA implementation of RtAudio be used on systems which have ALSA drivers installed.
The ALSA implementation of RtAudio makes no use of the ALSA "plug" interface. All necessary data format conversions, channel compensation, de-interleaving, and byte-swapping is handled by internal RtAudio routines.
The Jack API is based on a callback scheme. RtAudio provides blocking functionality, in addition to callback functionality, within the context of that behavior. It should be noted, however, that the best performance is achieved when using RtAudio's callback functionality with the Jack API. At the moment, only one RtAudio instance can be connected to the Jack server. Because RtAudio does not provide a mechanism for allowing the user to specify particular channels (or ports) of a device, it simply opens the first N enumerated Jack ports for input/output.
\subsection macosx Macintosh OS X (CoreAudio):
The Apple CoreAudio API is based on a callback scheme. RtAudio provides blocking functionality, in addition to callback functionality, within the context of that behavior. CoreAudio is designed to use a separate callback procedure for each of its audio devices. A single RtAudio duplex stream using two different devices is supported, though it cannot be guaranteed to always behave correctly because we cannot synchronize these two callbacks. This same functionality might be achieved with better synchrony by creating separate instances of RtAudio for each device and making use of RtAudio blocking calls (i.e. RtAudio::tickStream()). The numberOfBuffers parameter to the RtAudio::openStream() function has no affect in this implementation.
It is not possible to have multiple instances of RtAudio accessing the same CoreAudio device.
\subsection irix Irix (SGI):
The Irix version of RtAudio was written and tested on an SGI Indy running Irix version 6.5.4 and the newer "al" audio library. RtAudio does not compile under Irix version 6.3, mainly because the C++ compiler is too old. Despite the relatively slow speed of the Indy, RtAudio was found to behave quite well and input/output latency was very good. No problems were found with respect to using the pthread library.
\subsection windowsds Windows (DirectSound):
In order to compile RtAudio under Windows for the DirectSound API, you must have the header and source files for DirectSound version 5.0 or higher. As far as I know, there is no DirectSoundCapture support for Windows NT. Audio output latency with DirectSound can be reasonably good (on the order of 20 milliseconds). On the other hand, input audio latency tends to be terrible (100 milliseconds or more). Further, DirectSound drivers tend to crash easily when experimenting with buffer parameters. On my system, I found it necessary to use values around nBuffers = 8 and bufferSize = 512 to avoid crashes. RtAudio was originally developed with Visual C++ version 6.0.
\subsection windowsasio Windows (ASIO):
The Steinberg ASIO audio API is based on a callback scheme. In addition, the API allows only a single device driver to be loaded and accessed at a time. ASIO device drivers must be supplied by audio hardware manufacturers, though ASIO emulation is possible on top of systems with DirectSound drivers. The numberOfBuffers parameter to the RtAudio::openStream() function has no affect in this implementation.
A number of ASIO source and header files are required for use with RtAudio. Specifically, an RtAudio project must include the following files: asio.h,cpp; asiodrivers.h,cpp; asiolist.h,cpp; asiodrvr.h; asiosys.h; ginclude.h; iasiodrv.h. The Visual C++ projects found in /tests/Windows/ compile both ASIO and DirectSound support.
\section acknowledge Acknowledgements
The RtAudio API incorporates many of the concepts developed in the PortAudio project by Phil Burk and Ross Bencina. Early development also incorporated ideas from Bill Schottstaedt's sndlib. The CCRMA SoundWire group provided valuable feedback during the API proposal stages.
The early 2.0 version of RtAudio was slowly developed over the course of many months while in residence at the Institut Universitari de L'Audiovisual (IUA) in Barcelona, Spain and the Laboratory of Acoustics and Audio Signal Processing at the Helsinki University of Technology, Finland. Much subsequent development happened while working at the Center for Computer Research in Music and Acoustics (CCRMA) at Stanford University. The most recent version of RtAudio was finished while working as an assistant professor of Music Technology at McGill University. This work was supported in part by the United States Air Force Office of Scientific Research (grant \#F49620-99-1-0293).
\section license License
RtAudio: a realtime audio i/o C++ classes
Copyright (c) 2001-2004 Gary P. Scavone
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
requested to send the modifications to the original developer so that
they can be incorporated into the canonical version.
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.
*/