AudioHardware
Discussion
The audio HAL provides an abstraction through which applications can access audio hardware. To
do this, the HAL provides a small set of AudioObjects that provide access to the various pieces
of the system.
AudioObjects all have a set of properties that describe and manipulate their state. A property
is accessed via an ordered triple. The first ordinate is the selector which describes the
property. The other two ordinates are the scope and element that identify the particular part of
the object in which to look for the selector. The AudioObjectPropertyAddress structure
encapsulates the property address. The value of a property is an untyped block of data whose
content depends on the specifics of the selector. Some selectors also require the use of a
qualifier when querying. The qualifier allows for additional information to be provided to be
used in the manipulation of the property. Changing the value of a property is always considered
asynchronous.
Applications use the routines AudioObjectHasProperty(), AudioObjectIsPropertySettable() and
AudioObjectGetPropertyDataSize() to find useful meta-information about the property. Apps use
AudioObjectGetPropertyData() and AudioObjectSetPropertyData() to manipulate the value of the
property. Apps use AudioObjectAddPropertyListener() and AudioObjectRemovePropertyListener() to
register/unregister a function that is to be called when a given property's value changes.
The class of an AudioObject determines the basic functionality of the object in terms of what
functions will operate on it as well as the set of properties that can be expected to be
implemented by the object. The set of available classes for objects is limited to those defined
here. There are no other classes. The set of classes is arranged in a hierarchy such that one
class inherits the properties/routines of it's super class.
The base class for all AudioObjects is the class AudioObject. As such, each AudioObject will
provide basic properties such as it's class, it's human readable name, and the other
AudioObjects it contains. Other important classes include AudioSystemObject, AudioDevice, and
AudioStream.
The AudioObjects in the HAL are arranged in a containment hierarchy. The root of the hierarchy
is the one and only instance of the AudioSystemObject class. The properties of the
AudioSystemObject describe the process global settings such as the various default devices and
the notification run loop. The AudioSystemObject also contains all the AudioDevices that are
available.
Instances of the AudioDevice class encapsulate individual audio devices. An AudioDevice serves
as the basic unit of IO. It provides a single IO cycle, a timing source based on it, and all the
buffers synchronized to it. The IO cycle presents all the synchronized buffers to the client in
the same call out along with time stamps that specify the current time, when the input data was
acquired and when the output data will be presented.
AudioDevices contain instances of the AudioStream class. An AudioStream represents a single
buffer of data for transferring across the user/kernel boundary. As such, AudioStreams are the
gatekeepers of format information. Each has it's own format and list of available formats.
AudioStreams can provide data in any format, including encoded formats and non-audio formats. If
the format is a linear PCM format, the data will always be presented as 32 bit, native endian
floating point. All conversions to and from the true physical format of the hardware is handled
by the device's driver.
Both AudioDevices and AudioStreams can contain instances of the AudioControl class or it's many
subclasses. An AudioControl provides properties that describe/manipulate a particular aspect of
the object such as gain, mute, data source selection, etc. Many common controls are also
also available as properties on the AudioDevice or AudioStream.
Functions
Registers the given AudioDeviceIOProc with the AudioDevice.
extern OSStatus AudioDeviceAddIOProc (
AudioDeviceID inDevice,
AudioDeviceIOProc inProc,
void* inClientData
) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
Discussion
A client may have multiple IOProcs for a given device, but the device is free to
only accept as many as it can handle. Note that it is not recommended for
clients to have more than a single IOProc registered at a time as this can be
wasteful of system resources. Rather, it is recommended that the client do any
necessary mixing itself so that only one IOProc is necessary.
Parameter Descriptions
- inDevice
- The AudioDevice to register the IOProc with.
- inProc
- The AudioDeviceIOProc to register.
- inClientData
- A pointer to client data that is passed back to the IOProc when it is
called.
- function result
- An OSStatus indicating success or failure.
Registers the given AudioDevicePropertyListenerProc to receive notifications
when the given property changes.
extern OSStatus AudioDeviceAddPropertyListener (
AudioDeviceID inDevice,
UInt32 inChannel,
Boolean isInput,
AudioDevicePropertyID inPropertyID,
AudioDevicePropertyListenerProc inProc,
void* inClientData
) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
Discussion
Note that the same functionality is provided by AudioObjectAddPropertyListener
in conjunction with AudioObjectPropertyListenerProc.
Parameter Descriptions
- inDevice
- The AudioDevice with whom to register the listener.
- inChannel
- The channel of the property to listen to.
- isInput
- Which section of the AudioDevice to listen to.
- inPropertyID
- The AudioDevicePropertyID of the property to listen to.
- inProc
- AudioDevicePropertyListenerProc to call.
- inClientData
- A pointer to client data that is passed to the listener when it is called.
- function result
- An OSStatus indicating success or failure.
Retrieves the current time from an AudioDevice. Note that the device has to be
running.
extern OSStatus AudioDeviceGetCurrentTime (
AudioDeviceID inDevice,
AudioTimeStamp* outTime
) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
Parameter Descriptions
- inDevice
- The AudioDevice to from which to get the time.
- outTime
- An AudioTimeStamp into which the current time is put.
- function result
- An OSStatus indicating success or failure. kAudioHardwareNotRunningError will be
returned if the AudioDevice isn't running.
Query an AudioDevice to get a time equal to or later than the given time that is
the best time to start IO.
extern OSStatus AudioDeviceGetNearestStartTime (
AudioDeviceID inDevice,
AudioTimeStamp* ioRequestedStartTime,
UInt32 inFlags
) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
Discussion
The time that is returned is dictated by the constraints of the device and the
system. For instance, the driver of a device that provides both audio and video
data may only allow start times that coincide with the edge of a video frame.
Also, if the device already has one or more active IOProcs, the start time will
be shifted to the beginning of the next IO cycle so as not to cause
discontinuities in the existing IOProcs. Another reason the start time may shift
is to allow for aligning the buffer accesses in an optimal fashion. Note that
the device must be running to use this function.
Parameter Descriptions
- inDevice
- The AudioDevice to query.
- ioRequestedStartTime
- A pointer to an AudioTimeStamp that, on entry, is the requested start time.
On exit, it will have the a time equal to or later than the requested time,
as dictated by the device's constraints.
- inFlags
- A UInt32 containing flags that modify how this function behaves.
- function result
- An OSStatus indicating success or failure. kAudioHardwareNotRunningError will be
returned if the AudioDevice isn't running.
kAudioHardwareUnsupportedOperationError will be returned if the AudioDevice does
not support starting at a specific time.
Queries an the AudioDevice object to get the data of the given property and
places it in the provided buffer.
extern OSStatus AudioDeviceGetProperty (
AudioDeviceID inDevice,
UInt32 inChannel,
Boolean isInput,
AudioDevicePropertyID inPropertyID,
UInt32* ioPropertyDataSize,
void* outPropertyData
) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
Discussion
Note that the same functionality is provided by the function
AudioObjectGetPropertyData().
Parameter Descriptions
- inDevice
- The AudioDevice to query.
- inChannel
- The channel of the property to query where 0 is the master channel.
- isInput
- Which section of the AudioDevice to query.
- inPropertyID
- The AudioDevicePropertyID of the property to query.
- ioPropertyDataSize
- A UInt32 which on entry indicates the size of the buffer pointed to by
outData and on exit indicates how much of the buffer was used.
- outPropertyData
- The buffer into which the object will put the data for the given property.
- function result
- An OSStatus indicating success or failure.
Retrieve information about the given property of an AudioDevice.
extern OSStatus AudioDeviceGetPropertyInfo (
AudioDeviceID inDevice,
UInt32 inChannel,
Boolean isInput,
AudioDevicePropertyID inPropertyID,
UInt32* outSize,
Boolean* outWritable
) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
Discussion
Note that the same functionality is provided by the functions
AudioObjectHasProperty(), AudioObjectIsPropertySettable(), and
AudioObjectGetPropertyDataSize().
Parameter Descriptions
- inDevice
- The AudioDevice to query.
- inChannel
- The channel of the property to query where 0 is the master channel.
- isInput
- Which section of the AudioDevice to query.
- inPropertyID
- The AudioDevicePropertyID of the property to query.
- outSize
- A pointer to a UInt32 that receives the size of the property data in bytes
on exit. This can be NULL if the size information is not being requested.
- outWritable
- A pointer to a Boolean that receives indication of whether or not the given
property can be set. This can be NULL if the writability is not being
requested.
- function result
- An OSStatus indicating success or failure.
Read some data from an AudioDevice starting at the given time.
extern OSStatus AudioDeviceRead (
AudioDeviceID inDevice,
const AudioTimeStamp* inStartTime,
AudioBufferList* outData
) AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER;
Discussion
With the advent of aggregate devices, the need for AudioDeviceRead has gone
away. Consequently, this function is a good candidate for deprecation some day.
Parameter Descriptions
- inDevice
- The AudioDevice to read from.
- inStartTime
- An AudioTimeStamp indicating the time from which to read the data. In
general, the valid range of time (in frames) is from the current time minus
the maximum IO buffer size to the current time minus the safety offset.
- outData
- An AudioBufferList that must be the same size and shape as that returned by
kAudioDevicePropertyStreamConfiguration. Further, the AudioBufferList must
have been previously registered with the device via
kAudioDevicePropertyRegisterBufferList. On exit, the mDataSize fields will
be updated with the amount of data read.
- function result
- An OSStatus indicating success or failure.
kAudioHardwareUnsupportedOperationError will be returned if the AudioDevice does
not support direct reading.
Unregisters the given AudioDeviceIOProc from the AudioDevice.
extern OSStatus AudioDeviceRemoveIOProc (
AudioDeviceID inDevice,
AudioDeviceIOProc inProc
) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
Parameter Descriptions
- inDevice
- The AudioDevice to unregister the IOProc from.
- inProc
- The AudioDeviceIOProc to unregister.
- function result
- An OSStatus indicating success or failure.
Unregisters the given AudioDevicePropertyListenerProc from receiving
notifications when the given property changes.
extern OSStatus AudioDeviceRemovePropertyListener (
AudioDeviceID inDevice,
UInt32 inChannel,
Boolean isInput,
AudioDevicePropertyID inPropertyID,
AudioDevicePropertyListenerProc inProc
) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
Discussion
Note that the same functionality is provided by
AudioObjectRemovePropertyListener in conjunction with
AudioObjectPropertyListenerProc.
Parameter Descriptions
- inDevice
- The AudioDevice with whom to unregister the listener.
- inChannel
- The channel of the property to unregister from.
- isInput
- Which section of the AudioDevice to unregister from.
- inPropertyID
- The AudioDevicePropertyID of the property to stop listening to.
- inProc
- AudioDevicePropertyListenerProc to unregister.
- function result
- An OSStatus indicating success or failure.
Tells the AudioDevice object to change the value of the given property using the
provided data.
extern OSStatus AudioDeviceSetProperty (
AudioDeviceID inDevice,
const AudioTimeStamp* inWhen,
UInt32 inChannel,
Boolean isInput,
AudioDevicePropertyID inPropertyID,
UInt32 inPropertyDataSize,
const void* inPropertyData
) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
Discussion
Note that the value of the property should not be considered changed until the
HAL has called the listeners as many properties values are changed
asynchronously. Also note that the same functionality is provided by the
function AudioObjectGetPropertyData().
Parameter Descriptions
- inDevice
- The AudioDevice to change.
- inWhen
- A pointer to an AudioTimeStamp that says when to change the property's value
relative to the device's time base. NULL means execute the change
immediately.
- inChannel
- The channel of the property to change where 0 is the master channel.
- isInput
- Which section of the AudioDevice to change.
- inPropertyID
- The AudioDevicePropertyID of the property to change.
- inPropertyDataSize
- A UInt32 indicating the size of the buffer pointed to by inData.
- inPropertyData
- The buffer containing the data to be used to change the property's value.
- function result
- An OSStatus indicating success or failure.
Starts IO for the given AudioDeviceIOProc.
extern OSStatus AudioDeviceStart (
AudioDeviceID inDevice,
AudioDeviceIOProc inProc
) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
Parameter Descriptions
- inDevice
- The AudioDevice to start the IOProc on.
- inProc
- The AudioDeviceIOProc to start. Note that this can be NULL, which starts the
hardware regardless of whether or not there are any IOProcs registered. This
is necessary if any of the AudioDevice's timing services are to be used. A
balancing call to AudioDeviceStop with a NULL IOProc is required to stop the
hardware.
- function result
- An OSStatus indicating success or failure.
Starts IO for the given AudioDeviceIOProc and aligns the IO cycle of the
AudioDevice with the given time.
extern OSStatus AudioDeviceStartAtTime (
AudioDeviceID inDevice,
AudioDeviceIOProc inProc,
AudioTimeStamp* ioRequestedStartTime,
UInt32 inFlags
) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
Parameter Descriptions
- inDevice
- The AudioDevice to start the IOProc on.
- inProc
- The AudioDeviceIOProc to start. Note that this can be NULL, which starts the
hardware regardless of whether or not there are any IOProcs registered.
- ioRequestedStartTime
- A pointer to an AudioTimeStamp that, on entry, is the requested time to
start the IOProc. On exit, it will be the actual time the IOProc will start.
- inFlags
- A UInt32 containing flags that modify how this function behaves.
- function result
- An OSStatus indicating success or failure.
kAudioHardwareUnsupportedOperationError will be returned if the AudioDevice does
not support starting at a specific time and inProc and ioRequestedStartTime are
not NULL.
Stops IO for the given AudioDeviceIOProc.
extern OSStatus AudioDeviceStop (
AudioDeviceID inDevice,
AudioDeviceIOProc inProc
) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
Parameter Descriptions
- inDevice
- The AudioDevice to stop the IOProc on.
- inProc
- The AudioDeviceIOProc to stop.
- function result
- An OSStatus indicating success or failure.
Translates the time in the AudioDevice's time base from one representation to
another. Note that the device has to be running
extern OSStatus AudioDeviceTranslateTime (
AudioDeviceID inDevice,
const AudioTimeStamp* inTime,
AudioTimeStamp* outTime
) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
Parameter Descriptions
- inDevice
- The AudioDevice whose time base governs the translation.
- inTime
- An AudioTimeStamp containing the time to be translated.
- outTime
- An AudioTimeStamp into which the translated time is put. On entry, the
mFlags field specifies which representations to translate the input time
into. Because not every device supports all time representations, on exit,
the mFlags field will indicate which translations were actually done.
- function result
- An OSStatus indicating success or failure. kAudioHardwareNotRunningError will be
returned if the AudioDevice isn't running.
Registers the given AudioHardwarePropertyListenerProc to receive notifications
when the given property changes.
extern OSStatus AudioHardwareAddPropertyListener (
AudioHardwarePropertyID inPropertyID,
AudioHardwarePropertyListenerProc inProc,
void* inClientData
) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
Discussion
Note that the same functionality is provided by AudioObjectAddPropertyListener
in conjunction with AudioObjectPropertyListenerProc.
Parameter Descriptions
- inPropertyID
- The AudioHardwarePropertyID of the property to listen to.
- inProc
- AudioHardwarePropertyListenerProc to call.
- inClientData
- A pointer to client data that is passed to the listener when it is called.
- function result
- An OSStatus indicating success or failure.
Add the given CFRunLoopSource to the the HAL's notification CFRunLoop.
extern OSStatus AudioHardwareAddRunLoopSource (
CFRunLoopSourceRef inRunLoopSource
) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
Discussion
The CFRunLoop the HAL uses for notifications is specified by
kAudioHardwarePropertyRunLoop. If kAudioHardwarePropertyRunLoop changes,
CFRunLoopSources added with this function will automatically be transferred to
the new CFRunLoop.
Parameter Descriptions
- inRunLoopSource
- The CFRunLoopSource to add.
- function result
- An OSStatus indicating success or failure.
Queries an the AudioSystemObject to get the data of the given property and
places it in the provided buffer.
extern OSStatus AudioHardwareGetProperty (
AudioHardwarePropertyID inPropertyID,
UInt32* ioPropertyDataSize,
void* outPropertyData
) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
Discussion
Note that the same functionality is provided by the function
AudioObjectGetPropertyData().
Parameter Descriptions
- inPropertyID
- The AudioHardwarePropertyID of the property to query.
- ioDataSize
- A UInt32 which on entry indicates the size of the buffer pointed to by
outData and on exit indicates how much of the buffer was used.
- outData
- The buffer into which the AudioSystemObject will put the data for the given
property.
- function result
- An OSStatus indicating success or failure.
Retrieve information about the given property.
extern OSStatus AudioHardwareGetPropertyInfo (
AudioHardwarePropertyID inPropertyID,
UInt32* outSize,
Boolean* outWritable
) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
Discussion
Note that the same functionality is provided by the functions
AudioObjectHasProperty(), AudioObjectIsPropertySettable(), and
AudioObjectGetPropertyDataSize().
Parameter Descriptions
- inPropertyID
- The AudioHardwarePropertyID of the property to query.
- outSize
- A pointer to a UInt32 that receives the size of the property data in bytes
on exit. This can be NULL if the size information is not being requested.
- outWritable
- A pointer to a Boolean that receives indication of whether or not the given
property can be set. This can be NULL if the writability is not being
requested.
- function result
- An OSStatus indicating success or failure.
Unregisters the given AudioHardwarePropertyListenerProc from receive
notifications when the given property changes.
extern OSStatus AudioHardwareRemovePropertyListener (
AudioHardwarePropertyID inPropertyID,
AudioHardwarePropertyListenerProc inProc
) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
Discussion
Note that the same functionality is provided by
AudioObjectRemovePropertyListener in conjunction with
AudioObjectPropertyListenerProc.
Parameter Descriptions
- inPropertyID
- The AudioHardwarePropertyID of the property to stop listening to.
- inProc
- AudioHardwarePropertyListenerProc to unregister.
- function result
- An OSStatus indicating success or failure.
Remove the given CFRunLoopSource from the the HAL's notification CFRunLoop.
extern OSStatus AudioHardwareRemoveRunLoopSource (
CFRunLoopSourceRef inRunLoopSource
) AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;
Discussion
The CFRunLoop the HAL uses for notifications is specified by
kAudioHardwarePropertyRunLoop.
Parameter Descriptions
- inRunLoopSource
- The CFRunLoopSource to remove.
- function result
- An OSStatus indicating success or failure.
Tells the AudioSystemObject to change the value of the given property using the
provided data.
extern OSStatus AudioHardwareSetProperty (
AudioHardwarePropertyID inPropertyID,
UInt32 inPropertyDataSize,
const void* inPropertyData
) AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER;
Discussion
Note that the value of the property should not be considered changed until the
HAL has called the listeners as many properties values are changed
asynchronously. Also note that the same functionality is provided by the
function AudioObjectGetPropertyData().
Parameter Descriptions
- inPropertyID
- The AudioHardwarePropertyID of the property to change.
- inDataSize
- A UInt32 indicating the size of the buffer pointed to by inData.
- inData
- The buffer containing the data to be used to change the property's value.
- function result
- An OSStatus indicating success or failure.
When this routine is called, all IO on all devices within a process will be
terminated and all resources capable of being released will be released. This
routine essentially returns the HAL to it's uninitialized state.
extern OSStatus AudioHardwareUnload (void) AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER;
- function result
- An OSStatus indicating success or failure.
Registers the given AudioObjectPropertyListenerProc to receive notifications
when the given properties change.
extern OSStatus AudioObjectAddPropertyListener (
AudioObjectID inObjectID,
const AudioObjectPropertyAddress* inAddress,
AudioObjectPropertyListenerProc inListener,
void* inClientData
) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;
Parameter Descriptions
- inObjectID
- The AudioObject to register the listener with.
- inAddress
- The AudioObjectPropertyAddresses indicating which property the listener
should be notified about.
- inListener
- The AudioObjectPropertyListenerProc to call.
- inClientData
- A pointer to client data that is passed to the listener when it is called.
- function result
- An OSStatus indicating success or failure.
Queries an AudioObject to get the data of the given property and places it in
the provided buffer.
extern OSStatus AudioObjectGetPropertyData (
AudioObjectID inObjectID,
const AudioObjectPropertyAddress* inAddress,
UInt32 inQualifierDataSize,
const void* inQualifierData,
UInt32* ioDataSize,
void* outData
) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;
Parameter Descriptions
- inObjectID
- The AudioObject to query.
- inAddress
- An AudioObjectPropertyAddress indicating which property is being queried.
- inQualifierDataSize
- A UInt32 indicating the size of the buffer pointed to by inQualifierData.
Note that not all properties require qualification, in which case this
value will be 0.
- inQualifierData,
- A buffer of data to be used in determining the data of the property being
queried. Note that not all properties require qualification, in which case
this value will be NULL.
- ioDataSize
- A UInt32 which on entry indicates the size of the buffer pointed to by
outData and on exit indicates how much of the buffer was used.
- outData
- The buffer into which the AudioObject will put the data for the given
property.
- function result
- An OSStatus indicating success or failure.
Queries an AudioObject to find the size of the data for the given property.
extern OSStatus AudioObjectGetPropertyDataSize (
AudioObjectID inObjectID,
const AudioObjectPropertyAddress* inAddress,
UInt32 inQualifierDataSize,
const void* inQualifierData,
UInt32* outDataSize
) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;
Parameter Descriptions
- inObjectID
- The AudioObject to query.
- inAddress
- An AudioObjectPropertyAddress indicating which property is being queried.
- inQualifierDataSize
- A UInt32 indicating the size of the buffer pointed to by inQualifierData.
Note that not all properties require qualification, in which case this
value will be 0.
- inQualifierData,
- A buffer of data to be used in determining the data of the property being
queried. Note that not all properties require qualification, in which case
this value will be NULL.
- outDataSize
- A UInt32 indicating how many bytes the data for the given property occupies.
- function result
- An OSStatus indicating success or failure.
Queries an AudioObject about whether or not it has the given property.
extern Boolean AudioObjectHasProperty (
AudioObjectID inObjectID,
const AudioObjectPropertyAddress* inAddress
) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;
Parameter Descriptions
- inObjectID
- The AudioObject to query.
- inAddress
- An AudioObjectPropertyAddress indicating which property is being queried.
- function result
- A Boolean indicating whether or not the AudioObject has the given property.
Queries an AudioObject about whether or not the given property can be set using
AudioObjectSetPropertyData.
extern OSStatus AudioObjectIsPropertySettable (
AudioObjectID inObjectID,
const AudioObjectPropertyAddress* inAddress,
Boolean* outIsSettable
) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;
Parameter Descriptions
- inObjectID
- The AudioObject to query.
- inAddress
- An AudioObjectPropertyAddress indicating which property is being queried.
- outIsSettable
- A Boolean indicating whether or not the property can be set.
- function result
- An OSStatus indicating success or failure.
Unregisters the given AudioObjectPropertyListenerProc from receiving
notifications when the given properties change.
extern OSStatus AudioObjectRemovePropertyListener (
AudioObjectID inObjectID,
const AudioObjectPropertyAddress* inAddress,
AudioObjectPropertyListenerProc inListener,
void* inClientData
) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;
Parameter Descriptions
- inObjectID
- The AudioObject to unregister the listener from.
- inNumberAddresses
- The number of elements in the inAddresses array.
- inAddresses
- The AudioObjectPropertyAddress indicating which property the listener should
be removed from.
- inListener
- The AudioObjectPropertyListenerProc being removed.
- inClientData
- A pointer to client data that is passed to the listener when it is called.
- function result
- An OSStatus indicating success or failure.
Tells an AudioObject to change the value of the given property using the
provided data.
extern OSStatus AudioObjectSetPropertyData (
AudioObjectID inObjectID,
const AudioObjectPropertyAddress* inAddress,
UInt32 inQualifierDataSize,
const void* inQualifierData,
UInt32 inDataSize,
const void* inData
) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;
Discussion
Note that the value of the property should not be considered changed until the
HAL has called the listeners as many properties values are changed
asynchronously.
Parameter Descriptions
- inObjectID
- The AudioObject to change.
- inAddress
- An AudioObjectPropertyAddress indicating which property is being changed.
- inQualifierDataSize
- A UInt32 indicating the size of the buffer pointed to by inQualifierData.
Note that not all properties require qualification, in which case this
value will be 0.
- inQualifierData,
- A buffer of data to be used in determining the data of the property being
queried. Note that not all properties require qualification, in which case
this value will be NULL.
- inDataSize
- A UInt32 indicating the size of the buffer pointed to by inData.
- inData
- The buffer containing the data to be used to change the property's value.
- function result
- An OSStatus indicating success or failure.
Prints to standard out a textural description of the AudioObject.
extern void AudioObjectShow (
AudioObjectID inObjectID
) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;
Parameter Descriptions
- inObjectID
- The AudioObject to show.
Registers the given AudioStreamPropertyListenerProc to receive notifications
when the given property changes.
extern OSStatus AudioStreamAddPropertyListener (
AudioStreamID inStream,
UInt32 inChannel,
AudioDevicePropertyID inPropertyID,
AudioStreamPropertyListenerProc inProc,
void* inClientData
) AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER;
Discussion
Note that the same functionality is provided by AudioObjectAddPropertyListener
in conjunction with AudioObjectPropertyListenerProc.
Parameter Descriptions
- inStream
- The AudioStream with whom to register the listener.
- inChannel
- The channel of the property to listen to.
- inPropertyID
- The AudioDevicePropertyID of the property to listen to.
- inProc
- AudioStreamPropertyListenerProc to call.
- inClientData
- A pointer to client data that is passed to the listener when it is called.
- function result
- An OSStatus indicating success or failure.
Queries an the AudioStream object to get the data of the given property and
places it in the provided buffer.
extern OSStatus AudioStreamGetProperty (
AudioStreamID inStream,
UInt32 inChannel,
AudioDevicePropertyID inPropertyID,
UInt32* ioPropertyDataSize,
void* outPropertyData
) AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER;
Discussion
Note that the same functionality is provided by the function
AudioObjectGetPropertyData().
Parameter Descriptions
- inStream
- The AudioStream to query.
- inChannel
- The channel of the property to query where 0 is the master channel.
- inPropertyID
- The AudioDevicePropertyID of the property to query.
- ioPropertyDataSize
- A UInt32 which on entry indicates the size of the buffer pointed to by
outData and on exit indicates how much of the buffer was used.
- outPropertyData
- The buffer into which the object will put the data for the given property.
- function result
- An OSStatus indicating success or failure.
Retrieve information about the given property of an AudioStream.
extern OSStatus AudioStreamGetPropertyInfo (
AudioStreamID inStream,
UInt32 inChannel,
AudioDevicePropertyID inPropertyID,
UInt32* outSize,
Boolean* outWritable
) AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER;
Parameter Descriptions
- inStream
- The AudioStream to query.
- inChannel
- The channel of the property to query where 0 is the master channel.
- inPropertyID
- The AudioDevicePropertyID of the property to query.
- outSize
- A pointer to a UInt32 that receives the size of the property data in bytes
on exit. This can be NULL if the size information is not being requested.
- outWritable
- A pointer to a Boolean that receives indication of whether or not the given
property can be set. This can be NULL if the writability is not being
requested.
- function result
- An OSStatus indicating success or failure.
Unregisters the given AudioStreamPropertyListenerProc from receiving
notifications when the given property changes.
extern OSStatus AudioStreamRemovePropertyListener (
AudioStreamID inStream,
UInt32 inChannel,
AudioDevicePropertyID inPropertyID,
AudioStreamPropertyListenerProc inProc
) AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER;
Discussion
Note that the same functionality is provided by
AudioObjectRemovePropertyListener in conjunction with
AudioObjectPropertyListenerProc.
Parameter Descriptions
- inStream
- The AudioStream with whom to unregister the listener.
- inChannel
- The channel of the property to unregister from.
- inPropertyID
- The AudioDevicePropertyID of the property to stop listening to.
- inProc
- AudioStreamPropertyListenerProc to unregister.
- function result
- An OSStatus indicating success or failure.
Tells the AudioStream object to change the value of the given property using the
provided data.
extern OSStatus AudioStreamSetProperty (
AudioStreamID inStream,
const AudioTimeStamp* inWhen,
UInt32 inChannel,
AudioDevicePropertyID inPropertyID,
UInt32 inPropertyDataSize,
const void* inPropertyData
) AVAILABLE_MAC_OS_X_VERSION_10_1_AND_LATER;
Discussion
Note that the value of the property should not be considered changed until the
HAL has called the listeners as many properties values are changed
asynchronously. Also note that the same functionality is provided by the
function AudioObjectGetPropertyData().
Parameter Descriptions
- inStream
- The AudioStream to change.
- inWhen
- A pointer to an AudioTimeStamp that says when to change the property's value
relative to the device's time base. NULL means execute the change
immediately.
- inChannel
- The channel of the property to change where 0 is the master channel.
- inPropertyID
- The AudioDevicePropertyID of the property to change.
- inPropertyDataSize
- A UInt32 indicating the size of the buffer pointed to by inData.
- inPropertyData
- The buffer containing the data to be used to change the property's value.
- function result
- An OSStatus indicating success or failure.
Typedefs
AudioClassIDs are used to identify the class of an AudioObject.
typedef UInt32 AudioClassID;
AudioDevice is the base class for all objects that represent an audio device.
typedef AudioObjectID AudioDeviceID;
Discussion
AudioDevice is a subclass of AudioObject. AudioDevices normally contain
AudioStreams and AudioControls, but may contain other things depending on the
kind of AudioDevice (e.g. aggregate devices contain other AudioDevices).
An AudioDeviceIOProc is called by an AudioDevice to provide input data read from
the device and collect output data to be written to the device for the current
IO cycle.
typedef OSStatus (typedef OSStatus
*AudioDeviceIOProc) (
AudioDeviceID inDevice,
const AudioTimeStamp* inNow,
const AudioBufferList* inInputData,
const AudioTimeStamp* inInputTime,
AudioBufferList* outOutputData,
const AudioTimeStamp* inOutputTime,
void* inClientData
);
Parameter Descriptions
- inDevice
- The AudioDevice doing the IO.
- inNow
- An AudioTimeStamp that indicates the IO cycle started. Note that this time
includes any scheduling latency that may have been incurred waking the
thread on which IO is being done.
- inInputData
- An AudioBufferList containing the input data for the current IO cycle. For
streams that are disabled, the AudioBuffer's mData field will be NULL but
the mDataByteSize field will still say how much data would have been there
if it was enabled. Note that the contents of this structure should never be
modified.
- inInputTime
- An AudioTimeStamp that indicates the time at which the first frame in the
data was acquired from the hardware. If the device has no input streams, the
time stamp will be zeroed out.
- outOutputData
- An AudioBufferList in which the output data for the current IO cycle is to
be placed. On entry, each AudioBuffer's mDataByteSize field indicates the
maximum amount of data that can be placed in the buffer and the buffer's
memory has been zeroed out. For formats where the number of bytes per packet
can vary (as with AC-3, for example), the client has to fill out on exit
each mDataByteSize field in each AudioBuffer with the amount of data that
was put in the buffer. Otherwise, the mDataByteSize field should not be
changed. For streams that are disabled, the AudioBuffer's mData field will
be NULL but the mDataByteSize field will still say how much data would have
been there if it was enabled. Except as noted above, the contents of this
structure should not other wise be modified.
- inOutputTime
- An AudioTimeStamp that indicates the time at which the first frame in the
data will be passed to the hardware. If the device has no output streams,
the time stamp will be zeroed out.
- inClientData
- A pointer to client data established when the AudioDeviceIOProc was
registered with the AudioDevice.
- function result
- The return value is currently unused and should always be 0.
An AudioDevicePropertyID is an integer that identifies a specific piece of
information about the object.
typedef AudioObjectPropertySelector AudioDevicePropertyID;
Clients register an AudioDevicePropertyListenerProc with the AudioDevice object
in order to receive notifications when the properties of the object change.
typedef OSStatus (typedef OSStatus
*AudioDevicePropertyListenerProc) (
AudioDeviceID inDevice,
UInt32 inChannel,
Boolean isInput,
AudioDevicePropertyID inPropertyID,
void* inClientData
);
Discussion
Note that the same functionality is provided by AudioObjectPropertyListenerProc.
Parameter Descriptions
- inDevice
- The AudioDevice whose property has changed.
- inChannel
- The channel of the property that changed where 0 is the master channel.
- isInput
- Which section of the AudioDevice changed.
- inPropertyID
- The AudioDevicePropertyID of the property that changed.
- inClientData
- A pointer to client data established when the listener proc was registered
with the object.
- function result
- The return value is currently unused and should always be 0.
An AudioHardwarePropertyID is a integer that identifies a specific piece of
information about the AudioSystemObject.
typedef AudioObjectPropertySelector AudioHardwarePropertyID;
Clients register an AudioHardwarePropertyListenerProc with the AudioSystemObject
in order to receive notifications when the properties of the object change.
typedef OSStatus (typedef OSStatus
*AudioHardwarePropertyListenerProc) (
AudioHardwarePropertyID inPropertyID,
void* inClientData
);
Discussion
Note that the same functionality is provided by AudioObjectPropertyListenerProc.
Parameter Descriptions
- inPropertyID
- The AudioHardwarePropertyID of the property that changed.
- inClientData
- A pointer to client data established when the listener proc was registered
with the AudioSystemObject.
- function result
- The return value is currently unused and should always be 0.
AudioObject is the base class for all the objects in the HAL.
typedef UInt32 AudioObjectID;
Discussion
AudioObjects have properties and can contain other AudioObjects.
An AudioObjectPropertyElement is an integer that identifies, along with the
AudioObjectPropertySelector and AudioObjectPropertyScope, a specific piece of
information about an AudioObject.
typedef UInt32 AudioObjectPropertyElement;
Discussion
The element selects one of possibly many items in the section of the object in
which to look for the property. Elements are number sequentially where 0
represents the master element. Elements are particular to an instance of a
class, meaning that two instances can have different numbers of elements in the
same scope. There is no inheritance of elements.
Clients register an AudioObjectPropertyListenerProc with an AudioObject in order
to receive notifications when the properties of the object change.
typedef OSStatus (typedef OSStatus
*AudioObjectPropertyListenerProc) (
AudioObjectID inObjectID,
UInt32 inNumberAddresses,
const AudioObjectPropertyAddress inAddresses[],
void* inClientData
);
Discussion
Listeners will be called when possibly many properties have changed.
Consequently, the implementation of a listener must go through the array of
addresses to see what exactly has changed. Note that the array of addresses will
always have at least one address in it for which the listener is signed up to
receive notifications about but may contain addresses for properties for which
the listener is not signed up to receive notifications.
Parameter Descriptions
- inObjectID
- The AudioObject whose properties have changed.
- inNumberAddresses
- The number of elements in the inAddresses array.
- inAddresses
- An array of AudioObjectPropertyAddresses indicating which properties
changed.
- inClientData
- A pointer to client data established when the listener proc was registered
with the AudioObject.
- function result
- The return value is currently unused and should always be 0.
An AudioObjectPropertyScope is a four char code that identifies, along with the
AudioObjectPropertySelector and AudioObjectPropertyElement, a specific piece of
information about an AudioObject.
typedef UInt32 AudioObjectPropertyScope;
Discussion
The scope specifies the section of the object in which to look for the property,
such as input, output, global, etc. Note that each class has a different set of
scopes. A subclass inherits it's superclass's set of scopes.
An AudioObjectPropertySelector is a four char code that identifies, along with
the AudioObjectPropertyScope and AudioObjectPropertyElement, a specific piece of
information about an AudioObject.
typedef UInt32 AudioObjectPropertySelector;
Discussion
The property selector specifies the general classification of the property such
as volume, stream format, latency, etc. Note that each class has a different set
of selectors. A subclass inherits it's super class's set of selectors, although
it may not implement them all.
AudioStream is the base class for all objects that represent a stream of data on
an audio device.
typedef AudioObjectID AudioStreamID;
Discussion
AudioStream is a subclass of AudioObject and can contain AudioControls.
Clients register an AudioStreamPropertyListenerProc with the AudioStream object
in order to receive notifications when the properties of the object change.
typedef OSStatus (typedef OSStatus
*AudioStreamPropertyListenerProc) (
AudioStreamID inStream,
UInt32 inChannel,
AudioDevicePropertyID inPropertyID,
void* inClientData
);
Discussion
Note that the same functionality is provided by AudioObjectPropertyListenerProc.
Parameter Descriptions
- inStream
- The AudioStream whose property has changed.
- inChannel
- The channel of the property that changed where 0 is the master channel.
- inPropertyID
- The AudioDevicePropertyID of the property that changed.
- inClientData
- A pointer to client data established when the listener proc was registered
with the object.
- function result
- The return value is currently unused and should always be 0.
Structs
This structure describes which streams a given AudioDeviceIOProc will use. It is
used in conjunction with kAudioDevicePropertyIOProcStreamUsage.
struct AudioHardwareIOProcStreamUsage {
void* mIOProc;
UInt32 mNumberStreams;
UInt32 mStreamIsOn[kVariableLengthArray];
} ;
Field Descriptions
- mIOProc
- The IOProc whose stream usage is being specified.
- mNumberStreams
- The number of streams being specified.
- mStreamIsOn
- An array of UInt32's whose length is specified by mNumberStreams. Each
element of the array corresponds to a stream. A value of 0 means the stream
is not to be enabled. Any other value means the stream is to be used.
An AudioObjectPropertyAddress collects the three parts that identify a specific
property together in a struct for easy transmission.
struct AudioObjectPropertyAddress {
AudioObjectPropertySelector mSelector;
AudioObjectPropertyScope mScope;
AudioObjectPropertyElement mElement;
} ;
Field Descriptions
- mSelector
- The AudioObjectPropertySelector for the property.
- mScope
- The AudioObjectPropertyScope for the property.
- mElement
- The AudioObjectPropertyElement for the property.
This structure allows a specific sample rate range to be associated with an
AudioStreamBasicDescription that specifies it's sample rate as
kAudioStreamAnyRate.
struct AudioStreamRangedDescription {
AudioStreamBasicDescription mFormat;
AudioValueRange mSampleRateRange;
} ;
Discussion
Note that this structure is only used to desicribe the the available formats
for a stream. It is not used for the current format.
Field Descriptions
- mFormat
- The AudioStreamBasicDescription that describes the format of the stream.
Note that the mSampleRate field of the structure will be the same as the
the values in mSampleRateRange when only a single sample rate is supported.
It will be kAudioStreamAnyRate when there is a range with more elements.
- mSampleRateRange
- The AudioValueRange that describes the minimum and maximum sample rate for
the stream. If the mSampleRate field of mFormat is kAudioStreamAnyRate the
format supports the range of sample rates described by this structure.
Otherwise, the minimum will be the same as the maximum which will be the
same as the mSampleRate field of mFormat.
Enumerations
Various constants related to AudioAggregateDevices.
enum
{
kAudioAggregateDeviceClassID = 'aagg',
kAudioDeviceTransportTypeAggregate = 'grup',
kAudioDeviceTransportTypeAutoAggregate = 'fgrp'
};
Discussion
Class Constants
Constants
- kAudioAggregateDeviceClassID
- The AudioClassID that identifies the AudioAggregateDevice class.
- kAudioDeviceTransportTypeAggregate
- The transport type ID (see kAudioDevicePropertyTransportType) for aggregate
devices.
- kAudioDeviceTransportTypeAutoAggregate
- The transport type ID (see kAudioDevicePropertyTransportType) for
automatically generated aggregate devices.
AudioObjectPropertySelector values that apply to all AudioAggregateDevices.
enum
{
kAudioAggregateDevicePropertyFullSubDeviceList = 'grup',
kAudioAggregateDevicePropertyActiveSubDeviceList = 'agrp',
kAudioAggregateDevicePropertyComposition = 'acom'
};
Discussion
AudioAggregateDevice is a subclass of AudioDevice.
Constants
- kAudioAggregateDevicePropertyFullSubDeviceList
- A CFArray of CFStrings that contain the UIDs of all the devices, active or
inactive, contained in the AudioAggregateDevice. The order of the items in
the array is significant and is used to determine the order of the streams
of the AudioAggregateDevice. The caller is responsible for releasing the
returned CFObject.
- kAudioAggregateDevicePropertyActiveSubDeviceList
- An array of AudioObjectIDs for all the active sub-devices in the aggregate
device.
- kAudioAggregateDevicePropertyComposition
- A CFDictionary that describes the composition of the AudioAggregateDevice.
The keys for this CFDicitionary are defined in the AudioAggregateDevice
Constants section.
AudioObjectPropertySelector values for AudioAggregateDevice properties that are
implemented by AudioControl objects.
enum
{
kAudioAggregateDevicePropertyMasterSubDevice = 'amst'
};
Discussion
These properties are also accessible by locating the AudioControl object
attached to the AudioAggregateDevice and using that object to access the
properties of the control.
Constants
- kAudioAggregateDevicePropertyMasterSubDevice
- A CFString that contains the UID for the AudioDevice that is currently
serving as the master time base of the aggregate device. This property is
also implemented by the AudioClockSourceControl on the master element of the
global scope of the AudioAggregateDevice.
The four char codes that identify the various standard subclasses of
AudioBooleanControl.
enum
{
kAudioMuteControlClassID = 'mute',
kAudioSoloControlClassID = 'solo',
kAudioJackControlClassID = 'jack',
kAudioLFEMuteControlClassID = 'subm',
kAudioISubOwnerControlClassID = 'atch'
};
Discussion
Subclass IDs
Constants
- kAudioMuteControlClassID
- An AudioBooleanControl where a true value means that mute is enabled making
that element inaudible.
- kAudioSoloControlClassID
- An AudioBooleanControl where a true value means that solo is enabled making
just that element audible and the other elements inaudible.
- kAudioJackControlClassID
- An AudioBooleanControl where a true value means something is plugged into
that element.
- kAudioLFEMuteControlClassID
- An AudioBooleanControl where true means that mute is enabled make that LFE
element inaudible. This control is for LFE channels that result from bass
management such as the iSub. Note that LFE channels that are represented as
normal audio channels (in other words, real data is being fed them in an
IOProc) will use kAudioVolumeControlClassID to manipulate mute.
- kAudioISubOwnerClassID
- An AudioBooleanControl where true means that the AudioDevice that
ultimately owns the control also owns any iSub attached to the CPU.
AudioObjectPropertySelector values that apply to all AudioBooleanControls.
enum
{
kAudioBooleanControlPropertyValue = 'bcvl'
};
Discussion
AudioBooleanControl is a subclass of AudioControl and has only the single scope,
kAudioObjectPropertyScopeGlobal, and only a master element.
Constants
- kAudioBooleanControlPropertyValue
- A UInt32 where 0 means false and 1 means true.
AudioObjectPropertySelector values that apply only to AudioClockSourceControls.
enum
{
kAudioClockSourceControlPropertyItemKind = 'clkk'
};
Discussion
These properties supplement the regular AudioSelectorControl Properties.
Constants
- kAudioClockSourceControlPropertyItemKind
- This property returns a UInt32 that identifies the kind of clock source
the item ID refers to. The qualifier contains the ID of the item. Values for
this property are defined in .
The AudioClassIDs that identify the various AudioControl base classes.
enum
{
kAudioControlClassID = 'actl',
kAudioLevelControlClassID = 'levl',
kAudioBooleanControlClassID = 'togl',
kAudioSelectorControlClassID = 'slct',
kAudioStereoPanControlClassID = 'span'
};
Discussion
Base Class IDs
Constants
- kAudioControlClassID
- The AudioClassID that identifies the AudioControl class.
- kAudioLevelControlClassID
- The AudioClassID that identifies the AudioLevelControl class which is a
subclass of AudioControl. AudioLevelControls manipulate gain/attenuation
stages in the hardware.
- kAudioBooleanControlClassID
- The AudioClassID that identifies the AudioBooleanControl class which is a
subclass of AudioControl. AudioBooleanControls manipulate on/off switches
in the hardware.
- kAudioSelectorControlClassID
- The AudioClassID that identifies the AudioSelectorControl class which is a
subclass of AudioControl. AudioSelectorControls manipulate controls that
have multiple, but discreet values.
- kAudioStereoPanControlClassID
- The AudioClassID that identifies the AudioStereoPanControl class which is
a subclass of AudioControl. AudioStereoPanControls manipulate the pot for
panning a mono signal between a left/right pair of outputs.
AudioObjectPropertySelector values that apply to all AudioControls.
enum
{
kAudioControlPropertyScope = 'cscp',
kAudioControlPropertyElement = 'celm',
kAudioControlPropertyVariant = 'cvar'
};
Discussion
AudioControl is a subclass of AudioObject and has only the single scope,
kAudioObjectPropertyScopeGlobal, and only a master element.
Constants
- kAudioControlPropertyScope
- The AudioObjectPropertyScope in the owning AudioObject that contains the
AudioControl.
- kAudioControlPropertyElement
- The AudioObjectPropertyElement in the owning AudioObject that contains the
AudioControl.
- kAudioControlPropertyVariant
- A UInt32 that identifies the specific variant of an AudioControl. This
allows the owning AudioObject to support controls that are of the same basic
class (that is, the values of kAudioObjectPropertyClass are the same) but
may control a part of the object for which the standard controls do not
control.
Various constants related to AudioDevices.
enum
{
kAudioDevicePropertyScopeInput = 'inpt',
kAudioDevicePropertyScopeOutput = 'outp',
kAudioDevicePropertyScopePlayThrough = 'ptru',
kAudioDeviceClassID = 'adev',
kAudioDeviceUnknown = kAudioObjectUnknown
};
Discussion
Class Constants
Constants
- kAudioDevicePropertyScopeInput
- The AudioObjectPropertyScope for properties that apply to the input signal
paths of the AudioDevice.
- kAudioDevicePropertyScopeOutput
- The AudioObjectPropertyScope for properties that apply to the output signal
paths of the AudioDevice.
- kAudioDevicePropertyScopePlayThrough
- The AudioObjectPropertyScope for properties that apply to the play through
signal paths of the AudioDevice.
- kAudioDeviceClassID
- The AudioClassID that identifies the AudioDevice class.
- kAudioDeviceUnknown
- The AudioObjectID for a nonexistent AudioObject.
AudioObjectPropertySelector values that apply to AudioDevice objects.
enum
{
kAudioDevicePropertyPlugIn = 'plug',
kAudioDevicePropertyConfigurationApplication = 'capp',
kAudioDevicePropertyDeviceUID = 'uid ',
kAudioDevicePropertyModelUID = 'muid',
kAudioDevicePropertyTransportType = 'tran',
kAudioDevicePropertyRelatedDevices = 'akin',
kAudioDevicePropertyClockDomain = 'clkd',
kAudioDevicePropertyDeviceIsAlive = 'livn',
kAudioDevicePropertyDeviceHasChanged = 'diff',
kAudioDevicePropertyDeviceIsRunning = 'goin',
kAudioDevicePropertyDeviceIsRunningSomewhere = 'gone',
kAudioDevicePropertyDeviceCanBeDefaultDevice = 'dflt',
kAudioDevicePropertyDeviceCanBeDefaultSystemDevice = 'sflt',
kAudioDeviceProcessorOverload = 'over',
kAudioDevicePropertyHogMode = 'oink',
kAudioDevicePropertyLatency = 'ltnc',
kAudioDevicePropertyBufferFrameSize = 'fsiz',
kAudioDevicePropertyBufferFrameSizeRange = 'fsz#',
kAudioDevicePropertyUsesVariableBufferFrameSizes = 'vfsz',
kAudioDevicePropertyStreams = 'stm#',
kAudioDevicePropertySafetyOffset = 'saft',
kAudioDevicePropertyIOCycleUsage = 'ncyc',
kAudioDevicePropertyStreamConfiguration = 'slay',
kAudioDevicePropertyIOProcStreamUsage = 'suse',
kAudioDevicePropertyPreferredChannelsForStereo = 'dch2',
kAudioDevicePropertyPreferredChannelLayout = 'srnd',
kAudioDevicePropertyNominalSampleRate = 'nsrt',
kAudioDevicePropertyAvailableNominalSampleRates = 'nsr#',
kAudioDevicePropertyActualSampleRate = 'asrt'
};
Discussion
AudioDevices have four scopes: kAudioDevicePropertyScopeGlobal,
kAudioDevicePropertyScopeInput, kAudioDevicePropertyScopeOutput, and
kAudioDevicePropertyScopePlayThrough. They have a master element and an element
for each channel in each stream numbered according to the starting channel
number of each stream.
Constants
- kAudioDevicePropertyPlugIn
- An OSStatus that contains any error codes generated by loading the IOAudio
driver plug-in for the AudioDevice or kAudioHardwareNoError if the plug-in
loaded successfully. This property only exists for IOAudio-based
AudioDevices whose driver has specified a plug-in to load.
- kAudioDevicePropertyConfigurationApplication
- A CFString that contains the bundle ID for an application that provides a
GUI for configuring the AudioDevice. By default, the value of this property
is the bundle ID for Audio MIDI Setup. The caller is responsible for
releasing the returned CFObject.
- kAudioDevicePropertyDeviceUID
- A CFString that contains a persistent identifier for the AudioDevice. An
AudioDevice's UID is persistent across boots. The content of the UID string
is a black box and may contain information that is unique to a particular
instance of an AudioDevice's hardware or unique to the CPU. Therefore they
are not suitable for passing between CPUs or for identifying similar models
of hardware.
- kAudioDevicePropertyModelUID
- A CFString that contains a persistent identifier for the model of an
AudioDevice. The identifier is unique such that the identifier from two
AudioDevices are equal if and only if the two AudioDevices are the exact
same model from the same manufacturer. Further, the identifier has to be the
same no matter on what machine the AudioDevice appears.
- kAudioDevicePropertyTransportType
- A UInt32 whose value indicates how the AudioDevice is connected to the CPU.
Constants for some of the values for this property can be found in
.
- kAudioDevicePropertyRelatedDevices
- An array of AudioDeviceIDs for devices related to the AudioDevice. For
IOAudio-based devices, a AudioDevices are related if they share the same
IOAudioDevice object.
- kAudioDevicePropertyClockDomain
- A UInt32 whose value indicates the clock domain to which this AudioDevice
belongs. AudioDevices that have the same value for this property are able to
be synchronized in hardware. However, a value of 0 indicates that the clock
domain for the device is unspecified and should be assumed to be separate
from every other device's clock domain, even if they have the value of 0 as
their clock domain as well.
- kAudioDevicePropertyDeviceIsAlive
- A UInt32 where a value of 1 means the device is ready and available and 0
means the device is usable and will most likely go away shortly.
- kAudioDevicePropertyDeviceHasChanged
- The type of this property is a UInt32, but it's value has no meaning. This
property exists so that clients can listen to it and be told when the
configuration of the AudioDevice has changed in ways that cannot otherwise
be conveyed through other notifications. In response to this notification,
clients should re-evaluate everything they need to know about the device,
particularly the layout and values of the controls.
- kAudioDevicePropertyDeviceIsRunning
- A UInt32 where a value of 0 means the AudioDevice is not performing IO and
a value of 1 means that it is. Note that the device can be running even if
there are no active IOProcs such as by calling AudioDeviceStart() and
passing a NULL IOProc. Note that the notification for this property is
usually sent from the AudioDevice's IO thread.
- kAudioDevicePropertyDeviceIsRunningSomewhere
- A UInt32 where 1 means that the AudioDevice is running in at least one
process on the system and 0 means that it isn't running at all.
- kAudioDevicePropertyDeviceCanBeDefaultDevice
- A UInt32 where 1 means that the AudioDevice is a possible selection for
kAudioHardwarePropertyDefaultInputDevice or
kAudioHardwarePropertyDefaultOutputDevice depending on the scope.
- kAudioDevicePropertyDeviceCanBeDefaultSystemDevice
- A UInt32 where 1 means that the AudioDevice is a possible selection for
kAudioHardwarePropertyDefaultSystemOutputDevice.
- kAudioDeviceProcessorOverload
- A UInt32 where the value has no meaning. This property exists so that
clients can be notified when the AudioDevice detects that an IO cycle has
run past it's deadline. Note that the notification for this property is
usually sent from the AudioDevice's IO thread.
- kAudioDevicePropertyHogMode
- A pid_t indicating the process that currently owns exclusive access to the
AudioDevice or a value of -1 indicating that the device is currently
available to all processes. If the AudioDevice is in a non-mixable mode,
the HAL will automatically take hog mode on behalf of the first process to
start an IOProc.
- kAudioDevicePropertyLatency
- A UInt32 containing the number of frames of latency in the AudioDevice. Note
that input and output latency may differ. Further, the AudioDevice's
AudioStreams may have additional latency so they should be queried as well.
If both the device and the stream say they have latency, then the total
latency for the stream is the device latency summed with the stream latency.
- kAudioDevicePropertyBufferFrameSize
- A UInt32 whose value indicates the number of frames in the IO buffers.
- kAudioDevicePropertyBufferFrameSizeRange
- An AudioValueRange indicating the minimum and maximum values, inclusive, for
kAudioDevicePropertyBufferFrameSize.
- kAudioDevicePropertyUsesVariableBufferFrameSizes
- A UInt32 that, if implemented by a device, indicates that the sizes of the
buffers passed to an IOProc will vary by a small amount. The value of this
property will indicate the largest buffer that will be passed and
kAudioDevicePropertyBufferFrameSize will indicate the smallest buffer that
will get passed to the IOProc. The usage of this property is narrowed to
only allow for devices whose buffer sizes vary by small amounts greater than
kAudioDevicePropertyBufferFrameSize. It is not intended to be a license for
devices to be able to send buffers however they please. Rather, it is
intended to allow for hardware whose natural rhythms lead to this necessity.
- kAudioDevicePropertyStreams
- An array of AudioStreamIDs that represent the AudioStreams of the
AudioDevice. Note that if a notification is received for this property, any
cached AudioStreamIDs for the device become invalid and need to be
re-fetched.
- kAudioDevicePropertySafetyOffset
- A UInt32 whose value indicates the number for frames in ahead (for output)
or behind (for input the current hardware position that is safe to do IO.
- kAudioDevicePropertyIOCycleUsage
- A Float32 whose range is from 0 to 1. This value indicates how much of the
client portion of the IO cycle the process will use. The client portion of
the IO cycle is the portion of the cycle in which the device calls the
IOProcs so this property does not the apply to the duration of the entire
cycle.
- kAudioDevicePropertyStreamConfiguration
- This property returns the stream configuration of the device in an
AudioBufferList (with the buffer pointers set to NULL) which describes the
list of streams and the number of channels in each stream. This corresponds
to what will be passed into the IOProc.
- kAudioDevicePropertyIOProcStreamUsage
- An AudioHardwareIOProcStreamUsage structure which details the stream usage
of a given IO proc. If a stream is marked as not being used, the given
IOProc will see a corresponding NULL buffer pointer in the AudioBufferList
passed to it's IO proc. Note that the number of streams detailed in the
AudioHardwareIOProcStreamUsage must include all the streams of that
direction on the device. Also, when getting the value of the property, one
must fill out the mIOProc field of the AudioHardwareIOProcStreamUsage with
the address of the of the IOProc whose stream usage is to be retrieved.
- kAudioDevicePropertyPreferredChannelsForStereo
- An array of two UInt32s, the first for the left channel, the second for the
right channel, that indicate the channel numbers to use for stereo IO on the
device. The value of this property can be different for input and output and
there are no restrictions on the channel numbers that can be used.
- kAudioDevicePropertyPreferredChannelLayout
- An AudioChannelLayout that indicates how each channel of the AudioDevice
should be used.
- kAudioDevicePropertyNominalSampleRate
- A Float64 that indicates the current nominal sample rate of the AudioDevice.
- kAudioDevicePropertyAvailableNominalSampleRates
- An array of AudioValueRange structs that indicates the valid ranges for the
nominal sample rate of the AudioDevice.
- kAudioDevicePropertyActualSampleRate
- A Float64 that indicates the current actual sample rate of the AudioDevice
as measured by it's time stamps.
AudioObjectPropertySelector values for AudioDevice properties that are
implemented by AudioControl objects.
enum
{
kAudioDevicePropertyJackIsConnected = 'jack',
kAudioDevicePropertyVolumeScalar = 'volm',
kAudioDevicePropertyVolumeDecibels = 'vold',
kAudioDevicePropertyVolumeRangeDecibels = 'vdb#',
kAudioDevicePropertyVolumeScalarToDecibels = 'v2db',
kAudioDevicePropertyVolumeDecibelsToScalar = 'db2v',
kAudioDevicePropertyStereoPan = 'span',
kAudioDevicePropertyStereoPanChannels = 'spn#',
kAudioDevicePropertyMute = 'mute',
kAudioDevicePropertySolo = 'solo',
kAudioDevicePropertyDataSource = 'ssrc',
kAudioDevicePropertyDataSources = 'ssc#',
kAudioDevicePropertyDataSourceNameForIDCFString = 'lscn',
kAudioDevicePropertyClockSource = 'csrc',
kAudioDevicePropertyClockSources = 'csc#',
kAudioDevicePropertyClockSourceNameForIDCFString = 'lcsn',
kAudioDevicePropertyClockSourceKindForID = 'csck',
kAudioDevicePropertyPlayThru = 'thru',
kAudioDevicePropertyPlayThruSolo = 'thrs',
kAudioDevicePropertyPlayThruVolumeScalar = 'mvsc',
kAudioDevicePropertyPlayThruVolumeDecibels = 'mvdb',
kAudioDevicePropertyPlayThruVolumeRangeDecibels = 'mvd#',
kAudioDevicePropertyPlayThruVolumeScalarToDecibels = 'mv2d',
kAudioDevicePropertyPlayThruVolumeDecibelsToScalar = 'mv2s',
kAudioDevicePropertyPlayThruStereoPan = 'mspn',
kAudioDevicePropertyPlayThruStereoPanChannels = 'msp#',
kAudioDevicePropertyPlayThruDestination = 'mdds',
kAudioDevicePropertyPlayThruDestinations = 'mdd#',
kAudioDevicePropertyPlayThruDestinationNameForIDCFString = 'mddc',
kAudioDevicePropertyChannelNominalLineLevel = 'nlvl',
kAudioDevicePropertyChannelNominalLineLevels = 'nlv#',
kAudioDevicePropertyChannelNominalLineLevelNameForIDCFString = 'lcnl',
kAudioDevicePropertyDriverShouldOwniSub = 'isub',
kAudioDevicePropertySubVolumeScalar = 'svlm',
kAudioDevicePropertySubVolumeDecibels = 'svld',
kAudioDevicePropertySubVolumeRangeDecibels = 'svd#',
kAudioDevicePropertySubVolumeScalarToDecibels = 'sv2d',
kAudioDevicePropertySubVolumeDecibelsToScalar = 'sd2v',
kAudioDevicePropertySubMute = 'smut'
};
Discussion
These properties are also accessible by locating the AudioControl object
attached to the AudioDevice and using that object to access the properties of
the control.
Constants
- kAudioDevicePropertyJackIsConnected
- A UInt32 where a value of 0 means that there isn't anything plugged into the
jack associated withe given element and scope. This property is implemented
by an AudioJackControl, a subclass of AudioBooleanControl.
- kAudioDevicePropertyVolumeScalar
- A Float32 that represents the value of the volume control. The range is
between 0.0 and 1.0 (inclusive). This property is implemented by an
AudioControl object that is a subclass of AudioVolumeControl.
- kAudioDevicePropertyVolumeDecibels
- A Float32 that represents the value of the volume control in dB. This
property is implemented by an AudioControl object that is a subclass of
AudioVolumeControl.
- kAudioDevicePropertyVolumeRangeDecibels
- An AudioValueRange that contains the minimum and maximum dB values the
control can have. This property is implemented by an AudioControl object
that is a subclass of AudioVolumeControl.
- kAudioDevicePropertyVolumeScalarToDecibels
- A Float32 that on input contains a scalar volume value for the and on exit
contains the equivalent dB value. This property is implemented by an
AudioControl object that is a subclass of AudioVolumeControl.
- kAudioDevicePropertyVolumeDecibelsToScalar
- A Float32 that on input contains a dB volume value for the and on exit
contains the equivalent scalar value. This property is implemented by an
AudioControl object that is a subclass of AudioVolumeControl.
- kAudioDevicePropertyStereoPan
- A Float32 where 0.0 is full left, 1.0 is full right, and 0.5 is center. This
property is implemented by an AudioControl object that is a subclass of
AudioStereoPanControl.
- kAudioDevicePropertyStereoPanChannels
- An array of two UInt32s that indicate which elements of the owning object
the signal is being panned between. This property is implemented by an
AudioControl object that is a subclass of AudioStereoPanControl.
- kAudioDevicePropertyMute
- A UInt32 where a value of 1 means that mute is enabled making that element
inaudible. The property is implemented by an AudioControl object that is a
subclass of AudioMuteControl.
- kAudioDevicePropertySolo
- A UInt32 where a value of 1 means that just that element is audible and the
other elements are inaudible. The property is implemented by an AudioControl
object that is a subclass of AudioSoloControl.
- kAudioDevicePropertyDataSource
- A UInt32 whose value is the item ID for the currently selected data source.
This property is implemented by an AudioControl object that is a subclass of
AudioDataSourceControl.
- kAudioDevicePropertyDataSources
- An array of UInt32s that are represent all the IDs of all the data sources
currently available. This property is implemented by an AudioControl object
that is a subclass of AudioDataSourceControl.
- kAudioDevicePropertyDataSourceNameForIDCFString
- This property translates the given data source item ID into a human readable
name using an AudioValueTranslation structure. The input data is the UInt32
containing the item ID to translated and the output data is a CFString. The
caller is responsible for releasing the returned CFObject. This property is
implemented by an AudioControl object that is a subclass of
AudioDataSourceControl.
- kAudioDevicePropertyClockSource
- A UInt32 whose value is the item ID for the currently selected clock source.
This property is implemented by an AudioControl object that is a subclass of
AudioClockControl.
- kAudioDevicePropertyClockSources
- An array of UInt32s that are represent all the IDs of all the clock sources
currently available. This property is implemented by an AudioControl object
that is a subclass of AudioClockControl.
- kAudioDevicePropertyClockSourceNameForIDCFString
- This property translates the given clock source item ID into a human
readable name using an AudioValueTranslation structure. The input data is
the UInt32 containing the item ID to translated and the output data is a
CFString. The caller is responsible for releasing the returned CFObject.
This property is implemented by an AudioControl object that is a subclass of
AudioClockControl.
- kAudioDevicePropertyClockSourceKindForID
- This property returns a UInt32 that identifies the kind of clock source
the item ID refers to using an AudioValueTranslation structure. The input
data is the UInt32 containing the item ID and the output data is the UInt32.
Values for this property are defined in .
- kAudioDevicePropertyPlayThru
- A UInt32 where a value of 0 means that play through is off and a value of 1
means that it is on. This property is implemented by an AudioControl object
that is a subclass of AudioMuteControl. Further, the control that implements
this property is only available through
kAudioDevicePropertyScopePlayThrough.
- kAudioDevicePropertyPlayThruSolo
- A UInt32 where a value of 1 means that just that play through element is
audible and the other elements are inaudible. The property is implemented by
an AudioControl object that is a subclass of AudioSoloControl. Further, the
control that implements this property is only available through
kAudioDevicePropertyScopePlayThrough.
- kAudioDevicePropertyPlayThruVolumeScalar
- A Float32 that represents the value of the volume control. The range is
between 0.0 and 1.0 (inclusive). This property is implemented by an
AudioControl object that is a subclass of AudioVolumeControl.Further, the
control that implements this property is only available through
kAudioDevicePropertyScopePlayThrough.
- kAudioDevicePropertyPlayThruVolumeDecibels
- A Float32 that represents the value of the volume control in dB. This
property is implemented by an AudioControl object that is a subclass of
AudioVolumeControl. Further, the control that implements this property is
only available through kAudioDevicePropertyScopePlayThrough.
- kAudioDevicePropertyPlayThruVolumeRangeDecibels
- An AudioValueRange that contains the minimum and maximum dB values the
control can have. This property is implemented by an AudioControl object
that is a subclass of AudioVolumeControl. Further, the control that
implements this property is only available through
kAudioDevicePropertyScopePlayThrough.
- kAudioDevicePropertyPlayThruVolumeScalarToDecibels
- A Float32 that on input contains a scalar volume value for the and on exit
contains the equivalent dB value. This property is implemented by an
AudioControl object that is a subclass of AudioVolumeControl. Further, the
control that implements this property is only available through
kAudioDevicePropertyScopePlayThrough.
- kAudioDevicePropertyPlayThruVolumeDecibelsToScalar
- A Float32 that on input contains a dB volume value for the and on exit
contains the equivalent scalar value. This property is implemented by an
AudioControl object that is a subclass of AudioVolumeControl. Further, the
control that implements this property is only available through
kAudioDevicePropertyScopePlayThrough.
- kAudioDevicePropertyPlayThruStereoPan
- A Float32 where 0.0 is full left, 1.0 is full right, and 0.5 is center. This
property is implemented by an AudioControl object that is a subclass of
AudioStereoPanControl. Further, the control that implements this property is
only available through kAudioDevicePropertyScopePlayThrough.
- kAudioDevicePropertyPlayThruStereoPanChannels
- An array of two UInt32s that indicate which elements of the owning object
the signal is being panned between. This property is implemented by an
AudioControl object that is a subclass of AudioStereoPanControl. Further,
the control that implements this property is only available through
kAudioDevicePropertyScopePlayThrough.
- kAudioDevicePropertyPlayThruDestination
- A UInt32 whose value is the item ID for the currently selected play through
data destination. This property is implemented by an AudioControl object
that is a subclass of AudioDataDestinationControl. Further, the control that
implements this property is only available through
kAudioDevicePropertyScopePlayThrough.
- kAudioDevicePropertyPlayThruDestinations
- An array of UInt32s that are represent all the IDs of all the play through
data destinations currently available. This property is implemented by an
AudioControl object that is a subclass of AudioDataDestinationControl.
Further, the control that implements this property is only available through
kAudioDevicePropertyScopePlayThrough.
- kAudioDevicePropertyPlayThruDestinationNameForIDCFString
- This property translates the given play through data destination item ID
into a human readable name using an AudioValueTranslation structure. The
input data is the UInt32 containing the item ID to translated and the output
data is a CFString. The caller is responsible for releasing the returned
CFObject. This property is implemented by an AudioControl object that is a
subclass of AudioDataDestinationControl. Further, the control that
implements this property is only available through
kAudioDevicePropertyScopePlayThrough.
- kAudioDevicePropertyChannelNominalLineLevel
- A UInt32 whose value is the item ID for the currently selected nominal line
level. This property is implemented by an AudioControl object that is a
subclass of AudioLineLevelControl.
- kAudioDevicePropertyChannelNominalLineLevels
- An array of UInt32s that represent all the IDs of all the nominal line
levels currently available. This property is implemented by an AudioControl
object that is a subclass of AudioLineLevelControl.
- kAudioDevicePropertyChannelNominalLineLevelNameForIDCFString
- This property translates the given nominal line level item ID into a human
readable name using an AudioValueTranslation structure. The input data is
the UInt32 containing the item ID to be translated and the output data is a
CFString. The caller is responsible for releasing the returned CFObject.
This property is implemented by an AudioCOntrol object that is a subclass of
AudioLineLevelControl.
- kAudioDevicePropertyDriverShouldOwniSub
- A UInt32 where a value of 0 means that the AudioDevice should not claim
ownership of any attached iSub and a value of 1 means that it should. Note
that this property is only available for built-in devices and for USB Audio
devices that use the standard class compliant driver. This property is
implemented by an AudioControl object that is a subclass of
AudioISubOwnerControl.
- kAudioDevicePropertySubVolumeScalar
- A Float32 that represents the value of the LFE volume control. The range is
between 0.0 and 1.0 (inclusive). This property is implemented by an
AudioControl object that is a subclass of AudioLFEVolumeControl.
- kAudioDevicePropertySubVolumeDecibels
- A Float32 that represents the value of the LFE volume control in dB. This
property is implemented by an AudioControl object that is a subclass of
AudioLFE VolumeControl.
- kAudioDevicePropertySubVolumeRangeDecibels
- An AudioValueRange that contains the minimum and maximum dB values the
control can have. This property is implemented by an AudioControl object
that is a subclass of AudioLFEVolumeControl.
- kAudioDevicePropertySubVolumeScalarToDecibels
- A Float32 that on input contains a scalar volume value for the and on exit
contains the equivalent dB value. This property is implemented by an
AudioControl object that is a subclass of AudioLFEVolumeControl.
- kAudioDevicePropertySubVolumeDecibelsToScalar
- A Float32 that on input contains a dB volume value for the and on exit
contains the equivalent scalar value. This property is implemented by an
AudioControl object that is a subclass of AudioLFEVolumeControl.
- kAudioDevicePropertySubMute
- A UInt32 where a value of 1 means that mute is enabled making the LFE on
that element inaudible. The property is implemented by an AudioControl
object that is a subclass of AudioLFEMuteControl.
AudioObjectPropertySelector values whose functionality is better provided by
other selectors.
enum
{
kAudioDevicePropertyDeviceName = 'name',
kAudioDevicePropertyDeviceNameCFString = kAudioObjectPropertyName,
kAudioDevicePropertyDeviceManufacturer = 'makr',
kAudioDevicePropertyDeviceManufacturerCFString = kAudioObjectPropertyManufacturer,
kAudioDevicePropertyRegisterBufferList = 'rbuf',
kAudioDevicePropertyBufferSize = 'bsiz',
kAudioDevicePropertyBufferSizeRange = 'bsz#',
kAudioDevicePropertyChannelName = 'chnm',
kAudioDevicePropertyChannelNameCFString = kAudioObjectPropertyElementName,
kAudioDevicePropertyChannelCategoryName = 'ccnm',
kAudioDevicePropertyChannelCategoryNameCFString = kAudioObjectPropertyElementCategoryName,
kAudioDevicePropertyChannelNumberName = 'cnnm',
kAudioDevicePropertyChannelNumberNameCFString = kAudioObjectPropertyElementNumberName,
kAudioDevicePropertySupportsMixing = 'mix?',
kAudioDevicePropertyStreamFormat = 'sfmt',
kAudioDevicePropertyStreamFormats = 'sfm#',
kAudioDevicePropertyStreamFormatSupported = 'sfm?',
kAudioDevicePropertyStreamFormatMatch = 'sfmm',
kAudioDevicePropertyDataSourceNameForID = 'sscn',
kAudioDevicePropertyClockSourceNameForID = 'cscn',
kAudioDevicePropertyPlayThruDestinationNameForID = 'mddn',
kAudioDevicePropertyChannelNominalLineLevelNameForID = 'cnlv'
};
Discussion
These selectors are still provided for backward compatibility. The description
of the property will indicate in parentheses the better selectors to use and
why.
Constants
- kAudioDevicePropertyDeviceName
- A C-string that contains the human readable name of the AudioDevice.
(kAudioObjectPropertyName: CFStrings are better for localization.)
- kAudioDevicePropertyDeviceNameCFString
- A CFStringRef that contains the human readable name of the AudioDevice. The
caller is responsible for releasing the returned CFObject.
(kAudioObjectPropertyName: This is just another name for the inherited
selector.)
- kAudioDevicePropertyDeviceManufacturer
- A C-string that contains the human readable name of the manufacturer of the
AudioDevice.
(kAudioObjectPropertyManufacturer: CFStrings are better for localization.)
- kAudioDevicePropertyDeviceManufacturerCFString
- A CFString that contains the human readable name of the manufacturer of the
AudioDevice. The caller is responsible for releasing the returned CFObject.
(kAudioObjectPropertyManufacturer: This is just another name for the
inherited selector.)
- kAudioDevicePropertyRegisterBufferList
- This property allows clients to register a fully populated AudioBufferList
that matches the topology described by
kAudioDevicePropertyStreamConfiguration for doing input using
AudioDeviceRead(). The AudioBufferList will be registered with the call the
AudioDeviceSetProperty() and will be unregistered with the call to
AudioDeviceGetProperty(). If this property isn't implemented by the
AudioDevice, it implies that the AudioDevice also doesn't support
AudioDeviceRead().
(Aggregate devices make AudioDeviceRead() obsolete for the most part.)
- kAudioDevicePropertyBufferSize
- A UInt32 containing the size in bytes of the IO buffer for the AudioStream
containing the element.
(kAudioDevicePropertyBufferFrameSize: with multiple AudioStreams and the
requirement that all streams' buffers represent the same amount of time, it
doesn't make sense to set the buffer size in bytes since it will be
different for each stream.)
- kAudioDevicePropertyBufferSizeRange
- An AudioValueRange specifying the minimum and maximum bytes size for the
IO buffer for the AudioStream containing the given element.
(kAudioDevicePropertyBufferFrameSizeRange: see
kAudioDevicePropertyBufferSize.)
- kAudioDevicePropertyChannelName
- A CFString that contains a human readable name for the given element in the
given scope. The caller is responsible for releasing the returned CFObject.
(kAudioObjectPropertyElementName: CFStrings are better for
localization.)
- kAudioDevicePropertyChannelNameCFString
- A CFString that contains a human readable name for the given element in the
given scope. The caller is responsible for releasing the returned CFObject.
(kAudioObjectPropertyElementName: This is just another name for the
inherited selector.)
- kAudioDevicePropertyChannelCategoryName
- A CFString that contains a human readable name for the category of the given
element in the given scope. The caller is responsible for releasing the
returned CFObject.
(kAudioObjectPropertyElementCategoryName: CFStrings are better for
localization.)
- kAudioDevicePropertyChannelCategoryNameCFString
- A CFString that contains a human readable name for the category of the given
element in the given scope. The caller is responsible for releasing the
returned CFObject.
(kAudioObjectPropertyElementCategoryName: This is just another name for the
inherited selector.)
- kAudioDevicePropertyChannelNumberName
- A CFString that contains a human readable name for the number of the given
element in the given scope. The caller is responsible for releasing the
returned CFObject.
(kAudioObjectPropertyElementNumberName: CFStrings are better for
localization.)
- kAudioDevicePropertyChannelNumberNameCFString
- A CFString that contains a human readable name for the number of the given
element in the given scope. The caller is responsible for releasing the
returned CFObject.
(kAudioObjectPropertyElementNumberName: This is just another name for the
inherited selector.)
- kAudioDevicePropertySupportsMixing
- A UInt32 where a value of 1 means the AudioDevice supports mixing and a
value of 0 means that it doesn't and that all IO is performed in each
AudioStream's current physical format. This property is changed indirectly
by changing to a format that doesn't support mixing, such as AC-3. (The HAL
now vends it's format information with a flag indicating the mixability in
order to better support devices with streams that are both mixable and non-
mixable.)
- kAudioDevicePropertyStreamFormat
- An AudioStreamBasicDescription that describes the current data format for
the AudioStream that contains the channel referred to by the element number.
(kAudioStreamPropertyVirtualFormat: Managing format information is
inherently an operation on AudioStreams, rather than AudioDevices. It is
confusing for the client to work with formats at the AudioDevice level and
has been shown to lead to programming mistakes by clients when working with
devices that have multiple streams.)
- kAudioDevicePropertyStreamFormats
- An array of AudioStreamBasicDescriptions that describe the available data
formats for the AudioStream that contains the channel referred to by the
element number.
(kAudioStreamPropertyAvailableVirtualFormats: Managing format information is
inherently an operation on AudioStreams, rather than AudioDevices. It is
confusing for the client to work with formats at the AudioDevice level and
has been shown to lead to programming mistakes by clients when working with
devices that have multiple streams.)
- kAudioDevicePropertyStreamFormatSupported
- An AudioStreamBasicDescription is passed in to query whether or not the
format is supported. A kAudioDeviceUnsupportedFormatError will be returned
if the format is not supported and kAudioHardwareNoError will be returned if
it is supported. AudioStreamBasicDescription fields set to 0 will be ignored
in the query, but otherwise values must match exactly.
(kAudioStreamPropertyAvailableVirtualFormats: The proper and most robust way
to find a format that the AudioStream can support is to get the list of
available formats and look through that rather than using this property.)
- kAudioDevicePropertyStreamFormatMatch
- An AudioStreamBasicDescription is passed in and the AudioStream will modify
it to describe the best match, in the AudioDevice's opinion, for the given
format.
(kAudioStreamPropertyAvailableVirtualFormats: The proper and most robust way
to find a format that the AudioStream can support is to get the list of
available formats and look through that rather than using this property.)
- kAudioDevicePropertyDataSourceNameForID
- This property translates the given data source item ID into a human readable
name using an AudioValueTranslation structure. The input data is the UInt32
holding the item ID to be translated and the output data is a buffer to hold
the name as a null terminated c-string.
(kAudioDevicePropertyDataSourceNameForIDCFString: CFStrings are better for
localization.)
- kAudioDevicePropertyClockSourceNameForID
- This property translates the given clock source item ID into a human
readable name using an AudioValueTranslation structure. The input data is
the UInt32 holding the item ID to be translated and the output data is a
buffer to hold the name as a null terminated c-string.
(kAudioDevicePropertyClockSourceNameForIDCFString: CFStrings are better for
localization.)
- kAudioDevicePropertyPlayThruDestinationNameForID
- This property translates the given play through destination item ID into a
human readable name using an AudioValueTranslation structure. The input data
is the UInt32 holding the item ID to be translated and the output data is a
buffer to hold the name as a null terminated c-string.
(kAudioDevicePropertyPlayThruDestinationNameForIDCFString: CFStrings are
better for localization.)
- kAudioDevicePropertyChannelNominalLineLevelNameForID
- This property translates the given nominal line level item ID into a human
readable name using an AudioValueTranslation structure. The input data is
the UInt32 holding the item ID to be translated and the output data is a
buffer to hold the name as a null terminated c-string.
(kAudioDevicePropertyChannelNominalLineLevelNameForIDCFString: CFStrings are
better for localization.)
The four char codes that identify the various standard subclasses of
AudioLevelControl.
enum
{
kAudioVolumeControlClassID = 'vlme',
kAudioLFEVolumeControlClassID = 'subv',
kAudioBootChimeVolumeControlClassID = 'pram'
};
Discussion
Subclass IDs
Constants
- kAudioVolumeControlClassID
- An AudioLevelControl for a general gain/attenuation stage.
- kAudioLFEVolumeControlClassID
- An AudioLevelControl for an LFE channel that results from bass management
such as the iSub. Note that LFE channels that are represented as normal
audio channels (in other words, real data is being fed them in an IOProc)
will use kAudioVolumeControlClassID to manipulate the level.
- kAudioBootChimeVolumeControlClassID
- An AudioLevelControl for the boot chime of the CPU.
AudioObjectPropertySelector values that apply to all AudioLevelControls.
enum
{
kAudioLevelControlPropertyScalarValue = 'lcsv',
kAudioLevelControlPropertyDecibelValue = 'lcdv',
kAudioLevelControlPropertyDecibelRange = 'lcdr',
kAudioLevelControlPropertyConvertScalarToDecibels = 'lcsd',
kAudioLevelControlPropertyConvertDecibelsToScalar = 'lcds'
};
Discussion
AudioLevelControl is a subclass of AudioControl and has only the single scope,
kAudioObjectPropertyScopeGlobal, and only a master element.
Constants
- kAudioLevelControlPropertyScalarValue
- A Float32 that represents the value of the boot chime volume control. The
range is between 0.0 and 1.0 (inclusive).
- kAudioLevelControlPropertyDecibelValue
- A Float32 that represents the value of the boot chime volume control in dB.
- kAudioLevelControlPropertyDecibelRange
- An AudioValueRange that contains the minimum and maximum dB values the
boot chime control can have.
- kAudioLevelControlPropertyConvertScalarToDecibels
- A Float32 that on input contains a scalar volume value for the boot chime
and on exit contains the equivalent dB value.
- kAudioLevelControlPropertyConvertDecibelsToScalar
- A Float32 that on input contains a dB volume value for the boot chime and on
exit contains the equivalent scalar value.
Various constants related to AudioObjects.
enum
{
kAudioObjectPropertyScopeGlobal = 'glob',
kAudioObjectPropertyElementMaster = 0UL,
kAudioObjectClassID = 'aobj',
kAudioObjectClassIDWildcard = '****',
kAudioObjectUnknown = 0UL
};
Discussion
Class Constants
Constants
- kAudioObjectPropertyScopeGlobal
- The AudioObjectPropertyScope for properties that apply to the object as a
whole. All AudioObjects have a global scope and for some it is their only
scope.
- kAudioObjectPropertyElementMaster
- The AudioObjectPropertyElement value for properties that apply to the master
element or to the entire scope.
- kAudioObjectClassID
- The AudioClassID that identifies the AudioObject class.
- kAudioObjectClassIDWildcard
- The wildcard value for AudioClassIDs.
- kAudioObjectUnknown
- The AudioObjectID for a non-existant AudioObject.
AudioObjectPropertySelector values that apply to all AudioObjects.
enum
{
kAudioObjectPropertyClass = 'clas',
kAudioObjectPropertyOwner = 'stdv',
kAudioObjectPropertyCreator = 'oplg',
kAudioObjectPropertyName = 'lnam',
kAudioObjectPropertyManufacturer = 'lmak',
kAudioObjectPropertyElementName = 'lchn',
kAudioObjectPropertyElementCategoryName = 'lccn',
kAudioObjectPropertyElementNumberName = 'lcnn',
kAudioObjectPropertyOwnedObjects = 'ownd',
kAudioObjectPropertyListenerAdded = 'lisa',
kAudioObjectPropertyListenerRemoved = 'lisr'
};
Discussion
Property Selectors
Constants
- kAudioObjectPropertyClass
- An AudioClassID that identifies the class of the AudioObject.
- kAudioObjectPropertyOwner
- An AudioObjectID that identifies the the AudioObject that owns the given
AudioObject. Note that all AudioObjects are owned by some other AudioObject.
The only exception is the AudioSystemObject, for which the value of this
property is kAudioObjectUnknown.
- kAudioObjectPropertyCreator
- A CFString that contains the bundle ID of the plug-in that instantiated the
object.
- kAudioObjectPropertyObjectName
- A CFString that contains the human readable name of the object. The caller
is responsible for releasing the returned CFObject.
- kAudioObjectPropertyManufacturer
- A CFString that contains the human readable name of the manufacturer of the
hardware the AudioObject is a part of. The caller is responsible for
releasing the returned CFObject.
- kAudioObjectPropertyElementName
- A CFString that contains a human readable name for the given element in the
given scope. The caller is responsible for releasing the returned CFObject.
- kAudioObjectPropertyElementCategoryName
- A CFString that contains a human readable name for the category of the given
element in the given scope. The caller is responsible for releasing the
returned CFObject.
- kAudioObjectPropertyElementNumberName
- A CFString that contains a human readable name for the number of the given
element in the given scope. The caller is responsible for releasing the
returned CFObject.
- kAudioObjectPropertyOwnedObjects
- An array of AudioObjectIDs that represent all the AudioObjects owned by the
given object. The qualifier is an array of AudioClassIDs. If it is
non-empty, the returned array of AudioObjectIDs will only refer to objects
whose class is in the qualifier array or whose is a subclass of one in the
qualifier array.
- kAudioObjectPropertyListenerAdded
- An AudioObjectPropertyAddress indicating the address to which a new listener
was added. Note that this property is not for applications to use. Rather,
this property is for the HAL shell to notify AudioObjects implemented by an
AudioPlugIn when a listener is added.
- kAudioObjectPropertyListenerRemoved
- An AudioObjectPropertyAddress indicating the address to which a listener was
removed. Note that this property is not for applications to use. Rather,
this property is for the HAL shell to notify AudioObjects implemented by an
AudioPlugIn when a listener is removed.
Various constants related to AudioPlugIns.
enum
{
kAudioPlugInClassID = 'aplg'
};
Discussion
Class Constants
Constants
- kAudioPlugInClassID
- The AudioClassID that identifies the AudioPlugIn class.
AudioObjectPropertySelector values that apply to AudioPlugIns.
enum
{
kAudioPlugInPropertyBundleID = 'piid',
kAudioPlugInCreateAggregateDevice = 'cagg',
kAudioPlugInDestroyAggregateDevice = 'dagg'
};
Discussion
AudioPlugIn is a subclass of AudioObject that represents a plug-in loaded by the
HAL that conforms to the API in . AudioPlugIns
have one scope, kAudioObjectPropertyScopeGlobal, and only a master element.
Constants
- kAudioPlugInPropertyBundleID
- A CFString that contains the bundle identifier for the AudioPlugIn. The
caller is responsible for releasing the returned CFObject.
- kAudioPlugInCreateAggregateDevice
- This property is used to tell a plug-in to create a new
AudioAggregateDevice. It's value is only read. The qualifier data for this
property is a CFDictionary containing a description of the
AudioAggregateDevice to create. The keys for the CFDictionary are defined in
the AudioAggregateDevice Constants section. The value of the property that
gets returned is the AudioObjectID of the newly created device.
- kAudioPlugInDestroyAggregateDevice
- This property is used to tell a plug-in to destroy an AudioAggregateDevice.
Like kAudioPlugInCreateAggregateDevice, this property is read only. The
value of the property is the AudioObjectID of the AudioAggregateDevice to
destroy.
The four char codes that identify the various standard subclasses of
AudioSelectorControl.
enum
{
kAudioDataSourceControlClassID = 'dsrc',
kAudioDataDestinationControlClassID = 'dest',
kAudioClockSourceControlClassID = 'clck',
kAudioLineLevelControlClassID = 'nlvl'
};
Discussion
Subclass IDs
Constants
- kAudioDataSourceControlClassID
- An AudioSelectorControl that identifies where the data for the element is
coming from.
- kAudioDataDestinationControlClassID
- An AudioSelectorControl that identifies where the data for the element is
going.
- kAudioClockSourceControlClassID
- An AudioSelectorControl that identifies where the timing info for the object
is coming from.
- kAudioLineLevelControlClassID
- An AudioSelectorControl that identifies the nominal line level for the
element. Note that this is not a gain stage but rather indicating the
voltage standard (if any) used for the element, such as +4dBu, -10dBV,
instrument, etc.
AudioObjectPropertySelector values that apply to all AudioSelectorControls.
enum
{
kAudioSelectorControlPropertyCurrentItem = 'scci',
kAudioSelectorControlPropertyAvailableItems = 'scai',
kAudioSelectorControlPropertyItemName = 'scin'
};
Discussion
AudioSelectorControl is a subclass of AudioControl and has only the single
scope, kAudioObjectPropertyScopeGlobal, and only a master element.
Constants
- kAudioSelectorControlPropertyCurrentItem
- A UInt32 that is the ID of the item currently selected.
- kAudioSelectorControlPropertyAvailableItems
- An array of UInt32s that represent the IDs of all the items available.
- kAudioSelectorControlPropertyItemName
- This property translates the given item ID into a human readable name. The
qualifier contains the ID of the item to be translated and name is returned
as a CFString as the property data. The caller is responsible for releasing
the returned CFObject.
AudioObjectPropertySelector values that apply to all AudioStereoPanControls.
enum
{
kAudioStereoPanControlPropertyValue = 'spcv',
kAudioStereoPanControlPropertyPanningChannels = 'spcc'
};
Discussion
AudioStereoPanControl is a subclass of AudioControl and has only the single
scope, kAudioObjectPropertyScopeGlobal, and only a master element.
Constants
- kAudioStereoPanControlPropertyValue
- A Float32 where 0.0 is full left, 1.0 is full right, and 0.5 is center.
- kAudioStereoPanControlPropertyPanningChannels
- An array of two UInt32s that indicate which elements of the owning object
the signal is being panned between.
Various constants related to AudioStreams.
enum
{
kAudioStreamClassID = 'astr',
kAudioStreamUnknown = kAudioObjectUnknown
};
Discussion
Class Constants
Constants
- kAudioStreamClassID
- The AudioClassID that identifies the AudioStream class.
- kAudioStreamUnknown
- The AudioObjectID for a nonexistent AudioObject.
AudioObjectPropertySelector values that apply to all AudioStreams.
enum
{
kAudioStreamPropertyDirection = 'sdir',
kAudioStreamPropertyTerminalType = 'term',
kAudioStreamPropertyStartingChannel = 'schn',
kAudioStreamPropertyLatency = kAudioDevicePropertyLatency,
kAudioStreamPropertyVirtualFormat = 'sfmt',
kAudioStreamPropertyAvailableVirtualFormats = 'sfma',
kAudioStreamPropertyPhysicalFormat = 'pft ',
kAudioStreamPropertyAvailablePhysicalFormats = 'pfta'
};
Discussion
AudioStream is a subclass of AudioObject and has only the single scope,
kAudioObjectPropertyScopeGlobal. They have a master element and an element for
each channel in the stream numbered upward from 1. Note that AudioStream objects
share AudioControl objects with their owning AudioDevice. Consequently, all the
standard AudioControl related property selectors implemented by AudioDevices are
also implemented by AudioStreams. The same constants are to be used for such
properties.
Constants
- kAudioStreamPropertyDirection
- A UInt32 where a value of 0 means that this AudioStream is an output stream
and a value of 1 means that it is an input stream.
- kAudioStreamPropertyTerminalType
- A UInt32 whose value describes the general kind of functionality attached
to the AudioStream. Constants that describe some of the values of this
property are defined in
- kAudioStreamPropertyStartingChannel
- A UInt32 that specifies the first element in the owning device that
corresponds to element one of this stream.
- kAudioStreamPropertyLatency
- A UInt32 containing the number of frames of latency in the AudioStream. Note
that the owning AudioDevice may have additional latency so it should be
queried as well. If both the device and the stream say they have latency,
then the total latency for the stream is the device latency summed with the
stream latency.
- kAudioStreamPropertyVirtualFormat
- An AudioStreamBasicDescription that describes the current data format for
the AudioStream. The virtual format refers to the data format in which all
IOProcs for the owning AudioDevice will perform IO transactions.
- kAudioStreamPropertyAvailableVirtualFormats
- An array of AudioStreamRangedDescriptions that describe the available data
formats for the AudioStream. The virtual format refers to the data format in
which all IOProcs for the owning AudioDevice will perform IO transactions.
- kAudioStreamPropertyPhysicalFormat
- An AudioStreamBasicDescription that describes the current data format for
the AudioStream. The physical format refers to the data format in which the
hardware for the owning AudioDevice performs it's IO transactions.
- kAudioStreamPropertyAvailablePhysicalFormats
- An array of AudioStreamRangedDescriptions that describe the available data
formats for the AudioStream. The physical format refers to the data format
in which the hardware for the owning AudioDevice performs it's IO
transactions.
AudioObjectPropertySelector values whose functionality is better provided by
other selectors.
enum
{
kAudioStreamPropertyOwningDevice = kAudioObjectPropertyOwner,
kAudioStreamPropertyPhysicalFormats = 'pft#',
kAudioStreamPropertyPhysicalFormatSupported = 'pft?',
kAudioStreamPropertyPhysicalFormatMatch = 'pftm'
};
Discussion
These selectors are still provided for backward compatibility. The description
of the property will indicate in parentheses the better selectors to use and
why.
Constants
- kAudioStreamPropertyOwningDevice
- The AudioObjectID of the AudioDevice of which this AudioStream is a part.
(kAudioObjectPropertyOwner: This is just another name for the inherited
selector.)
- kAudioStreamPropertyPhysicalFormats
- An array of AudioStreamBasicDescriptions that describe the available data
formats for the AudioStream. The physical format refers to the data format
in which the hardware for the owning AudioDevice performs it's IO
transactions.
(kAudioStreamPropertyAvailablePhysicalFormats: The new name for this
property is much clearer for readers of the API to see what is meant and the
AudioStreamRangedDescription structure provides better information.)
- kAudioStreamPropertyPhysicalFormatSupported
- An AudioStreamBasicDescription is passed in to query whether or not the
format is supported. A kAudioDeviceUnsupportedFormatError will be returned
if the format is not supported and kAudioHardwareNoError will be returned if
it is supported. AudioStreamBasicDescription fields set to 0 will be ignored
in the query, but otherwise values must match exactly. The physical format
refers to the data format in which the hardware for the owning AudioDevice
performs it's IO transactions.
(kAudioStreamPropertyAvailablePhysicalFormats: The proper and most robust
way to find a format that the AudioStream can support is to get the list of
available formats and look through that rather than using this property.)
- kAudioStreamPropertyPhysicalFormatMatch
- An AudioStreamBasicDescription is passed in and the AudioStream will modify
it to describe the best match, in the AudioDevice's opinion, for the given
format. The physical format refers to the data format in which the hardware
for the owning AudioDevice performs it's IO transactions.
(kAudioStreamPropertyAvailablePhysicalFormats: The proper and most robust
way to find a format that the AudioStream can support is to get the list of
available formats and look through that rather than using this property.)
Various constants related to AudioSubDevices.
enum
{
kAudioSubDeviceClassID = 'asub'
};
Discussion
Class Constants
Constants
- kAudioSubDeviceClassID
- The AudioClassID that identifies the AudioSubDevice class.
Constants that describe the range of values the property
kAudioSubDevicePropertyDriftCompensation. It is a continuous range from
kAudioSubDeviceDriftCompensationMinQuality to
kAudioSubDeviceDriftCompensationMaxQuality, with some commonly used settings
called out.
enum
{
kAudioSubDeviceDriftCompensationMinQuality = 0,
kAudioSubDeviceDriftCompensationLowQuality = 0x20,
kAudioSubDeviceDriftCompensationMediumQuality = 0x40,
kAudioSubDeviceDriftCompensationHighQuality = 0x60,
kAudioSubDeviceDriftCompensationMaxQuality = 0x7F
};
Discussion
Clock Drift Compensation Methods
AudioObjectPropertySelector values that apply to all AudioSubDevices.
enum
{
kAudioSubDevicePropertyExtraLatency = 'xltc',
kAudioSubDevicePropertyDriftCompensation = 'drft',
kAudioSubDevicePropertyDriftCompensationQuality = 'drfq'
};
Discussion
AudioSubDevice is a subclass of AudioDevice that is collected together with
other sub-devices in an AudioAggregateDevice. AudioSubDevice objects do not
implement an IO path nor any AudioDevice properties associated with the IO path.
They also don't have any streams.
Constants
- kAudioSubDevicePropertyExtraLatency
- A Float64 indicating the number of sample frames to add to or subtract from
the latency compensation used for this AudioSubDevice.
- kAudioSubDevicePropertyDriftCompensation
- A UInt32 where a value of 0 indicates that no drift compensation should be
done for this AudioSubDevice and a value of 1 means that it should.
- kAudioSubDevicePropertyDriftCompensationQuality
- A UInt32 that controls the trade-off between quality and CPU load in the
drift compensation. The range of values is from 0 to 128, where the lower
the number, the worse the quality but also the less CPU is used to do the
compensation.
Various constants related to the AudioSystemObject.
enum
{
kAudioSystemObjectClassID = 'asys',
kAudioObjectSystemObject = 1UL
};
Discussion
Class Constants
Constants
- kAudioSystemObjectClassID
- The AudioClassID that identifies the AudioSystemObject class.
- kAudioObjectSystemObject
- The AudioObjectID that always refers to the one and only instance of the
AudioSystemObject.
AudioObjectPropertySelector values that apply to the AudioSystemObject.
enum
{
kAudioHardwarePropertyProcessIsMaster = 'mast',
kAudioHardwarePropertyIsInitingOrExiting = 'inot',
kAudioHardwarePropertyDevices = 'dev#',
kAudioHardwarePropertyDefaultInputDevice = 'dIn ',
kAudioHardwarePropertyDefaultOutputDevice = 'dOut',
kAudioHardwarePropertyDefaultSystemOutputDevice = 'sOut',
kAudioHardwarePropertyDeviceForUID = 'duid',
kAudioHardwarePropertySleepingIsAllowed = 'slep',
kAudioHardwarePropertyUnloadingIsAllowed = 'unld',
kAudioHardwarePropertyHogModeIsAllowed = 'hogr',
kAudioHardwarePropertyRunLoop = 'rnlp',
kAudioHardwarePropertyPlugInForBundleID = 'pibi'
};
Discussion
The AudioSystemObject has one scope, kAudioObjectPropertyScopeGlobal, and only a
master element.
Constants
- kAudioHardwarePropertyProcessIsMaster
- A UInt32 where 1 means that the current process contains the master instance
of the HAL. The master instance of the HAL is the only instance in which
plug-ins should save/restore their devices' settings.
- kAudioHardwarePropertyIsInitingOrExiting
- A UInt32 whose value will be non-zero if the HAL is either in the midst of
initializing or in the midst of exiting the process.
- kAudioHardwarePropertyDevices
- An array of the AudioDeviceIDs that represent all the devices currently
available to the system.
- kAudioHardwarePropertyDefaultInputDevice
- The AudioDeviceID of the default input AudioDevice.
- kAudioHardwarePropertyDefaultOutputDevice
- The AudioDeviceID of the default output AudioDevice.
- kAudioHardwarePropertyDefaultOutputDevice
- The AudioDeviceID of the output AudioDevice to use for system related sound
from the alert sound to digital call progress.
- kAudioHardwarePropertyDeviceForUID
- Using an AudioValueTranslation structure, this property translates the input
CFStringRef containing a UID into the AudioDeviceID that refers to the
AudioDevice with that UID. This property will return kAudioDeviceUnknown if
the given UID does not match any currently available AudioDevice.
- kAudioHardwarePropertySleepingIsAllowed
- A UInt32 where 1 means that the process will allow the CPU to idle sleep
even if there is audio IO in progress. A 0 means that the CPU will not be
allowed to idle sleep. Note that this property won't affect when the CPU is
forced to sleep.
- kAudioHardwarePropertyUnloadingIsAllowed
- A UInt32 where 1 means that this process wants the HAL to unload itself
after a period of inactivity where there are no IOProcs and no listeners
registered with any AudioObject.
- kAudioHardwarePropertyHogModeIsAllowed
- A UInt32 where 1 means that this process wants the HAL to automatically take
hog mode and 0 means that the HAL should not automatically take hog mode on
behalf of the process. Processes that only ever use the default device are
the sort of that should set this property's value to 0.
- kAudioHardwarePropertyRunLoop
- The CFRunLoopRef the HAL is currently attaching all of it's system
notification handlers to. By default, the HAL will create and manage it's
own thread for this job. Clients can set this property to tell the HAL to
use a thread of the client's choosing. The caller is responsible for
releasing the returned CFObject.
- kAudioHardwarePropertyPlugInForBundleID
- Using an AudioValueTranslation structure, this property translates the input
CFString containing a bundle ID into the AudioObjectID of the AudioPlugIn
that corresponds to it. This property will return kAudioObjectUnkown if the
given bundle ID doesn't match any AudioPlugIns.
AudioObjectPropertySelector values for AudioSystemObject properties that are
implemented by AudioControl objects.
enum
{
kAudioHardwarePropertyBootChimeVolumeScalar = 'bbvs',
kAudioHardwarePropertyBootChimeVolumeDecibels = 'bbvd',
kAudioHardwarePropertyBootChimeVolumeRangeDecibels = 'bbd#',
kAudioHardwarePropertyBootChimeVolumeScalarToDecibels = 'bv2d',
kAudioHardwarePropertyBootChimeVolumeDecibelsToScalar = 'bd2v'
};
Discussion
These properties are also accessible by locating the AudioControl object
attached to the AudioSystemObject and using that object to access the properties
of the control.
Constants
- kAudioHardwarePropertyBootChimeVolumeScalar
- A Float32 that represents the value of the boot chime volume control. The
range is between 0.0 and 1.0 (inclusive). This property is implemented by an
AudioControl object that is a subclass of AudioBootChimeVolumeControl.
- kAudioHardwarePropertyBootChimeVolumeDecibels
- A Float32 that represents the value of the boot chime volume control in dB.
This property is implemented by an AudioControl object that is a subclass
of AudioBootChimeVolumeControl.
- kAudioHardwarePropertyBootChimeVolumeRangeDecibels
- An AudioValueRange that contains the minimum and maximum dB values the
boot chime control can have. This property is implemented by an AudioControl
object that is a subclass of AudioBootChimeVolumeControl.
- kAudioHardwarePropertyBootChimeVolumeScalarToDecibels
- A Float32 that on input contains a scalar volume value for the boot chime
and on exit contains the equivalent dB value. This property is implemented
by an AudioControl object that is a subclass of AudioBootChimeVolumeControl.
- kAudioHardwarePropertyBootChimeVolumeDecibelsToScalar
- A Float32 that on input contains a dB volume value for the boot chime and on
exit contains the equivalent scalar value. This property is implemented by
an AudioControl object that is a subclass of AudioBootChimeVolumeControl.
The error constants unique to the HAL.
enum
{
kAudioHardwareNoError = 0,
kAudioHardwareNotRunningError = 'stop',
kAudioHardwareUnspecifiedError = 'what',
kAudioHardwareUnknownPropertyError = 'who?',
kAudioHardwareBadPropertySizeError = '!siz',
kAudioHardwareIllegalOperationError = 'nope',
kAudioHardwareBadObjectError = '!obj',
kAudioHardwareBadDeviceError = '!dev',
kAudioHardwareBadStreamError = '!str',
kAudioHardwareUnsupportedOperationError = 'unop',
kAudioDeviceUnsupportedFormatError = '!dat',
kAudioDevicePermissionsError = '!hog'
};
Discussion
These are the error constants that are unique to the HAL. Note that the HAL's
functions can and will return other codes that are not listed here. While these
constants give a general idea of what might have gone wrong during the execution
of an API call, if an API call returns anything other than kAudioHardwareNoError
it is to be viewed as the same failure regardless of what constant is actually
returned.
Constants
- kAudioHardwareNoError
- The function call completed successfully.
- kAudioHardwareNotRunningError
- The function call requires that the hardware be running but it isn't.
- kAudioHardwareUnspecifiedError
- The function call failed while doing something that doesn't provide any
error messages.
- kAudioHardwareUnknownPropertyError
- The AudioObject doesn't know about the property at the given address.
- kAudioHardwareBadPropertySizeError
- An improperly sized buffer was provided when accessing the data of a
property.
- kAudioHardwareIllegalOperationError
- The requested operation couldn't be completed.
- kAudioHardwareBadObjectError
- The AudioObjectID passed to the function doesn't map to a valid AudioObject.
- kAudioHardwareBadDeviceError
- The AudioDeviceID passed to the function doesn't map to a valid AudioDevice.
- kAudioHardwareBadStreamError
- The AudioStreamID passed to the function doesn't map to a valid AudioStream.
- kAudioHardwareUnsupportedOperationError
- The AudioObject doesn't support the requested operation.
- kAudioDeviceUnsupportedFormatError
- The AudioStream doesn't support the requested format.
- kAudioDevicePermissionsError
- The requested operation can't be completed because the process doesn't have
permission.
Constants that are used as wildcards in an AudioObjectPropertyAddress.
enum
{
kAudioObjectPropertySelectorWildcard = '****',
kAudioObjectPropertyScopeWildcard = '****',
kAudioObjectPropertyElementWildcard = 0xFFFFFFFFUL,
kAudioPropertyWildcardPropertyID = kAudioObjectPropertySelectorWildcard,
kAudioPropertyWildcardSection = 0xFF,
kAudioPropertyWildcardChannel = kAudioObjectPropertyElementWildcard
};
Discussion
Wildcards match any and all values for there associated type. They are
especially useful for registering listener procs to receive notifications and
for querying an AudioObject's list of AudioControls.
Constants
- kAudioObjectPropertySelectorWildcard
- The wildcard value for AudioObjectPropertySelectors.
- kAudioObjectPropertyScopeWildcard
- The wildcard value for AudioObjectPropertyScopes.
- kAudioObjectPropertyElementWildcard
- The wildcard value for AudioObjectPropertyElements.
- kAudioPropertyWildcardPropertyID
- A synonym for kAudioObjectPropertySelectorWildcard.
- kAudioPropertyWildcardSection
- The wildcard value for the isInput argument of AudioDeviceGetPropertyInfo(),
AudioDeviceGetProperty(), and AudioDeviceSetProperty().
- kAudioPropertyWildcardChannel
- A synonym for kAudioObjectPropertyElementWildcard.
The flags that can be passed to control the behavior of AudioDeviceStartAtTime()
andAudioDeviceGetNearestStartTime().
enum
{
kAudioDeviceStartTimeIsInputFlag = (1L << 0),
kAudioDeviceStartTimeDontConsultDeviceFlag = (1L << 1),
kAudioDeviceStartTimeDontConsultHALFlag = (1L << 2)
};
Discussion
Flags
Constants
- kAudioDeviceStartTimeIsInputFlag
- Set to indicate that the requested time refers to an input time. Clear to
indicate that it is an output time.
- kAudioDeviceStartTimeDontConsultDeviceFlag
- Set to indicate that the device should not be consulted when determining the
start time. Clear to indicate that the device should be consulted. This flag
cannot be set if kAudioDeviceStartTimeDontConsultHALFlag is set.
- kAudioDeviceStartTimeDontConsultHALFlag
- Set to indicate that the HAL should not be consulted when determining the
start time. Clear to indicate that the HAL should be consulted. This flag
cannot be set if kAudioDeviceStartTimeDontConsultDeviceFlag is set.
#defines
#define kAudioAggregateDeviceIsPrivateKey "private"
Discussion
The key used in a CFDictionary that describes the composition of an
AudioAggregateDevice. The value for this key is a CFNumber where a value of 0
means that the AudioAggregateDevice is to be published to the entire system and
a value of 1 means that the AudioAggregateDevice is private to the process that
created it. Note that a private AudioAggregateDevice is not persistent across
launches of the process that created it. Note that if this key is not present,
it implies that the AudioAggregateDevice is published to the entire system.
#define kAudioAggregateDeviceMasterSubDeviceKey "master"
Discussion
The key used in a CFDictionary that describes the composition of an
AudioAggregateDevice. The value for this key is a CFString that contains the
UID for the sub-device that is the master time source for the
AudioAggregateDevice.
#define kAudioAggregateDeviceNameKey "name"
Discussion
The key used in a CFDictionary that describes the composition of an
AudioAggregateDevice. The value for this key is a CFString that contains the
human readable name of the AudioAggregateDevice.
#define kAudioAggregateDeviceSubDeviceListKey "subdevices"
Discussion
The key used in a CFDictionary that describes the composition of an
AudioAggregateDevice. The value for this key is a CFArray of CFDictionaries that
describe each sub-device in the AudioAggregateDevice. The keys for this
CFDictionary are defined in the AudioSubDevice section.
#define kAudioAggregateDeviceUIDKey "uid"
Discussion
The key used in a CFDictionary that describes the composition of an
AudioAggregateDevice. The value for this key is a CFString that contains the UID
of the AudioAggregateDevice.
#define kAudioSubDeviceUIDKey "uid"
Discussion
The key used in a CFDictionary that describes the state of an AudioSubDevice.
The value for this key is a CFString that contains the UID for the
AudioSubDevice.
(Last Updated 12/13/2004)