RtAudio.h

Go to the documentation of this file.

/************************************************************************/
/************************************************************************/

#ifndef __RTAUDIO_H
#define __RTAUDIO_H

#define RTAUDIO_VERSION_MAJOR 6
#define RTAUDIO_VERSION_MINOR 0
#define RTAUDIO_VERSION_PATCH 1
#define RTAUDIO_VERSION_BETA  0

#define RTAUDIO_TOSTRING2(n) #n
#define RTAUDIO_TOSTRING(n) RTAUDIO_TOSTRING2(n)

#if RTAUDIO_VERSION_BETA > 0
    #define RTAUDIO_VERSION RTAUDIO_TOSTRING(RTAUDIO_VERSION_MAJOR) \
                        "." RTAUDIO_TOSTRING(RTAUDIO_VERSION_MINOR) \
                        "." RTAUDIO_TOSTRING(RTAUDIO_VERSION_PATCH) \
                     "beta" RTAUDIO_TOSTRING(RTAUDIO_VERSION_BETA)
#else
    #define RTAUDIO_VERSION RTAUDIO_TOSTRING(RTAUDIO_VERSION_MAJOR) \
                        "." RTAUDIO_TOSTRING(RTAUDIO_VERSION_MINOR) \
                        "." RTAUDIO_TOSTRING(RTAUDIO_VERSION_PATCH)
#endif

#if defined _WIN32 || defined __CYGWIN__
  #if defined(RTAUDIO_EXPORT)
    #define RTAUDIO_DLL_PUBLIC __declspec(dllexport)
  #else
    #define RTAUDIO_DLL_PUBLIC
  #endif
#else
  #if __GNUC__ >= 4
    #define RTAUDIO_DLL_PUBLIC __attribute__( (visibility( "default" )) )
  #else
    #define RTAUDIO_DLL_PUBLIC
  #endif
#endif

#include <string>
#include <vector>
#include <iostream>
#include <functional>

typedef unsigned long RtAudioFormat;
static const RtAudioFormat RTAUDIO_SINT8 = 0x1;    // 8-bit signed integer.
static const RtAudioFormat RTAUDIO_SINT16 = 0x2;   // 16-bit signed integer.
static const RtAudioFormat RTAUDIO_SINT24 = 0x4;   // 24-bit signed integer.
static const RtAudioFormat RTAUDIO_SINT32 = 0x8;   // 32-bit signed integer.
static const RtAudioFormat RTAUDIO_FLOAT32 = 0x10; // Normalized between plus/minus 1.0.
static const RtAudioFormat RTAUDIO_FLOAT64 = 0x20; // Normalized between plus/minus 1.0.

typedef unsigned int RtAudioStreamFlags;
static const RtAudioStreamFlags RTAUDIO_NONINTERLEAVED = 0x1;    // Use non-interleaved buffers (default = interleaved).
static const RtAudioStreamFlags RTAUDIO_MINIMIZE_LATENCY = 0x2;  // Attempt to set stream parameters for lowest possible latency.
static const RtAudioStreamFlags RTAUDIO_HOG_DEVICE = 0x4;        // Attempt grab device and prevent use by others.
static const RtAudioStreamFlags RTAUDIO_SCHEDULE_REALTIME = 0x8; // Try to select realtime scheduling for callback thread.
static const RtAudioStreamFlags RTAUDIO_ALSA_USE_DEFAULT = 0x10; // Use the "default" PCM device (ALSA only).
static const RtAudioStreamFlags RTAUDIO_JACK_DONT_CONNECT = 0x20; // Do not automatically connect ports (JACK only).

typedef unsigned int RtAudioStreamStatus;
static const RtAudioStreamStatus RTAUDIO_INPUT_OVERFLOW = 0x1;    // Input data was discarded because of an overflow condition at the driver.
static const RtAudioStreamStatus RTAUDIO_OUTPUT_UNDERFLOW = 0x2;  // The output buffer ran low, likely causing a gap in the output sound.


typedef int (*RtAudioCallback)( void *outputBuffer, void *inputBuffer,
                                unsigned int nFrames,
                                double streamTime,
                                RtAudioStreamStatus status,
                                void *userData );

enum RtAudioErrorType {
  RTAUDIO_NO_ERROR = 0,      
  RTAUDIO_WARNING,           
  RTAUDIO_UNKNOWN_ERROR,     
  RTAUDIO_NO_DEVICES_FOUND,  
  RTAUDIO_INVALID_DEVICE,    
  RTAUDIO_DEVICE_DISCONNECT, 
  RTAUDIO_MEMORY_ERROR,      
  RTAUDIO_INVALID_PARAMETER, 
  RTAUDIO_INVALID_USE,       
  RTAUDIO_DRIVER_ERROR,      
  RTAUDIO_SYSTEM_ERROR,      
  RTAUDIO_THREAD_ERROR       
};


