PortAudio 2.0

Utility Functions

In addition to the functions described elsewhere in this tutorial, PortAudio provides a number of Utility functions that are useful in a variety of circumstances. You'll want to read the portaudio.h reference, which documents the entire V19 API for details, but we'll try to cover the basics here.

# Version Information

PortAudio offers two functions to determine the PortAudio Version. This is most useful when you are using PortAudio as a dynamic library, but it may also be useful at other times.

int Pa_GetVersion (void)
const char * Pa_GetVersionText (void)
Pa_GetVersionText
const char * Pa_GetVersionText(void)
Pa_GetVersion
int Pa_GetVersion(void)

# Error Text

PortAudio allows you to get error text from an error number.

const char * Pa_GetErrorText (PaError errorCode)
PaError
int PaError
Definition: portaudio.h:121
Pa_GetErrorText
const char * Pa_GetErrorText(PaError errorCode)

# Stream State

PortAudio Streams exist in 3 states: Active, Stopped, and Callback Stopped. If a stream is in callback stopped state, you'll need to stop it before you can start it again. If you need to query the state of a PortAudio stream, there are two functions for doing so:

PaError Pa_IsStreamStopped (PaStream *stream)
PaError Pa_IsStreamActive (PaStream *stream)
PaStream
void PaStream
Definition: portaudio.h:635
Pa_IsStreamActive
PaError Pa_IsStreamActive(PaStream *stream)
Pa_IsStreamStopped
PaError Pa_IsStreamStopped(PaStream *stream)

# Stream Info

If you need to retrieve info about a given stream, such as latency, and sample rate info, there's a function for that too:

const PaStreamInfo * Pa_GetStreamInfo (PaStream *stream)
Pa_GetStreamInfo
const PaStreamInfo * Pa_GetStreamInfo(PaStream *stream)
PaStreamInfo
Definition: portaudio.h:1043

# Stream Time

If you need to synchronise other activities such as display updates or MIDI output with the PortAudio callback you need to know the current time according to the same timebase used by the stream callback timestamps.

PaTime Pa_GetStreamTime (PaStream *stream)
Pa_GetStreamTime
PaTime Pa_GetStreamTime(PaStream *stream)
PaTime
double PaTime
Definition: portaudio.h:460

# Usage

To determine how much CPU is being used by the callback, use these:

double Pa_GetStreamCpuLoad (PaStream *stream)
Pa_GetStreamCpuLoad
double Pa_GetStreamCpuLoad(PaStream *stream)

# Other utilities

These functions allow you to determine the size of a sample from its format and sleep for a given amount of time. The sleep function should not be used for precise timing or synchronization because it makes few guarantees about the exact length of time it waits. It is most useful for testing.

PaError Pa_GetSampleSize (PaSampleFormat format)
void Pa_Sleep (long msec)
Pa_Sleep
void Pa_Sleep(long msec)
PaSampleFormat
unsigned long PaSampleFormat
Definition: portaudio.h:484
Pa_GetSampleSize
PaError Pa_GetSampleSize(PaSampleFormat format)

Previous: Closing a Stream and Terminating PortAudio | Next: Enumerating and Querying PortAudio Devices