Home   Information   Classes   Download   Usage   Mail List   Requirements   Links   FAQ   Tutorial


RtAudio.h
Go to the documentation of this file.
1/************************************************************************/
40/************************************************************************/
41
46#ifndef __RTAUDIO_H
47#define __RTAUDIO_H
48
49#define RTAUDIO_VERSION_MAJOR 6
50#define RTAUDIO_VERSION_MINOR 0
51#define RTAUDIO_VERSION_PATCH 1
52#define RTAUDIO_VERSION_BETA 0
53
54#define RTAUDIO_TOSTRING2(n) #n
55#define RTAUDIO_TOSTRING(n) RTAUDIO_TOSTRING2(n)
56
57#if RTAUDIO_VERSION_BETA > 0
58 #define RTAUDIO_VERSION RTAUDIO_TOSTRING(RTAUDIO_VERSION_MAJOR) \
59 "." RTAUDIO_TOSTRING(RTAUDIO_VERSION_MINOR) \
60 "." RTAUDIO_TOSTRING(RTAUDIO_VERSION_PATCH) \
61 "beta" RTAUDIO_TOSTRING(RTAUDIO_VERSION_BETA)
62#else
63 #define RTAUDIO_VERSION RTAUDIO_TOSTRING(RTAUDIO_VERSION_MAJOR) \
64 "." RTAUDIO_TOSTRING(RTAUDIO_VERSION_MINOR) \
65 "." RTAUDIO_TOSTRING(RTAUDIO_VERSION_PATCH)
66#endif
67
68#if defined _WIN32 || defined __CYGWIN__
69 #if defined(RTAUDIO_EXPORT)
70 #define RTAUDIO_DLL_PUBLIC __declspec(dllexport)
71 #else
72 #define RTAUDIO_DLL_PUBLIC
73 #endif
74#else
75 #if __GNUC__ >= 4
76 #define RTAUDIO_DLL_PUBLIC __attribute__( (visibility( "default" )) )
77 #else
78 #define RTAUDIO_DLL_PUBLIC
79 #endif
80#endif
81
82#include <string>
83#include <vector>
84#include <iostream>
85#include <functional>
86
105typedef unsigned long RtAudioFormat;
106static const RtAudioFormat RTAUDIO_SINT8 = 0x1; // 8-bit signed integer.
107static const RtAudioFormat RTAUDIO_SINT16 = 0x2; // 16-bit signed integer.
108static const RtAudioFormat RTAUDIO_SINT24 = 0x4; // 24-bit signed integer.
109static const RtAudioFormat RTAUDIO_SINT32 = 0x8; // 32-bit signed integer.
110static const RtAudioFormat RTAUDIO_FLOAT32 = 0x10; // Normalized between plus/minus 1.0.
111static const RtAudioFormat RTAUDIO_FLOAT64 = 0x20; // Normalized between plus/minus 1.0.
112
159typedef unsigned int RtAudioStreamFlags;
160static const RtAudioStreamFlags RTAUDIO_NONINTERLEAVED = 0x1; // Use non-interleaved buffers (default = interleaved).
161static const RtAudioStreamFlags RTAUDIO_MINIMIZE_LATENCY = 0x2; // Attempt to set stream parameters for lowest possible latency.
162static const RtAudioStreamFlags RTAUDIO_HOG_DEVICE = 0x4; // Attempt grab device and prevent use by others.
163static const RtAudioStreamFlags RTAUDIO_SCHEDULE_REALTIME = 0x8; // Try to select realtime scheduling for callback thread.
164static const RtAudioStreamFlags RTAUDIO_ALSA_USE_DEFAULT = 0x10; // Use the "default" PCM device (ALSA only).
165static const RtAudioStreamFlags RTAUDIO_JACK_DONT_CONNECT = 0x20; // Do not automatically connect ports (JACK only).
166
178typedef unsigned int RtAudioStreamStatus;
179static const RtAudioStreamStatus RTAUDIO_INPUT_OVERFLOW = 0x1; // Input data was discarded because of an overflow condition at the driver.
180static const RtAudioStreamStatus RTAUDIO_OUTPUT_UNDERFLOW = 0x2; // The output buffer ran low, likely causing a gap in the output sound.
181
183
222typedef int (*RtAudioCallback)( void *outputBuffer, void *inputBuffer,
223 unsigned int nFrames,
224 double streamTime,
225 RtAudioStreamStatus status,
226 void *userData );
227
242
244
248typedef std::function<void(RtAudioErrorType type,
249 const std::string &errorText )>
251
252// **************************************************************** //
253//
254// RtAudio class declaration.
255//
256// RtAudio is a "controller" used to select an available audio i/o
257// interface. It presents a common API for the user to call but all
258// functionality is implemented by the class RtApi and its
259// subclasses. RtAudio creates an instance of an RtApi subclass
260// based on the user's API choice. If no choice is made, RtAudio
261// attempts to make a "logical" API selection.
262//
263// **************************************************************** //
264
265class RtApi;
266
267class RTAUDIO_DLL_PUBLIC RtAudio
268{
269 public:
270
272 enum Api {
283 NUM_APIS
284 };
285
287 struct DeviceInfo {
288 unsigned int ID{};
289 std::string name;
290 unsigned int outputChannels{};
291 unsigned int inputChannels{};
292 unsigned int duplexChannels{};
293 bool isDefaultOutput{false};
294 bool isDefaultInput{false};
295 std::vector<unsigned int> sampleRates;
296 unsigned int currentSampleRate{};
297 unsigned int preferredSampleRate{};
298 RtAudioFormat nativeFormats{};
299 };
300
303 //std::string deviceName{}; /*!< Device name from device list. */
304 unsigned int deviceId{};
305 unsigned int nChannels{};
306 unsigned int firstChannel{};
307 };
308
310
370 unsigned int numberOfBuffers{};
371 std::string streamName;
372 int priority{};
373 };
374
376 static std::string getVersion( void );
377
379
384 static void getCompiledApi( std::vector<RtAudio::Api> &apis );
385
387
392 static std::string getApiName( RtAudio::Api api );
393
395
399 static std::string getApiDisplayName( RtAudio::Api api );
400
402
407 static RtAudio::Api getCompiledApiByName( const std::string &name );
408
410
415 static RtAudio::Api getCompiledApiByDisplayName( const std::string &name );
416
418
433 RtAudio( RtAudio::Api api=UNSPECIFIED, RtAudioErrorCallback&& errorCallback=0 );
434
436
441
443 RtAudio::Api getCurrentApi( void );
444
446
452 unsigned int getDeviceCount( void );
453
455
465 std::vector<unsigned int> getDeviceIds( void );
466
468
475 std::vector<std::string> getDeviceNames( void );
476
478
490 RtAudio::DeviceInfo getDeviceInfo( unsigned int deviceId );
491
493
499 unsigned int getDefaultOutputDevice( void );
500
502
508 unsigned int getDefaultInputDevice( void );
509
511
549 RtAudio::StreamParameters *inputParameters,
550 RtAudioFormat format, unsigned int sampleRate,
551 unsigned int *bufferFrames, RtAudioCallback callback,
552 void *userData = NULL, RtAudio::StreamOptions *options = NULL );
553
555
560 void closeStream( void );
561
563
568 RtAudioErrorType startStream( void );
569
571
576 RtAudioErrorType stopStream( void );
577
579
584 RtAudioErrorType abortStream( void );
585
587
592 const std::string getErrorText( void );
593
595 bool isStreamOpen( void ) const;
596
598 bool isStreamRunning( void ) const;
599
601
608 double getStreamTime( void );
609
611 void setStreamTime( double time );
612
614
622 long getStreamLatency( void );
623
625
630 unsigned int getStreamSampleRate( void );
631
633 void setErrorCallback( RtAudioErrorCallback errorCallback );
634
636
641 void showWarnings( bool value = true );
642
643 protected:
644
645 void openRtApi( RtAudio::Api api );
646 RtApi *rtapi_;
647};
648
649// Operating system dependent thread functionality.
650#if defined(_MSC_VER)
651
652 #ifndef NOMINMAX
653 #define NOMINMAX
654 #endif
655 #include <windows.h>
656 #include <process.h>
657 #include <stdint.h>
658
659 typedef uintptr_t ThreadHandle;
660 typedef CRITICAL_SECTION StreamMutex;
661
662#else
663
664 // Using pthread library for various flavors of unix.
665 #include <pthread.h>
666
667 typedef pthread_t ThreadHandle;
668 typedef pthread_mutex_t StreamMutex;
669
670#endif
671
672// Setup for "dummy" behavior if no apis specified.
673#if !(defined(__WINDOWS_DS__) || defined(__WINDOWS_ASIO__) || defined(__WINDOWS_WASAPI__) \
674 || defined(__LINUX_ALSA__) || defined(__LINUX_PULSE__) || defined(__UNIX_JACK__) \
675 || defined(__LINUX_OSS__) || defined(__MACOSX_CORE__))
676
677 #define __RTAUDIO_DUMMY__
678
679#endif
680
681// This global structure type is used to pass callback information
682// between the private RtAudio stream structure and global callback
683// handling functions.
684struct CallbackInfo {
685 void *object{}; // Used as a "this" pointer.
686 ThreadHandle thread{};
687 void *callback{};
688 void *userData{};
689 void *apiInfo{}; // void pointer for API specific callback information
690 bool isRunning{false};
691 bool doRealtime{false};
692 int priority{};
693 bool deviceDisconnected{false};
694};
695
696// **************************************************************** //
697//
698// RtApi class declaration.
699//
700// Subclasses of RtApi contain all API- and OS-specific code necessary
701// to fully implement the RtAudio API.
702//
703// Note that RtApi is an abstract base class and cannot be
704// explicitly instantiated. The class RtAudio will create an
705// instance of an RtApi subclass (RtApiOss, RtApiAlsa,
706// RtApiJack, RtApiCore, RtApiDs, or RtApiAsio).
707//
708// **************************************************************** //
709
710#pragma pack(push, 1)
711class S24 {
712
713 protected:
714 unsigned char c3[3];
715
716 public:
717 S24() {}
718
719 S24& operator = ( const int& i ) {
720 c3[0] = (unsigned char)(i & 0x000000ff);
721 c3[1] = (unsigned char)((i & 0x0000ff00) >> 8);
722 c3[2] = (unsigned char)((i & 0x00ff0000) >> 16);
723 return *this;
724 }
725
726 S24( const double& d ) { *this = (int) d; }
727 S24( const float& f ) { *this = (int) f; }
728 S24( const signed short& s ) { *this = (int) s; }
729 S24( const char& c ) { *this = (int) c; }
730
731 int asInt() {
732 int i = c3[0] | (c3[1] << 8) | (c3[2] << 16);
733 if (i & 0x800000) i |= ~0xffffff;
734 return i;
735 }
736};
737#pragma pack(pop)
738
739#if defined( HAVE_GETTIMEOFDAY )
740 #include <sys/time.h>
741#endif
742
743#include <sstream>
744
745class RTAUDIO_DLL_PUBLIC RtApi
746{
747public:
748
749 RtApi();
750 virtual ~RtApi();
751 virtual RtAudio::Api getCurrentApi( void ) = 0;
752 unsigned int getDeviceCount( void );
753 std::vector<unsigned int> getDeviceIds( void );
754 std::vector<std::string> getDeviceNames( void );
755 RtAudio::DeviceInfo getDeviceInfo( unsigned int deviceId );
756 virtual unsigned int getDefaultInputDevice( void );
757 virtual unsigned int getDefaultOutputDevice( void );
758 RtAudioErrorType openStream( RtAudio::StreamParameters *outputParameters,
759 RtAudio::StreamParameters *inputParameters,
760 RtAudioFormat format, unsigned int sampleRate,
761 unsigned int *bufferFrames, RtAudioCallback callback,
762 void *userData, RtAudio::StreamOptions *options );
763 virtual void closeStream( void );
764 virtual RtAudioErrorType startStream( void ) = 0;
765 virtual RtAudioErrorType stopStream( void ) = 0;
766 virtual RtAudioErrorType abortStream( void ) = 0;
767 const std::string getErrorText( void ) const { return errorText_; }
768 long getStreamLatency( void );
769 unsigned int getStreamSampleRate( void );
770 virtual double getStreamTime( void ) const { return stream_.streamTime; }
771 virtual void setStreamTime( double time );
772 bool isStreamOpen( void ) const { return stream_.state != STREAM_CLOSED; }
773 bool isStreamRunning( void ) const { return stream_.state == STREAM_RUNNING; }
774 void setErrorCallback( RtAudioErrorCallback errorCallback ) { errorCallback_ = errorCallback; }
775 void showWarnings( bool value ) { showWarnings_ = value; }
776
777
778protected:
779
780 static const unsigned int MAX_SAMPLE_RATES;
781 static const unsigned int SAMPLE_RATES[];
782
783 enum { FAILURE, SUCCESS };
784
785 enum StreamState {
786 STREAM_STOPPED,
787 STREAM_STOPPING,
788 STREAM_RUNNING,
789 STREAM_CLOSED = -50
790 };
791
792 enum StreamMode {
793 OUTPUT,
794 INPUT,
795 DUPLEX,
796 UNINITIALIZED = -75
797 };
798
799 // A protected structure used for buffer conversion.
800 struct ConvertInfo {
801 int channels;
802 int inJump, outJump;
803 RtAudioFormat inFormat, outFormat;
804 std::vector<int> inOffset;
805 std::vector<int> outOffset;
806 };
807
808 // A protected structure for audio streams.
809 struct RtApiStream {
810 unsigned int deviceId[2]; // Playback and record, respectively.
811 void *apiHandle; // void pointer for API specific stream handle information
812 StreamMode mode; // OUTPUT, INPUT, or DUPLEX.
813 StreamState state; // STOPPED, RUNNING, or CLOSED
814 char *userBuffer[2]; // Playback and record, respectively.
815 char *deviceBuffer;
816 bool doConvertBuffer[2]; // Playback and record, respectively.
817 bool userInterleaved;
818 bool deviceInterleaved[2]; // Playback and record, respectively.
819 bool doByteSwap[2]; // Playback and record, respectively.
820 unsigned int sampleRate;
821 unsigned int bufferSize;
822 unsigned int nBuffers;
823 unsigned int nUserChannels[2]; // Playback and record, respectively.
824 unsigned int nDeviceChannels[2]; // Playback and record channels, respectively.
825 unsigned int channelOffset[2]; // Playback and record, respectively.
826 unsigned long latency[2]; // Playback and record, respectively.
827 RtAudioFormat userFormat;
828 RtAudioFormat deviceFormat[2]; // Playback and record, respectively.
829 StreamMutex mutex;
830 CallbackInfo callbackInfo;
831 ConvertInfo convertInfo[2];
832 double streamTime; // Number of elapsed seconds since the stream started.
833
834#if defined(HAVE_GETTIMEOFDAY)
835 struct timeval lastTickTimestamp;
836#endif
837
838 RtApiStream()
839 :apiHandle(0), deviceBuffer(0) {} // { device[0] = std::string(); device[1] = std::string(); }
840 };
841
842 typedef S24 Int24;
843 typedef signed short Int16;
844 typedef signed int Int32;
845 typedef float Float32;
846 typedef double Float64;
847
848 std::ostringstream errorStream_;
849 std::string errorText_;
850 RtAudioErrorCallback errorCallback_;
851 bool showWarnings_;
852 std::vector<RtAudio::DeviceInfo> deviceList_;
853 unsigned int currentDeviceId_;
854 RtApiStream stream_;
855
864 virtual void probeDevices( void );
865
873 virtual bool probeDeviceOpen( unsigned int deviceId, StreamMode mode, unsigned int channels,
874 unsigned int firstChannel, unsigned int sampleRate,
875 RtAudioFormat format, unsigned int *bufferSize,
876 RtAudio::StreamOptions *options );
877
879 void tickStreamTime( void );
880
882 void clearStreamInfo();
883
886
891 void convertBuffer( char *outBuffer, char *inBuffer, ConvertInfo &info );
892
894 void byteSwapBuffer( char *buffer, unsigned int samples, RtAudioFormat format );
895
897 unsigned int formatBytes( RtAudioFormat format );
898
900 void setConvertInfo( StreamMode mode, unsigned int firstChannel );
901};
902
903// **************************************************************** //
904//
905// Inline RtAudio definitions.
906//
907// **************************************************************** //
908
909inline RtAudio::Api RtAudio :: getCurrentApi( void ) { return rtapi_->getCurrentApi(); }
910inline unsigned int RtAudio :: getDeviceCount( void ) { return rtapi_->getDeviceCount(); }
911inline RtAudio::DeviceInfo RtAudio :: getDeviceInfo( unsigned int deviceId ) { return rtapi_->getDeviceInfo( deviceId ); }
912inline std::vector<unsigned int> RtAudio :: getDeviceIds( void ) { return rtapi_->getDeviceIds(); }
913inline std::vector<std::string> RtAudio :: getDeviceNames( void ) { return rtapi_->getDeviceNames(); }
914inline unsigned int RtAudio :: getDefaultInputDevice( void ) { return rtapi_->getDefaultInputDevice(); }
915inline unsigned int RtAudio :: getDefaultOutputDevice( void ) { return rtapi_->getDefaultOutputDevice(); }
916inline void RtAudio :: closeStream( void ) { return rtapi_->closeStream(); }
917inline RtAudioErrorType RtAudio :: startStream( void ) { return rtapi_->startStream(); }
918inline RtAudioErrorType RtAudio :: stopStream( void ) { return rtapi_->stopStream(); }
919inline RtAudioErrorType RtAudio :: abortStream( void ) { return rtapi_->abortStream(); }
920inline const std::string RtAudio :: getErrorText( void ) { return rtapi_->getErrorText(); }
921inline bool RtAudio :: isStreamOpen( void ) const { return rtapi_->isStreamOpen(); }
922inline bool RtAudio :: isStreamRunning( void ) const { return rtapi_->isStreamRunning(); }
923inline long RtAudio :: getStreamLatency( void ) { return rtapi_->getStreamLatency(); }
924inline unsigned int RtAudio :: getStreamSampleRate( void ) { return rtapi_->getStreamSampleRate(); }
925inline double RtAudio :: getStreamTime( void ) { return rtapi_->getStreamTime(); }
926inline void RtAudio :: setStreamTime( double time ) { return rtapi_->setStreamTime( time ); }
927inline void RtAudio :: setErrorCallback( RtAudioErrorCallback errorCallback ) { rtapi_->setErrorCallback( errorCallback ); }
928inline void RtAudio :: showWarnings( bool value ) { rtapi_->showWarnings( value ); }
929
930#endif
931
932// Indentation settings for Vim and Emacs
933//
934// Local Variables:
935// c-basic-offset: 2
936// indent-tabs-mode: nil
937// End:
938//
939// vim: et sts=2 sw=2
unsigned int RtAudioStreamFlags
RtAudio stream option flags.
Definition RtAudio.h:159
std::function< void(RtAudioErrorType type, const std::string &errorText)> RtAudioErrorCallback
RtAudio error callback function prototype.
Definition RtAudio.h:250
unsigned int RtAudioStreamStatus
RtAudio stream status (over- or underflow) flags.
Definition RtAudio.h:178
int(* RtAudioCallback)(void *outputBuffer, void *inputBuffer, unsigned int nFrames, double streamTime, RtAudioStreamStatus status, void *userData)
RtAudio callback function prototype.
Definition RtAudio.h:222
unsigned long RtAudioFormat
RtAudio data format type.
Definition RtAudio.h:105
RtAudioErrorType
Definition RtAudio.h:228
@ RTAUDIO_DEVICE_DISCONNECT
Definition RtAudio.h:234
@ RTAUDIO_DRIVER_ERROR
Definition RtAudio.h:238
@ RTAUDIO_NO_ERROR
Definition RtAudio.h:229
@ RTAUDIO_INVALID_PARAMETER
Definition RtAudio.h:236
@ RTAUDIO_INVALID_DEVICE
Definition RtAudio.h:233
@ RTAUDIO_SYSTEM_ERROR
Definition RtAudio.h:239
@ RTAUDIO_WARNING
Definition RtAudio.h:230
@ RTAUDIO_THREAD_ERROR
Definition RtAudio.h:240
@ RTAUDIO_INVALID_USE
Definition RtAudio.h:237
@ RTAUDIO_UNKNOWN_ERROR
Definition RtAudio.h:231
@ RTAUDIO_NO_DEVICES_FOUND
Definition RtAudio.h:232
@ RTAUDIO_MEMORY_ERROR
Definition RtAudio.h:235
Realtime audio i/o C++ classes.
Definition RtAudio.h:268
static RtAudio::Api getCompiledApiByDisplayName(const std::string &name)
Return the compiled audio API having the given display name.
static std::string getApiName(RtAudio::Api api)
Return the name of a specified compiled audio API.
static std::string getApiDisplayName(RtAudio::Api api)
Return the display name of a specified compiled audio API.
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)
A public function for opening a stream with the specified parameters.
~RtAudio()
The destructor.
static RtAudio::Api getCompiledApiByName(const std::string &name)
Return the compiled audio API having the given name.
Api
Audio API specifier arguments.
Definition RtAudio.h:272
@ WINDOWS_ASIO
Definition RtAudio.h:279
@ WINDOWS_DS
Definition RtAudio.h:281
@ LINUX_OSS
Definition RtAudio.h:278
@ UNIX_JACK
Definition RtAudio.h:276
@ MACOSX_CORE
Definition RtAudio.h:274
@ UNSPECIFIED
Definition RtAudio.h:273
@ LINUX_ALSA
Definition RtAudio.h:275
@ RTAUDIO_DUMMY
Definition RtAudio.h:282
@ WINDOWS_WASAPI
Definition RtAudio.h:280
@ LINUX_PULSE
Definition RtAudio.h:277
RtAudio(RtAudio::Api api=UNSPECIFIED, RtAudioErrorCallback &&errorCallback=0)
The class constructor.
static void getCompiledApi(std::vector< RtAudio::Api > &apis)
A static function to determine the available compiled audio APIs.
static std::string getVersion(void)
A static function to determine the current RtAudio version.
The public device information structure for returning queried values.
Definition RtAudio.h:287
std::string name
Definition RtAudio.h:289
std::vector< unsigned int > sampleRates
Definition RtAudio.h:295
The structure for specifying stream options.
Definition RtAudio.h:368
std::string streamName
Definition RtAudio.h:371
The structure for specifying input or output stream parameters.
Definition RtAudio.h:302

The Synthesis ToolKit in C++ (STK)
©1995--2023 Perry R. Cook and Gary P. Scavone. All Rights Reserved.