typedef std::function<void(RtAudioErrorType type,
                           const std::string &errorText )>
  RtAudioErrorCallback;

// **************************************************************** //
//
// RtAudio class declaration.
//
// RtAudio is a "controller" used to select an available audio i/o
// interface.  It presents a common API for the user to call but all
// functionality is implemented by the class RtApi and its
// subclasses.  RtAudio creates an instance of an RtApi subclass
// based on the user's API choice.  If no choice is made, RtAudio
// attempts to make a "logical" API selection.
//
// **************************************************************** //

class RtApi;

class RTAUDIO_DLL_PUBLIC RtAudio
{
 public:

  enum Api {
    UNSPECIFIED,    
    MACOSX_CORE,    
    LINUX_ALSA,     
    UNIX_JACK,      
    LINUX_PULSE,    
    LINUX_OSS,      
    WINDOWS_ASIO,   
    WINDOWS_WASAPI, 
    WINDOWS_DS,     
    RTAUDIO_DUMMY,  
    NUM_APIS        
  };

  struct DeviceInfo {
    unsigned int ID{};              
    std::string name;               
    unsigned int outputChannels{};  
    unsigned int inputChannels{};   
    unsigned int duplexChannels{};  
    bool isDefaultOutput{false};         
    bool isDefaultInput{false};          
    std::vector<unsigned int> sampleRates; 
    unsigned int currentSampleRate{};   
    unsigned int preferredSampleRate{}; 
    RtAudioFormat nativeFormats{};  
  };

  struct StreamParameters {
    //std::string deviceName{};     /*!< Device name from device list. */
    unsigned int deviceId{};     
    unsigned int nChannels{};    
    unsigned int firstChannel{}; 
  };


  struct StreamOptions {
    RtAudioStreamFlags flags{};      
    unsigned int numberOfBuffers{};  
    std::string streamName;        
    int priority{};                  
  };

  static std::string getVersion( void );


  static void getCompiledApi( std::vector<RtAudio::Api> &apis );


  static std::string getApiName( RtAudio::Api api );


  static std::string getApiDisplayName( RtAudio::Api api );


  static RtAudio::Api getCompiledApiByName( const std::string &name );


  static RtAudio::Api getCompiledApiByDisplayName( const std::string &name );


  RtAudio( RtAudio::Api api=UNSPECIFIED, RtAudioErrorCallback&& errorCallback=0 );


  ~RtAudio();

  RtAudio::Api getCurrentApi( void );


  unsigned int getDeviceCount( void );


  std::vector<unsigned int> getDeviceIds( void );


  std::vector<std::string> getDeviceNames( void );


  RtAudio::DeviceInfo getDeviceInfo( unsigned int deviceId );


  unsigned int getDefaultOutputDevice( void );


  unsigned int getDefaultInputDevice( void );


  RtAudioErrorType openStream( RtAudio::StreamParameters *outputParameters,
                               RtAudio::StreamParameters *inputParameters,
                               RtAudioFormat format, unsigned int sampleRate,
                               unsigned int *bufferFrames, RtAudioCallback callback,
                               void *userData = NULL, RtAudio::StreamOptions *options = NULL );


  void closeStream( void );


  RtAudioErrorType startStream( void );


  RtAudioErrorType stopStream( void );


  RtAudioErrorType abortStream( void );


  const std::string getErrorText( void );

  bool isStreamOpen( void ) const;

  bool isStreamRunning( void ) const;


  double getStreamTime( void );

  void setStreamTime( double time );


  long getStreamLatency( void );


  unsigned int getStreamSampleRate( void );

  void setErrorCallback( RtAudioErrorCallback errorCallback );


  void showWarnings( bool value = true );

 protected:

  void openRtApi( RtAudio::Api api );
  RtApi *rtapi_;
};

// Operating system dependent thread functionality.
#if defined(_MSC_VER)

  #ifndef NOMINMAX
    #define NOMINMAX
  #endif
  #include <windows.h>
  #include <process.h>
  #include <stdint.h>

  typedef uintptr_t ThreadHandle;
  typedef CRITICAL_SECTION StreamMutex;

#else

  // Using pthread library for various flavors of unix.
  #include <pthread.h>

  typedef pthread_t ThreadHandle;
  typedef pthread_mutex_t StreamMutex;

#endif

// Setup for "dummy" behavior if no apis specified.
#if !(defined(__WINDOWS_DS__) || defined(__WINDOWS_ASIO__) || defined(__WINDOWS_WASAPI__) \
      || defined(__LINUX_ALSA__) || defined(__LINUX_PULSE__) || defined(__UNIX_JACK__) \
      || defined(__LINUX_OSS__) || defined(__MACOSX_CORE__))

  #define __RTAUDIO_DUMMY__

#endif

// This global structure type is used to pass callback information
// between the private RtAudio stream structure and global callback
// handling functions.
struct CallbackInfo {
  void *object{};    // Used as a "this" pointer.
  ThreadHandle thread{};
  void *callback{};
  void *userData{};
  void *apiInfo{};   // void pointer for API specific callback information
  bool isRunning{false};
  bool doRealtime{false};
  int priority{};
  bool deviceDisconnected{false};
};

// **************************************************************** //
//
// RtApi class declaration.
//
// Subclasses of RtApi contain all API- and OS-specific code necessary
// to fully implement the RtAudio API.
//
// Note that RtApi is an abstract base class and cannot be
// explicitly instantiated.  The class RtAudio will create an
// instance of an RtApi subclass (RtApiOss, RtApiAlsa,
// RtApiJack, RtApiCore, RtApiDs, or RtApiAsio).
//
// **************************************************************** //

#pragma pack(push, 1)
class S24 {

 protected:
  unsigned char c3[3];

 public:
  S24() {}

  S24& operator = ( const int& i ) {
    c3[0] = (unsigned char)(i & 0x000000ff);
    c3[1] = (unsigned char)((i & 0x0000ff00) >> 8);
    c3[2] = (unsigned char)((i & 0x00ff0000) >> 16);
    return *this;
  }

  S24( const double& d ) { *this = (int) d; }
  S24( const float& f ) { *this = (int) f; }
  S24( const signed short& s ) { *this = (int) s; }
  S24( const char& c ) { *this = (int) c; }

  int asInt() {
    int i = c3[0] | (c3[1] << 8) | (c3[2] << 16);
    if (i & 0x800000) i |= ~0xffffff;
    return i;
  }
};
#pragma pack(pop)

#if defined( HAVE_GETTIMEOFDAY )
  #include <sys/time.h>
#endif

#include <sstream>

class RTAUDIO_DLL_PUBLIC RtApi
{
public:

  RtApi();
  virtual ~RtApi();
  virtual RtAudio::Api getCurrentApi( void ) = 0;
  unsigned int getDeviceCount( void );
  std::vector<unsigned int> getDeviceIds( void );
  std::vector<std::string> getDeviceNames( void );
  RtAudio::DeviceInfo getDeviceInfo( unsigned int deviceId );
  virtual unsigned int getDefaultInputDevice( void );
  virtual unsigned int getDefaultOutputDevice( void );
  RtAudioErrorType openStream( RtAudio::StreamParameters *outputParameters,
                                 RtAudio::StreamParameters *inputParameters,
                                 RtAudioFormat format, unsigned int sampleRate,
                                 unsigned int *bufferFrames, RtAudioCallback callback,
                                 void *userData, RtAudio::StreamOptions *options );
  virtual void closeStream( void );
  virtual RtAudioErrorType startStream( void ) = 0;
  virtual RtAudioErrorType stopStream( void ) = 0;
  virtual RtAudioErrorType abortStream( void ) = 0;
  const std::string getErrorText( void ) const { return errorText_; }
  long getStreamLatency( void );
  unsigned int getStreamSampleRate( void );
  virtual double getStreamTime( void ) const { return stream_.streamTime; }
  virtual void setStreamTime( double time );
  bool isStreamOpen( void ) const { return stream_.state != STREAM_CLOSED; }
  bool isStreamRunning( void ) const { return stream_.state == STREAM_RUNNING; }
  void setErrorCallback( RtAudioErrorCallback errorCallback ) { errorCallback_ = errorCallback; }
  void showWarnings( bool value ) { showWarnings_ = value; }


protected:

  static const unsigned int MAX_SAMPLE_RATES;
  static const unsigned int SAMPLE_RATES[];

  enum { FAILURE, SUCCESS };

  enum StreamState {
    STREAM_STOPPED,
    STREAM_STOPPING,
    STREAM_RUNNING,
    STREAM_CLOSED = -50
  };

  enum StreamMode {
    OUTPUT,
    INPUT,
    DUPLEX,
    UNINITIALIZED = -75
  };

  // A protected structure used for buffer conversion.
  struct ConvertInfo {
    int channels;
    int inJump, outJump;
    RtAudioFormat inFormat, outFormat;
    std::vector<int> inOffset;
    std::vector<int> outOffset;
  };

  // A protected structure for audio streams.
  struct RtApiStream {
    unsigned int deviceId[2];  // Playback and record, respectively.
    void *apiHandle;           // void pointer for API specific stream handle information
    StreamMode mode;           // OUTPUT, INPUT, or DUPLEX.
    StreamState state;         // STOPPED, RUNNING, or CLOSED
    char *userBuffer[2];       // Playback and record, respectively.
    char *deviceBuffer;
    bool doConvertBuffer[2];   // Playback and record, respectively.
    bool userInterleaved;
    bool deviceInterleaved[2]; // Playback and record, respectively.
    bool doByteSwap[2];        // Playback and record, respectively.
    unsigned int sampleRate;
    unsigned int bufferSize;
    unsigned int nBuffers;
    unsigned int nUserChannels[2];    // Playback and record, respectively.
    unsigned int nDeviceChannels[2];  // Playback and record channels, respectively.
    unsigned int channelOffset[2];    // Playback and record, respectively.
    unsigned long latency[2];         // Playback and record, respectively.
    RtAudioFormat userFormat;
    RtAudioFormat deviceFormat[2];    // Playback and record, respectively.
    StreamMutex mutex;
    CallbackInfo callbackInfo;
    ConvertInfo convertInfo[2];
    double streamTime;         // Number of elapsed seconds since the stream started.

#if defined(HAVE_GETTIMEOFDAY)
    struct timeval lastTickTimestamp;
#endif

    RtApiStream()
    :apiHandle(0), deviceBuffer(0) {} // { device[0] = std::string(); device[1] = std::string(); }
  };

  typedef S24 Int24;
  typedef signed short Int16;
  typedef signed int Int32;
  typedef float Float32;
  typedef double Float64;

  std::ostringstream errorStream_;
  std::string errorText_;
  RtAudioErrorCallback errorCallback_;
  bool showWarnings_;
  std::vector<RtAudio::DeviceInfo> deviceList_;
  unsigned int currentDeviceId_;
  RtApiStream stream_;

  virtual void probeDevices( void );
  
  virtual bool probeDeviceOpen( unsigned int deviceId, StreamMode mode, unsigned int channels,
                                unsigned int firstChannel, unsigned int sampleRate,
                                RtAudioFormat format, unsigned int *bufferSize,
                                RtAudio::StreamOptions *options );

  void tickStreamTime( void );

  void clearStreamInfo();

  RtAudioErrorType error( RtAudioErrorType type );

  void convertBuffer( char *outBuffer, char *inBuffer, ConvertInfo &info );

  void byteSwapBuffer( char *buffer, unsigned int samples, RtAudioFormat format );

  unsigned int formatBytes( RtAudioFormat format );

  void setConvertInfo( StreamMode mode, unsigned int firstChannel );
};

// **************************************************************** //
//
// Inline RtAudio definitions.
//
// **************************************************************** //

inline RtAudio::Api RtAudio :: getCurrentApi( void ) { return rtapi_->getCurrentApi(); }
inline unsigned int RtAudio :: getDeviceCount( void ) { return rtapi_->getDeviceCount(); }
inline RtAudio::DeviceInfo RtAudio :: getDeviceInfo( unsigned int deviceId ) { return rtapi_->getDeviceInfo( deviceId ); }
inline std::vector<unsigned int> RtAudio :: getDeviceIds( void ) { return rtapi_->getDeviceIds(); }
inline std::vector<std::string> RtAudio :: getDeviceNames( void ) { return rtapi_->getDeviceNames(); }
inline unsigned int RtAudio :: getDefaultInputDevice( void ) { return rtapi_->getDefaultInputDevice(); }
inline unsigned int RtAudio :: getDefaultOutputDevice( void ) { return rtapi_->getDefaultOutputDevice(); }
inline void RtAudio :: closeStream( void ) { return rtapi_->closeStream(); }
inline RtAudioErrorType RtAudio :: startStream( void ) { return rtapi_->startStream(); }
inline RtAudioErrorType RtAudio :: stopStream( void )  { return rtapi_->stopStream(); }
inline RtAudioErrorType RtAudio :: abortStream( void ) { return rtapi_->abortStream(); }
inline const std::string RtAudio :: getErrorText( void ) { return rtapi_->getErrorText(); }
inline bool RtAudio :: isStreamOpen( void ) const { return rtapi_->isStreamOpen(); }
inline bool RtAudio :: isStreamRunning( void ) const { return rtapi_->isStreamRunning(); }
inline long RtAudio :: getStreamLatency( void ) { return rtapi_->getStreamLatency(); }
inline unsigned int RtAudio :: getStreamSampleRate( void ) { return rtapi_->getStreamSampleRate(); }
inline double RtAudio :: getStreamTime( void ) { return rtapi_->getStreamTime(); }
inline void RtAudio :: setStreamTime( double time ) { return rtapi_->setStreamTime( time ); }
inline void RtAudio :: setErrorCallback( RtAudioErrorCallback errorCallback ) { rtapi_->setErrorCallback( errorCallback ); }
inline void RtAudio :: showWarnings( bool value ) { rtapi_->showWarnings( value ); }

#endif

// Indentation settings for Vim and Emacs
//
// Local Variables:
// c-basic-offset: 2
// indent-tabs-mode: nil
// End:
//
// vim: et sts=2 sw=2