1 /************************************************************************/
3 \brief Realtime audio i/o C++ classes.
5 RtAudio provides a common API (Application Programming Interface)
6 for realtime audio input/output across Linux (native ALSA, Jack,
7 and OSS), Macintosh OS X (CoreAudio and Jack), and Windows
8 (DirectSound and ASIO) operating systems.
10 RtAudio WWW site: http://www.music.mcgill.ca/~gary/rtaudio/
12 RtAudio: realtime audio i/o C++ classes
13 Copyright (c) 2001-2010 Gary P. Scavone
15 Permission is hereby granted, free of charge, to any person
16 obtaining a copy of this software and associated documentation files
17 (the "Software"), to deal in the Software without restriction,
18 including without limitation the rights to use, copy, modify, merge,
19 publish, distribute, sublicense, and/or sell copies of the Software,
20 and to permit persons to whom the Software is furnished to do so,
21 subject to the following conditions:
23 The above copyright notice and this permission notice shall be
24 included in all copies or substantial portions of the Software.
26 Any person wishing to distribute modifications to the Software is
27 asked to send the modifications to the original developer so that
28 they can be incorporated into the canonical version. This is,
29 however, not a binding provision of this license.
31 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
32 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
33 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
34 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
35 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
36 CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
37 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
39 /************************************************************************/
45 // RtAudio: Version 4.0.7
54 /*! \typedef typedef unsigned long RtAudioFormat;
55 \brief RtAudio data format type.
57 Support for signed integers and floats. Audio data fed to/from an
58 RtAudio stream is assumed to ALWAYS be in host byte order. The
59 internal routines will automatically take care of any necessary
60 byte-swapping between the host format and the soundcard. Thus,
61 endian-ness is not a concern in the following format definitions.
63 - \e RTAUDIO_SINT8: 8-bit signed integer.
64 - \e RTAUDIO_SINT16: 16-bit signed integer.
65 - \e RTAUDIO_SINT24: Upper 3 bytes of 32-bit signed integer.
66 - \e RTAUDIO_SINT32: 32-bit signed integer.
67 - \e RTAUDIO_FLOAT32: Normalized between plus/minus 1.0.
68 - \e RTAUDIO_FLOAT64: Normalized between plus/minus 1.0.
70 typedef unsigned long RtAudioFormat;
71 static const RtAudioFormat RTAUDIO_SINT8 = 0x1; // 8-bit signed integer.
72 static const RtAudioFormat RTAUDIO_SINT16 = 0x2; // 16-bit signed integer.
73 static const RtAudioFormat RTAUDIO_SINT24 = 0x4; // Lower 3 bytes of 32-bit signed integer.
74 static const RtAudioFormat RTAUDIO_SINT32 = 0x8; // 32-bit signed integer.
75 static const RtAudioFormat RTAUDIO_FLOAT32 = 0x10; // Normalized between plus/minus 1.0.
76 static const RtAudioFormat RTAUDIO_FLOAT64 = 0x20; // Normalized between plus/minus 1.0.
78 /*! \typedef typedef unsigned long RtAudioStreamFlags;
79 \brief RtAudio stream option flags.
81 The following flags can be OR'ed together to allow a client to
82 make changes to the default stream behavior:
84 - \e RTAUDIO_NONINTERLEAVED: Use non-interleaved buffers (default = interleaved).
85 - \e RTAUDIO_MINIMIZE_LATENCY: Attempt to set stream parameters for lowest possible latency.
86 - \e RTAUDIO_HOG_DEVICE: Attempt grab device for exclusive use.
88 By default, RtAudio streams pass and receive audio data from the
89 client in an interleaved format. By passing the
90 RTAUDIO_NONINTERLEAVED flag to the openStream() function, audio
91 data will instead be presented in non-interleaved buffers. In
92 this case, each buffer argument in the RtAudioCallback function
93 will point to a single array of data, with \c nFrames samples for
94 each channel concatenated back-to-back. For example, the first
95 sample of data for the second channel would be located at index \c
96 nFrames (assuming the \c buffer pointer was recast to the correct
97 data type for the stream).
99 Certain audio APIs offer a number of parameters that influence the
100 I/O latency of a stream. By default, RtAudio will attempt to set
101 these parameters internally for robust (glitch-free) performance
102 (though some APIs, like Windows Direct Sound, make this difficult).
103 By passing the RTAUDIO_MINIMIZE_LATENCY flag to the openStream()
104 function, internal stream settings will be influenced in an attempt
105 to minimize stream latency, though possibly at the expense of stream
108 If the RTAUDIO_HOG_DEVICE flag is set, RtAudio will attempt to
109 open the input and/or output stream device(s) for exclusive use.
110 Note that this is not possible with all supported audio APIs.
112 If the RTAUDIO_SCHEDULE_REALTIME flag is set, RtAudio will attempt
113 to select realtime scheduling (round-robin) for the callback thread.
115 typedef unsigned int RtAudioStreamFlags;
116 static const RtAudioStreamFlags RTAUDIO_NONINTERLEAVED = 0x1; // Use non-interleaved buffers (default = interleaved).
117 static const RtAudioStreamFlags RTAUDIO_MINIMIZE_LATENCY = 0x2; // Attempt to set stream parameters for lowest possible latency.
118 static const RtAudioStreamFlags RTAUDIO_HOG_DEVICE = 0x4; // Attempt grab device and prevent use by others.
119 static const RtAudioStreamFlags RTAUDIO_SCHEDULE_REALTIME = 0x8; // Try to select realtime scheduling for callback thread.
121 /*! \typedef typedef unsigned long RtAudioStreamStatus;
122 \brief RtAudio stream status (over- or underflow) flags.
124 Notification of a stream over- or underflow is indicated by a
125 non-zero stream \c status argument in the RtAudioCallback function.
126 The stream status can be one of the following two options,
127 depending on whether the stream is open for output and/or input:
129 - \e RTAUDIO_INPUT_OVERFLOW: Input data was discarded because of an overflow condition at the driver.
130 - \e RTAUDIO_OUTPUT_UNDERFLOW: The output buffer ran low, likely producing a break in the output sound.
132 typedef unsigned int RtAudioStreamStatus;
133 static const RtAudioStreamStatus RTAUDIO_INPUT_OVERFLOW = 0x1; // Input data was discarded because of an overflow condition at the driver.
134 static const RtAudioStreamStatus RTAUDIO_OUTPUT_UNDERFLOW = 0x2; // The output buffer ran low, likely causing a gap in the output sound.
136 //! RtAudio callback function prototype.
138 All RtAudio clients must create a function of type RtAudioCallback
139 to read and/or write data from/to the audio stream. When the
140 underlying audio system is ready for new input or output data, this
141 function will be invoked.
143 \param outputBuffer For output (or duplex) streams, the client
144 should write \c nFrames of audio sample frames into this
145 buffer. This argument should be recast to the datatype
146 specified when the stream was opened. For input-only
147 streams, this argument will be NULL.
149 \param inputBuffer For input (or duplex) streams, this buffer will
150 hold \c nFrames of input audio sample frames. This
151 argument should be recast to the datatype specified when the
152 stream was opened. For output-only streams, this argument
155 \param nFrames The number of sample frames of input or output
156 data in the buffers. The actual buffer size in bytes is
157 dependent on the data type and number of channels in use.
159 \param streamTime The number of seconds that have elapsed since the
162 \param status If non-zero, this argument indicates a data overflow
163 or underflow condition for the stream. The particular
164 condition can be determined by comparison with the
165 RtAudioStreamStatus flags.
167 \param userData A pointer to optional data provided by the client
168 when opening the stream (default = NULL).
170 To continue normal stream operation, the RtAudioCallback function
171 should return a value of zero. To stop the stream and drain the
172 output buffer, the function should return a value of one. To abort
173 the stream immediately, the client should return a value of two.
175 typedef int (*RtAudioCallback)( void *outputBuffer, void *inputBuffer,
176 unsigned int nFrames,
178 RtAudioStreamStatus status,
182 // **************************************************************** //
184 // RtAudio class declaration.
186 // RtAudio is a "controller" used to select an available audio i/o
187 // interface. It presents a common API for the user to call but all
188 // functionality is implemented by the class RtApi and its
189 // subclasses. RtAudio creates an instance of an RtApi subclass
190 // based on the user's API choice. If no choice is made, RtAudio
191 // attempts to make a "logical" API selection.
193 // **************************************************************** //
201 //! Audio API specifier arguments.
203 UNSPECIFIED, /*!< Search for a working compiled API. */
204 LINUX_ALSA, /*!< The Advanced Linux Sound Architecture API. */
205 LINUX_OSS, /*!< The Linux Open Sound System API. */
206 UNIX_JACK, /*!< The Jack Low-Latency Audio Server API. */
207 MACOSX_CORE, /*!< Macintosh OS-X Core Audio API. */
208 WINDOWS_ASIO, /*!< The Steinberg Audio Stream I/O API. */
209 WINDOWS_DS, /*!< The Microsoft Direct Sound API. */
210 RTAUDIO_DUMMY /*!< A compilable but non-functional API. */
213 //! The public device information structure for returning queried values.
215 bool probed; /*!< true if the device capabilities were successfully probed. */
216 std::string name; /*!< Character string device identifier. */
217 unsigned int outputChannels; /*!< Maximum output channels supported by device. */
218 unsigned int inputChannels; /*!< Maximum input channels supported by device. */
219 unsigned int duplexChannels; /*!< Maximum simultaneous input/output channels supported by device. */
220 bool isDefaultOutput; /*!< true if this is the default output device. */
221 bool isDefaultInput; /*!< true if this is the default input device. */
222 std::vector<unsigned int> sampleRates; /*!< Supported sample rates (queried from list of standard rates). */
223 RtAudioFormat nativeFormats; /*!< Bit mask of supported data formats. */
225 // Default constructor.
227 :probed(false), outputChannels(0), inputChannels(0), duplexChannels(0),
228 isDefaultOutput(false), isDefaultInput(false), nativeFormats(0) {}
231 //! The structure for specifying input or ouput stream parameters.
232 struct StreamParameters {
233 unsigned int deviceId; /*!< Device index (0 to getDeviceCount() - 1). */
234 unsigned int nChannels; /*!< Number of channels. */
235 unsigned int firstChannel; /*!< First channel index on device (default = 0). */
237 // Default constructor.
239 : deviceId(0), nChannels(0), firstChannel(0) {}
242 //! The structure for specifying stream options.
244 The following flags can be OR'ed together to allow a client to
245 make changes to the default stream behavior:
247 - \e RTAUDIO_NONINTERLEAVED: Use non-interleaved buffers (default = interleaved).
248 - \e RTAUDIO_MINIMIZE_LATENCY: Attempt to set stream parameters for lowest possible latency.
249 - \e RTAUDIO_HOG_DEVICE: Attempt grab device for exclusive use.
250 - \e RTAUDIO_SCHEDULE_REALTIME: Attempt to select realtime scheduling for callback thread.
252 By default, RtAudio streams pass and receive audio data from the
253 client in an interleaved format. By passing the
254 RTAUDIO_NONINTERLEAVED flag to the openStream() function, audio
255 data will instead be presented in non-interleaved buffers. In
256 this case, each buffer argument in the RtAudioCallback function
257 will point to a single array of data, with \c nFrames samples for
258 each channel concatenated back-to-back. For example, the first
259 sample of data for the second channel would be located at index \c
260 nFrames (assuming the \c buffer pointer was recast to the correct
261 data type for the stream).
263 Certain audio APIs offer a number of parameters that influence the
264 I/O latency of a stream. By default, RtAudio will attempt to set
265 these parameters internally for robust (glitch-free) performance
266 (though some APIs, like Windows Direct Sound, make this difficult).
267 By passing the RTAUDIO_MINIMIZE_LATENCY flag to the openStream()
268 function, internal stream settings will be influenced in an attempt
269 to minimize stream latency, though possibly at the expense of stream
272 If the RTAUDIO_HOG_DEVICE flag is set, RtAudio will attempt to
273 open the input and/or output stream device(s) for exclusive use.
274 Note that this is not possible with all supported audio APIs.
276 If the RTAUDIO_SCHEDULE_REALTIME flag is set, RtAudio will attempt
277 to select realtime scheduling (round-robin) for the callback thread.
278 The \c priority parameter will only be used if the RTAUDIO_SCHEDULE_REALTIME
279 flag is set. It defines the thread's realtime priority.
281 The \c numberOfBuffers parameter can be used to control stream
282 latency in the Windows DirectSound, Linux OSS, and Linux Alsa APIs
283 only. A value of two is usually the smallest allowed. Larger
284 numbers can potentially result in more robust stream performance,
285 though likely at the cost of stream latency. The value set by the
286 user is replaced during execution of the RtAudio::openStream()
287 function by the value actually used by the system.
289 The \c streamName parameter can be used to set the client name
290 when using the Jack API. By default, the client name is set to
291 RtApiJack. However, if you wish to create multiple instances of
292 RtAudio with Jack, each instance must have a unique client name.
294 struct StreamOptions {
295 RtAudioStreamFlags flags; /*!< A bit-mask of stream flags (RTAUDIO_NONINTERLEAVED, RTAUDIO_MINIMIZE_LATENCY, RTAUDIO_HOG_DEVICE). */
296 unsigned int numberOfBuffers; /*!< Number of stream buffers. */
297 std::string streamName; /*!< A stream name (currently used only in Jack). */
298 int priority; /*!< Scheduling priority of callback thread (only used with flag RTAUDIO_SCHEDULE_REALTIME). */
300 // Default constructor.
302 : flags(0), numberOfBuffers(0), priority(0) {}
305 //! A static function to determine the available compiled audio APIs.
307 The values returned in the std::vector can be compared against
308 the enumerated list values. Note that there can be more than one
309 API compiled for certain operating systems.
311 static void getCompiledApi( std::vector<RtAudio::Api> &apis ) throw();
313 //! The class constructor.
315 The constructor performs minor initialization tasks. No exceptions
318 If no API argument is specified and multiple API support has been
319 compiled, the default order of use is JACK, ALSA, OSS (Linux
320 systems) and ASIO, DS (Windows systems).
322 RtAudio( RtAudio::Api api=UNSPECIFIED ) throw();
326 If a stream is running or open, it will be stopped and closed
331 //! Returns the audio API specifier for the current instance of RtAudio.
332 RtAudio::Api getCurrentApi( void ) throw();
334 //! A public function that queries for the number of audio devices available.
336 This function performs a system query of available devices each time it
337 is called, thus supporting devices connected \e after instantiation. If
338 a system error occurs during processing, a warning will be issued.
340 unsigned int getDeviceCount( void ) throw();
342 //! Return an RtAudio::DeviceInfo structure for a specified device number.
345 Any device integer between 0 and getDeviceCount() - 1 is valid.
346 If an invalid argument is provided, an RtError (type = INVALID_USE)
347 will be thrown. If a device is busy or otherwise unavailable, the
348 structure member "probed" will have a value of "false" and all
349 other members are undefined. If the specified device is the
350 current default input or output device, the corresponding
351 "isDefault" member will have a value of "true".
353 RtAudio::DeviceInfo getDeviceInfo( unsigned int device );
355 //! A function that returns the index of the default output device.
357 If the underlying audio API does not provide a "default
358 device", or if no devices are available, the return value will be
359 0. Note that this is a valid device identifier and it is the
360 client's responsibility to verify that a device is available
361 before attempting to open a stream.
363 unsigned int getDefaultOutputDevice( void ) throw();
365 //! A function that returns the index of the default input device.
367 If the underlying audio API does not provide a "default
368 device", or if no devices are available, the return value will be
369 0. Note that this is a valid device identifier and it is the
370 client's responsibility to verify that a device is available
371 before attempting to open a stream.
373 unsigned int getDefaultInputDevice( void ) throw();
375 //! A public function for opening a stream with the specified parameters.
377 An RtError (type = SYSTEM_ERROR) is thrown if a stream cannot be
378 opened with the specified parameters or an error occurs during
379 processing. An RtError (type = INVALID_USE) is thrown if any
380 invalid device ID or channel number parameters are specified.
382 \param outputParameters Specifies output stream parameters to use
383 when opening a stream, including a device ID, number of channels,
384 and starting channel number. For input-only streams, this
385 argument should be NULL. The device ID is an index value between
386 0 and getDeviceCount() - 1.
387 \param inputParameters Specifies input stream parameters to use
388 when opening a stream, including a device ID, number of channels,
389 and starting channel number. For output-only streams, this
390 argument should be NULL. The device ID is an index value between
391 0 and getDeviceCount() - 1.
392 \param format An RtAudioFormat specifying the desired sample data format.
393 \param sampleRate The desired sample rate (sample frames per second).
394 \param *bufferFrames A pointer to a value indicating the desired
395 internal buffer size in sample frames. The actual value
396 used by the device is returned via the same pointer. A
397 value of zero can be specified, in which case the lowest
398 allowable value is determined.
399 \param callback A client-defined function that will be invoked
400 when input data is available and/or output data is needed.
401 \param userData An optional pointer to data that can be accessed
402 from within the callback function.
403 \param options An optional pointer to a structure containing various
404 global stream options, including a list of OR'ed RtAudioStreamFlags
405 and a suggested number of stream buffers that can be used to
406 control stream latency. More buffers typically result in more
407 robust performance, though at a cost of greater latency. If a
408 value of zero is specified, a system-specific median value is
409 chosen. If the RTAUDIO_MINIMIZE_LATENCY flag bit is set, the
410 lowest allowable value is used. The actual value used is
411 returned via the structure argument. The parameter is API dependent.
413 void openStream( RtAudio::StreamParameters *outputParameters,
414 RtAudio::StreamParameters *inputParameters,
415 RtAudioFormat format, unsigned int sampleRate,
416 unsigned int *bufferFrames, RtAudioCallback callback,
417 void *userData = NULL, RtAudio::StreamOptions *options = NULL );
419 //! A function that closes a stream and frees any associated stream memory.
421 If a stream is not open, this function issues a warning and
422 returns (no exception is thrown).
424 void closeStream( void ) throw();
426 //! A function that starts a stream.
428 An RtError (type = SYSTEM_ERROR) is thrown if an error occurs
429 during processing. An RtError (type = INVALID_USE) is thrown if a
430 stream is not open. A warning is issued if the stream is already
433 void startStream( void );
435 //! Stop a stream, allowing any samples remaining in the output queue to be played.
437 An RtError (type = SYSTEM_ERROR) is thrown if an error occurs
438 during processing. An RtError (type = INVALID_USE) is thrown if a
439 stream is not open. A warning is issued if the stream is already
442 void stopStream( void );
444 //! Stop a stream, discarding any samples remaining in the input/output queue.
446 An RtError (type = SYSTEM_ERROR) is thrown if an error occurs
447 during processing. An RtError (type = INVALID_USE) is thrown if a
448 stream is not open. A warning is issued if the stream is already
451 void abortStream( void );
453 //! Returns true if a stream is open and false if not.
454 bool isStreamOpen( void ) const throw();
456 //! Returns true if the stream is running and false if it is stopped or not open.
457 bool isStreamRunning( void ) const throw();
459 //! Returns the number of elapsed seconds since the stream was started.
461 If a stream is not open, an RtError (type = INVALID_USE) will be thrown.
463 double getStreamTime( void );
465 //! Returns the internal stream latency in sample frames.
467 The stream latency refers to delay in audio input and/or output
468 caused by internal buffering by the audio system and/or hardware.
469 For duplex streams, the returned value will represent the sum of
470 the input and output latencies. If a stream is not open, an
471 RtError (type = INVALID_USE) will be thrown. If the API does not
472 report latency, the return value will be zero.
474 long getStreamLatency( void );
476 //! Returns actual sample rate in use by the stream.
478 On some systems, the sample rate used may be slightly different
479 than that specified in the stream parameters. If a stream is not
480 open, an RtError (type = INVALID_USE) will be thrown.
482 unsigned int getStreamSampleRate( void );
484 //! Specify whether warning messages should be printed to stderr.
485 void showWarnings( bool value = true ) throw();
489 void openRtApi( RtAudio::Api api );
493 // Operating system dependent thread functionality.
494 #if defined(__WINDOWS_DS__) || defined(__WINDOWS_ASIO__)
498 typedef unsigned long ThreadHandle;
499 typedef CRITICAL_SECTION StreamMutex;
501 #elif defined(__LINUX_ALSA__) || defined(__UNIX_JACK__) || defined(__LINUX_OSS__) || defined(__MACOSX_CORE__)
502 // Using pthread library for various flavors of unix.
505 typedef pthread_t ThreadHandle;
506 typedef pthread_mutex_t StreamMutex;
508 #else // Setup for "dummy" behavior
510 #define __RTAUDIO_DUMMY__
511 typedef int ThreadHandle;
512 typedef int StreamMutex;
516 // This global structure type is used to pass callback information
517 // between the private RtAudio stream structure and global callback
518 // handling functions.
519 struct CallbackInfo {
520 void *object; // Used as a "this" pointer.
524 void *apiInfo; // void pointer for API specific callback information
527 // Default constructor.
529 :object(0), callback(0), userData(0), apiInfo(0), isRunning(false) {}
532 // **************************************************************** //
534 // RtApi class declaration.
536 // Subclasses of RtApi contain all API- and OS-specific code necessary
537 // to fully implement the RtAudio API.
539 // Note that RtApi is an abstract base class and cannot be
540 // explicitly instantiated. The class RtAudio will create an
541 // instance of an RtApi subclass (RtApiOss, RtApiAlsa,
542 // RtApiJack, RtApiCore, RtApiAl, RtApiDs, or RtApiAsio).
544 // **************************************************************** //
546 #if defined( HAVE_GETTIMEOFDAY )
547 #include <sys/time.h>
558 virtual RtAudio::Api getCurrentApi( void ) = 0;
559 virtual unsigned int getDeviceCount( void ) = 0;
560 virtual RtAudio::DeviceInfo getDeviceInfo( unsigned int device ) = 0;
561 virtual unsigned int getDefaultInputDevice( void );
562 virtual unsigned int getDefaultOutputDevice( void );
563 void openStream( RtAudio::StreamParameters *outputParameters,
564 RtAudio::StreamParameters *inputParameters,
565 RtAudioFormat format, unsigned int sampleRate,
566 unsigned int *bufferFrames, RtAudioCallback callback,
567 void *userData, RtAudio::StreamOptions *options );
568 virtual void closeStream( void );
569 virtual void startStream( void ) = 0;
570 virtual void stopStream( void ) = 0;
571 virtual void abortStream( void ) = 0;
572 long getStreamLatency( void );
573 unsigned int getStreamSampleRate( void );
574 virtual double getStreamTime( void );
575 bool isStreamOpen( void ) const { return stream_.state != STREAM_CLOSED; };
576 bool isStreamRunning( void ) const { return stream_.state == STREAM_RUNNING; };
577 void showWarnings( bool value ) { showWarnings_ = value; };
582 static const unsigned int MAX_SAMPLE_RATES;
583 static const unsigned int SAMPLE_RATES[];
585 enum { FAILURE, SUCCESS };
600 // A protected structure used for buffer conversion.
604 RtAudioFormat inFormat, outFormat;
605 std::vector<int> inOffset;
606 std::vector<int> outOffset;
609 // A protected structure for audio streams.
611 unsigned int device[2]; // Playback and record, respectively.
612 void *apiHandle; // void pointer for API specific stream handle information
613 StreamMode mode; // OUTPUT, INPUT, or DUPLEX.
614 StreamState state; // STOPPED, RUNNING, or CLOSED
615 char *userBuffer[2]; // Playback and record, respectively.
617 bool doConvertBuffer[2]; // Playback and record, respectively.
618 bool userInterleaved;
619 bool deviceInterleaved[2]; // Playback and record, respectively.
620 bool doByteSwap[2]; // Playback and record, respectively.
621 unsigned int sampleRate;
622 unsigned int bufferSize;
623 unsigned int nBuffers;
624 unsigned int nUserChannels[2]; // Playback and record, respectively.
625 unsigned int nDeviceChannels[2]; // Playback and record channels, respectively.
626 unsigned int channelOffset[2]; // Playback and record, respectively.
627 unsigned long latency[2]; // Playback and record, respectively.
628 RtAudioFormat userFormat;
629 RtAudioFormat deviceFormat[2]; // Playback and record, respectively.
631 CallbackInfo callbackInfo;
632 ConvertInfo convertInfo[2];
633 double streamTime; // Number of elapsed seconds since the stream started.
635 #if defined(HAVE_GETTIMEOFDAY)
636 struct timeval lastTickTimestamp;
640 :apiHandle(0), deviceBuffer(0) { device[0] = 11111; device[1] = 11111; }
643 typedef signed short Int16;
644 typedef signed int Int32;
645 typedef float Float32;
646 typedef double Float64;
648 std::ostringstream errorStream_;
649 std::string errorText_;
654 Protected, api-specific method that attempts to open a device
655 with the given parameters. This function MUST be implemented by
656 all subclasses. If an error is encountered during the probe, a
657 "warning" message is reported and FAILURE is returned. A
658 successful probe is indicated by a return value of SUCCESS.
660 virtual bool probeDeviceOpen( unsigned int device, StreamMode mode, unsigned int channels,
661 unsigned int firstChannel, unsigned int sampleRate,
662 RtAudioFormat format, unsigned int *bufferSize,
663 RtAudio::StreamOptions *options );
665 //! A protected function used to increment the stream time.
666 void tickStreamTime( void );
668 //! Protected common method to clear an RtApiStream structure.
669 void clearStreamInfo();
672 Protected common method that throws an RtError (type =
673 INVALID_USE) if a stream is not open.
675 void verifyStream( void );
677 //! Protected common error method to allow global control over error handling.
678 void error( RtError::Type type );
681 Protected method used to perform format, channel number, and/or interleaving
682 conversions between the user and device buffers.
684 void convertBuffer( char *outBuffer, char *inBuffer, ConvertInfo &info );
686 //! Protected common method used to perform byte-swapping on buffers.
687 void byteSwapBuffer( char *buffer, unsigned int samples, RtAudioFormat format );
689 //! Protected common method that returns the number of bytes for a given format.
690 unsigned int formatBytes( RtAudioFormat format );
692 //! Protected common method that sets up the parameters for buffer conversion.
693 void setConvertInfo( StreamMode mode, unsigned int firstChannel );
696 // **************************************************************** //
698 // Inline RtAudio definitions.
700 // **************************************************************** //
702 inline RtAudio::Api RtAudio :: getCurrentApi( void ) throw() { return rtapi_->getCurrentApi(); }
703 inline unsigned int RtAudio :: getDeviceCount( void ) throw() { return rtapi_->getDeviceCount(); }
704 inline RtAudio::DeviceInfo RtAudio :: getDeviceInfo( unsigned int device ) { return rtapi_->getDeviceInfo( device ); }
705 inline unsigned int RtAudio :: getDefaultInputDevice( void ) throw() { return rtapi_->getDefaultInputDevice(); }
706 inline unsigned int RtAudio :: getDefaultOutputDevice( void ) throw() { return rtapi_->getDefaultOutputDevice(); }
707 inline void RtAudio :: closeStream( void ) throw() { return rtapi_->closeStream(); }
708 inline void RtAudio :: startStream( void ) { return rtapi_->startStream(); }
709 inline void RtAudio :: stopStream( void ) { return rtapi_->stopStream(); }
710 inline void RtAudio :: abortStream( void ) { return rtapi_->abortStream(); }
711 inline bool RtAudio :: isStreamOpen( void ) const throw() { return rtapi_->isStreamOpen(); }
712 inline bool RtAudio :: isStreamRunning( void ) const throw() { return rtapi_->isStreamRunning(); }
713 inline long RtAudio :: getStreamLatency( void ) { return rtapi_->getStreamLatency(); }
714 inline unsigned int RtAudio :: getStreamSampleRate( void ) { return rtapi_->getStreamSampleRate(); };
715 inline double RtAudio :: getStreamTime( void ) { return rtapi_->getStreamTime(); }
716 inline void RtAudio :: showWarnings( bool value ) throw() { rtapi_->showWarnings( value ); }
718 // RtApi Subclass prototypes.
720 #if defined(__MACOSX_CORE__)
722 #include <CoreAudio/AudioHardware.h>
724 class RtApiCore: public RtApi
730 RtAudio::Api getCurrentApi( void ) { return RtAudio::MACOSX_CORE; };
731 unsigned int getDeviceCount( void );
732 RtAudio::DeviceInfo getDeviceInfo( unsigned int device );
733 unsigned int getDefaultOutputDevice( void );
734 unsigned int getDefaultInputDevice( void );
735 void closeStream( void );
736 void startStream( void );
737 void stopStream( void );
738 void abortStream( void );
739 long getStreamLatency( void );
741 // This function is intended for internal use only. It must be
742 // public because it is called by the internal callback handler,
743 // which is not a member of RtAudio. External use of this function
744 // will most likely produce highly undesireable results!
745 bool callbackEvent( AudioDeviceID deviceId,
746 const AudioBufferList *inBufferList,
747 const AudioBufferList *outBufferList );
751 bool probeDeviceOpen( unsigned int device, StreamMode mode, unsigned int channels,
752 unsigned int firstChannel, unsigned int sampleRate,
753 RtAudioFormat format, unsigned int *bufferSize,
754 RtAudio::StreamOptions *options );
755 static const char* getErrorCode( OSStatus code );
760 #if defined(__UNIX_JACK__)
762 class RtApiJack: public RtApi
768 RtAudio::Api getCurrentApi( void ) { return RtAudio::UNIX_JACK; };
769 unsigned int getDeviceCount( void );
770 RtAudio::DeviceInfo getDeviceInfo( unsigned int device );
771 void closeStream( void );
772 void startStream( void );
773 void stopStream( void );
774 void abortStream( void );
775 long getStreamLatency( void );
777 // This function is intended for internal use only. It must be
778 // public because it is called by the internal callback handler,
779 // which is not a member of RtAudio. External use of this function
780 // will most likely produce highly undesireable results!
781 bool callbackEvent( unsigned long nframes );
785 bool probeDeviceOpen( unsigned int device, StreamMode mode, unsigned int channels,
786 unsigned int firstChannel, unsigned int sampleRate,
787 RtAudioFormat format, unsigned int *bufferSize,
788 RtAudio::StreamOptions *options );
793 #if defined(__WINDOWS_ASIO__)
795 class RtApiAsio: public RtApi
801 RtAudio::Api getCurrentApi( void ) { return RtAudio::WINDOWS_ASIO; };
802 unsigned int getDeviceCount( void );
803 RtAudio::DeviceInfo getDeviceInfo( unsigned int device );
804 void closeStream( void );
805 void startStream( void );
806 void stopStream( void );
807 void abortStream( void );
808 long getStreamLatency( void );
810 // This function is intended for internal use only. It must be
811 // public because it is called by the internal callback handler,
812 // which is not a member of RtAudio. External use of this function
813 // will most likely produce highly undesireable results!
814 bool callbackEvent( long bufferIndex );
818 std::vector<RtAudio::DeviceInfo> devices_;
819 void saveDeviceInfo( void );
821 bool probeDeviceOpen( unsigned int device, StreamMode mode, unsigned int channels,
822 unsigned int firstChannel, unsigned int sampleRate,
823 RtAudioFormat format, unsigned int *bufferSize,
824 RtAudio::StreamOptions *options );
829 #if defined(__WINDOWS_DS__)
831 class RtApiDs: public RtApi
837 RtAudio::Api getCurrentApi( void ) { return RtAudio::WINDOWS_DS; };
838 unsigned int getDeviceCount( void );
839 unsigned int getDefaultOutputDevice( void );
840 unsigned int getDefaultInputDevice( void );
841 RtAudio::DeviceInfo getDeviceInfo( unsigned int device );
842 void closeStream( void );
843 void startStream( void );
844 void stopStream( void );
845 void abortStream( void );
846 long getStreamLatency( void );
848 // This function is intended for internal use only. It must be
849 // public because it is called by the internal callback handler,
850 // which is not a member of RtAudio. External use of this function
851 // will most likely produce highly undesireable results!
852 void callbackEvent( void );
858 long duplexPrerollBytes;
859 bool probeDeviceOpen( unsigned int device, StreamMode mode, unsigned int channels,
860 unsigned int firstChannel, unsigned int sampleRate,
861 RtAudioFormat format, unsigned int *bufferSize,
862 RtAudio::StreamOptions *options );
867 #if defined(__LINUX_ALSA__)
869 class RtApiAlsa: public RtApi
875 RtAudio::Api getCurrentApi() { return RtAudio::LINUX_ALSA; };
876 unsigned int getDeviceCount( void );
877 RtAudio::DeviceInfo getDeviceInfo( unsigned int device );
878 void closeStream( void );
879 void startStream( void );
880 void stopStream( void );
881 void abortStream( void );
883 // This function is intended for internal use only. It must be
884 // public because it is called by the internal callback handler,
885 // which is not a member of RtAudio. External use of this function
886 // will most likely produce highly undesireable results!
887 void callbackEvent( void );
891 std::vector<RtAudio::DeviceInfo> devices_;
892 void saveDeviceInfo( void );
893 bool probeDeviceOpen( unsigned int device, StreamMode mode, unsigned int channels,
894 unsigned int firstChannel, unsigned int sampleRate,
895 RtAudioFormat format, unsigned int *bufferSize,
896 RtAudio::StreamOptions *options );
901 #if defined(__LINUX_OSS__)
903 class RtApiOss: public RtApi
909 RtAudio::Api getCurrentApi() { return RtAudio::LINUX_OSS; };
910 unsigned int getDeviceCount( void );
911 RtAudio::DeviceInfo getDeviceInfo( unsigned int device );
912 void closeStream( void );
913 void startStream( void );
914 void stopStream( void );
915 void abortStream( void );
917 // This function is intended for internal use only. It must be
918 // public because it is called by the internal callback handler,
919 // which is not a member of RtAudio. External use of this function
920 // will most likely produce highly undesireable results!
921 void callbackEvent( void );
925 bool probeDeviceOpen( unsigned int device, StreamMode mode, unsigned int channels,
926 unsigned int firstChannel, unsigned int sampleRate,
927 RtAudioFormat format, unsigned int *bufferSize,
928 RtAudio::StreamOptions *options );
933 #if defined(__RTAUDIO_DUMMY__)
935 class RtApiDummy: public RtApi
939 RtApiDummy() { errorText_ = "RtApiDummy: This class provides no functionality."; error( RtError::WARNING ); };
940 RtAudio::Api getCurrentApi( void ) { return RtAudio::RTAUDIO_DUMMY; };
941 unsigned int getDeviceCount( void ) { return 0; };
942 RtAudio::DeviceInfo getDeviceInfo( unsigned int device ) { RtAudio::DeviceInfo info; return info; };
943 void closeStream( void ) {};
944 void startStream( void ) {};
945 void stopStream( void ) {};
946 void abortStream( void ) {};
950 bool probeDeviceOpen( unsigned int device, StreamMode mode, unsigned int channels,
951 unsigned int firstChannel, unsigned int sampleRate,
952 RtAudioFormat format, unsigned int *bufferSize,
953 RtAudio::StreamOptions *options ) { return false; };
960 // Indentation settings for Vim and Emacs
964 // indent-tabs-mode: nil
967 // vim: et sts=2 sw=2