RtAudio.h File Reference

#include <string>
#include <vector>
#include "RtError.h"
@@ -21,141 +22,110 @@ class RtAudio Realtime audio i/o C++ classes. More...
-struct RtAudio::DeviceInfo +struct RtAudio::RtAudio::DeviceInfo The public device information structure for returning queried values. More...
-struct RtAudio::StreamParameters +struct RtAudio::RtAudio::StreamParameters The structure for specifying input or ouput stream parameters. More...
-struct RtAudio::StreamOptions +struct RtAudio::RtAudio::StreamOptions The structure for specifying stream options. More...

Typedefs

-typedef unsigned long RtAudioFormat +typedef unsigned long RtAudioFormat - RtAudio data format type.
-typedef unsigned int RtAudioStreamFlags + RtAudio data format type.
+typedef unsigned int RtAudioStreamFlags - RtAudio stream option flags.
-typedef unsigned int RtAudioStreamStatus + RtAudio stream option flags.
+typedef unsigned int RtAudioStreamStatus - RtAudio stream status (over- or underflow) flags.
-typedef int(* RtAudioCallback )(void *outputBuffer, void *inputBuffer, unsigned int nFrames, double streamTime, RtAudioStreamStatus status, void *userData) + RtAudio stream status (over- or underflow) flags.
+typedef int(* RtAudioCallback )(void *outputBuffer, void *inputBuffer, unsigned int nFrames, double streamTime, RtAudioStreamStatus status, void *userData) - RtAudio callback function prototype.
+ RtAudio callback function prototype.

Detailed Description

Typedef Documentation

-

- - - - -
- + +
+
+
- +

typedef unsigned long RtAudioFormat typedef unsigned long RtAudioFormat

-
- - - - - -
- - + +

-RtAudio data format type. +RtAudio data format type.
-Support for signed integers and floats. Audio data fed to/from an RtAudio stream is assumed to ALWAYS be in host byte order. The internal routines will automatically take care of any necessary byte-swapping between the host format and the soundcard. Thus, endian-ness is not a concern in the following format definitions.
+Support for signed integers and floats. Audio data fed to/from an RtAudio stream is assumed to ALWAYS be in host byte order. The internal routines will automatically take care of any necessary byte-swapping between the host format and the soundcard. Thus, endian-ness is not a concern in the following format definitions.

-
RTAUDIO_SINT8: 8-bit signed integer.
RTAUDIO_SINT16: 16-bit signed integer.
RTAUDIO_SINT24: Upper 3 bytes of 32-bit signed integer.
RTAUDIO_SINT32: 32-bit signed integer.
RTAUDIO_FLOAT32: Normalized between plus/minus 1.0.
RTAUDIO_FLOAT64: Normalized between plus/minus 1.0.
-
-

- - - - -
- +
RTAUDIO_SINT8: 8-bit signed integer.
RTAUDIO_SINT16: 16-bit signed integer.
RTAUDIO_SINT24: Upper 3 bytes of 32-bit signed integer.
RTAUDIO_SINT32: 32-bit signed integer.
RTAUDIO_FLOAT32: Normalized between plus/minus 1.0.
RTAUDIO_FLOAT64: Normalized between plus/minus 1.0.
+ + +
+ +
+
+
- +

typedef unsigned long RtAudioStreamFlags typedef unsigned long RtAudioStreamFlags

-
- - - - - -
- - + +

-RtAudio stream option flags. +RtAudio stream option flags.
The following flags can be OR'ed together to allow a client to make changes to the default stream behavior:

RTAUDIO_NONINTERLEAVED: Use non-interleaved buffers (default = interleaved).
RTAUDIO_MINIMIZE_LATENCY: Attempt to set stream parameters for lowest possible latency.
RTAUDIO_HOG_DEVICE: Attempt grab device for exclusive use.

-By default, RtAudio streams pass and receive audio data from the client in an interleaved format. By passing the RTAUDIO_NONINTERLEAVED flag to the openStream() function, audio data will instead be presented in non-interleaved buffers. In this case, each buffer argument in the RtAudioCallback function will point to a single array of data, with nFrames samples for each channel concatenated back-to-back. For example, the first sample of data for the second channel would be located at index nFrames (assuming the buffer pointer was recast to the correct data type for the stream).
-Certain audio APIs offer a number of parameters that influence the I/O latency of a stream. By default, RtAudio will attempt to set these parameters internally for robust (glitch-free) performance (though some APIs, like Windows Direct Sound, make this difficult). By passing the RTAUDIO_MINIMIZE_LATENCY flag to the openStream() function, internal stream settings will be influenced in an attempt to minimize stream latency, though possibly at the expense of stream performance.
-If the RTAUDIO_HOG_DEVICE flag is set, RtAudio will attempt to open the input and/or output stream device(s) for exclusive use. Note that this is not possible with all supported audio APIs.
-

- - - - -
- +By default, RtAudio streams pass and receive audio data from the client in an interleaved format. By passing the RTAUDIO_NONINTERLEAVED flag to the openStream() function, audio data will instead be presented in non-interleaved buffers. In this case, each buffer argument in the RtAudioCallback function will point to a single array of data, with nFrames samples for each channel concatenated back-to-back. For example, the first sample of data for the second channel would be located at index nFrames (assuming the buffer pointer was recast to the correct data type for the stream).
+Certain audio APIs offer a number of parameters that influence the I/O latency of a stream. By default, RtAudio will attempt to set these parameters internally for robust (glitch-free) performance (though some APIs, like Windows Direct Sound, make this difficult). By passing the RTAUDIO_MINIMIZE_LATENCY flag to the openStream() function, internal stream settings will be influenced in an attempt to minimize stream latency, though possibly at the expense of stream performance.
+If the RTAUDIO_HOG_DEVICE flag is set, RtAudio will attempt to open the input and/or output stream device(s) for exclusive use. Note that this is not possible with all supported audio APIs.
+If the RTAUDIO_SCHEDULE_REALTIME flag is set, RtAudio will attempt to select realtime scheduling (round-robin) for the callback thread. + +
+ +
+
+
- +

typedef unsigned long RtAudioStreamStatus typedef unsigned long RtAudioStreamStatus

-
- - - - - -
- - + +

-RtAudio stream status (over- or underflow) flags. +RtAudio stream status (over- or underflow) flags.
Notification of a stream over- or underflow is indicated by a non-zero stream status argument in the RtAudioCallback function. The stream status can be one of the following two options, depending on whether the stream is open for output and/or input:

-
RTAUDIO_INPUT_OVERFLOW: Input data was discarded because of an overflow condition at the driver.
RTAUDIO_OUTPUT_UNDERFLOW: The output buffer ran low, likely producing a break in the output sound.
-
-

- - - - -
- +
RTAUDIO_INPUT_OVERFLOW: Input data was discarded because of an overflow condition at the driver.
RTAUDIO_OUTPUT_UNDERFLOW: The output buffer ran low, likely producing a break in the output sound.
+ + +
+ +
+
+
- +

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

-
- - - - - -
- - + +

-RtAudio callback function prototype. +RtAudio callback function prototype.
-All RtAudio clients must create a function of type RtAudioCallback to read and/or write data from/to the audio stream. When the underlying audio system is ready for new input or output data, this function will be invoked.
+All RtAudio clients must create a function of type RtAudioCallback to read and/or write data from/to the audio stream. When the underlying audio system is ready for new input or output data, this function will be invoked.

Parameters:
@@ -166,13 +136,14 @@ All RtAudio clients must create a fun

outputBuffer For output (or duplex) streams, the client should write nFrames of audio sample frames into this buffer. This argument should be recast to the datatype specified when the stream was opened. For input-only streams, this argument will be NULL.
userData A pointer to optional data provided by the client when opening the stream (default = NULL).

-To continue normal stream operation, the RtAudioCallback function should return a value of zero. To stop the stream and drain the output buffer, the function should return a value of one. To abort the stream immediately, the client should return a value of two.
+To continue normal stream operation, the RtAudioCallback function should return a value of zero. To stop the stream and drain the output buffer, the function should return a value of one. To abort the stream immediately, the client should return a value of two. +

#	Version	API	Description	Status
1	3.03	CoreAudio	Do we need a run-time test for endianness given the new Intel Macs?	Not yet tested (GS)

abortStream(void)	RtAudio	`[inline]`
Api enum name	RtAudio
closeStream(void)	RtAudio	`[inline]`
getCompiledApi(std::vector< RtAudio::Api > &apis)	RtAudio	`[static]`
getCurrentApi(void)	RtAudio	`[inline]`
getDefaultInputDevice(void)	RtAudio	`[inline]`
getDefaultOutputDevice(void)	RtAudio	`[inline]`
getDeviceCount(void)	RtAudio	`[inline]`
getDeviceInfo(unsigned int device)	RtAudio	`[inline]`
getStreamLatency(void)	RtAudio	`[inline]`
getStreamTime(void)	RtAudio	`[inline]`
isStreamOpen(void)	RtAudio	`[inline]`
isStreamRunning(void)	RtAudio	`[inline]`
LINUX_ALSA enum value	RtAudio
LINUX_OSS enum value	RtAudio
MACOSX_CORE enum value	RtAudio
openStream(RtAudio::StreamParameters outputParameters, RtAudio::StreamParameters inputParameters, RtAudioFormat format, unsigned int sampleRate, unsigned int bufferFrames, RtAudioCallback callback, void userData=NULL, RtAudio::StreamOptions *options=NULL)	RtAudio
RtAudio(RtAudio::Api api=UNSPECIFIED)	RtAudio
RTAUDIO_DUMMY enum value	RtAudio
showWarnings(bool value=true)	RtAudio	`[inline]`
startStream(void)	RtAudio	`[inline]`
stopStream(void)	RtAudio	`[inline]`
UNIX_JACK enum value	RtAudio
UNSPECIFIED enum value	RtAudio
WINDOWS_ASIO enum value	RtAudio
WINDOWS_DS enum value	RtAudio
~RtAudio()	RtAudio


Classes
struct	DeviceInfo
	The public device information structure for returning queried values. More...
struct	StreamOptions
	The structure for specifying stream options. More...
struct	StreamParameters
	The structure for specifying input or ouput stream parameters. More...
Public Types
enum	Api { - UNSPECIFIED, -LINUX_ALSA, -LINUX_OSS, -UNIX_JACK, +
enum	Api { + UNSPECIFIED, +LINUX_ALSA, +LINUX_OSS, +UNIX_JACK, - MACOSX_CORE, -WINDOWS_ASIO, -WINDOWS_DS, -RTAUDIO_DUMMY + MACOSX_CORE, +WINDOWS_ASIO, +WINDOWS_DS, +RTAUDIO_DUMMY }
	Audio API specifier arguments. More...
	Audio API specifier arguments. More...
Public Member Functions
	RtAudio (RtAudio::Api api=UNSPECIFIED) throw ()
	RtAudio (RtAudio::Api api=UNSPECIFIED) throw ()
	The class constructor.
	~RtAudio () throw ()
	The class constructor.
	~RtAudio () throw ()
	The destructor.
-RtAudio::Api	getCurrentApi (void) throw ()
	The destructor.
+RtAudio::Api	getCurrentApi (void) throw ()
	Returns the audio API specifier for the current instance of RtAudio.
unsigned int	getDeviceCount (void) throw ()
	Returns the audio API specifier for the current instance of RtAudio.
unsigned int	getDeviceCount (void) throw ()
	A public function that queries for the number of audio devices available.
RtAudio::DeviceInfo	getDeviceInfo (unsigned int device)
	A public function that queries for the number of audio devices available.
RtAudio::DeviceInfo	getDeviceInfo (unsigned int device)
	Return an RtAudio::DeviceInfo structure for a specified device number.
unsigned int	getDefaultOutputDevice (void) throw ()
	Return an RtAudio::DeviceInfo structure for a specified device number.
unsigned int	getDefaultOutputDevice (void) throw ()
	A function that returns the index of the default output device.
unsigned int	getDefaultInputDevice (void) throw ()
	A function that returns the index of the default output device.
unsigned int	getDefaultInputDevice (void) throw ()
	A function that returns the index of the default input device.
void	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 function that returns the index of the default input device.
void	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.
void	closeStream (void) throw ()
	A public function for opening a stream with the specified parameters.
void	closeStream (void) throw ()
	A function that closes a stream and frees any associated stream memory.
void	startStream (void)
	A function that closes a stream and frees any associated stream memory.
void	startStream (void)
	A function that starts a stream.
void	stopStream (void)
	A function that starts a stream.
void	stopStream (void)
	Stop a stream, allowing any samples remaining in the output queue to be played.
void	abortStream (void)
	Stop a stream, allowing any samples remaining in the output queue to be played.
void	abortStream (void)
	Stop a stream, discarding any samples remaining in the input/output queue.
-bool	isStreamOpen (void) throw ()
	Stop a stream, discarding any samples remaining in the input/output queue.
+bool	isStreamOpen (void) const throw ()
	Returns true if a stream is open and false if not.
-bool	isStreamRunning (void) throw ()
+bool	isStreamRunning (void) const throw ()
	Returns true if the stream is running and false if it is stopped or not open.
double	getStreamTime (void)
double	getStreamTime (void)
	Returns the number of elapsed seconds since the stream was started.
long	getStreamLatency (void)
	Returns the number of elapsed seconds since the stream was started.
long	getStreamLatency (void)
	Returns the internal stream latency in sample frames.
-void	showWarnings (bool value=true) throw ()
	Returns the internal stream latency in sample frames.
unsigned int	getStreamSampleRate (void)
	Returns actual sample rate in use by the stream.
+void	showWarnings (bool value=true) throw ()
	Specify whether warning messages should be printed to stderr.
Static Public Member Functions
static void	getCompiledApi (std::vector< RtAudio::Api > &apis) throw ()
	A static function to determine the available compiled audio APIs.
Classes
struct	DeviceInfo
static void	getCompiledApi (std::vector< RtAudio::Api > &apis) throw ()
	The public device information structure for returning queried values. More...
struct	StreamOptions
	The structure for specifying stream options. More...
struct	StreamParameters
	The structure for specifying input or ouput stream parameters. More...
	A static function to determine the available compiled audio APIs.

DEBUG_WARNING enum value	RtError
DRIVER_ERROR enum value	RtError
getMessage(void)	RtError	`[inline, virtual]`
getType(void)	RtError	`[inline, virtual]`
INVALID_DEVICE enum value	RtError
INVALID_PARAMETER enum value	RtError
INVALID_USE enum value	RtError
MEMORY_ERROR enum value	RtError
NO_DEVICES_FOUND enum value	RtError
printMessage(void)	RtError	`[inline, virtual]`
RtError(const std::string &message, Type type=RtError::UNSPECIFIED)	RtError	`[inline]`
SYSTEM_ERROR enum value	RtError
THREAD_ERROR enum value	RtError
Type enum name	RtError
UNSPECIFIED enum value	RtError
WARNING enum value	RtError
what(void) const	RtError	`[inline, virtual]`
~RtError(void)	RtError	`[inline, virtual]`


Public Types
enum	Type { - WARNING, -DEBUG_WARNING, -UNSPECIFIED, -NO_DEVICES_FOUND, +
enum	Type { + WARNING, +DEBUG_WARNING, +UNSPECIFIED, +NO_DEVICES_FOUND, - INVALID_DEVICE, -MEMORY_ERROR, -INVALID_PARAMETER, -INVALID_USE, + INVALID_DEVICE, +MEMORY_ERROR, +INVALID_PARAMETER, +INVALID_USE, - DRIVER_ERROR, -SYSTEM_ERROR, -THREAD_ERROR + DRIVER_ERROR, +SYSTEM_ERROR, +THREAD_ERROR }
	Defined RtError types. More...
	Defined RtError types. More...
Public Member Functions
-	RtError (const std::string &message, Type type=RtError::UNSPECIFIED) throw ()
+	RtError (const std::string &message, Type type=RtError::UNSPECIFIED) throw ()
	The constructor.
-virtual	~RtError (void) throw ()
+virtual	~RtError (void) throw ()
	The destructor.
-virtual void	printMessage (void) throw ()
+virtual void	printMessage (void) throw ()
	Prints thrown error message to stderr.
-virtual const Type &	getType (void) throw ()
+virtual const Type &	getType (void) throw ()
	Returns the thrown error message type.
-virtual const std::string &	getMessage (void) throw ()
+virtual const std::string &	getMessage (void) throw ()
	Returns the thrown error message string.
-virtual const char *	what (void) const throw ()
+virtual const char *	what (void) const throw ()
	Returns the thrown error message as a c-style string.

	©2001-2008 Gary P. Scavone, McGill University. All Rights Reserved. Maintained by Gary P. Scavone.
©2001-2009 Gary P. Scavone, McGill University. All Rights Reserved. Maintained by Gary P. Scavone.

RtAudio	Realtime audio i/o C++ classes
RtAudio::DeviceInfo	The public device information structure for returning queried values
RtAudio::StreamOptions	The structure for specifying stream options
RtAudio::StreamParameters	The structure for specifying input or ouput stream parameters
RtError	Exception handling class for RtAudio & RtMidi
RtAudio::RtAudio::DeviceInfo	The public device information structure for returning queried values
RtAudio::RtAudio::StreamOptions	The structure for specifying stream options
RtAudio::RtAudio::StreamParameters	The structure for specifying input or ouput stream parameters
RtError	Exception handling class for RtAudio & RtMidi

OS:	Audio API:	C++ Class:	Preprocessor Definition:	Library or Framework:	Example Compiler Statement:
Windows	ASIO	RtApiAsio	__WINDOWS_ASIO__	various ASIO header and source files	compiler specific

duplexChannels	RtAudio::DeviceInfo
inputChannels	RtAudio::DeviceInfo
isDefaultInput	RtAudio::DeviceInfo
isDefaultOutput	RtAudio::DeviceInfo
name	RtAudio::DeviceInfo
nativeFormats	RtAudio::DeviceInfo
outputChannels	RtAudio::DeviceInfo
probed	RtAudio::DeviceInfo
sampleRates	RtAudio::DeviceInfo


Public Attributes
bool	probed
bool	probed
std::string	name
std::string	name
unsigned int	outputChannels
unsigned int	outputChannels
unsigned int	inputChannels
unsigned int	inputChannels
unsigned int	duplexChannels
unsigned int	duplexChannels
bool	isDefaultOutput
bool	isDefaultOutput
bool	isDefaultInput
bool	isDefaultInput
std::vector< unsigned int >	sampleRates
std::vector< unsigned int >	sampleRates
RtAudioFormat	nativeFormats
RtAudioFormat	nativeFormats

flags	RtAudio::StreamOptions
numberOfBuffers	RtAudio::StreamOptions
streamName	RtAudio::StreamOptions


Public Attributes
RtAudioStreamFlags	flags
RtAudioStreamFlags	flags
unsigned int	numberOfBuffers
unsigned int	numberOfBuffers
std::string	streamName
std::string	streamName
int	priority

deviceId	RtAudio::StreamParameters
firstChannel	RtAudio::StreamParameters
nChannels	RtAudio::StreamParameters

RtAudio.h

RtAudio.h File Reference

Typedefs

Detailed Description

Typedef Documentation

RtError.h

RtAudio Class List

Class List

Confirmed Bugs (Unfixed):

RtAudio Member List

RtAudio Class Reference

Classes

Public Types

Public Member Functions

Static Public Member Functions

Classes

Detailed Description

Member Enumeration Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

RtError Member List

RtError Class Reference

RtError Class Reference

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Member Enumeration Documentation

Class Index

RtAudio File List

File List

The RtAudio Home Page

The RtAudio Home Page

4.0.4

4.0.5

+Devices are now re-enumerated every time the RtAudio::getDeviceCount(), RtAudio::getDeviceInfo(), and RtAudio::openStream() functions are called. This allows for the proper identification of hot-pluggable (USB, Firewire, ...) devices that are connected after an RtAudio instance is created.

RtAudio Related Pages

Related Pages

RtAudio::DeviceInfo Member List

RtAudio::RtAudio::DeviceInfo Member List

RtAudio::DeviceInfo Struct Reference

RtAudio::RtAudio::DeviceInfo Struct Reference

Public Attributes

Detailed Description

Member Data Documentation

Member Data Documentation

RtAudio::StreamOptions Member List

RtAudio::RtAudio::StreamOptions Member List

RtAudio::StreamOptions Struct Reference

RtAudio::RtAudio::StreamOptions Struct Reference

Public Attributes

Detailed Description

Member Data Documentation

Member Data Documentation

RtAudio::StreamParameters Member List

RtAudio::RtAudio::StreamParameters Member List

RtAudio::StreamParameters Struct Reference

RtAudio::RtAudio::StreamParameters Struct Reference

Public Attributes

Detailed Description

Member Data Documentation

Member Data Documentation

Details: