/*! \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 wishlist Possible Future Changes There are a few issues that still need to be addressed in future versions of RtAudio, including: