Retrieve a pointer to a PaDeviceInfo structure containing information
about the specified device.
return A pointer to an immutable PaDeviceInfo structure. If the device
parameter is out of range the function returns NULL.
Retrieve the number of available host APIs. Even if a host API is
available it may have no devices available.
return A non-negative value indicating the number of available host APIs
or, a PaErrorCode (which are always negative) if PortAudio is not initialized
or an error is encountered.
see PaHostApiIndex
Return information about the last host error encountered. The error
information returned by Pa_GetLastHostErrorInfo() will never be modified
asynchronously by errors occurring in other PortAudio owned threads
(such as the thread that manages the stream callback.)
Retrieve the size of a given sample format in bytes.
return The size in bytes of a single sample in the specified format,
or paSampleFormatNotSupported if the format is not supported.
Retrieve CPU usage information for the specified stream.
The “CPU Load” is a fraction of total CPU time consumed by a callback stream’s
audio processing routines including, but not limited to the client supplied
stream callback. This function does not work with blocking read/write streams.
This function may be called from the stream callback function or the
application.
returns a floating point value, typically between 0.0 and 1.0, where 1.0 indicates
that the stream callback is consuming the maximum number of CPU cycles possible
to maintain real-time operation. A value of 0.5 would imply that PortAudio and
the stream callback was consuming roughly 50% of the available CPU time. The
return value may exceed 1.0. A value of 0.0 will always be returned for a
blocking read/write stream, or if an error occurs.
Retrieve a pointer to a PaStreamInfo structure containing information
about the specified stream.
return A pointer to an immutable PaStreamInfo structure. If the stream
parameter is invalid, or an error is encountered, the function returns NULL.
param stream A pointer to an open stream previously created with Pa_OpenStream.
note PortAudio manages the memory referenced by the returned pointer,
the client must not manipulate or free the memory. The pointer is only
guaranteed to be valid until the specified stream is closed.
see PaStreamInfo
Retrieve the number of frames that can be read from the stream without
waiting.
return Returns a non-negative value representing the maximum number of frames
that can be read from the stream without blocking or busy waiting or, a
PaErrorCode (which are always negative) if PortAudio is not initialized or an
error is encountered.
Returns the current time in seconds for a stream according to the same clock used
to generate callback PaStreamCallbackTimeInfo timestamps. The time values are
monotonically increasing and have unspecified origin.
Pa_GetStreamTime returns valid time values for the entire life of the stream,
from when the stream is opened until it is closed. Starting and stopping the stream
does not affect the passage of time returned by Pa_GetStreamTime.
This time may be used for synchronizing other events to the audio stream, for
example synchronizing audio to MIDI.
return The stream’s current time in seconds, or 0 if an error occurred.
see PaTime, PaStreamCallback, PaStreamCallbackTimeInfo
Retrieve the number of frames that can be written to the stream without
waiting.
return Returns a non-negative value representing the maximum number of frames
that can be written to the stream without blocking or busy waiting or, a
PaErrorCode (which are always negative) if PortAudio is not initialized or an
error is encountered.
Retrieve the release number of the currently running PortAudio build.
For example, for version “19.5.1” this will return 0x00130501.
see paMakeVersionNumber
Retrieve version information for the currently running PortAudio build.
return A pointer to an immutable PaVersionInfo structure.
note This function can be called at any time. It does not require PortAudio
to be initialized. The structure pointed to is statically allocated. Do not
attempt to free it or modify it.
see PaVersionInfo, paMakeVersionNumber
version Available as of 19.5.0.
Retrieve a textual description of the current PortAudio build,
e.g. “PortAudio V19.5.0-devel, revision 1952M”.
The format of the text may change in the future. Do not try to parse the
returned string.
deprecated As of 19.5.0, use Pa_GetVersionInfo()->versionText instead.
Convert a host-API-specific device index to standard PortAudio device index.
This function may be used in conjunction with the deviceCount field of
PaHostApiInfo to enumerate all devices for the specified host API.
Library initialization function - call this before using PortAudio.
This function initializes internal data structures and prepares underlying
host APIs for use. With the exception of Pa_GetVersion(), Pa_GetVersionText(),
and Pa_GetErrorText(), this function MUST be called before using any other
PortAudio API functions.
If Pa_Initialize() is called multiple times, each successful
call must be matched with a corresponding call to Pa_Terminate().
Pairs of calls to Pa_Initialize()/Pa_Terminate() may overlap, and are not
required to be fully nested.
Note that if Pa_Initialize() returns an error code, Pa_Terminate() should NOT be called.
return paNoError if successful, otherwise an error code indicating the cause
of failure.
see Pa_Terminate
Determine whether the stream is active.
A stream is active after a successful call to Pa_StartStream(), until it
becomes inactive either as a result of a call to Pa_StopStream() or
Pa_AbortStream(), or as a result of a return value other than paContinue from
the stream callback. In the latter case, the stream is considered inactive
after the last buffer has finished playing.
Returns one (1) when the stream is active (ie playing or recording
audio), zero (0) when not playing or, a PaErrorCode (which are always negative)
if PortAudio is not initialized or an error is encountered.
see Pa_StopStream, Pa_AbortStream, Pa_IsStreamStopped
Determine whether the stream is stopped.
A stream is considered to be stopped prior to a successful call to
Pa_StartStream and after a successful call to Pa_StopStream or Pa_AbortStream.
If a stream callback returns a value other than paContinue the stream is NOT
considered to be stopped.
Returns one (1) when the stream is stopped, zero (0) when
the stream is running or, a PaErrorCode (which are always negative) if
PortAudio is not initialized or an error is encountered.
see Pa_StopStream, Pa_AbortStream, Pa_IsStreamActive
Register a stream finished callback function which will be called when the
stream becomes inactive. See the description of PaStreamFinishedCallback for
further details about when the callback will be called.
param stream a pointer to a PaStream that is in the stopped state - if the
stream is not stopped, the stream’s finished callback will remain unchanged
and an error code will be returned.
param streamFinishedCallback a pointer to a function with the same signature
as PaStreamFinishedCallback, that will be called when the stream becomes
inactive. Passing NULL for this parameter will un-register a previously
registered stream finished callback function.
return on success returns paNoError, otherwise an error code indicating the cause
of the error.
see PaStreamFinishedCallback
Put the caller to sleep for at least ‘msec’ milliseconds. This function is
provided only as a convenience for authors of portable code (such as the tests
and examples in the PortAudio distribution.)
The function may sleep longer than requested so don’t rely on this for accurate
musical timing.
Library termination function - call this when finished using PortAudio.
This function deallocates all resources allocated by PortAudio since it was
initialized by a call to Pa_Initialize(). In cases where Pa_Initialise() has
been called multiple times, each call must be matched with a corresponding call
to Pa_Terminate(). The final matching call to Pa_Terminate() will automatically
close any PortAudio streams that are still open.
Pa_Terminate() MUST be called before exiting a program which uses PortAudio.
Failure to do so may result in serious resource leaks, such as audio devices
not being available until the next reboot.
return paNoError if successful, otherwise an error code indicating the cause
of failure.
see Pa_Initialize
Write samples to an output stream. This function doesn’t return until the
entire buffer has been written - this may involve waiting for the operating
system to consume the data.
param stream A pointer to an open stream previously created with Pa_OpenStream.
param buffer A pointer to a buffer of sample frames. The buffer contains
samples in the format specified by the outputParameters->sampleFormat field
used to open the stream, and the number of channels specified by
outputParameters->numChannels. If non-interleaved samples were requested using
the paNonInterleaved sample format flag, buffer is a pointer to the first element
of an array of buffer pointers, one non-interleaved buffer for each channel.
param frames The number of frames to be written from buffer. This parameter
is not constrained to a specific range, however high performance applications
will want to match this parameter to the framesPerBuffer parameter used
when opening the stream.
return On success PaNoError will be returned, or paOutputUnderflowed if
additional output data was inserted after the previous call and before this
call.
The type used to refer to audio devices. Values of this type usually
range from 0 to (Pa_GetDeviceCount()-1), and may also take on the PaNoDevice
and paUseHostApiSpecificDeviceSpecification values.
Unchanging unique identifiers for each supported host API. This type
is used in the PaHostApiInfo structure. The values are guaranteed to be
unique and to never change, thus allowing code to be written that
conditionally uses host API specific extensions.
A type used to specify one or more sample formats. Each value indicates
a possible format for sound data passed to and from the stream callback,
Pa_ReadStream and Pa_WriteStream.
A single PaStream can provide multiple channels of real-time
streaming audio input and output to a client application. A stream
provides access to audio hardware represented by one or more
PaDevices. Depending on the underlying Host API, it may be possible
to open multiple streams using the same device, however this behavior
is implementation defined. Portable applications should assume that
a PaDevice may be simultaneously used by at most one PaStream.
Functions of type PaStreamCallback are implemented by PortAudio clients.
They consume, process or generate audio in response to requests from an
active PortAudio stream.
Functions of type PaStreamFinishedCallback are implemented by PortAudio
clients. They can be registered with a stream using the Pa_SetStreamFinishedCallback
function. Once registered they are called when the stream becomes inactive
(ie once a call to Pa_StopStream() will not block).
A stream will become inactive after the stream callback returns non-zero,
or when Pa_StopStream or Pa_AbortStream is called. For a stream providing audio
output, if the stream callback returns paComplete, or Pa_StopStream() is called,
the stream finished callback will not be called until all generated sample data
has been played.
param userData The userData parameter supplied to Pa_OpenStream()
see Pa_SetStreamFinishedCallback
Flags used to control the behavior of a stream. They are passed as
parameters to Pa_OpenStream or Pa_OpenDefaultStream. Multiple flags may be
ORed together.
The type used to represent monotonic time in seconds. PaTime is
used for the fields of the PaStreamCallbackTimeInfo argument to the
PaStreamCallback and as the result of Pa_GetStreamTime().