The RtAudio Tutorial

00001 /************************************************************************/
-00038 /************************************************************************/
+
+RtAudio.h
00001 /************************************************************************/
+00038 /************************************************************************/
 00039 
-00040 #if !defined(__RTAUDIO_H)
-00041 #define __RTAUDIO_H
-00042 
-00043 #include <map>
-00044 
-00045 #if defined(__LINUX_ALSA__)
-00046   #include <alsa/asoundlib.h>
-00047   #include <pthread.h>
-00048   #include <unistd.h>
-00049 
-00050   typedef snd_pcm_t *AUDIO_HANDLE;
-00051   typedef int DEVICE_ID;
-00052   typedef pthread_t THREAD_HANDLE;
-00053   typedef pthread_mutex_t MUTEX;
-00054 
-00055 #elif defined(__LINUX_OSS__)
-00056   #include <pthread.h>
-00057   #include <unistd.h>
-00058 
-00059   typedef int AUDIO_HANDLE;
-00060   typedef int DEVICE_ID;
-00061   typedef pthread_t THREAD_HANDLE;
-00062   typedef pthread_mutex_t MUTEX;
-00063 
-00064 #elif defined(__WINDOWS_DS__)
-00065   #include <windows.h>
-00066   #include <process.h>
-00067 
-00068   // The following struct is used to hold the extra variables
-00069   // specific to the DirectSound implementation.
-00070   typedef struct {
-00071     void * object;
-00072     void * buffer;
-00073     UINT bufferPointer;
-00074   } AUDIO_HANDLE;
+00040 // RtAudio: Version 3.0, 11 March 2004
+00041 
+00042 #ifndef __RTAUDIO_H
+00043 #define __RTAUDIO_H
+00044 
+00045 #include "RtError.h"
+00046 #include <string>
+00047 #include <vector>
+00048 
+00049 // Operating system dependent thread functionality.
+00050 #if defined(__WINDOWS_DS__) || defined(__WINDOWS_ASIO__)
+00051   #include <windows.h>
+00052   #include <process.h>
+00053 
+00054   typedef unsigned long ThreadHandle;
+00055   typedef CRITICAL_SECTION StreamMutex;
+00056 
+00057 #else // Various unix flavors with pthread support.
+00058   #include <pthread.h>
+00059 
+00060   typedef pthread_t ThreadHandle;
+00061   typedef pthread_mutex_t StreamMutex;
+00062 
+00063 #endif
+00064 
+00065 // This global structure type is used to pass callback information
+00066 // between the private RtAudio stream structure and global callback
+00067 // handling functions.
+00068 struct CallbackInfo {
+00069   void *object;    // Used as a "this" pointer.
+00070   ThreadHandle thread;
+00071   bool usingCallback;
+00072   void *callback;
+00073   void *userData;
+00074   void *apiInfo;   // void pointer for API specific callback information
 00075 
-00076   typedef LPGUID DEVICE_ID;
-00077   typedef unsigned long THREAD_HANDLE;
-00078   typedef CRITICAL_SECTION MUTEX;
-00079 
-00080 #elif defined(__WINDOWS_ASIO__)
-00081   #include <windows.h>
-00082   #include <process.h>
-00083 
-00084   typedef int AUDIO_HANDLE;
-00085   typedef int DEVICE_ID;
-00086   typedef unsigned long THREAD_HANDLE;
-00087   typedef CRITICAL_SECTION MUTEX;
-00088 
-00089 #elif defined(__IRIX_AL__)
-00090   #include <dmedia/audio.h>
-00091   #include <pthread.h>
-00092   #include <unistd.h>
-00093 
-00094   typedef ALport AUDIO_HANDLE;
-00095   typedef long DEVICE_ID;
-00096   typedef pthread_t THREAD_HANDLE;
-00097   typedef pthread_mutex_t MUTEX;
-00098 
-00099 #elif defined(__MACOSX_CORE__)
-00100 
-00101   #include <CoreAudio/AudioHardware.h>
-00102   #include <pthread.h>
-00103 
-00104   typedef unsigned int AUDIO_HANDLE;
-00105   typedef AudioDeviceID DEVICE_ID;
-00106   typedef pthread_t THREAD_HANDLE;
-00107   typedef pthread_mutex_t MUTEX;
-00108 
-00109 #endif
-00110 
-00111 
-00112 /************************************************************************/
-00125 /************************************************************************/
-00126 
-00127 class RtError
-00128 {
-00129 public:
-00131   enum TYPE {
-00132     WARNING,
-00133     DEBUG_WARNING,
-00134     UNSPECIFIED,
-00135     NO_DEVICES_FOUND,
-00136     INVALID_DEVICE,
-00137     INVALID_STREAM,
-00138     MEMORY_ERROR,
-00139     INVALID_PARAMETER,
-00140     DRIVER_ERROR,
-00141     SYSTEM_ERROR,
-00142     THREAD_ERROR
-00143   };
-00144 
-00145 protected:
-00146   char error_message[256];
-00147   TYPE type;
+00076   // Default constructor.
+00077   CallbackInfo()
+00078     :object(0), usingCallback(false), callback(0),
+00079      userData(0), apiInfo(0) {}
+00080 };
+00081 
+00082 // Support for signed integers and floats.  Audio data fed to/from
+00083 // the tickStream() routine is assumed to ALWAYS be in host
+00084 // byte order.  The internal routines will automatically take care of
+00085 // any necessary byte-swapping between the host format and the
+00086 // soundcard.  Thus, endian-ness is not a concern in the following
+00087 // format definitions.
+00088 typedef unsigned long RtAudioFormat;
+00089 static const RtAudioFormat RTAUDIO_SINT8 = 0x1;    
+00090 static const RtAudioFormat RTAUDIO_SINT16 = 0x2;   
+00091 static const RtAudioFormat RTAUDIO_SINT24 = 0x4;   
+00092 static const RtAudioFormat RTAUDIO_SINT32 = 0x8;   
+00093 static const RtAudioFormat RTAUDIO_FLOAT32 = 0x10; 
+00094 static const RtAudioFormat RTAUDIO_FLOAT64 = 0x20; 
+00096 typedef int (*RtAudioCallback)(char *buffer, int bufferSize, void *userData);
+00097 
+00099 struct RtAudioDeviceInfo {
+00100   std::string name;      
+00101   bool probed;          
+00102   int outputChannels;   
+00103   int inputChannels;    
+00104   int duplexChannels;   
+00105   bool isDefault;       
+00106   std::vector<int> sampleRates; 
+00107   RtAudioFormat nativeFormats;  
+00109   // Default constructor.
+00110   RtAudioDeviceInfo()
+00111     :probed(false), outputChannels(0), inputChannels(0),
+00112        duplexChannels(0), isDefault(false), nativeFormats(0) {}
+00113 };
+00114 
+00115 // **************************************************************** //
+00116 //
+00117 // RtApi class declaration.
+00118 //
+00119 // Note that RtApi is an abstract base class and cannot be
+00120 // explicitly instantiated.  The class RtAudio will create an
+00121 // instance of an RtApi subclass (RtApiOss, RtApiAlsa,
+00122 // RtApiJack, RtApiCore, RtApiAl, RtApiDs, or RtApiAsio).
+00123 //
+00124 // **************************************************************** //
+00125 
+00126 class RtApi
+00127 {
+00128 public:
+00129 
+00130   RtApi();
+00131   virtual ~RtApi();
+00132   void openStream( int outputDevice, int outputChannels,
+00133                    int inputDevice, int inputChannels,
+00134                    RtAudioFormat format, int sampleRate,
+00135                    int *bufferSize, int numberOfBuffers );
+00136   virtual void setStreamCallback( RtAudioCallback callback, void *userData ) = 0;
+00137   virtual void cancelStreamCallback() = 0;
+00138   int getDeviceCount(void);
+00139   RtAudioDeviceInfo getDeviceInfo( int device );
+00140   char * const getStreamBuffer();
+00141   virtual void tickStream() = 0;
+00142   virtual void closeStream();
+00143   virtual void startStream() = 0;
+00144   virtual void stopStream() = 0;
+00145   virtual void abortStream() = 0;
+00146 
+00147 protected:
 00148 
-00149 public:
-00151   RtError(const char *p, TYPE tipe = RtError::UNSPECIFIED);
-00152 
-00154   virtual ~RtError(void);
-00155 
-00157   virtual void printMessage(void);
-00158 
-00160   virtual const TYPE& getType(void) { return type; }
-00161 
-00163   virtual const char *getMessage(void) { return error_message; }
-00164 };
+00149   static const unsigned int MAX_SAMPLE_RATES;
+00150   static const unsigned int SAMPLE_RATES[];
+00151 
+00152   enum { FAILURE, SUCCESS };
+00153 
+00154   enum StreamMode {
+00155     OUTPUT,
+00156     INPUT,
+00157     DUPLEX,
+00158     UNINITIALIZED = -75
+00159   };
+00160 
+00161   enum StreamState {
+00162     STREAM_STOPPED,
+00163     STREAM_RUNNING
+00164   };
 00165 
-00166 
-00167 // This public structure type is used to pass callback information
-00168 // between the private RtAudio stream structure and global callback
-00169 // handling functions.
-00170 typedef struct {
-00171   void *object;  // Used as a "this" pointer.
-00172   int streamId;
-00173   DEVICE_ID device[2];
-00174   THREAD_HANDLE thread;
-00175   void *callback;
-00176   void *buffers;
-00177   unsigned long waitTime;
-00178   bool blockTick;
-00179   bool stopStream;
-00180   bool usingCallback;
-00181   void *userData;
-00182 } CALLBACK_INFO;
-00183 
-00184 
-00185 // *************************************************** //
-00186 //
-00187 // RtAudio class declaration.
-00188 //
-00189 // *************************************************** //
-00190 
-00191 class RtAudio
-00192 {
-00193 public:
-00194 
-00195   // Support for signed integers and floats.  Audio data fed to/from
-00196   // the tickStream() routine is assumed to ALWAYS be in host
-00197   // byte order.  The internal routines will automatically take care of
-00198   // any necessary byte-swapping between the host format and the
-00199   // soundcard.  Thus, endian-ness is not a concern in the following
-00200   // format definitions.
-00201   typedef unsigned long RTAUDIO_FORMAT;
-00202   static const RTAUDIO_FORMAT RTAUDIO_SINT8; 
-00203   static const RTAUDIO_FORMAT RTAUDIO_SINT16; 
-00204   static const RTAUDIO_FORMAT RTAUDIO_SINT24; 
-00205   static const RTAUDIO_FORMAT RTAUDIO_SINT32; 
-00206   static const RTAUDIO_FORMAT RTAUDIO_FLOAT32; 
-00207   static const RTAUDIO_FORMAT RTAUDIO_FLOAT64; 
-00209   //static const int MAX_SAMPLE_RATES = 14;
-00210   enum { MAX_SAMPLE_RATES = 14 };
-00211 
-00212   typedef int (*RTAUDIO_CALLBACK)(char *buffer, int bufferSize, void *userData);
-00213 
-00215   typedef struct {
-00216     char name[128];    
-00217     DEVICE_ID id[2];  /* No value reported by getDeviceInfo(). */
-00218     bool probed;       
-00219     int maxOutputChannels; 
-00220     int maxInputChannels;  
-00221     int maxDuplexChannels; 
-00222     int minOutputChannels; 
-00223     int minInputChannels;  
-00224     int minDuplexChannels; 
-00225     bool hasDuplexSupport; 
-00226     bool isDefault;        
-00227     int nSampleRates;      
-00228     int sampleRates[MAX_SAMPLE_RATES]; 
-00229     RTAUDIO_FORMAT nativeFormats;     
-00230   } RTAUDIO_DEVICE;
+00166   // A protected structure for audio streams.
+00167   struct RtApiStream {
+00168     int device[2];          // Playback and record, respectively.
+00169     void *apiHandle;        // void pointer for API specific stream handle information
+00170     StreamMode mode;         // OUTPUT, INPUT, or DUPLEX.
+00171     StreamState state;       // STOPPED or RUNNING
+00172     char *userBuffer;
+00173     char *deviceBuffer;
+00174     bool doConvertBuffer[2]; // Playback and record, respectively.
+00175     bool deInterleave[2];    // Playback and record, respectively.
+00176     bool doByteSwap[2];      // Playback and record, respectively.
+00177     int sampleRate;
+00178     int bufferSize;
+00179     int nBuffers;
+00180     int nUserChannels[2];    // Playback and record, respectively.
+00181     int nDeviceChannels[2];  // Playback and record channels, respectively.
+00182     RtAudioFormat userFormat;
+00183     RtAudioFormat deviceFormat[2]; // Playback and record, respectively.
+00184     StreamMutex mutex;
+00185     CallbackInfo callbackInfo;
+00186 
+00187     RtApiStream()
+00188       :apiHandle(0), userBuffer(0), deviceBuffer(0) {}
+00189     //      :apiHandle(0), mode(UNINITIALIZED), state(STREAM_STOPPED),
+00190     //       userBuffer(0), deviceBuffer(0) {}
+00191   };
+00192 
+00193   // A protected device structure for audio devices.
+00194   struct RtApiDevice {
+00195     std::string name;      
+00196     bool probed;           
+00197     void *apiDeviceId;     // void pointer for API specific device information
+00198     int maxOutputChannels; 
+00199     int maxInputChannels;  
+00200     int maxDuplexChannels; 
+00201     int minOutputChannels; 
+00202     int minInputChannels;  
+00203     int minDuplexChannels; 
+00204     bool hasDuplexSupport; 
+00205     bool isDefault;        
+00206     std::vector<int> sampleRates; 
+00207     RtAudioFormat nativeFormats;  
+00209     // Default constructor.
+00210     RtApiDevice()
+00211       :probed(false), apiDeviceId(0), maxOutputChannels(0), maxInputChannels(0),
+00212        maxDuplexChannels(0), minOutputChannels(0), minInputChannels(0),
+00213        minDuplexChannels(0), isDefault(false), nativeFormats(0) {}
+00214   };
+00215 
+00216   typedef signed short Int16;
+00217   typedef signed int Int32;
+00218   typedef float Float32;
+00219   typedef double Float64;
+00220 
+00221   char message_[256];
+00222   int nDevices_;
+00223   std::vector<RtApiDevice> devices_;
+00224   RtApiStream stream_;
+00225 
+00230   virtual void initialize(void) = 0;
 00231 
-00233 
-00239   RtAudio();
-00240 
-00242 
-00253   RtAudio(int *streamId,
-00254           int outputDevice, int outputChannels,
-00255           int inputDevice, int inputChannels,
-00256           RTAUDIO_FORMAT format, int sampleRate,
-00257           int *bufferSize, int numberOfBuffers);
-00258 
-00260 
-00264   ~RtAudio();
+00240   virtual void probeDeviceInfo( RtApiDevice *info );
+00241 
+00250   virtual bool probeDeviceOpen( int device, StreamMode mode, int channels, 
+00251                                 int sampleRate, RtAudioFormat format,
+00252                                 int *bufferSize, int numberOfBuffers );
+00253 
+00258   virtual int getDefaultInputDevice(void);
+00259 
+00264   virtual int getDefaultOutputDevice(void);
 00265 
-00267 
-00294   int openStream(int outputDevice, int outputChannels,
-00295                  int inputDevice, int inputChannels,
-00296                  RTAUDIO_FORMAT format, int sampleRate,
-00297                  int *bufferSize, int numberOfBuffers);
-00298 
-00300 
-00319   void setStreamCallback(int streamId, RTAUDIO_CALLBACK callback, void *userData);
-00320 
-00322 
-00329   void cancelStreamCallback(int streamId);
-00330 
-00332   int getDeviceCount(void);
-00333 
-00335 
-00343   void getDeviceInfo(int device, RTAUDIO_DEVICE *info);
-00344 
-00346 
-00351   char * const getStreamBuffer(int streamId);
-00352 
-00354 
-00359   void tickStream(int streamId);
+00267   void clearDeviceInfo( RtApiDevice *info );
+00268 
+00270   void clearStreamInfo();
+00271 
+00273   void error( RtError::Type type );
+00274 
+00279   void verifyStream();
+00280 
+00285   void convertStreamBuffer( StreamMode mode );
+00286 
+00288   void byteSwapBuffer( char *buffer, int samples, RtAudioFormat format );
+00289 
+00291   int formatBytes( RtAudioFormat format );
+00292 };
+00293 
+00294 
+00295 // **************************************************************** //
+00296 //
+00297 // RtAudio class declaration.
+00298 //
+00299 // RtAudio is a "controller" used to select an available audio i/o
+00300 // interface.  It presents a common API for the user to call but all
+00301 // functionality is implemented by the class RtAudioApi and its
+00302 // subclasses.  RtAudio creates an instance of an RtAudioApi subclass
+00303 // based on the user's API choice.  If no choice is made, RtAudio
+00304 // attempts to make a "logical" API selection.
+00305 //
+00306 // **************************************************************** //
+00307 
+00308 class RtAudio
+00309 {
+00310 public:
+00311 
+00313   enum RtAudioApi {
+00314     UNSPECIFIED,    
+00315     LINUX_ALSA,     
+00316     LINUX_OSS,      
+00317     LINUX_JACK,     
+00318     MACOSX_CORE,    
+00319     IRIX_AL,        
+00320     WINDOWS_ASIO,   
+00321     WINDOWS_DS      
+00322   };
+00323 
+00325 
+00335   RtAudio( RtAudioApi api=UNSPECIFIED );
+00336 
+00338 
+00349   RtAudio( int outputDevice, int outputChannels,
+00350            int inputDevice, int inputChannels,
+00351            RtAudioFormat format, int sampleRate,
+00352            int *bufferSize, int numberOfBuffers, RtAudioApi api=UNSPECIFIED );
+00353 
+00355 
+00359   ~RtAudio();
 00360 
 00362 
-00366   void closeStream(int streamId);
-00367 
-00369 
-00373   void startStream(int streamId);
-00374 
-00376 
-00380   void stopStream(int streamId);
-00381 
-00383 
-00387   void abortStream(int streamId);
-00388 
-00390 
-00395   int streamWillBlock(int streamId);
-00396 
-00397 #if (defined(__MACOSX_CORE__) || defined(__WINDOWS_ASIO__))
-00398   // This function is intended for internal use only.  It must be
-00399   // public because it is called by the internal callback handler,
-00400   // which is not a member of RtAudio.  External use of this function
-00401   // will most likely produce highly undesireable results!
-00402   void callbackEvent(int streamId, DEVICE_ID deviceId, void *inData, void *outData);
-00403 #endif
-00404 
-00405 protected:
-00406 
-00407 private:
-00408 
-00409   static const unsigned int SAMPLE_RATES[MAX_SAMPLE_RATES];
-00410 
-00411   enum { FAILURE, SUCCESS };
-00412 
-00413   enum STREAM_MODE {
-00414     OUTPUT,
-00415     INPUT,
-00416     DUPLEX,
-00417     UNINITIALIZED = -75
-00418   };
-00419 
-00420   enum STREAM_STATE {
-00421     STREAM_STOPPED,
-00422     STREAM_RUNNING
-00423   };
+00388   void openStream( int outputDevice, int outputChannels,
+00389                    int inputDevice, int inputChannels,
+00390                    RtAudioFormat format, int sampleRate,
+00391                    int *bufferSize, int numberOfBuffers );
+00392 
+00394 
+00413   void setStreamCallback(RtAudioCallback callback, void *userData) { rtapi_->setStreamCallback( callback, userData ); };
+00414 
+00416 
+00423   void cancelStreamCallback() { rtapi_->cancelStreamCallback(); };
 00424 
-00425   typedef struct {
-00426     int device[2];          // Playback and record, respectively.
-00427     STREAM_MODE mode;       // OUTPUT, INPUT, or DUPLEX.
-00428     AUDIO_HANDLE handle[2]; // Playback and record handles, respectively.
-00429     STREAM_STATE state;     // STOPPED or RUNNING
-00430     char *userBuffer;
-00431     char *deviceBuffer;
-00432     bool doConvertBuffer[2]; // Playback and record, respectively.
-00433     bool deInterleave[2];    // Playback and record, respectively.
-00434     bool doByteSwap[2];      // Playback and record, respectively.
-00435     int sampleRate;
-00436     int bufferSize;
-00437     int nBuffers;
-00438     int nUserChannels[2];    // Playback and record, respectively.
-00439     int nDeviceChannels[2];  // Playback and record channels, respectively.
-00440     RTAUDIO_FORMAT userFormat;
-00441     RTAUDIO_FORMAT deviceFormat[2]; // Playback and record, respectively.
-00442     MUTEX mutex;
-00443     CALLBACK_INFO callbackInfo;
-00444   } RTAUDIO_STREAM;
-00445 
-00446   typedef signed short INT16;
-00447   typedef signed int INT32;
-00448   typedef float FLOAT32;
-00449   typedef double FLOAT64;
-00450 
-00451   char message[256];
-00452   int nDevices;
-00453   RTAUDIO_DEVICE *devices;
+00426   int getDeviceCount(void) { return rtapi_->getDeviceCount(); };
+00427 
+00429 
+00437   RtAudioDeviceInfo getDeviceInfo(int device) { return rtapi_->getDeviceInfo( device ); };
+00438 
+00440 
+00445   char * const getStreamBuffer() { return rtapi_->getStreamBuffer(); };
+00446 
+00448 
+00453   void tickStream() { rtapi_->tickStream(); };
 00454 
-00455   std::map<int, void *> streams;
 00456 
-00458   void error(RtError::TYPE type);
-00459 
-00464   void initialize(void);
-00465 
-00470   int getDefaultInputDevice(void);
-00471 
-00476   int getDefaultOutputDevice(void);
+00460   void closeStream()  { rtapi_->closeStream(); };
+00461 
+00463 
+00467   void startStream() { rtapi_->startStream(); };
+00468 
+00470 
+00474   void stopStream() { rtapi_->stopStream(); };
+00475 
 00477 
-00479   void clearDeviceInfo(RTAUDIO_DEVICE *info);
-00480 
-00488   void probeDeviceInfo(RTAUDIO_DEVICE *info);
-00489 
-00496   bool probeDeviceOpen(int device, RTAUDIO_STREAM *stream,
-00497                        STREAM_MODE mode, int channels, 
-00498                        int sampleRate, RTAUDIO_FORMAT format,
-00499                        int *bufferSize, int numberOfBuffers);
-00500 
-00507   void *verifyStream(int streamId);
-00508 
-00513   void convertStreamBuffer(RTAUDIO_STREAM *stream, STREAM_MODE mode);
-00514 
-00516   void byteSwapBuffer(char *buffer, int samples, RTAUDIO_FORMAT format);
-00517 
-00519   int formatBytes(RTAUDIO_FORMAT format);
-00520 };
-00521 
-00522 // Define the following flag to have extra information spewed to stderr.
-00523 //#define __RTAUDIO_DEBUG__
-00524 
-00525 #endif
-

+00481   void abortStream() { rtapi_->abortStream(); };
+00482 
+00483 
+00484  protected:
+00485 
+00486   void initialize( RtAudioApi api );
+00487 
+00488   RtApi *rtapi_;
+00489 };
+00490 
+00491 
+00492 // RtApi Subclass prototypes.
+00493 
+00494 #if defined(__LINUX_ALSA__)
+00495 
+00496 class RtApiAlsa: public RtApi
+00497 {
+00498 public:
+00499 
+00500   RtApiAlsa();
+00501   ~RtApiAlsa();
+00502   void tickStream();
+00503   void closeStream();
+00504   void startStream();
+00505   void stopStream();
+00506   void abortStream();
+00507   int streamWillBlock();
+00508   void setStreamCallback( RtAudioCallback callback, void *userData );
+00509   void cancelStreamCallback();
+00510 
+00511   private:
+00512 
+00513   void initialize(void);
+00514   void probeDeviceInfo( RtApiDevice *info );
+00515   bool probeDeviceOpen( int device, StreamMode mode, int channels, 
+00516                         int sampleRate, RtAudioFormat format,
+00517                         int *bufferSize, int numberOfBuffers );
+00518 };
+00519 
+00520 #endif
+00521 
+00522 #if defined(__LINUX_JACK__)
+00523 
+00524 class RtApiJack: public RtApi
+00525 {
+00526 public:
+00527 
+00528   RtApiJack();
+00529   ~RtApiJack();
+00530   void tickStream();
+00531   void closeStream();
+00532   void startStream();
+00533   void stopStream();
+00534   void abortStream();
+00535   void setStreamCallback( RtAudioCallback callback, void *userData );
+00536   void cancelStreamCallback();
+00537   // This function is intended for internal use only.  It must be
+00538   // public because it is called by the internal callback handler,
+00539   // which is not a member of RtAudio.  External use of this function
+00540   // will most likely produce highly undesireable results!
+00541   void callbackEvent( unsigned long nframes );
+00542 
+00543   private:
+00544 
+00545   void initialize(void);
+00546   void probeDeviceInfo( RtApiDevice *info );
+00547   bool probeDeviceOpen( int device, StreamMode mode, int channels, 
+00548                         int sampleRate, RtAudioFormat format,
+00549                         int *bufferSize, int numberOfBuffers );
+00550 };
+00551 
+00552 #endif
+00553 
+00554 #if defined(__LINUX_OSS__)
+00555 
+00556 class RtApiOss: public RtApi
+00557 {
+00558 public:
+00559 
+00560   RtApiOss();
+00561   ~RtApiOss();
+00562   void tickStream();
+00563   void closeStream();
+00564   void startStream();
+00565   void stopStream();
+00566   void abortStream();
+00567   int streamWillBlock();
+00568   void setStreamCallback( RtAudioCallback callback, void *userData );
+00569   void cancelStreamCallback();
+00570 
+00571   private:
+00572 
+00573   void initialize(void);
+00574   void probeDeviceInfo( RtApiDevice *info );
+00575   bool probeDeviceOpen( int device, StreamMode mode, int channels, 
+00576                         int sampleRate, RtAudioFormat format,
+00577                         int *bufferSize, int numberOfBuffers );
+00578 };
+00579 
+00580 #endif
+00581 
+00582 #if defined(__MACOSX_CORE__)
+00583 
+00584 #include <CoreAudio/AudioHardware.h>
+00585 
+00586 class RtApiCore: public RtApi
+00587 {
+00588 public:
+00589 
+00590   RtApiCore();
+00591   ~RtApiCore();
+00592   int getDefaultOutputDevice(void);
+00593   int getDefaultInputDevice(void);
+00594   void tickStream();
+00595   void closeStream();
+00596   void startStream();
+00597   void stopStream();
+00598   void abortStream();
+00599   void setStreamCallback( RtAudioCallback callback, void *userData );
+00600   void cancelStreamCallback();
+00601 
+00602   // This function is intended for internal use only.  It must be
+00603   // public because it is called by the internal callback handler,
+00604   // which is not a member of RtAudio.  External use of this function
+00605   // will most likely produce highly undesireable results!
+00606   void callbackEvent( AudioDeviceID deviceId, void *inData, void *outData );
+00607 
+00608   private:
+00609 
+00610   void initialize(void);
+00611   void probeDeviceInfo( RtApiDevice *info );
+00612   bool probeDeviceOpen( int device, StreamMode mode, int channels, 
+00613                         int sampleRate, RtAudioFormat format,
+00614                         int *bufferSize, int numberOfBuffers );
+00615 };
+00616 
+00617 #endif
+00618 
+00619 #if defined(__WINDOWS_DS__)
+00620 
+00621 class RtApiDs: public RtApi
+00622 {
+00623 public:
+00624 
+00625   RtApiDs();
+00626   ~RtApiDs();
+00627   int getDefaultOutputDevice(void);
+00628   int getDefaultInputDevice(void);
+00629   void tickStream();
+00630   void closeStream();
+00631   void startStream();
+00632   void stopStream();
+00633   void abortStream();
+00634   int streamWillBlock();
+00635   void setStreamCallback( RtAudioCallback callback, void *userData );
+00636   void cancelStreamCallback();
+00637 
+00638   private:
+00639 
+00640   void initialize(void);
+00641   void probeDeviceInfo( RtApiDevice *info );
+00642   bool probeDeviceOpen( int device, StreamMode mode, int channels, 
+00643                         int sampleRate, RtAudioFormat format,
+00644                         int *bufferSize, int numberOfBuffers );
+00645 };
+00646 
+00647 #endif
+00648 
+00649 #if defined(__WINDOWS_ASIO__)
+00650 
+00651 class RtApiAsio: public RtApi
+00652 {
+00653 public:
+00654 
+00655   RtApiAsio();
+00656   ~RtApiAsio();
+00657   void tickStream();
+00658   void closeStream();
+00659   void startStream();
+00660   void stopStream();
+00661   void abortStream();
+00662   void setStreamCallback( RtAudioCallback callback, void *userData );
+00663   void cancelStreamCallback();
+00664 
+00665   // This function is intended for internal use only.  It must be
+00666   // public because it is called by the internal callback handler,
+00667   // which is not a member of RtAudio.  External use of this function
+00668   // will most likely produce highly undesireable results!
+00669   void callbackEvent( long bufferIndex );
+00670 
+00671   private:
+00672 
+00673   void initialize(void);
+00674   void probeDeviceInfo( RtApiDevice *info );
+00675   bool probeDeviceOpen( int device, StreamMode mode, int channels, 
+00676                         int sampleRate, RtAudioFormat format,
+00677                         int *bufferSize, int numberOfBuffers );
+00678 };
+00679 
+00680 #endif
+00681 
+00682 #if defined(__IRIX_AL__)
+00683 
+00684 class RtApiAl: public RtApi
+00685 {
+00686 public:
+00687 
+00688   RtApiAl();
+00689   ~RtApiAl();
+00690   int getDefaultOutputDevice(void);
+00691   int getDefaultInputDevice(void);
+00692   void tickStream();
+00693   void closeStream();
+00694   void startStream();
+00695   void stopStream();
+00696   void abortStream();
+00697   int streamWillBlock();
+00698   void setStreamCallback( RtAudioCallback callback, void *userData );
+00699   void cancelStreamCallback();
+00700 
+00701   private:
+00702 
+00703   void initialize(void);
+00704   void probeDeviceInfo( RtApiDevice *info );
+00705   bool probeDeviceOpen( int device, StreamMode mode, int channels, 
+00706                         int sampleRate, RtAudioFormat format,
+00707                         int *bufferSize, int numberOfBuffers );
+00708 };
+00709 
+00710 #endif
+00711 
+00712 // Define the following flag to have extra information spewed to stderr.
+00713 //#define __RTAUDIO_DEBUG__
+00714 
+00715 #endif
+

+ +

diff --git a/doc/html/functions_enum.html b/doc/html/functions_enum.html new file mode 100644 index 0000000..7c5672a --- /dev/null +++ b/doc/html/functions_enum.html @@ -0,0 +1,26 @@ + + +The RtAudio Tutorial + + + +

The RtAudio Tutorial

-RtAudio is a C++ class which provides a common API (Application Programming Interface) for realtime audio input/output across Linux (native ALSA and OSS), Macintosh OS X, SGI, and Windows (DirectSound and ASIO) operating systems. RtAudio significantly simplifies the process of interacting with computer audio hardware. It was designed with the following goals: + +

The RtAudio Tutorial

+Introduction

-RtAudio incorporates the concept of audio streams, which represent audio output (playback) and/or input (recording). Available audio devices and their capabilities can be enumerated and then specified when opening a stream. When allowed by the underlying audio API, multiple streams can run at the same time and a single device can serve multiple streams. See the OS Notes section for information specific to each of the supported audio APIs. -

-The RtAudio API provides both blocking (synchronous) and callback (asyncronous) functionality. Callbacks are typically used in conjunction with graphical user interfaces (GUI). Blocking functionality is often necessary for explicit control of multiple input/output stream synchronization or when audio must be synchronized with other system events. -

Download

Getting Started

-The first thing that must be done when using RtAudio is to create an instance of the class. The default constructor RtAudio::RtAudio() scans the underlying audio system to verify that at least one device is available. RtAudio often uses C++ exceptions to report errors, necessitating try/catch blocks around most member functions. The following code example demonstrates default object construction and destruction: -

#include "RtAudio.h"
-
-int main()
-{
+
+object oriented C++ design 
+
+simple, common API across all supported platforms 
+
+only two header files and one source file for easy inclusion in programming projects 
+
+allow simultaneous multi-api support 
+
+blocking functionality 
+
+callback functionality 
+
+extensive audio device parameter control 
+
+audio device capability probing 
+
+automatic internal conversion for data format, channel number compensation, de-interleaving, and byte-swapping 
+
+
+RtAudio incorporates the concept of audio streams, which represent audio output (playback) and/or input (recording). Available audio devices and their capabilities can be enumerated and then specified when opening a stream. Where applicable, multiple API support can be compiled and a particular API specified when creating an RtAudio instance. See the API Notes section for information specific to each of the supported audio APIs.

+The RtAudio API provides both blocking (synchronous) and callback (asynchronous) functionality. Callbacks are typically used in conjunction with graphical user interfaces (GUI). Blocking functionality is often necessary for explicit control of multiple input/output stream synchronization or when audio must be synchronized with other system events.

+What's New (Version 3.0)
+RtAudio now allows simultaneous multi-api support. For example, you can compile RtAudio to provide both DirectSound and ASIO support on Windows platforms or ALSA, JACK, and OSS support on Linux platforms. This was accomplished by creating an abstract base class, RtApi, with subclasses for each supported API (RtApiAlsa, RtApiJack, RtApiOss, RtApiDs, RtApiAsio, RtApiCore, and RtApiAl). The class RtAudio is now a "controller" which creates an instance of an RtApi subclass based on the user's API choice via an optional RtAudio::RtAudioApi instantiation argument. If no API is specified, RtAudio attempts to make a "logical" API selection.
+Support for the JACK low-latency audio server has been added with this version of RtAudio. It is necessary to have the JACK server running before creating an instance of RtAudio.

+Several API changes have been made in version 3.0 of RtAudio in an effort to provide more consistent behavior across all supported audio APIs. The most significant of these changes is that multiple stream support from a single RtAudio instance has been discontinued. As a result, stream identifier input arguments are no longer required. Also, the RtAudio::streamWillBlock() function was poorly supported by most APIs and has been deprecated (though the function still exists in those subclasses of RtApi that do allow it to be implemented).

+The RtAudio::getDeviceInfo() function was modified to return a globally defined RtAudioDeviceInfo structure. This structure is a simplified version of the previous RTAUDIO_DEVICE structure. In addition, the RTAUDIO_FORMAT structure was renamed RtAudioFormat and defined globally within RtAudio.h. These changes were made for clarity and to better conform with standard C++ programming practices.

+The RtError class declaration and definition have been extracted to a separate file (RtError.h). This was done in preparation for a new release of the RtMidi class (planned for Summer 2004).

+Download
+Latest Release (11 March 2004): Version 3.0 (200 kB tar/gzipped)
+Getting Started
+With version 3.0, it is now possible to compile multiple API support on a given platform and to specify an API choice during class instantiation. In the examples that follow, no API will be specified (in which case, RtAudio attempts to select the most "logical" available API).
+The first thing that must be done when using RtAudio is to create an instance of the class. The default constructor scans the underlying audio system to verify that at least one device is available. RtAudio often uses C++ exceptions to report errors, necessitating try/catch blocks around most member functions. The following code example demonstrates default object construction and destruction:

+
#include "RtAudio.h"
+
+int main()
+{
   RtAudio *audio;
 
-  // Default RtAudio constructor
-  try {
-    audio = new RtAudio();
+  // Default RtAudio constructor
+  try {
+    audio = new RtAudio();
   }
-  catch (RtError &error) {
-    // Handle the exception here
+  catch (RtError &error) {
+    // Handle the exception here
+    error.printMessage();
   }
 
-  // Clean up
-  delete audio;
-}
-
-Obviously, this example doesn't demonstrate any of the real functionality of RtAudio. However, all uses of RtAudio must begin with a constructor (either default or overloaded varieties) and must end with class destruction. Further, it is necessary that all class methods which can throw a C++ exception be called within a try/catch block.
-

-
Error Handling
-
-
-RtAudio uses a C++ exception handler called RtError, which is declared and defined within the RtAudio class files. The RtError class is quite simple but it does allow errors to be "caught" by RtError::TYPE. Almost all RtAudio methods can "throw" an RtError, most typically if an invalid stream identifier is supplied to a method or a driver error occurs. There are a number of cases within RtAudio where warning messages may be displayed but an exception is not thrown. There is a private RtAudio method, error(), which can be modified to globally control how these messages are handled and reported.
-

-
Probing Device Capabilities
-
-
-A programmer may wish to query the available audio device capabilities before deciding which to use. The following example outlines how this can be done.
-

-
// probe.cpp
-
-#include <iostream>
-#include "RtAudio.h"
-
-int main()
-{
+  // Clean up
+  delete audio;
+}
+

+Obviously, this example doesn't demonstrate any of the real functionality of RtAudio. However, all uses of RtAudio must begin with a constructor (either default or overloaded varieties) and must end with class destruction. Further, it is necessary that all class methods which can throw a C++ exception be called within a try/catch block.

+Error Handling
+RtAudio uses a C++ exception handler called RtError, which is declared and defined in RtError.h. The RtError class is quite simple but it does allow errors to be "caught" by RtError::Type. Almost all RtAudio methods can "throw" an RtError, most typically if a driver error occurs or a stream function is called when no stream is open. There are a number of cases within RtAudio where warning messages may be displayed but an exception is not thrown. There is a protected RtAudio method, error(), which can be modified to globally control how these messages are handled and reported. By default, error messages are not automatically displayed in RtAudio unless the preprocessor definition __RTAUDIO_DEBUG__ is defined. Messages associated with caught exceptions can be displayed with, for example, the RtError::printMessage() function.
+Probing Device Capabilities
+A programmer may wish to query the available audio device capabilities before deciding which to use. The following example outlines how this can be done.
+
// probe.cpp
+
+#include <iostream>
+#include "RtAudio.h"
+
+int main()
+{
   RtAudio *audio;
 
-  // Default RtAudio constructor
-  try {
-    audio = new RtAudio();
+  // Default RtAudio constructor
+  try {
+    audio = new RtAudio();
   }
-  catch (RtError &error) {
+  catch (RtError &error) {
     error.printMessage();
     exit(EXIT_FAILURE);
   }
 
-  // Determine the number of devices available
-  int devices = audio->getDeviceCount();
+  // Determine the number of devices available
+  int devices = audio->getDeviceCount();
 
-  // Scan through devices for various capabilities
-  RtAudio::RTAUDIO_DEVICE info;
-  for (int i=1; i<=devices; i++) {
+  // Scan through devices for various capabilities
+  RtAudioDeviceInfo info;
+  for (int i=1; i<=devices; i++) {
 
-    try {
-      audio->getDeviceInfo(i, &info);
+    try {
+      info = audio->getDeviceInfo(i);
     }
-    catch (RtError &error) {
+    catch (RtError &error) {
       error.printMessage();
-      break;
+      break;
     }
 
-    // Print, for example, the maximum number of output channels for each device
-    cout << "device = " << i;
-    cout << ": maximum output channels = " << info.maxOutputChannels << "\n";
+    // Print, for example, the maximum number of output channels for each device
+    std::cout << "device = " << i;
+    std::cout << ": maximum output channels = " << info.outputChannels << "\n";
   }
 
-  // Clean up
-  delete audio;
-
-  return 0;
-}
-
-The RTAUDIO_DEVICE structure is defined in RtAudio.h and provides a variety of information useful in assessing the capabilities of a device:
-

-
  typedef struct {
-    char name[128];
-    bool probed;                          // true if the device probe was successful.
-    int maxOutputChannels;
-    int maxInputChannels;
-    int maxDuplexChannels;
-    int minOutputChannels;
-    int minInputChannels;
-    int minDuplexChannels;
-    bool hasDuplexSupport;                // true if duplex mode is supported.
-    bool isDefault;                       // true if this is the default output or input device.
-    int nSampleRates;                     // Number of discrete rates, or -1 if range supported.
-    double sampleRates[MAX_SAMPLE_RATES]; // Supported sample rates, or {min, max} if range.
-    RTAUDIO_FORMAT nativeFormats;
-  } RTAUDIO_DEVICE;
-
-The following data formats are defined and fully supported by RtAudio:
-

-
  typedef unsigned long RTAUDIO_FORMAT;
-  static const RTAUDIO_FORMAT  RTAUDIO_SINT8;   // Signed 8-bit integer
-  static const RTAUDIO_FORMAT  RTAUDIO_SINT16;  // Signed 16-bit integer
-  static const RTAUDIO_FORMAT  RTAUDIO_SINT24;  // Signed 24-bit integer (upper 3 bytes of 32-bit signed integer.)
-  static const RTAUDIO_FORMAT  RTAUDIO_SINT32;  // Signed 32-bit integer
-  static const RTAUDIO_FORMAT  RTAUDIO_FLOAT32; // 32-bit float normalized between +/- 1.0
-  static const RTAUDIO_FORMAT  RTAUDIO_FLOAT64; // 64-bit double normalized between +/- 1.0
-
-The nativeFormats member of the RtAudio::RTAUDIO_DEVICE structure is a bit mask of the above formats which are natively supported by the device. However, RtAudio will automatically provide format conversion if a particular format is not natively supported. When the probed member of the RTAUDIO_DEVICE structure is false, the remaining structure members are undefined and the device is probably unuseable.
-

-In general, the user need not be concerned with the minimum channel values reported in the RTAUDIO_DEVICE structure. While some audio devices may require a minimum channel value > 1, RtAudio will provide automatic channel number compensation when the number of channels set by the user is less than that required by the device. Channel compensation is NOT possible when the number of channels set by the user is greater than that supported by the device.
-

-It should be noted that the capabilities reported by a device driver or underlying audio API are not always accurate and/or may be dependent on a combination of device settings. For this reason, RtAudio does not rely on the reported values when attempting to open a stream.
-

-
Device Settings
+  // Clean up
+  delete audio;
 
-
-The next step in using RtAudio is to open a stream with particular device and parameter settings.
-

-
#include "RtAudio.h"
-
-int main()
-{
-  int channels = 2;
-  int sample_rate = 44100;
-  int buffer_size = 256;  // 256 sample frames
-  int n_buffers = 4;      // number of internal buffers used by device
-  int device = 0;         // 0 indicates the default or first available device
-  int stream;             // our stream identifier
+  return 0;
+}
+

+The RtAudioDeviceInfo structure is defined in RtAudio.h and provides a variety of information useful in assessing the capabilities of a device:

+
  typedef struct RtAudioDeviceInfo{
+    std::string name;             // Character string device identifier.
+    bool probed;                  // true if the device capabilities were successfully probed.
+    int outputChannels;           // Maximum output channels supported by device.
+    int inputChannels;            // Maximum input channels supported by device.
+    int duplexChannels;           // Maximum simultaneous input/output channels supported by device.
+    bool isDefault;               // true if this is the default output or input device.
+    std::vector<int> sampleRates; // Supported sample rates.
+    RtAudioFormat nativeFormats;  // Bit mask of supported data formats.
+  };
+

+The following data formats are defined and fully supported by RtAudio:

+
  typedef unsigned long RtAudioFormat;
+  static const RtAudioFormat  RTAUDIO_SINT8;   // Signed 8-bit integer
+  static const RtAudioFormat  RTAUDIO_SINT16;  // Signed 16-bit integer
+  static const RtAudioFormat  RTAUDIO_SINT24;  // Signed 24-bit integer (upper 3 bytes of 32-bit signed integer.)
+  static const RtAudioFormat  RTAUDIO_SINT32;  // Signed 32-bit integer
+  static const RtAudioFormat  RTAUDIO_FLOAT32; // 32-bit float normalized between +/- 1.0
+  static const RtAudioFormat  RTAUDIO_FLOAT64; // 64-bit double normalized between +/- 1.0
+

+The nativeFormats member of the RtAudioDeviceInfo structure is a bit mask of the above formats which are natively supported by the device. However, RtAudio will automatically provide format conversion if a particular format is not natively supported. When the probed member of the RtAudioDeviceInfo structure is false, the remaining structure members are undefined and the device is probably unuseable.

+While some audio devices may require a minimum channel value greater than one, RtAudio will provide automatic channel number compensation when the number of channels set by the user is less than that required by the device. Channel compensation is NOT possible when the number of channels set by the user is greater than that supported by the device.

+It should be noted that the capabilities reported by a device driver or underlying audio API are not always accurate and/or may be dependent on a combination of device settings. For this reason, RtAudio does not typically rely on the queried values when attempting to open a stream.

+Device Settings
+The next step in using RtAudio is to open a stream with particular device and parameter settings.
+
#include "RtAudio.h"
+
+int main()
+{
+  int channels = 2;
+  int sampleRate = 44100;
+  int bufferSize = 256;  // 256 sample frames
+  int nBuffers = 4;      // number of internal buffers used by device
+  int device = 0;        // 0 indicates the default or first available device
   RtAudio *audio;
 
-  // Instantiate RtAudio and open a stream within a try/catch block
-  try {
-    audio = new RtAudio();
-    stream = audio->openStream(device, channels, 0, 0, RtAudio::RTAUDIO_FLOAT32,
-                               sample_rate, &buffer_size, n_buffers);
+  // Instantiate RtAudio and open a stream within a try/catch block
+  try {
+    audio = new RtAudio();
   }
-  catch (RtError &error) {
+  catch (RtError &error) {
     error.printMessage();
     exit(EXIT_FAILURE);
   }
 
-  // Clean up
-  delete audio;
+  try {
+    audio->openStream(device, channels, 0, 0, RTAUDIO_FLOAT32,
+                      sampleRate, &bufferSize, nBuffers);
+  }
+  catch (RtError &error) {
+    error.printMessage();
+    // Perhaps try other parameters?
+  }
 
-  return 0;
-}
-
-The RtAudio::openStream() method attempts to open a stream with a specified set of parameter values. When successful, a stream identifier is returned. In this case, we attempt to open a two channel playback stream with the default output device, 32-bit floating point data, a sample rate of 44100 Hz, a frame rate of 256 sample frames per read/write, and 4 internal device buffers. When device = 0, RtAudio first attempts to open the default audio device with the given parameters. If that attempt fails, RtAudio searches through the remaining available devices in an effort to find a device which will meet the given parameters. If all attempts are unsuccessful, an RtError is thrown. When a non-zero device value is specified, an attempt is made to open that device only (device = 1 specifies the first identified device, as reported by RtAudio::getDeviceInfo()).
-

-RtAudio provides four signed integer and two floating point data formats which can be specified using the RtAudio::RTAUDIO_FORMAT parameter values mentioned earlier. If the opened device does not natively support the given format, RtAudio will automatically perform the necessary data format conversion.
-

-The bufferSize parameter specifies the desired number of sample frames which will be written to and/or read from a device per write/read operation. The nBuffers parameter is used in setting the underlying device buffer parameters. Both the bufferSize and nBuffers parameters can be used to control stream latency though there is no guarantee that the passed values will be those used by a device (the nBuffers parameter is ignored when using the OS X CoreAudio and the Windows ASIO APIs). In general, lower values for both parameters will produce less latency but perhaps less robust performance. Both parameters can be specified with values of zero, in which case the smallest allowable values will be used. The bufferSize parameter is passed as a pointer and the actual value used by the stream is set during the device setup procedure. bufferSize values should be a power of two. Optimal and allowable buffer values tend to vary between systems and devices. Check the OS Notes section for general guidelines.
-

-As noted earlier, the device capabilities reported by a driver or underlying audio API are not always accurate and/or may be dependent on a combination of device settings. Because of this, RtAudio does not attempt to query a device's capabilities or use previously reported values when opening a device. Instead, RtAudio simply attempts to set the given parameters on a specified device and then checks whether the setup is successful or not.
-

-
Playback (blocking functionality)
+  // Clean up
+  delete audio;
 
-
-Once the device is open for playback, there are only a few final steps necessary for realtime audio output. We'll first provide an example (blocking functionality) and then discuss the details.
-

-
// playback.cpp
-
-#include "RtAudio.h"
-
-int main()
-{
-  int count;
-  int channels = 2;
-  int sample_rate = 44100;
-  int buffer_size = 256;  // 256 sample frames
-  int n_buffers = 4;      // number of internal buffers used by device
-  float *buffer;
-  int device = 0;         // 0 indicates the default or first available device
-  int stream;             // our stream identifier
+  return 0;
+}
+

+The RtAudio::openStream() method attempts to open a stream with a specified set of parameter values. In this case, we attempt to open a two channel playback stream with the default output device, 32-bit floating point data, a sample rate of 44100 Hz, a frame rate of 256 sample frames per read/write, and 4 internal device buffers. When device = 0, RtAudio first attempts to open the default audio device with the given parameters. If that attempt fails, RtAudio searches through the remaining available devices in an effort to find a device which will meet the given parameters. If all attempts are unsuccessful, an RtError is thrown. When a non-zero device value is specified, an attempt is made to open that device ONLY (device = 1 specifies the first identified device, as reported by RtAudio::getDeviceInfo()).

+RtAudio provides four signed integer and two floating point data formats which can be specified using the RtAudioFormat parameter values mentioned earlier. If the opened device does not natively support the given format, RtAudio will automatically perform the necessary data format conversion.

+The bufferSize parameter specifies the desired number of sample frames which will be written to and/or read from a device per write/read operation. The nBuffers parameter is used in setting the underlying device buffer parameters. Both the bufferSize and nBuffers parameters can be used to control stream latency though there is no guarantee that the passed values will be those used by a device (the nBuffers parameter is ignored when using the OS X CoreAudio, Linux Jack, and the Windows ASIO APIs). In general, lower values for both parameters will produce less latency but perhaps less robust performance. Both parameters can be specified with values of zero, in which case the smallest allowable values will be used. The bufferSize parameter is passed as a pointer and the actual value used by the stream is set during the device setup procedure. bufferSize values should be a power of two. Optimal and allowable buffer values tend to vary between systems and devices. Check the API Notes section for general guidelines.

+As noted earlier, the device capabilities reported by a driver or underlying audio API are not always accurate and/or may be dependent on a combination of device settings. Because of this, RtAudio does not attempt to query a device's capabilities or use previously reported values when opening a device. Instead, RtAudio simply attempts to set the given parameters on a specified device and then checks whether the setup is successful or not.

+Playback (blocking functionality)
+Once the device is open for playback, there are only a few final steps necessary for realtime audio output. We'll first provide an example (blocking functionality) and then discuss the details.
+
// playback.cpp
+
+#include "RtAudio.h"
+
+int main()
+{
+  int count;
+  int channels = 2;
+  int sampleRate = 44100;
+  int bufferSize = 256;  // 256 sample frames
+  int nBuffers = 4;      // number of internal buffers used by device
+  float *buffer;
+  int device = 0;        // 0 indicates the default or first available device
   RtAudio *audio;
 
-  // Open a stream during RtAudio instantiation
-  try {
-    audio = new RtAudio(&stream, device, channels, 0, 0, RtAudio::RTAUDIO_FLOAT32,
-                        sample_rate, &buffer_size, n_buffers);
+  // Open a stream during RtAudio instantiation
+  try {
+    audio = new RtAudio(device, channels, 0, 0, RTAUDIO_FLOAT32,
+                        sampleRate, &bufferSize, nBuffers);
   }
-  catch (RtError &error) {
+  catch (RtError &error) {
     error.printMessage();
     exit(EXIT_FAILURE);
   }
 
-  try {
-    // Get a pointer to the stream buffer
-    buffer = (float *) audio->getStreamBuffer(stream);
+  try {
+    // Get a pointer to the stream buffer
+    buffer = (float *) audio->getStreamBuffer();
 
-    // Start the stream
-    audio->startStream(stream);
+    // Start the stream
+    audio->startStream();
   }
-  catch (RtError &error) {
+  catch (RtError &error) {
     error.printMessage();
-    goto cleanup;
+    goto cleanup;
   }
 
-  // An example loop which runs for about 40000 sample frames
+  // An example loop which runs for 40000 sample frames
   count = 0;
-  while (count < 40000) {
-    // Generate your samples and fill the buffer with buffer_size sample frames of data
+  while (count < 40000) {
+    // Generate your samples and fill the buffer with bufferSize sample frames of data
     ...
 
-    // Trigger the output of the data buffer
-    try {
-      audio->tickStream(stream);
+    // Trigger the output of the data buffer
+    try {
+      audio->tickStream();
     }
-    catch (RtError &error) {
+    catch (RtError &error) {
       error.printMessage();
-      goto cleanup;
+      goto cleanup;
     }
 
-    count += buffer_size;
+    count += bufferSize;
   }
 
-  try {
-    // Stop and close the stream
-    audio->stopStream(stream);
-    audio->closeStream(stream);
+  try {
+    // Stop and close the stream
+    audio->stopStream();
+    audio->closeStream();
   }
-  catch (RtError &error) {
+  catch (RtError &error) {
     error.printMessage();
   }
 
  cleanup:
-  delete audio;
-
-  return 0;
-}
-
-The first thing to notice in this example is that we attempt to open a stream during class instantiation with an overloaded constructor. This constructor simply combines the functionality of the default constructor, used earlier, and the RtAudio::openStream() method. Again, we have specified a device value of 0, indicating that the default or first available device meeting the given parameters should be used. The integer identifier of the opened stream is returned via the stream pointer value. An attempt is made to open the stream with the specified bufferSize value. However, it is possible that the device will not accept this value, in which case the closest allowable size is used and returned via the pointer value. The constructor can fail if no available devices are found, or a memory allocation or device driver error occurs. Note that you should not call the RtAudio destructor if an exception is thrown during instantiation.
-

-Because RtAudio can typically be used to simultaneously control more than a single stream, it is necessary that the stream identifier be provided to nearly all public methods. Assuming the constructor is successful, it is necessary to get a pointer to the buffer, provided by RtAudio, for use in feeding data to/from the opened stream. Note that the user should NOT attempt to deallocate the stream buffer memory ... memory management for the stream buffer will be automatically controlled by RtAudio. After starting the stream with RtAudio::startStream(), one simply fills that buffer, which is of length equal to the returned bufferSize value, with interleaved audio data (in the specified format) for playback. Finally, a call to the RtAudio::tickStream() routine triggers a blocking write call for the stream.
-

-In general, one should call the RtAudio::stopStream() and RtAudio::closeStream() methods after finishing with a stream. However, both methods will implicitly be called during object destruction if necessary.
-

-
Playback (callback functionality)
+  delete audio;
 
-
-The primary difference in using RtAudio with callback functionality involves the creation of a user-defined callback function. Here is an example which produces a sawtooth waveform for playback.
-

-
#include <iostream>
-#include "RtAudio.h"
-
-// Two-channel sawtooth wave generator.
-int sawtooth(char *buffer, int buffer_size, void *data)
-{
-  int i, j;
-  double *my_buffer = (double *) buffer;
-  double *my_data = (double *) data;
-
-  // Write interleaved audio data.
-  for (i=0; i<buffer_size; i++) {
-    for (j=0; j<2; j++) {
+  return 0;
+}
+

+The first thing to notice in this example is that we attempt to open a stream during class instantiation with an overloaded constructor. This constructor simply combines the functionality of the default constructor, used earlier, and the RtAudio::openStream() method. Again, we have specified a device value of 0, indicating that the default or first available device meeting the given parameters should be used. An attempt is made to open the stream with the specified bufferSize value. However, it is possible that the device will not accept this value, in which case the closest allowable size is used and returned via the pointer value. The constructor can fail if no available devices are found, or a memory allocation or device driver error occurs. Note that you should not call the RtAudio destructor if an exception is thrown during instantiation.

+Assuming the constructor is successful, it is necessary to get a pointer to the buffer, provided by RtAudio, for use in feeding data to/from the opened stream. Note that the user should NOT attempt to deallocate the stream buffer memory ... memory management for the stream buffer will be automatically controlled by RtAudio. After starting the stream with RtAudio::startStream(), one simply fills that buffer, which is of length equal to the returned bufferSize value, with interleaved audio data (in the specified format) for playback. Finally, a call to the RtAudio::tickStream() routine triggers a blocking write call for the stream.

+In general, one should call the RtAudio::stopStream() and RtAudio::closeStream() methods after finishing with a stream. However, both methods will implicitly be called during object destruction if necessary.

+Playback (callback functionality)
+The primary difference in using RtAudio with callback functionality involves the creation of a user-defined callback function. Here is an example which produces a sawtooth waveform for playback.
+
#include <iostream>
+#include "RtAudio.h"
+
+// Two-channel sawtooth wave generator.
+int sawtooth(char *buffer, int bufferSize, void *data)
+{
+  int i, j;
+  double *my_buffer = (double *) buffer;
+  double *my_data = (double *) data;
+
+  // Write interleaved audio data.
+  for (i=0; i<bufferSize; i++) {
+    for (j=0; j<2; j++) {
       *my_buffer++ = my_data[j];
 
       my_data[j] += 0.005 * (j+1+(j*0.1));
-      if (my_data[j] >= 1.0) my_data[j] -= 2.0;
+      if (my_data[j] >= 1.0) my_data[j] -= 2.0;
     }
   }
 
-  return 0;
+  return 0;
 }
 
-int main()
-{
-  int channels = 2;
-  int sample_rate = 44100;
-  int buffer_size = 256;  // 256 sample frames
-  int n_buffers = 4;      // number of internal buffers used by device
-  int device = 0;         // 0 indicates the default or first available device
-  int stream;             // our stream identifier
-  double data[2];
-  char input;
+int main()
+{
+  int channels = 2;
+  int sampleRate = 44100;
+  int bufferSize = 256;  // 256 sample frames
+  int nBuffers = 4;      // number of internal buffers used by device
+  int device = 0;        // 0 indicates the default or first available device
+  double data[2];
+  char input;
   RtAudio *audio;
 
-  // Open a stream during RtAudio instantiation
-  try {
-    audio = new RtAudio(&stream, device, channels, 0, 0, RtAudio::RTAUDIO_FLOAT64,
-                        sample_rate, &buffer_size, n_buffers);
+  // Open a stream during RtAudio instantiation
+  try {
+    audio = new RtAudio(device, channels, 0, 0, RTAUDIO_FLOAT64,
+                        sampleRate, &bufferSize, nBuffers);
   }
-  catch (RtError &error) {
+  catch (RtError &error) {
     error.printMessage();
     exit(EXIT_FAILURE);
   }
 
-  try {
-    // Set the stream callback function
-    audio->setStreamCallback(stream, &sawtooth, (void *)data);
+  try {
+    // Set the stream callback function
+    audio->setStreamCallback(&sawtooth, (void *)data);
 
-    // Start the stream
-    audio->startStream(stream);
+    // Start the stream
+    audio->startStream();
   }
-  catch (RtError &error) {
+  catch (RtError &error) {
     error.printMessage();
-    goto cleanup;
+    goto cleanup;
   }
 
-  cout << "\nPlaying ... press <enter> to quit.\n";
-  cin.get(input);
+  std::cout << "\nPlaying ... press <enter> to quit.\n";
+  std::cin.get(input);
 
-  try {
-    // Stop and close the stream
-    audio->stopStream(stream);
-    audio->closeStream(stream);
+  try {
+    // Stop and close the stream
+    audio->stopStream();
+    audio->closeStream();
   }
-  catch (RtError &error) {
+  catch (RtError &error) {
     error.printMessage();
   }
 
  cleanup:
-  delete audio;
-
-  return 0;
-}
-
-After opening the device in exactly the same way as the previous example (except with a data format change), we must set our callback function for the stream using RtAudio::setStreamCallback(). When the underlying audio API uses blocking calls (OSS, ALSA, SGI, and Windows DirectSound), this method will spawn a new process (or thread) which automatically calls the callback function when more data is needed. Callback-based audio APIs (OS X CoreAudio and ASIO) implement their own event notification schemes. Note that the callback function is called only when the stream is "running" (between calls to the RtAudio::startStream() and RtAudio::stopStream() methods). The last argument to RtAudio::setStreamCallback() is a pointer to arbitrary data that you wish to access from within your callback function.
-

-In this example, we stop the stream with an explicit call to RtAudio::stopStream(). When using callback functionality, it is also possible to stop a stream by returning a non-zero value from the callback function.
-

-Once set with RtAudio::setStreamCallback, the callback process exists for the life of the stream (until the stream is closed with RtAudio::closeStream() or the RtAudio instance is deleted). It is possible to disassociate a callback function and cancel its process for an open stream using the RtAudio::cancelStreamCallback() method. The stream can then be used with blocking functionality or a new callback can be associated with it.
-

-
Recording
+  delete audio;
 
-
-Using RtAudio for audio input is almost identical to the way it is used for playback. Here's the blocking playback example rewritten for recording:
-

-
// record.cpp
-
-#include "RtAudio.h"
-
-int main()
-{
-  int count;
-  int channels = 2;
-  int sample_rate = 44100;
-  int buffer_size = 256;  // 256 sample frames
-  int n_buffers = 4;      // number of internal buffers used by device
-  float *buffer;
-  int device = 0;         // 0 indicates the default or first available device
-  int stream;             // our stream identifier
+  return 0;
+}
+

+After opening the device in exactly the same way as the previous example (except with a data format change), we must set our callback function for the stream using RtAudio::setStreamCallback(). When the underlying audio API uses blocking calls (OSS, ALSA, SGI, and Windows DirectSound), this method will spawn a new process (or thread) which automatically calls the callback function when more data is needed. Callback-based audio APIs (OS X CoreAudio Linux Jack, and ASIO) implement their own event notification schemes. Note that the callback function is called only when the stream is "running" (between calls to the RtAudio::startStream() and RtAudio::stopStream() methods). The last argument to RtAudio::setStreamCallback() is a pointer to arbitrary data that you wish to access from within your callback function.

+In this example, we stop the stream with an explicit call to RtAudio::stopStream(). When using callback functionality, it is also possible to stop a stream by returning a non-zero value from the callback function.

+Once set with RtAudio::setStreamCallback, the callback process exists for the life of the stream (until the stream is closed with RtAudio::closeStream() or the RtAudio instance is deleted). It is possible to disassociate a callback function and cancel its process for an open stream using the RtAudio::cancelStreamCallback() method. The stream can then be used with blocking functionality or a new callback can be associated with it.

+Recording
+Using RtAudio for audio input is almost identical to the way it is used for playback. Here's the blocking playback example rewritten for recording:
+
// record.cpp
+
+#include "RtAudio.h"
+
+int main()
+{
+  int count;
+  int channels = 2;
+  int sampleRate = 44100;
+  int bufferSize = 256;  // 256 sample frames
+  int nBuffers = 4;      // number of internal buffers used by device
+  float *buffer;
+  int device = 0;        // 0 indicates the default or first available device
   RtAudio *audio;
 
-  // Instantiate RtAudio and open a stream.
-  try {
-    audio = new RtAudio(&stream, 0, 0, device, channels,
-                        RtAudio::RTAUDIO_FLOAT32, sample_rate, &buffer_size, n_buffers);
+  // Instantiate RtAudio and open a stream.
+  try {
+    audio = new RtAudio(&stream, 0, 0, device, channels,
+                        RTAUDIO_FLOAT32, sampleRate, &bufferSize, nBuffers);
   }
-  catch (RtError &error) {
+  catch (RtError &error) {
     error.printMessage();
     exit(EXIT_FAILURE);
   }
 
-  try {
-    // Get a pointer to the stream buffer
-    buffer = (float *) audio->getStreamBuffer(stream);
+  try {
+    // Get a pointer to the stream buffer
+    buffer = (float *) audio->getStreamBuffer();
 
-    // Start the stream
-    audio->startStream(stream);
+    // Start the stream
+    audio->startStream();
   }
-  catch (RtError &error) {
+  catch (RtError &error) {
     error.printMessage();
-    goto cleanup;
+    goto cleanup;
   }
 
-  // An example loop which runs for about 40000 sample frames
+  // An example loop which runs for about 40000 sample frames
   count = 0;
-  while (count < 40000) {
+  while (count < 40000) {
 
-    // Read a buffer of data
-    try {
-      audio->tickStream(stream);
+    // Read a buffer of data
+    try {
+      audio->tickStream();
     }
-    catch (RtError &error) {
+    catch (RtError &error) {
       error.printMessage();
-      goto cleanup;
+      goto cleanup;
     }
 
-    // Process the input samples (buffer_size sample frames) that were read
+    // Process the input samples (bufferSize sample frames) that were read
     ...
 
-    count += buffer_size;
+    count += bufferSize;
   }
 
-  try {
-    // Stop the stream
-    audio->stopStream(stream);
+  try {
+    // Stop the stream
+    audio->stopStream();
   }
-  catch (RtError &error) {
+  catch (RtError &error) {
     error.printMessage();
   }
 
  cleanup:
-  delete audio;
-
-  return 0;
-}
-
-In this example, the stream was opened for recording with a non-zero inputChannels value. The only other difference between this example and that for playback involves the order of data processing in the loop, where it is necessary to first read a buffer of input data before manipulating it.
-

-
Duplex Mode
-
-
-Finally, it is easy to use RtAudio for simultaneous audio input/output, or duplex operation. In this example, we use a callback function and simply scale the input data before sending it back to the output.
-

-
// duplex.cpp
-
-#include <iostream>
-#include "RtAudio.h"
-
-// Pass-through function.
-int scale(char *buffer, int buffer_size, void *)
-{
-  // Note: do nothing here for pass through.
-  double *my_buffer = (double *) buffer;
+  delete audio;
 
-  // Scale input data for output.
-  for (int i=0; i<buffer_size; i++) {
-    // Do for two channels.
+  return 0;
+}
+

+In this example, the stream was opened for recording with a non-zero inputChannels value. The only other difference between this example and that for playback involves the order of data processing in the loop, where it is necessary to first read a buffer of input data before manipulating it.

+Duplex Mode
+Finally, it is easy to use RtAudio for simultaneous audio input/output, or duplex operation. In this example, we use a callback function and simply scale the input data before sending it back to the output.
+
// duplex.cpp
+
+#include <iostream>
+#include "RtAudio.h"
+
+// Pass-through function.
+int scale(char *buffer, int bufferSize, void *)
+{
+  // Note: do nothing here for pass through.
+  double *my_buffer = (double *) buffer;
+
+  // Scale input data for output.
+  for (int i=0; i<bufferSize; i++) {
+    // Do for two channels.
     *my_buffer++ *= 0.5;
     *my_buffer++ *= 0.5;
   }
 
-  return 0;
+  return 0;
 }
 
-int main()
-{
-  int channels = 2;
-  int sample_rate = 44100;
-  int buffer_size = 256;  // 256 sample frames
-  int n_buffers = 4;      // number of internal buffers used by device
-  int device = 0;         // 0 indicates the default or first available device
-  int stream;             // our stream identifier
-  char input;
+int main()
+{
+  int channels = 2;
+  int sampleRate = 44100;
+  int bufferSize = 256;  // 256 sample frames
+  int nBuffers = 4;      // number of internal buffers used by device
+  int device = 0;        // 0 indicates the default or first available device
+  char input;
   RtAudio *audio;
 
-  // Open a stream during RtAudio instantiation
-  try {
-    audio = new RtAudio(&stream, device, channels, device, channels, RtAudio::RTAUDIO_FLOAT64,
-                        sample_rate, &buffer_size, n_buffers);
+  // Open a stream during RtAudio instantiation
+  try {
+    audio = new RtAudio(device, channels, device, channels, RTAUDIO_FLOAT64,
+                        sampleRate, &bufferSize, nBuffers);
   }
-  catch (RtError &error) {
+  catch (RtError &error) {
     error.printMessage();
     exit(EXIT_FAILURE);
   }
 
-  try {
-    // Set the stream callback function
-    audio->setStreamCallback(stream, &scale, NULL);
+  try {
+    // Set the stream callback function
+    audio->setStreamCallback(&scale, NULL);
 
-    // Start the stream
-    audio->startStream(stream);
+    // Start the stream
+    audio->startStream();
   }
-  catch (RtError &error) {
+  catch (RtError &error) {
     error.printMessage();
-    goto cleanup;
+    goto cleanup;
   }
 
-  cout << "\nRunning duplex ... press <enter> to quit.\n";
-  cin.get(input);
+  std::cout << "\nRunning duplex ... press <enter> to quit.\n";
+  std::cin.get(input);
 
-  try {
-    // Stop and close the stream
-    audio->stopStream(stream);
-    audio->closeStream(stream);
+  try {
+    // Stop and close the stream
+    audio->stopStream();
+    audio->closeStream();
   }
-  catch (RtError &error) {
+  catch (RtError &error) {
     error.printMessage();
   }
 
  cleanup:
-  delete audio;
-
-  return 0;
-}
-
-When an RtAudio stream is running in duplex mode (nonzero input AND output channels), the audio write (playback) operation always occurs before the audio read (record) operation. This sequence allows the use of a single buffer to store both output and input data.
-

-As we see with this example, the write-read sequence of operations does not preclude the use of RtAudio in situations where input data is first processed and then output through a duplex stream. When the stream buffer is first allocated, it is initialized with zeros, which produces no audible result when output to the device. In this example, anything recorded by the audio stream input will be scaled and played out during the next round of audio processing.
-

-Note that duplex operation can also be achieved by opening one output stream and one input stream using the same or different devices. However, there may be timing problems when attempting to use two different devices, due to possible device clock variations, unless a common external "sync" is provided. This becomes even more difficult to achieve using two separate callback streams because it is not possible to explicitly control the calling order of the callback functions.
-

-
Summary of Methods
+  delete audio;
 
-
-The following is short summary of public methods (not including constructors and the destructor) provided by RtAudio:
-

+  return 0;
+}
+

+When an RtAudio stream is running in duplex mode (nonzero input AND output channels), the audio write (playback) operation always occurs before the audio read (record) operation. This sequence allows the use of a single buffer to store both output and input data.

+As we see with this example, the write-read sequence of operations does not preclude the use of RtAudio in situations where input data is first processed and then output through a duplex stream. When the stream buffer is first allocated, it is initialized with zeros, which produces no audible result when output to the device. In this example, anything recorded by the audio stream input will be scaled and played out during the next round of audio processing.

+Note that duplex operation can also be achieved by opening one output stream instance and one input stream instance using the same or different devices. However, there may be timing problems when attempting to use two different devices, due to possible device clock variations, unless a common external "sync" is provided. This becomes even more difficult to achieve using two separate callback streams because it is not possible to explicitly control the calling order of the callback functions.

+Using Simultaneous Multiple APIs

+Summary of Methods

Compiling

-In order to compile RtAudio for a specific OS and audio API, it is necessary to supply the appropriate preprocessor definition and library within the compiler statement: -

- - - - - - -

OS:	Audio API:	Preprocessor Definition:	Library or Framework:	Example Compiler Statement:
Linux	ALSA	__LINUX_ALSA__	`asound, pthread`	`g++ -Wall -D__LINUX_ALSA__ -o probe probe.cpp RtAudio.cpp -lasound -lpthread`
Linux	OSS	__LINUX_OSS__	`pthread`	`g++ -Wall -D__LINUX_OSS__ -o probe probe.cpp RtAudio.cpp -lpthread`
Macintosh OS X	CoreAudio	__MACOSX_CORE__	`pthread, stdc++, CoreAudio`	`CC -Wall -D__MACOSX_CORE__ -o probe probe.cpp RtAudio.cpp -framework CoreAudio -lstdc++ -lpthread`
Irix	AL	__IRIX_AL__	`audio, pthread`	`CC -Wall -D__IRIX_AL__ -o probe probe.cpp RtAudio.cpp -laudio -lpthread`
Windows	Direct Sound	__WINDOWS_DS__	`dsound.lib (ver. 5.0 or higher), multithreaded`	compiler specific
Windows	ASIO	__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, and RtAudio.cpp all exist in the same directory. -

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. -

OS Notes

-RtAudio is designed to provide a common API across the various supported operating systems and audio libraries. Despite that, some issues need to be mentioned with regard to each. -

Linux:

-RtAudio for Linux was developed under Redhat distributions 7.0 - 7.2. Two different audio APIs are supported on Linux platforms: OSS and ALSA. 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. 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 0.9 and higher versions of ALSA. Input/output latency on the order of 15 milliseconds can typically be achieved under both OSS or ALSA 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. -

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 can be achieved with better synchrony by opening two separate streams for the devices and using RtAudio blocking calls (i.e. RtAudio::tickStream()). The numberOfBuffers parameter to the RtAudio::openStream() function has no affect in this implementation. It is not currently possible to have multiple simultaneous RtAudio streams accessing the same device. -

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. -

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 developed with Visual C++ version 6.0. I was forced in several instances to modify code in order to get it to compile under the non-standard version of C++ that Microsoft so unprofessionally implemented. Unfortunately, it appears they are continuing to undermine the C++ standard with more recent compiler releases. -

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. Therefore, it is not possible to have multiple simultaneous RtAudio streams running concurrently with this API. 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. See the /tests/asio/ directory for example Visual C++ 6.0 projects. -

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. -

License

-RtAudio: a realtime audio i/o C++ class
- Copyright (c) 2001-2002 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. +

+Compiling

+ + + + + + + + + + + + + + + + + +

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

RtAudio.h

RtAudio.h

RtError.h

RtAudio Compound List

RtAudio Class List

RtAudio Member List

RtAudio Member List

RtAudio Class Reference

RtAudio Class Reference

Public Methods

Static Public Attributes

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

RtError Member List

RtError Member List

RtError Class Reference

RtError Class Reference

Public Types

Public Methods

Public Member Functions

Detailed Description

Member Enumeration Documentation

RtAudio File List

RtAudio File List

RtAudio Compound Members

The RtAudio Tutorial

Introduction

The RtAudio Tutorial

RtAudioDeviceInfo Member List

RtAudioDeviceInfo Struct Reference

Public Attributes

Detailed Description

Member Data Documentation

RtAudio::RTAUDIO_DEVICE Member List

RtAudio::RTAUDIO_DEVICE Struct Reference

Public Attributes

Detailed Description

Member Data Documentation