Skip to content

Instantly share code, notes, and snippets.

@kdepp

kdepp/AudioHardware.h

Created November 19, 2019 04:48
Show Gist options
  • Save kdepp/46c812b05cda6e44a292328b31d0784c to your computer and use it in GitHub Desktop.
Save kdepp/46c812b05cda6e44a292328b31d0784c to your computer and use it in GitHub Desktop.
Download ZIP
Core Audio Header Files
Raw
AudioHardware.h
/*==================================================================================================
File: CoreAudio/AudioHardware.h
Contains: API for communicating with audio hardware.
Copyright: (c) 1985-2011 by Apple, Inc., all rights reserved.
Bugs?: For bug reports, consult the following page on
the World Wide Web:
http://developer.apple.com/bugreporter/
==================================================================================================*/
#if !defined(CoreAudio_AudioHardware_h)
#define CoreAudio_AudioHardware_h
//==================================================================================================
#pragma mark -
#pragma mark Overview
/*!
@header AudioHardware
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 its super class.
The base class for all AudioObjects is the class AudioObject. As such, each AudioObject will
provide basic properties such as its class, its 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 its 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 its 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.
*/
//==================================================================================================
#pragma mark -
#pragma mark Includes
#include <Availability.h>
#include <CoreAudio/CoreAudioTypes.h>
#include <CoreAudio/AudioHardwareBase.h>
#include <CoreFoundation/CoreFoundation.h>
#include <dispatch/dispatch.h>
//==================================================================================================
CF_ASSUME_NONNULL_BEGIN
#if defined(__cplusplus)
extern "C"
{
#endif
//==================================================================================================
#pragma mark Basic Constants
/*!
@enum Predefined AudioObjectID values
@abstract ObjectIDs that are always the same
@constant kAudioObjectSystemObject
The AudioObjectID that always refers to the one and only instance of the
AudioSystemObject class.
*/
CF_ENUM(int)
{
kAudioObjectSystemObject = 1
};
//==================================================================================================
#pragma mark -
#pragma mark AudioObject Types
/*!
@typedef AudioObjectPropertyListenerProc
@abstract Clients register an AudioObjectPropertyListenerProc with an AudioObject in order
to receive notifications when the properties of the object change.
@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.
@param inObjectID
The AudioObject whose properties have changed.
@param inNumberAddresses
The number of elements in the inAddresses array.
@param inAddresses
An array of AudioObjectPropertyAddresses indicating which properties
changed.
@param inClientData
A pointer to client data established when the listener proc was registered
with the AudioObject.
@result The return value is currently unused and should always be 0.
*/
typedef OSStatus
(*AudioObjectPropertyListenerProc)( AudioObjectID inObjectID,
UInt32 inNumberAddresses,
const AudioObjectPropertyAddress* inAddresses,
void* __nullable inClientData);
/*!
@typedef AudioObjectPropertyListenerBlock
@abstract Clients register an AudioObjectPropertyListenerBlock with an AudioObject in
order to receive notifications when the properties of the object change.
@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.
@param inNumberAddresses
The number of elements in the inAddresses array.
@param inAddresses
An array of AudioObjectPropertyAddresses indicating which properties
changed.
*/
typedef void
(^AudioObjectPropertyListenerBlock)( UInt32 inNumberAddresses,
const AudioObjectPropertyAddress* inAddresses);
//==================================================================================================
#pragma mark AudioObject Properties
/*!
@enum AudioObject Property Selectors
@abstract AudioObjectPropertySelector values provided by objects of the AudioObject class.
@discussion The AudioObject class is the base class for all classes. As such, all classes
inherit this set of properties.
@constant kAudioObjectPropertyCreator
A CFString that contains the bundle ID of the plug-in that instantiated the
object. The caller is responsible for releasing the returned CFObject.
@constant 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.
@constant 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.
*/
CF_ENUM(AudioObjectPropertySelector)
{
kAudioObjectPropertyCreator = 'oplg',
kAudioObjectPropertyListenerAdded = 'lisa',
kAudioObjectPropertyListenerRemoved = 'lisr'
};
//==================================================================================================
#pragma mark AudioObject Functions
/*!
@functiongroup AudioObject
*/
/*!
@function AudioObjectShow
@abstract Prints to standard out a textural description of the AudioObject.
@param inObjectID
The AudioObject to show.
*/
extern void
AudioObjectShow( AudioObjectID inObjectID) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0);
/*!
@function AudioObjectHasProperty
@abstract Queries an AudioObject about whether or not it has the given property.
@param inObjectID
The AudioObject to query.
@param inAddress
An AudioObjectPropertyAddress indicating which property is being queried.
@result A Boolean indicating whether or not the AudioObject has the given property.
*/
extern Boolean
AudioObjectHasProperty( AudioObjectID inObjectID,
const AudioObjectPropertyAddress* inAddress) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0);
/*!
@function AudioObjectIsPropertySettable
@abstract Queries an AudioObject about whether or not the given property can be set using
AudioObjectSetPropertyData.
@param inObjectID
The AudioObject to query.
@param inAddress
An AudioObjectPropertyAddress indicating which property is being queried.
@param outIsSettable
A Boolean indicating whether or not the property can be set.
@result An OSStatus indicating success or failure.
*/
extern OSStatus
AudioObjectIsPropertySettable( AudioObjectID inObjectID,
const AudioObjectPropertyAddress* inAddress,
Boolean* outIsSettable) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0);
/*!
@function AudioObjectGetPropertyDataSize
@abstract Queries an AudioObject to find the size of the data for the given property.
@param inObjectID
The AudioObject to query.
@param inAddress
An AudioObjectPropertyAddress indicating which property is being queried.
@param 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.
@param 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.
@param outDataSize
A UInt32 indicating how many bytes the data for the given property occupies.
@result An OSStatus indicating success or failure.
*/
extern OSStatus
AudioObjectGetPropertyDataSize( AudioObjectID inObjectID,
const AudioObjectPropertyAddress* inAddress,
UInt32 inQualifierDataSize,
const void* __nullable inQualifierData,
UInt32* outDataSize) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0);
/*!
@function AudioObjectGetPropertyData
@abstract Queries an AudioObject to get the data of the given property and places it in
the provided buffer.
@param inObjectID
The AudioObject to query.
@param inAddress
An AudioObjectPropertyAddress indicating which property is being queried.
@param 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.
@param 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.
@param 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.
@param outData
The buffer into which the AudioObject will put the data for the given
property.
@result An OSStatus indicating success or failure.
*/
extern OSStatus
AudioObjectGetPropertyData( AudioObjectID inObjectID,
const AudioObjectPropertyAddress* inAddress,
UInt32 inQualifierDataSize,
const void* __nullable inQualifierData,
UInt32* ioDataSize,
void* outData) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0);
/*!
@function AudioObjectSetPropertyData
@abstract Tells an AudioObject to change the value of the given property using the
provided data.
@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.
@param inObjectID
The AudioObject to change.
@param inAddress
An AudioObjectPropertyAddress indicating which property is being changed.
@param 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.
@param 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.
@param inDataSize
A UInt32 indicating the size of the buffer pointed to by inData.
@param inData
The buffer containing the data to be used to change the property's value.
@result An OSStatus indicating success or failure.
*/
extern OSStatus
AudioObjectSetPropertyData( AudioObjectID inObjectID,
const AudioObjectPropertyAddress* inAddress,
UInt32 inQualifierDataSize,
const void* __nullable inQualifierData,
UInt32 inDataSize,
const void* inData) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0);
/*!
@function AudioObjectAddPropertyListener
@abstract Registers the given AudioObjectPropertyListenerProc to receive notifications
when the given properties change.
@param inObjectID
The AudioObject to register the listener with.
@param inAddress
The AudioObjectPropertyAddresses indicating which property the listener
should be notified about.
@param inListener
The AudioObjectPropertyListenerProc to call.
@param inClientData
A pointer to client data that is passed to the listener when it is called.
@result An OSStatus indicating success or failure.
*/
extern OSStatus
AudioObjectAddPropertyListener( AudioObjectID inObjectID,
const AudioObjectPropertyAddress* inAddress,
AudioObjectPropertyListenerProc inListener,
void* __nullable inClientData) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0);
/*!
@function AudioObjectRemovePropertyListener
@abstract Unregisters the given AudioObjectPropertyListenerProc from receiving
notifications when the given properties change.
@param inObjectID
The AudioObject to unregister the listener from.
@param inAddress
The AudioObjectPropertyAddress indicating from which property the listener
should be removed.
@param inListener
The AudioObjectPropertyListenerProc being removed.
@param inClientData
A pointer to client data that is passed to the listener when it is called.
@result An OSStatus indicating success or failure.
*/
extern OSStatus
AudioObjectRemovePropertyListener( AudioObjectID inObjectID,
const AudioObjectPropertyAddress* inAddress,
AudioObjectPropertyListenerProc inListener,
void* __nullable inClientData) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0);
/*!
@function AudioObjectAddPropertyListenerBlock
@abstract Registers the given AudioObjectPropertyListenerBlock to receive notifications
when the given properties change.
@param inObjectID
The AudioObject to register the listener with.
@param inAddress
The AudioObjectPropertyAddresses indicating which property the listener
should be notified about.
@param inDispatchQueue
The dispatch queue on which the listener block will be dispatched. All
listener blocks will be dispatched asynchronously save for those dispatched
from the IO context (of which kAudioDevicePropertyDeviceIsRunning and
kAudioDeviceProcessorOverload are the only examples) which will be
dispatched synchronously. Note that this dispatch queue will be retained
until a matching call to AudioObjectRemovePropertyListenerBlock is made. If
this value is NULL, then the block will be directly invoked.
@param inListener
The AudioObjectPropertyListenerBlock to call. Note that this block will be
Block_copy'd and the reference maintained until a matching call to
AudioObjectRemovePropertyListenerBlock is made.
@result An OSStatus indicating success or failure.
*/
extern OSStatus
AudioObjectAddPropertyListenerBlock( AudioObjectID inObjectID,
const AudioObjectPropertyAddress* inAddress,
dispatch_queue_t __nullable inDispatchQueue,
AudioObjectPropertyListenerBlock inListener) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
/*!
@function AudioObjectRemovePropertyListenerBlock
@abstract Unregisters the given AudioObjectPropertyListenerBlock from receiving
notifications when the given properties change.
@param inObjectID
The AudioObject to unregister the listener from.
@param inAddress
The AudioObjectPropertyAddress indicating from which property the listener
should be removed.
@param inDispatchQueue
The dispatch queue on which the listener block was being dispatched to.
@param inListener
The AudioObjectPropertyListenerBlock being removed.
@result An OSStatus indicating success or failure.
*/
extern OSStatus
AudioObjectRemovePropertyListenerBlock( AudioObjectID inObjectID,
const AudioObjectPropertyAddress* inAddress,
dispatch_queue_t __nullable inDispatchQueue,
AudioObjectPropertyListenerBlock inListener) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
//==================================================================================================
#pragma mark -
#pragma mark AudioSystemObject Constants
/*!
@enum AudioSystemObject Class Constants
@abstract Various constants related to the AudioSystemObject class.
@discussion Note that there is only ever one instance of the AudioSystemObject class and it
is available via the AudioObjectID, kAudioObjectSystemObject.
@constant kAudioSystemObjectClassID
The AudioClassID that identifies the AudioSystemObject class.
*/
CF_ENUM(AudioClassID)
{
kAudioSystemObjectClassID = 'asys'
};
/*!
@enum Power Hints
@abstract The values for kAudioHardwarePropertyPowerHint
@discussion The system object property, kAudioHardwarePropertyPowerHint, allows a process to
to indicate how aggressive the system can be with optimizations that save power.
Note that the value of this property can be set in an application's info.plist
using the key, "AudioHardwarePowerHint". The values for this key are the strings
that correspond to the values in the enum.
@constant kAudioHardwarePowerHintNone
This is the default value and it indicates that the system will not make any
power optimizations that compromise latency or quality in order to save
power. The info.plist value is "None" or the "AudioHardwarePowerHint" entry
can be omitted entirely.
@constant kAudioHardwarePowerHintFavorSavingPower
The system will choose to save power even at the expense of latency. The
info.plist value is "Favor Saving Power"
*/
typedef CF_ENUM(UInt32, AudioHardwarePowerHint)
{
kAudioHardwarePowerHintNone = 0,
kAudioHardwarePowerHintFavorSavingPower = 1
};
//==================================================================================================
#pragma mark AudioSystemObject Properties
/*!
@enum AudioSystemObject Properties
@abstract AudioObjectPropertySelector values provided by the AudioSystemObject class.
@discussion The AudioSystemObject class is a subclass of the AudioObject class. the class
has just the global scope, kAudioObjectPropertyScopeGlobal, and only a master element.
@constant kAudioHardwarePropertyDevices
An array of the AudioObjectIDs that represent all the devices currently
available to the system.
@constant kAudioHardwarePropertyDefaultInputDevice
The AudioObjectID of the default input AudioDevice.
@constant kAudioHardwarePropertyDefaultOutputDevice
The AudioObjectID of the default output AudioDevice.
@constant kAudioHardwarePropertyDefaultSystemOutputDevice
The AudioObjectID of the output AudioDevice to use for system related sound
from the alert sound to digital call progress.
@constant kAudioHardwarePropertyTranslateUIDToDevice
This property fetches the AudioObjectID that corresponds to the AudioDevice
that has the given UID. The UID is passed in via the qualifier as a CFString
while the AudioObjectID for the AudioDevice is returned to the caller as the
property's data. Note that an error is not returned if the UID doesn't refer
to any AudioDevices. Rather, this property will return kAudioObjectUnknown
as the value of the property.
@constant kAudioHardwarePropertyMixStereoToMono
A UInt32 where a value other than 0 indicates that AudioDevices should mix
stereo signals down to mono. Note that the two channels on the device that
comprise the stereo signal are defined on the device by
kAudioDevicePropertyPreferredChannelsForStereo.
@constant kAudioHardwarePropertyPlugInList
An array of AudioObjectIDs that represent all the AudioPlugIn objects
currently provided by the system
@constant kAudioHardwarePropertyTranslateBundleIDToPlugIn
This property fetches the AudioObjectID that corresponds to the AudioPlugIn
that has the given bundle ID. The bundle ID is passed in via the qualifier
as a CFString while the AudioObjectID for the AudioPlugIn is returned to the
caller as the property's data. Note that an error is not returned if the UID
doesn't refer to any AudioPlugIns. Rather, this property will return
kAudioObjectUnknown as the value of the property.
@constant kAudioHardwarePropertyTransportManagerList
An array of the AudioObjectIDs for all the AudioTransportManager objects.
@constant kAudioHardwarePropertyTranslateBundleIDToTransportManager
This property fetches the AudioObjectID that corresponds to the
AudioTransportManager whose bundle has the given bundle ID. The bundle ID is
passed in via the qualifier as a CFString while the AudioObjectID for the
AudioTransportManager is returned to the caller as the property's data. Note
that an error is not returned if the bundle ID doesn't refer to any
AudioTransportManagers. Rather, this property will return
kAudioObjectUnknown as the value of the property.
@constant kAudioHardwarePropertyBoxList
An array of AudioObjectIDs that represent all the AudioBox objects currently
provided by the system.
@constant kAudioHardwarePropertyTranslateUIDToBox
This property fetches the AudioObjectID that corresponds to the AudioBox
that has the given UID. The UID is passed in via the qualifier as a CFString
while the AudioObjectID for the AudioBox is returned to the caller as the
property's data. Note that an error is not returned if the UID doesn't refer
to any AudioBoxes. Rather, this property will return kAudioObjectUnknown
as the value of the property.
@constant kAudioHardwarePropertyClockDeviceList
An array of AudioObjectIDs that represent all the AudioClockDevice objects
currently provided by the system.
@constant kAudioHardwarePropertyTranslateUIDToClockDevice
This property fetches the AudioObjectID that corresponds to the AudioClockDevice
that has the given UID. The UID is passed in via the qualifier as a CFString
while the AudioObjectID for the AudioClockDevice is returned to the caller
as the property's data. Note that an error is not returned if the UID doesn't
refer to any AudioClockDevice. Rather, this property will return
kAudioObjectUnknown as the value of the property.
@constant 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.
@constant 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.
@constant kAudioHardwarePropertyUserIDChanged
This property exists so that clients can tell the HAL when they are changing
the effective user ID of the process. The way it works is that a client will
set the value of this property and the HAL will flush all its cached per-
user preferences such as the default devices. The value of this property is
a UInt32, but its value has no currently defined meaning and clients may
pass any value when setting it to trigger the cache flush.
@constant kAudioHardwarePropertyProcessIsAudible
A UInt32 where a non-zero value indicates that the audio of the process will
be heard. A value of 0 indicates that all audio in the process will not be
heard.
@constant 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.
@constant 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.
@constant 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.
@constant kAudioHardwarePropertyUserSessionIsActiveOrHeadless
A UInt32 where a value other than 0 indicates that the login session of the
user of the process is either an active console session or a headless
session.
@constant kAudioHardwarePropertyServiceRestarted
A UInt32 whose value has no meaning. Rather, this property exists so that
clients can be informed when the service has been reset for some reason.
When a reset happens, any state the client has, such as cached data or
added listeners, must be re-established by the client.
@constant kAudioHardwarePropertyPowerHint
A UInt32 whose values are drawn from the AudioHardwarePowerHint enum above.
Only those values are allowed. This property allows a process to indicate how
aggressive the system can be with optimizations that save power. The default
value is kAudioHardwarePowerHintNone. Note that the value of this
property can be set in an application's info.plist using the key,
"AudioHardwarePowerHint". The values for this key are the strings that
correspond to the values in the Power Hints enum.
*/
CF_ENUM(AudioObjectPropertySelector)
{
kAudioHardwarePropertyDevices = 'dev#',
kAudioHardwarePropertyDefaultInputDevice = 'dIn ',
kAudioHardwarePropertyDefaultOutputDevice = 'dOut',
kAudioHardwarePropertyDefaultSystemOutputDevice = 'sOut',
kAudioHardwarePropertyTranslateUIDToDevice = 'uidd',
kAudioHardwarePropertyMixStereoToMono = 'stmo',
kAudioHardwarePropertyPlugInList = 'plg#',
kAudioHardwarePropertyTranslateBundleIDToPlugIn = 'bidp',
kAudioHardwarePropertyTransportManagerList = 'tmg#',
kAudioHardwarePropertyTranslateBundleIDToTransportManager = 'tmbi',
kAudioHardwarePropertyBoxList = 'box#',
kAudioHardwarePropertyTranslateUIDToBox = 'uidb',
kAudioHardwarePropertyClockDeviceList = 'clk#',
kAudioHardwarePropertyTranslateUIDToClockDevice = 'uidc',
kAudioHardwarePropertyProcessIsMaster = 'mast',
kAudioHardwarePropertyIsInitingOrExiting = 'inot',
kAudioHardwarePropertyUserIDChanged = 'euid',
kAudioHardwarePropertyProcessIsAudible = 'pmut',
kAudioHardwarePropertySleepingIsAllowed = 'slep',
kAudioHardwarePropertyUnloadingIsAllowed = 'unld',
kAudioHardwarePropertyHogModeIsAllowed = 'hogr',
kAudioHardwarePropertyUserSessionIsActiveOrHeadless = 'user',
kAudioHardwarePropertyServiceRestarted = 'srst',
kAudioHardwarePropertyPowerHint = 'powh'
};
//==================================================================================================
#pragma mark AudioSystemObject Functions
/*!
@functiongroup AudioSystemObject
*/
/*!
@function AudioHardwareUnload
@abstract 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 its uninitialized state.
@result An OSStatus indicating success or failure.
*/
extern OSStatus
AudioHardwareUnload() __OSX_AVAILABLE_STARTING(__MAC_10_1, __IPHONE_2_0);
/*!
@function AudioHardwareCreateAggregateDevice
@abstract This routine creates a new AudioAggregateDevice using the provided description.
@param inDescription
The CFDictionary that specifies how to build the AudioAggregateDevice. The
supported keys are described in the AudioAggregateDevice Constants section.
@param outDeviceID
The AudioObjectID of the newly created AudioAggregateDevice.
@result An OSStatus indicating success or failure.
*/
extern OSStatus
AudioHardwareCreateAggregateDevice( CFDictionaryRef inDescription,
AudioObjectID* outDeviceID) __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
/*!
@function AudioHardwareDestroyAggregateDevice
@abstract This routine destroys the given AudioAggregateDevice.
@discussion The actual destruction of the device is asynchronous and may take place after
the call to this routine has returned.
@param inDeviceID
The AudioObjectID of the AudioAggregateDevice to destroy.
@result An OSStatus indicating success or failure.
*/
extern OSStatus
AudioHardwareDestroyAggregateDevice(AudioObjectID inDeviceID) __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
//==================================================================================================
#pragma mark -
#pragma mark AudioPlugIn Properties
/*!
@enum AudioPlugIn Properties
@abstract AudioObjectPropertySelector values provided by the AudioPlugIn class.
@discussion The AudioPlugIn class is a subclass of the AudioObject class. the class has just
the global scope, kAudioObjectPropertyScopeGlobal, and only a master element.
@constant kAudioPlugInCreateAggregateDevice
This property is used to tell a plug-in to create a new
AudioAggregateDevice. Its 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.
@constant 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.
*/
CF_ENUM(AudioObjectPropertySelector)
{
kAudioPlugInCreateAggregateDevice = 'cagg',
kAudioPlugInDestroyAggregateDevice = 'dagg'
};
//==================================================================================================
#pragma mark -
#pragma mark AudioTransportManager Properties
/*!
@enum AudioTransportManager Properties
@abstract AudioObjectPropertySelector values provided by the AudioTransportManager class.
@discussion The AudioTransportManager class is a subclass of the AudioPlugIn class. The
class has just the global scope, kAudioObjectPropertyScopeGlobal, and only a
master element.
@constant kAudioTransportManagerCreateEndPointDevice
This property is used to tell a transport manager to create a new
AudioDevice. Its value is only read. The qualifier data for this
property is a CFDictionary containing a description of the
AudioDevice to create. The standard keys for the CFDictionary are defined in
the AudioEndPointDevice Constants section. The value of the property that
gets returned is the AudioObjectID of the newly created device.
@constant kAudioTransportManagerDestroyEndPointDevice
This property is used to tell a transport manager to destroy an AudioDevice.
Like kAudioTransportManagerCreateDevice, this property is read only. The
value of the property is the AudioObjectID of the AudioAggregateDevice to
destroy.
*/
CF_ENUM(AudioObjectPropertySelector)
{
kAudioTransportManagerCreateEndPointDevice = 'cdev',
kAudioTransportManagerDestroyEndPointDevice = 'ddev'
};
//==================================================================================================
#pragma mark -
#pragma mark AudioDevice Types
/*!
@typedef AudioDeviceIOProc
@abstract 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.
@param inDevice
The AudioDevice doing the IO.
@param 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.
@param 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.
@param 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.
@param 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.
@param 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.
@param inClientData
A pointer to client data established when the AudioDeviceIOProc was
registered with the AudioDevice.
@result The return value is currently unused and should always be 0.
*/
typedef OSStatus
(*AudioDeviceIOProc)( AudioObjectID inDevice,
const AudioTimeStamp* inNow,
const AudioBufferList* inInputData,
const AudioTimeStamp* inInputTime,
AudioBufferList* outOutputData,
const AudioTimeStamp* inOutputTime,
void* __nullable inClientData);
/*!
@typedef AudioDeviceIOBlock
@abstract An AudioDeviceIOBlock 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.
@param 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.
@param 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.
@param 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.
@param 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.
@param 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.
*/
typedef void
(^AudioDeviceIOBlock)( const AudioTimeStamp* inNow,
const AudioBufferList* inInputData,
const AudioTimeStamp* inInputTime,
AudioBufferList* outOutputData,
const AudioTimeStamp* inOutputTime);
/*!
@typedef AudioDeviceIOProcID
@abstract An AudioDeviceIOProcID represents both an IOProc and the client data that goes
with it. Once created, an AudioDeviceIOProcID can be used everywhere one would
use a regular IOProc. The purpose for an AudioDeviceIOProcID is to allow a
client to register the same function pointer as an IOProc with a device multiple
times provided
*/
typedef AudioDeviceIOProc AudioDeviceIOProcID;
/*!
@struct AudioHardwareIOProcStreamUsage
@abstract This structure describes which streams a given AudioDeviceIOProc will use. It is
used in conjunction with kAudioDevicePropertyIOProcStreamUsage.
@field mIOProc
The IOProc whose stream usage is being specified.
@field mNumberStreams
The number of streams being specified.
@field 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.
*/
struct AudioHardwareIOProcStreamUsage
{
void* mIOProc;
UInt32 mNumberStreams;
UInt32 mStreamIsOn[1];
};
typedef struct AudioHardwareIOProcStreamUsage AudioHardwareIOProcStreamUsage;
//==================================================================================================
#pragma mark AudioDevice Constants
/*!
@enum StartAtTime/GetNearestStartTime Flags
@abstract The flags that can be passed to control the behavior of AudioDeviceStartAtTime()
andAudioDeviceGetNearestStartTime().
@constant kAudioDeviceStartTimeIsInputFlag
Set to indicate that the requested time refers to an input time. Clear to
indicate that it is an output time.
@constant 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.
@constant 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.
*/
CF_ENUM(UInt32)
{
kAudioDeviceStartTimeIsInputFlag = (1 << 0),
kAudioDeviceStartTimeDontConsultDeviceFlag = (1 << 1),
kAudioDeviceStartTimeDontConsultHALFlag = (1 << 2)
};
//==================================================================================================
#pragma mark AudioDevice Properties
/*!
@enum AudioDevice Properties
@abstract AudioObjectPropertySelector values provided by the AudioDevice class.
@discussion The AudioDevice class is a subclass of the AudioObjectClass. The class has four
scopes, kAudioObjectPropertyScopeGlobal, kAudioObjectPropertyScopeInput,
kAudioObjectPropertyScopeOutput, and kAudioObjectPropertyScopePlayThrough. The
class has a master element and an element for each channel in each stream
numbered according to the starting channel number of each stream.
@constant 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.
@constant kAudioDevicePropertyDeviceHasChanged
The type of this property is a UInt32, but its 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.
@constant 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.
@constant 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 its deadline. Note that the notification for this property is
usually sent from the AudioDevice's IO thread.
@constant kAudioDevicePropertyIOStoppedAbnormally
A UInt32 where the value has no meaning. This property exists so that
clients can be notified when IO on the device has stopped outside of the
normal mechanisms. This typically comes up when IO is stopped after
AudioDeviceStart has returned successfully but prior to the notification for
kAudioDevicePropertyIsRunning being sent.
@constant 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.
Note that when setting this property, the value passed in is ignored. If
another process owns exclusive access, that remains unchanged. If the
current process owns exclusive access, it is released and made available to
all processes again. If no process has exclusive access (meaning the current
value is -1), this process gains ownership of exclusive access. On return,
the pid_t pointed to by inPropertyData will contain the new value of the
property.
@constant kAudioDevicePropertyBufferFrameSize
A UInt32 whose value indicates the number of frames in the IO buffers.
@constant kAudioDevicePropertyBufferFrameSizeRange
An AudioValueRange indicating the minimum and maximum values, inclusive, for
kAudioDevicePropertyBufferFrameSize.
@constant 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.
@constant 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.
@constant 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.
@constant 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 its 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.
@constant kAudioDevicePropertyActualSampleRate
A Float64 that indicates the current actual sample rate of the AudioDevice
as measured by its time stamps.
@constant kAudioDevicePropertyClockDevice
A CFString that contains the UID for the AudioClockDevice that is currently
serving as the master time base of the device. The caller is responsible
for releasing the returned CFObject.
*/
CF_ENUM(AudioObjectPropertySelector)
{
kAudioDevicePropertyPlugIn = 'plug',
kAudioDevicePropertyDeviceHasChanged = 'diff',
kAudioDevicePropertyDeviceIsRunningSomewhere = 'gone',
kAudioDeviceProcessorOverload = 'over',
kAudioDevicePropertyIOStoppedAbnormally = 'stpd',
kAudioDevicePropertyHogMode = 'oink',
kAudioDevicePropertyBufferFrameSize = 'fsiz',
kAudioDevicePropertyBufferFrameSizeRange = 'fsz#',
kAudioDevicePropertyUsesVariableBufferFrameSizes = 'vfsz',
kAudioDevicePropertyIOCycleUsage = 'ncyc',
kAudioDevicePropertyStreamConfiguration = 'slay',
kAudioDevicePropertyIOProcStreamUsage = 'suse',
kAudioDevicePropertyActualSampleRate = 'asrt',
kAudioDevicePropertyClockDevice = 'apcd'
};
/*!
@enum AudioDevice Properties Implemented via AudioControl objects
@abstract AudioObjectPropertySelector values for AudioDevice properties that are
implemented by AudioControl objects.
@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.
@constant 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.
@constant kAudioDevicePropertyVolumeScalar
A Float32 that represents the value of the volume control. The range is
between 0.0 and 1.0 (inclusive). Note that the set of all Float32 values
between 0.0 and 1.0 inclusive is much larger than the set of actual values
that the hardware can select. This means that the Float32 range has a many
to one mapping with the underlying hardware values. As such, setting a
scalar value will result in the control taking on the value nearest to what
was set. This property is implemented by an AudioControl object that is a
subclass of AudioVolumeControl.
@constant kAudioDevicePropertyVolumeDecibels
A Float32 that represents the value of the volume control in dB. Note that
the set of all Float32 values in the dB range for the control is much larger
than the set of actual values that the hardware can select. This means that
the Float32 range has a many to one mapping with the underlying hardware
values. As such, setting a dB value will result in the control taking on the
value nearest to what was set. This property is implemented by an
AudioControl object that is a subclass of AudioVolumeControl.
@constant 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.
@constant 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.
@constant 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.
@constant 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.
@constant 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.
@constant 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.
@constant 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.
@constant kAudioDevicePropertyPhantomPower
A UInt32 where a value of 1 means that the AudioDevice has enabled phantom
power for the given element. The property is implemented by an AudioControl
object that is a subclass of AudioPhantomPowerControl.
@constant kAudioDevicePropertyPhaseInvert
A UInt32 where a value of 1 means that phase of the signal for the given
element has been flipped 180 degrees. The property is implemented by an
AudioControl object that is a subclass of AudioPhaseInvertControl.
@constant kAudioDevicePropertyClipLight
A UInt32 where a value of 1 means that the signal for the element has
exceeded the sample range. Once a clip light is turned on, it is to stay on
until either the value of the control is set to false or the current IO
session stops and a new IO session starts. The property is implemented by an
AudioControl object that is a subclass of AudioClipLightControl.
@constant kAudioDevicePropertyTalkback
A UInt32 where a value of 1 means that the talkback channel is enabled. The
property is implemented by an AudioControl object that is a subclass of
AudioTalkbackControl.
@constant kAudioDevicePropertyListenback
A UInt32 where a value of 1 means that the listenback channel is enabled.
The property is implemented by an AudioControl object that is a subclass of
AudioListenbackControl.
@constant kAudioDevicePropertyDataSource
An array of UInt32s whose values are the item IDs for the currently selected
data sources. This property is implemented by an AudioControl object that is
a subclass of AudioDataSourceControl.
@constant 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.
@constant 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.
@constant kAudioDevicePropertyDataSourceKindForID
This property returns a UInt32 that identifies the kind of data 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.
@constant kAudioDevicePropertyClockSource
An array of UInt32s whose values are the item IDs for the currently selected
clock sources. This property is implemented by an AudioControl object that
is a subclass of AudioClockControl.
@constant 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.
@constant 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.
@constant 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.
@constant 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.
@constant 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.
@constant kAudioDevicePropertyPlayThruVolumeScalar
A Float32 that represents the value of the volume control. The range is
between 0.0 and 1.0 (inclusive). Note that the set of all Float32 values
between 0.0 and 1.0 inclusive is much larger than the set of actual values
that the hardware can select. This means that the Float32 range has a many
to one mapping with the underlying hardware values. As such, setting a
scalar value will result in the control taking on the value nearest to what
was set. 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.
@constant kAudioDevicePropertyPlayThruVolumeDecibels
A Float32 that represents the value of the volume control in dB. Note that
the set of all Float32 values in the dB range for the control is much larger
than the set of actual values that the hardware can select. This means that
the Float32 range has a many to one mapping with the underlying hardware
values. As such, setting a dB value will result in the control taking on the
value nearest to what was set. 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.
@constant 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.
@constant 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.
@constant 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.
@constant 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.
@constant 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.
@constant kAudioDevicePropertyPlayThruDestination
An array of UInt32s whose values are the item IDs for the currently selected
play through data destinations. 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.
@constant 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.
@constant 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.
@constant kAudioDevicePropertyChannelNominalLineLevel
An array of UInt32s whose values are the item IDs for the currently selected
nominal line levels. This property is implemented by an AudioControl object
that is a subclass of AudioLineLevelControl.
@constant 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.
@constant 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.
@constant kAudioDevicePropertyHighPassFilterSetting
An array of UInt32s whose values are the item IDs for the currently selected
high pass filter setting. This property is implemented by an AudioControl
object that is a subclass of AudioHighPassFilterControl.
@constant kAudioDevicePropertyHighPassFilterSettings
An array of UInt32s that represent all the IDs of all the high pass filter
settings currently available. This property is implemented by an
AudioControl object that is a subclass of AudioHighPassFilterControl.
@constant kAudioDevicePropertyHighPassFilterSettingNameForIDCFString
This property translates the given high pass filter setting 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
AudioHighPassFilterControl.
@constant kAudioDevicePropertySubVolumeScalar
A Float32 that represents the value of the LFE volume control. The range is
between 0.0 and 1.0 (inclusive). Note that the set of all Float32 values
between 0.0 and 1.0 inclusive is much larger than the set of actual values
that the hardware can select. This means that the Float32 range has a many
to one mapping with the underlying hardware values. As such, setting a
scalar value will result in the control taking on the value nearest to what
was set. This property is implemented by an AudioControl object that is a
subclass of AudioLFEVolumeControl.
@constant kAudioDevicePropertySubVolumeDecibels
A Float32 that represents the value of the LFE volume control in dB. Note
that the set of all Float32 values in the dB range for the control is much
larger than the set of actual values that the hardware can select. This
means that the Float32 range has a many to one mapping with the underlying
hardware values. As such, setting a dB value will result in the control
taking on the value nearest to what was set. This property is implemented by
an AudioControl object that is a subclass of AudioLFE VolumeControl.
@constant 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.
@constant 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.
@constant 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.
@constant 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.
*/
CF_ENUM(AudioObjectPropertySelector)
{
kAudioDevicePropertyJackIsConnected = 'jack',
kAudioDevicePropertyVolumeScalar = 'volm',
kAudioDevicePropertyVolumeDecibels = 'vold',
kAudioDevicePropertyVolumeRangeDecibels = 'vdb#',
kAudioDevicePropertyVolumeScalarToDecibels = 'v2db',
kAudioDevicePropertyVolumeDecibelsToScalar = 'db2v',
kAudioDevicePropertyStereoPan = 'span',
kAudioDevicePropertyStereoPanChannels = 'spn#',
kAudioDevicePropertyMute = 'mute',
kAudioDevicePropertySolo = 'solo',
kAudioDevicePropertyPhantomPower = 'phan',
kAudioDevicePropertyPhaseInvert = 'phsi',
kAudioDevicePropertyClipLight = 'clip',
kAudioDevicePropertyTalkback = 'talb',
kAudioDevicePropertyListenback = 'lsnb',
kAudioDevicePropertyDataSource = 'ssrc',
kAudioDevicePropertyDataSources = 'ssc#',
kAudioDevicePropertyDataSourceNameForIDCFString = 'lscn',
kAudioDevicePropertyDataSourceKindForID = 'ssck',
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',
kAudioDevicePropertyHighPassFilterSetting = 'hipf',
kAudioDevicePropertyHighPassFilterSettings = 'hip#',
kAudioDevicePropertyHighPassFilterSettingNameForIDCFString = 'hipl',
kAudioDevicePropertySubVolumeScalar = 'svlm',
kAudioDevicePropertySubVolumeDecibels = 'svld',
kAudioDevicePropertySubVolumeRangeDecibels = 'svd#',
kAudioDevicePropertySubVolumeScalarToDecibels = 'sv2d',
kAudioDevicePropertySubVolumeDecibelsToScalar = 'sd2v',
kAudioDevicePropertySubMute = 'smut'
};
//==================================================================================================
#pragma mark AudioDevice Functions
/*!
@functiongroup AudioDevice
*/
/*!
@function AudioDeviceCreateIOProcID
@abstract Creates an AudioDeviceIOProcID from an AudioDeviceIOProc and a client data
pointer.
@discussion AudioDeviceIOProcIDs allow for the client to register the same function pointer
with a device multiple times
@param inDevice
The AudioDevice to register the IOProc with.
@param inProc
The AudioDeviceIOProc to register.
@param inClientData
A pointer to client data that is passed back to the IOProc when it is
called.
@param outIOProcID
The newly created AudioDeviceIOProcID.
@result An OSStatus indicating success or failure.
*/
extern OSStatus
AudioDeviceCreateIOProcID( AudioObjectID inDevice,
AudioDeviceIOProc inProc,
void* __nullable inClientData,
AudioDeviceIOProcID __nullable * __nonnull outIOProcID) __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_2_0);
/*!
@function AudioDeviceCreateIOProcIDWithBlock
@abstract Creates an AudioDeviceIOProcID from an AudioDeviceIOBlock
@param outIOProcID
The newly created AudioDeviceIOProcID.
@param inDevice
The AudioDevice to register the Block with.
@param inDispatchQueue
The dispatch queue on which the IOBlock will be dispatched. All
IOBlocks are dispatched synchronously. Note that this dispatch queue will be
retained until a matching call to AudioDeviceDestroyIOProcID is made. If
this value is NULL, then the IOBlock will be directly invoked.
@param inBlock
The AudioDeviceIOBlock to register. Note that this block will be
Block_copy'd and the reference maintained until a matching call to
AudioDeviceDestroyIOProcID is made.
@result An OSStatus indicating success or failure.
*/
extern OSStatus
AudioDeviceCreateIOProcIDWithBlock( AudioDeviceIOProcID __nullable * __nonnull outIOProcID,
AudioObjectID inDevice,
dispatch_queue_t __nullable inDispatchQueue,
AudioDeviceIOBlock inIOBlock) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
/*!
@function AudioDeviceDestroyIOProcID
@abstract Destroys an AudioDeviceIOProcID.
@discussion AudioDeviceIOProcIDs allow for the client to register the same function pointer
with a device multiple times
@param inDevice
The AudioDevice from which the ID came.
@param inIOProcID
The AudioDeviceIOProcID to get rid of.
@result An OSStatus indicating success or failure.
*/
extern OSStatus
AudioDeviceDestroyIOProcID( AudioObjectID inDevice,
AudioDeviceIOProcID inIOProcID) __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_2_0);
/*!
@function AudioDeviceStart
@abstract Starts IO for the given AudioDeviceIOProcID.
@param inDevice
The AudioDevice to start the IOProc on.
@param inProcID
The AudioDeviceIOProcID 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.
@result An OSStatus indicating success or failure.
*/
extern OSStatus
AudioDeviceStart( AudioObjectID inDevice,
AudioDeviceIOProcID __nullable inProcID) __OSX_AVAILABLE_STARTING(__MAC_10_0, __IPHONE_2_0);
/*!
@function AudioDeviceStartAtTime
@abstract Starts IO for the given AudioDeviceIOProcID and aligns the IO cycle of the
AudioDevice with the given time.
@param inDevice
The AudioDevice to start the IOProc on.
@param inProcID
The AudioDeviceIOProcID to start. Note that this can be NULL, which starts
the hardware regardless of whether or not there are any IOProcs registered.
@param 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.
@param inFlags
A UInt32 containing flags that modify how this function behaves.
@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.
*/
extern OSStatus
AudioDeviceStartAtTime( AudioObjectID inDevice,
AudioDeviceIOProcID __nullable inProcID,
AudioTimeStamp* ioRequestedStartTime,
UInt32 inFlags) __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0);
/*!
@function AudioDeviceStop
@abstract Stops IO for the given AudioDeviceIOProcID.
@param inDevice
The AudioDevice to stop the IOProc on.
@param inProcID
The AudioDeviceIOProcID to stop.
@result An OSStatus indicating success or failure.
*/
extern OSStatus
AudioDeviceStop( AudioObjectID inDevice,
AudioDeviceIOProcID __nullable inProcID) __OSX_AVAILABLE_STARTING(__MAC_10_0, __IPHONE_2_0);
/*!
@function AudioDeviceGetCurrentTime
@abstract Retrieves the current time from an AudioDevice. Note that the device has to be
running.
@param inDevice
The AudioDevice to from which to get the time.
@param outTime
An AudioTimeStamp into which the current time is put. On entry, the
mFlags field specifies which representations to provide. Because not every
device supports all time representations, on exit, the mFlags field will
indicate what values are actually valid.
@result An OSStatus indicating success or failure. kAudioHardwareNotRunningError will be
returned if the AudioDevice isn't running.
*/
extern OSStatus
AudioDeviceGetCurrentTime( AudioObjectID inDevice,
AudioTimeStamp* outTime) __OSX_AVAILABLE_STARTING(__MAC_10_0, __IPHONE_2_0);
/*!
@function AudioDeviceTranslateTime
@abstract Translates the time in the AudioDevice's time base from one representation to
another. Note that the device has to be running
@param inDevice
The AudioDevice whose time base governs the translation.
@param inTime
An AudioTimeStamp containing the time to be translated.
@param 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.
@result An OSStatus indicating success or failure. kAudioHardwareNotRunningError will be
returned if the AudioDevice isn't running.
*/
extern OSStatus
AudioDeviceTranslateTime( AudioObjectID inDevice,
const AudioTimeStamp* inTime,
AudioTimeStamp* outTime) __OSX_AVAILABLE_STARTING(__MAC_10_0, __IPHONE_2_0);
/*!
@function AudioDeviceGetNearestStartTime
@abstract Query an AudioDevice to get a time equal to or later than the given time that is
the best time to start IO.
@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.
@param inDevice
The AudioDevice to query.
@param 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.
@param inFlags
A UInt32 containing flags that modify how this function behaves.
@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.
*/
extern OSStatus
AudioDeviceGetNearestStartTime( AudioObjectID inDevice,
AudioTimeStamp* ioRequestedStartTime,
UInt32 inFlags) __OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0);
//==================================================================================================
#pragma mark -
#pragma mark AudioAggregateDevice Constants
/*!
@enum AudioAggregateDevice Class Constants
@abstract Various constants related to the AudioAggregateDevice class.
@constant kAudioAggregateDeviceClassID
The AudioClassID that identifies the AudioAggregateDevice class.
*/
CF_ENUM(AudioClassID)
{
kAudioAggregateDeviceClassID = 'aagg'
};
/*!
@defined kAudioAggregateDeviceUIDKey
@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 kAudioAggregateDeviceUIDKey "uid"
/*!
@defined kAudioAggregateDeviceNameKey
@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 kAudioAggregateDeviceNameKey "name"
/*!
@defined kAudioAggregateDeviceSubDeviceListKey
@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 kAudioAggregateDeviceSubDeviceListKey "subdevices"
/*!
@defined kAudioAggregateDeviceMasterSubDeviceKey
@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 kAudioAggregateDeviceMasterSubDeviceKey "master"
/*!
@defined kAudioAggregateDeviceClockDeviceKey
@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 clock device that is the master time source for the
AudioAggregateDevice. If the aggregate device includes both a master audio
device and a clock device, the clock device will control the master time base.
*/
#define kAudioAggregateDeviceClockDeviceKey "clock"
/*!
@defined kAudioAggregateDeviceIsPrivateKey
@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 kAudioAggregateDeviceIsPrivateKey "private"
/*!
@defined kAudioAggregateDeviceIsStackedKey
@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 sub-devices of the AudioAggregateDevice are arranged such that
the output streams are all fed the same data.
*/
#define kAudioAggregateDeviceIsStackedKey "stacked"
//==================================================================================================
#pragma mark AudioAggregateDevice Properties
/*!
@enum AudioAggregateDevice Properties
@abstract AudioObjectPropertySelector values provided by the AudioAggregateDevice class.
@discussion AudioAggregateDevice is a subclass of AudioDevice and has the same scope and
element structure.
@constant 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.
@constant kAudioAggregateDevicePropertyActiveSubDeviceList
An array of AudioObjectIDs for all the active sub-devices in the aggregate
device.
@constant kAudioAggregateDevicePropertyComposition
A CFDictionary that describes the composition of the AudioAggregateDevice.
The keys for this CFDicitionary are defined in the AudioAggregateDevice
Constants section. The caller is responsible for releasing the returned
CFObject.
@constant kAudioAggregateDevicePropertyMasterSubDevice
A CFString that contains the UID for the AudioDevice that is currently
serving as the master time base of the aggregate device. The caller is
responsible for releasing the returned CFObject.
@constant kAudioAggregateDevicePropertyClockDevice
A CFString that contains the UID for the AudioClockDevice that is currently
serving as the master time base of the aggregate device. If the aggregate
device includes both a master audio device and a clock device, the clock
device will control the master time base. Setting this property will enable
drift correction for all subdevices in the aggregate device. The caller is
responsible for releasing the returned CFObject.
*/
CF_ENUM(AudioObjectPropertySelector)
{
kAudioAggregateDevicePropertyFullSubDeviceList = 'grup',
kAudioAggregateDevicePropertyActiveSubDeviceList = 'agrp',
kAudioAggregateDevicePropertyComposition = 'acom',
kAudioAggregateDevicePropertyMasterSubDevice = 'amst',
kAudioAggregateDevicePropertyClockDevice = 'apcd'
};
//==================================================================================================
#pragma mark -
#pragma mark AudioSubDevice Constants
/*!
@enum AudioSubDevice Class Constants
@abstract Various constants related to the AudioSubDevice class.
@constant kAudioSubDeviceClassID
The AudioClassID that identifies the AudioSubDevice class.
*/
CF_ENUM(AudioClassID)
{
kAudioSubDeviceClassID = 'asub'
};
/*!
@enum AudioSubDevice Clock Drift Compensation Methods
@abstract 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.
*/
CF_ENUM(UInt32)
{
kAudioSubDeviceDriftCompensationMinQuality = 0,
kAudioSubDeviceDriftCompensationLowQuality = 0x20,
kAudioSubDeviceDriftCompensationMediumQuality = 0x40,
kAudioSubDeviceDriftCompensationHighQuality = 0x60,
kAudioSubDeviceDriftCompensationMaxQuality = 0x7F
};
/*!
@defined kAudioSubDeviceUIDKey
@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.
*/
#define kAudioSubDeviceUIDKey "uid"
/*!
@defined kAudioAggregateDeviceSubDeviceNameKey
@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 human readable
name of the AudioSubDevice.
*/
#define kAudioSubDeviceNameKey "name"
/*!
@defined kAudioSubDeviceInputChannelsKey
@discussion The key used in a CFDictionary that describes the state of an AudioSubDevice.
The value for this key is a CFNumber that indicates the total number of input
channels for the AudioSubDevice.
*/
#define kAudioSubDeviceInputChannelsKey "channels-in"
/*!
@defined kAudioSubDeviceOutputChannelsKey
@discussion The key used in a CFDictionary that describes the state of an AudioSubDevice.
The value for this key is a CFNumber that indicates the total number of output
channels for the AudioSubDevice.
*/
#define kAudioSubDeviceOutputChannelsKey "channels-out"
/*!
@defined kAudioSubDeviceExtraInputLatencyKey
@discussion The key used in a CFDictionary that describes the state of an AudioSubDevice.
The value for this key is a CFNumber that indicates the total number of frames
of additional latency that will be added to the input side of the
AudioSubDevice.
*/
#define kAudioSubDeviceExtraInputLatencyKey "latency-in"
/*!
@defined kAudioSubDeviceExtraOutputLatencyKey
@discussion The key used in a CFDictionary that describes the state of an AudioSubDevice.
The value for this key is a CFNumber that indicates the total number of frames
of additional latency that will be added to the output side of the
AudioSubDevice.
*/
#define kAudioSubDeviceExtraOutputLatencyKey "latency-out"
/*!
@defined kAudioSubDeviceDriftCompensationKey
@discussion The key used in a CFDictionary that describes the state of an AudioSubDevice.
The value for this key is a CFNumber where a non-zero value indicates that drift
compensation is enabled for the AudioSubDevice
*/
#define kAudioSubDeviceDriftCompensationKey "drift"
/*!
@defined kAudioSubDeviceDriftCompensationQualityKey
@discussion The key used in a CFDictionary that describes the state of an AudioSubDevice.
The value for this key is a CFNumber that indicates the quality of the drifty
compensation for the AudioSubDevice
*/
#define kAudioSubDeviceDriftCompensationQualityKey "drift quality"
//==================================================================================================
#pragma mark AudioSubDevice Properties
/*!
@enum AudioSubDevice Properties
@abstract AudioObjectPropertySelector values provided by the AudioSubDevice class.
@discussion The AudioSubDevice class is a subclass of AudioDevice class and has the same
scope and element structure. However, AudioSubDevice objects do not implement an
IO path of their own and as such do not implement any AudioDevice properties
associated with the IO path. They also don't have any streams.
@constant kAudioSubDevicePropertyExtraLatency
A Float64 indicating the number of sample frames to add to or subtract from
the latency compensation used for this AudioSubDevice.
@constant 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.
@constant 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.
*/
CF_ENUM(AudioObjectPropertySelector)
{
kAudioSubDevicePropertyExtraLatency = 'xltc',
kAudioSubDevicePropertyDriftCompensation = 'drft',
kAudioSubDevicePropertyDriftCompensationQuality = 'drfq'
};
//==================================================================================================
#if defined(__cplusplus)
}
#endif
CF_ASSUME_NONNULL_END
//==================================================================================================
#include <CoreAudio/AudioHardwareDeprecated.h>
#endif // CoreAudio_AudioHardware_h
Raw
AudioHardwareBase.h
/*==================================================================================================
File: CoreAudio/AudioHardwareBase.h
Copyright: (c) 1985-2011 by Apple, Inc., all rights reserved.
Bugs?: For bug reports, consult the following page on
the World Wide Web:
http://developer.apple.com/bugreporter/
==================================================================================================*/
#if !defined(CoreAudio_AudioHardwareBase_h)
#define CoreAudio_AudioHardwareBase_h
//==================================================================================================
#pragma mark -
#pragma mark Overview
/*!
@header AudioHardwareBase
This file defines the HAL's object model including the properties and their needed types and
constants that describe the property values.
*/
//==================================================================================================
// Includes
#include <CoreAudio/CoreAudioTypes.h>
//==================================================================================================
CF_ASSUME_NONNULL_BEGIN
#if defined(__cplusplus)
extern "C"
{
#endif
//==================================================================================================
#pragma mark -
#pragma mark Basic Types
/*!
@typedef AudioObjectID
@abstract A UInt32 that provides a handle on a specific AudioObject.
*/
typedef UInt32 AudioObjectID;
/*!
@typedef AudioClassID
@abstract AudioClassIDs are used to identify the class of an AudioObject.
*/
typedef UInt32 AudioClassID;
/*!
@typedef AudioObjectPropertySelector
@abstract An AudioObjectPropertySelector is a four char code that identifies, along with
the AudioObjectPropertyScope and AudioObjectPropertyElement, a specific piece of
information about an AudioObject.
@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 its super class's set of selectors, although
it may not implement them all.
*/
typedef UInt32 AudioObjectPropertySelector;
/*!
@typedef AudioObjectPropertyScope
@abstract An AudioObjectPropertyScope is a four char code that identifies, along with the
AudioObjectPropertySelector and AudioObjectPropertyElement, a specific piece of
information about an AudioObject.
@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 its superclass's set of scopes.
*/
typedef UInt32 AudioObjectPropertyScope;
/*!
@typedef AudioObjectPropertyElement
@abstract An AudioObjectPropertyElement is an integer that identifies, along with the
AudioObjectPropertySelector and AudioObjectPropertyScope, a specific piece of
information about an AudioObject.
@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.
*/
typedef UInt32 AudioObjectPropertyElement;
/*!
@struct AudioObjectPropertyAddress
@abstract An AudioObjectPropertyAddress collects the three parts that identify a specific
property together in a struct for easy transmission.
@field mSelector
The AudioObjectPropertySelector for the property.
@field mScope
The AudioObjectPropertyScope for the property.
@field mElement
The AudioObjectPropertyElement for the property.
*/
struct AudioObjectPropertyAddress
{
AudioObjectPropertySelector mSelector;
AudioObjectPropertyScope mScope;
AudioObjectPropertyElement mElement;
};
typedef struct AudioObjectPropertyAddress AudioObjectPropertyAddress;
//==================================================================================================
#pragma mark Basic Constants
/*!
@enum Error Constants
@abstract The error constants unique to the HAL.
@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.
@constant kAudioHardwareNoError
The function call completed successfully.
@constant kAudioHardwareNotRunningError
The function call requires that the hardware be running but it isn't.
@constant kAudioHardwareUnspecifiedError
The function call failed while doing something that doesn't provide any
error messages.
@constant kAudioHardwareUnknownPropertyError
The AudioObject doesn't know about the property at the given address.
@constant kAudioHardwareBadPropertySizeError
An improperly sized buffer was provided when accessing the data of a
property.
@constant kAudioHardwareIllegalOperationError
The requested operation couldn't be completed.
@constant kAudioHardwareBadObjectError
The AudioObjectID passed to the function doesn't map to a valid AudioObject.
@constant kAudioHardwareBadDeviceError
The AudioObjectID passed to the function doesn't map to a valid AudioDevice.
@constant kAudioHardwareBadStreamError
The AudioObjectID passed to the function doesn't map to a valid AudioStream.
@constant kAudioHardwareUnsupportedOperationError
The AudioObject doesn't support the requested operation.
@constant kAudioDeviceUnsupportedFormatError
The AudioStream doesn't support the requested format.
@constant kAudioDevicePermissionsError
The requested operation can't be completed because the process doesn't have
permission.
*/
CF_ENUM(OSStatus)
{
kAudioHardwareNoError = 0,
kAudioHardwareNotRunningError = 'stop',
kAudioHardwareUnspecifiedError = 'what',
kAudioHardwareUnknownPropertyError = 'who?',
kAudioHardwareBadPropertySizeError = '!siz',
kAudioHardwareIllegalOperationError = 'nope',
kAudioHardwareBadObjectError = '!obj',
kAudioHardwareBadDeviceError = '!dev',
kAudioHardwareBadStreamError = '!str',
kAudioHardwareUnsupportedOperationError = 'unop',
kAudioDeviceUnsupportedFormatError = '!dat',
kAudioDevicePermissionsError = '!hog'
};
/*!
@enum Predefined AudioObjectID values
@abstract ObjectIDs that are always the same
@constant kAudioObjectUnknown
This is the sentinel value. No object will have an ID whose value is 0.
*/
CF_ENUM(AudioObjectID)
{
kAudioObjectUnknown = 0
};
/*!
@enum Property Address Constants
@abstract The valid values for the scope in a property address.
@constant kAudioObjectPropertyScopeGlobal
The AudioObjectPropertyScope for properties that apply to the object as a
whole. All objects have a global scope and for most it is their only scope.
@constant kAudioObjectPropertyScopeInput
The AudioObjectPropertyScope for properties that apply to the input side of
an object.
@constant kAudioObjectPropertyScopeOutput
The AudioObjectPropertyScope for properties that apply to the output side of
an object.
@constant kAudioObjectPropertyScopePlayThrough
The AudioObjectPropertyScope for properties that apply to the play through
side of an object.
@constant kAudioObjectPropertyElementMaster
The AudioObjectPropertyElement value for properties that apply to the master
element or to the entire scope.
*/
CF_ENUM(AudioObjectPropertyScope)
{
kAudioObjectPropertyScopeGlobal = 'glob',
kAudioObjectPropertyScopeInput = 'inpt',
kAudioObjectPropertyScopeOutput = 'outp',
kAudioObjectPropertyScopePlayThrough = 'ptru',
kAudioObjectPropertyElementMaster = 0
};
/*!
@enum Wildcard Constants
@abstract Constants that are used as wildcards.
@discussion Wildcards match any and all values for their associated type. They are useful
when registering to receive notifications.
@constant kAudioObjectPropertySelectorWildcard
The wildcard value for AudioObjectPropertySelectors.
@constant kAudioObjectPropertyScopeWildcard
The wildcard value for AudioObjectPropertyScopes.
@constant kAudioObjectPropertyElementWildcard
The wildcard value for AudioObjectPropertyElements.
@constant kAudioObjectClassIDWildcard
The wildcard value for AudioClassIDs.
*/
CF_ENUM(AudioObjectPropertySelector)
{
kAudioObjectPropertySelectorWildcard = '****'
};
CF_ENUM(AudioObjectPropertyScope)
{
kAudioObjectPropertyScopeWildcard = '****'
};
CF_ENUM(AudioObjectPropertyElement)
{
kAudioObjectPropertyElementWildcard = 0xFFFFFFFF
};
CF_ENUM(AudioClassID)
{
kAudioObjectClassIDWildcard = '****'
};
//==================================================================================================
#pragma mark -
#pragma mark AudioObject Constants
/*!
@enum AudioObject Class Constants
@abstract Various constants related to the AudioObject class.
@discussion The AudioObject class is the base class for all classes.
@constant kAudioObjectClassID
The AudioClassID that identifies the AudioObject class.
*/
CF_ENUM(AudioClassID)
{
kAudioObjectClassID = 'aobj'
};
//==================================================================================================
#pragma mark AudioObject Properties
/*!
@enum AudioObject Property Selectors
@abstract AudioObjectPropertySelector values provided by objects of the AudioObject class.
@discussion The AudioObject class is the base class for all classes. As such, all classes
inherit this set of properties.
@constant kAudioObjectPropertyBaseClass
An AudioClassID that identifies the class from which the class of the
AudioObject is derived. This value must always be one of the standard
classes.
@constant kAudioObjectPropertyClass
An AudioClassID that identifies the class of the AudioObject.
@constant 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.
@constant kAudioObjectPropertyName
A CFString that contains the human readable name of the object. The caller
is responsible for releasing the returned CFObject.
@constant kAudioObjectPropertyModelName
A CFString that contains the human readable model name of the object. The
model name differs from kAudioObjectPropertyName in that two objects of the
same model will have the same value for this property but may have different
values for kAudioObjectPropertyName.
@constant 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.
@constant 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.
@constant 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.
@constant 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.
@constant 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.
@constant kAudioObjectPropertyIdentify
A UInt32 where a value of one indicates that the object's hardware is
drawing attention to itself, typically by flashing or lighting up its front
panel display. A value of 0 indicates that this function is turned off. This
makes it easy for a user to associate the physical hardware with its
representation in an application. Typically, this property is only supported
by AudioDevices and AudioBoxes.
@constant kAudioObjectPropertySerialNumber
A CFString that contains the human readable serial number for the object.
This property will typically be implemented by AudioBox and AudioDevice
objects. Note that the serial number is not defined to be unique in the same
way that an AudioBox's or AudioDevice's UID property are defined. This is
purely an informational value. The caller is responsible for releasing the
returned CFObject.
@constant kAudioObjectPropertyFirmwareVersion
A CFString that contains the human readable firmware version for the object.
This property will typically be implemented by AudioBox and AudioDevice
objects. Note that this is purely an informational value. The caller is
responsible for releasing the returned CFObject.
*/
CF_ENUM(AudioObjectPropertySelector)
{
kAudioObjectPropertyBaseClass = 'bcls',
kAudioObjectPropertyClass = 'clas',
kAudioObjectPropertyOwner = 'stdv',
kAudioObjectPropertyName = 'lnam',
kAudioObjectPropertyModelName = 'lmod',
kAudioObjectPropertyManufacturer = 'lmak',
kAudioObjectPropertyElementName = 'lchn',
kAudioObjectPropertyElementCategoryName = 'lccn',
kAudioObjectPropertyElementNumberName = 'lcnn',
kAudioObjectPropertyOwnedObjects = 'ownd',
kAudioObjectPropertyIdentify = 'iden',
kAudioObjectPropertySerialNumber = 'snum',
kAudioObjectPropertyFirmwareVersion = 'fwvn'
};
//==================================================================================================
#pragma mark -
#pragma mark AudioPlugIn Constants
/*!
@enum AudioPlugIn Class Constants
@abstract Various constants related to the AudioPlugIn class.
@constant kAudioPlugInClassID
The AudioClassID that identifies the AudioPlugIn class.
*/
CF_ENUM(AudioClassID)
{
kAudioPlugInClassID = 'aplg'
};
//==================================================================================================
#pragma mark AudioPlugIn Properties
/*!
@enum AudioPlugIn Properties
@abstract AudioObjectPropertySelector values provided by the AudioPlugIn class.
@discussion The AudioPlugIn class is a subclass of the AudioObject class. The class has just
the global scope, kAudioObjectPropertyScopeGlobal, and only a master element.
@constant kAudioPlugInPropertyBundleID
A CFString that contains the bundle identifier for the AudioPlugIn. The
caller is responsible for releasing the returned CFObject.
@constant kAudioPlugInPropertyDeviceList
An array of AudioObjectIDs that represent all the AudioDevices currently
provided by the plug-in.
@constant kAudioPlugInPropertyTranslateUIDToDevice
This property fetches the AudioObjectID that corresponds to the AudioDevice
that has the given UID. The UID is passed in via the qualifier as a CFString
while the AudioObjectID for the AudioDevice is returned to the caller as the
property's data. Note that an error is not returned if the UID doesn't refer
to any AudioDevices. Rather, this property will return kAudioObjectUnknown
as the value of the property.
@constant kAudioPlugInPropertyBoxList
An array of AudioObjectIDs that represent all the AudioBox objects currently
provided by the plug-in.
@constant kAudioPlugInPropertyTranslateUIDToBox
This property fetches the AudioObjectID that corresponds to the AudioBox
that has the given UID. The UID is passed in via the qualifier as a CFString
while the AudioObjectID for the AudioBox is returned to the caller as the
property's data. Note that an error is not returned if the UID doesn't refer
to any AudioBoxes. Rather, this property will return kAudioObjectUnknown
as the value of the property.
@constant kAudioPlugInPropertyClockDeviceList
An array of AudioObjectIDs that represent all the AudioClockDevice objects
currently provided by the plug-in.
@constant kAudioPlugInPropertyTranslateUIDToClockDevice
This property fetches the AudioObjectID that corresponds to the
AudioClockDevice that has the given UID. The UID is passed in via the
qualifier as a CFString while the AudioObjectID for the AudioClockDevice is
returned to the caller as the property's data. Note that an error is not
returned if the UID doesn't refer to any AudioClockDevices. Rather, this
property will return kAudioObjectUnknown as the value of the property.
*/
CF_ENUM(AudioObjectPropertySelector)
{
kAudioPlugInPropertyBundleID = 'piid',
kAudioPlugInPropertyDeviceList = 'dev#',
kAudioPlugInPropertyTranslateUIDToDevice = 'uidd',
kAudioPlugInPropertyBoxList = 'box#',
kAudioPlugInPropertyTranslateUIDToBox = 'uidb',
kAudioPlugInPropertyClockDeviceList = 'clk#',
kAudioPlugInPropertyTranslateUIDToClockDevice = 'uidc'
};
//==================================================================================================
#pragma mark -
#pragma mark AudioTransportManager Constants
/*!
@enum AudioTransportManager Class Constants
@abstract Various constants related to the AudioTransportManager class.
@discussion The AudioTransportManager class is a subclass of the AudioPlugIn class.
Instances manage an entire transport mechanism such as AirPlay or an AVB network
of devices. AudioTransportManagers present a list of AudioEndPoints that
represent all the devices that they manage. They can combine AudioEndPoints into
an AudioEndPointDevice that can be used by the system the same as any other
AudioDevice.
@constant kAudioTransportManagerClassID
The AudioClassID that identifies the AudioTransportManager class.
*/
CF_ENUM(AudioClassID)
{
kAudioTransportManagerClassID = 'trpm'
};
//==================================================================================================
#pragma mark AudioTransportManager Properties
/*!
@enum AudioTransportManager Properties
@abstract AudioObjectPropertySelector values provided by the AudioTransportManager class.
@discussion The AudioTransportManager class is a subclass of the AudioPlugIn class. The
class has just the global scope, kAudioObjectPropertyScopeGlobal, and only a
master element.
@constant kAudioTransportManagerPropertyEndPointList
An array of AudioObjectIDs for all the AudioEndPoint objects the transport
manager is tracking.
@constant kAudioTransportManagerPropertyTranslateUIDToEndPoint
This property fetches the AudioObjectID that corresponds to the
AudioEndpoint that has the given UID. The UID is passed in via the qualifier
as a CFString while the AudioObjectID for the AudioEndpoint is returned to
the caller as the property's data. Note that an error is not returned if the
UID doesn't refer to any AudioEndpoints. Rather, this property will return
kAudioObjectUnknown as the value of the property.
@constant kAudioTransportManagerPorpertyTransportType
A UInt32 whose value indicates how the transport manager's endpoints and
endpoint devices are connected to the CPU. Constants for some of the values
for this property can be found in the enum in the AudioDevice Constants
section of this file.
*/
CF_ENUM(AudioObjectPropertySelector)
{
kAudioTransportManagerPropertyEndPointList = 'end#',
kAudioTransportManagerPropertyTranslateUIDToEndPoint = 'uide',
kAudioTransportManagerPropertyTransportType = 'tran'
};
//==================================================================================================
#pragma mark -
#pragma mark AudioBox Constants
/*!
@enum AudioBox Class Constants
@abstract Various constants related to the AudioBox class.
@constant kAudioBoxClassID
The AudioClassID that identifies the AudioBox class.
*/
CF_ENUM(AudioClassID)
{
kAudioBoxClassID = 'abox'
};
//==================================================================================================
#pragma mark AudioBox Properties
/*!
@enum AudioBox Properties
@abstract AudioObjectPropertySelector values provided by the AudioBox class.
@discussion The AudioBox class is a subclass of the AudioObject class. The class has just
the global scope, kAudioObjectPropertyScopeGlobal, and only a master element.
An AudioBox is a container for other objects (typically AudioDevice objects). An
AudioBox publishes identifying information about itself and can be enabled or
disabled. A box's contents are only available to the system when the box is
enabled.
@constant kAudioBoxPropertyBoxUID
A CFString that contains a persistent identifier for the AudioBox. An
AudioBox'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 AudioBox's hardware or unique to the CPU. Therefore they are
not suitable for passing between CPUs or for identifying similar models of
hardware. The caller is responsible for releasing the returned CFObject.
@constant kAudioBoxPropertyTransportType
A UInt32 whose value indicates how the AudioBox is connected to the system.
Constants for some of the values for this property can be found in the enum
in the AudioDevice Constants section of AudioHardwareBase.h
@constant kAudioBoxPropertyHasAudio
A UInt32 where a non-zero value indicates that the box supports audio.
@constant kAudioBoxPropertyHasVideo
A UInt32 where a non-zero value indicates that the box supports video.
@constant kAudioBoxPropertyHasMIDI
A UInt32 where a non-zero value indicates that the box supports MIDI.
@constant kAudioBoxPropertyIsProtected
A UInt32 where a non-zero value indicates that the box requires
authentication to use.
@constant kAudioBoxPropertyAcquired
A UInt32 where a non-zero value indicates that the box's contents are
available to the system.
@constant kAudioBoxPropertyAcquisitionFailed
An OSStatus that indicates the reason for an attempt to acquire a box
failed. Note that this property is primarily used for notifications.
@constant kAudioBoxPropertyDeviceList
An array of AudioObjectIDs that represent all the AudioDevice objects that
came out of the given AudioBox. Note that until a box is enabled, this list
will be empty.
@constant kAudioBoxPropertyClockDeviceList
An array of AudioObjectIDs that represent all the AudioClockDevice objects
that came out of the given AudioBox. Note that until a box is enabled, this
list will be empty.
*/
CF_ENUM(AudioObjectPropertySelector)
{
kAudioBoxPropertyBoxUID = 'buid',
kAudioBoxPropertyTransportType = 'tran',
kAudioBoxPropertyHasAudio = 'bhau',
kAudioBoxPropertyHasVideo = 'bhvi',
kAudioBoxPropertyHasMIDI = 'bhmi',
kAudioBoxPropertyIsProtected = 'bpro',
kAudioBoxPropertyAcquired = 'bxon',
kAudioBoxPropertyAcquisitionFailed = 'bxof',
kAudioBoxPropertyDeviceList = 'bdv#',
kAudioBoxPropertyClockDeviceList = 'bcl#'
};
//==================================================================================================
#pragma mark -
#pragma mark AudioDevice Constants
/*!
@enum AudioDevice Class Constants
@abstract Various constants related to the AudioDevice class.
@constant kAudioDeviceClassID
The AudioClassID that identifies the AudioDevice class.
*/
CF_ENUM(AudioClassID)
{
kAudioDeviceClassID = 'adev'
};
/*!
@enum Transport Type IDs
@abstract Commonly used values for kAudioDevicePropertyTransportType and
kAudioTransportManagerPropertyTransportType
@constant kAudioDeviceTransportTypeUnknown
The transport type ID returned when a device doesn't provide a transport
type.
@constant kAudioDeviceTransportTypeBuiltIn
The transport type ID for AudioDevices built into the system.
@constant kAudioDeviceTransportTypeAggregate
The transport type ID for aggregate devices.
@constant kAudioDeviceTransportTypeAutoAggregate
The transport type ID for automatically generated aggregate devices.
@constant kAudioDeviceTransportTypeVirtual
The transport type ID for AudioDevices that don't correspond to real audio
hardware.
@constant kAudioDeviceTransportTypePCI
The transport type ID for AudioDevices connected via the PCI bus.
@constant kAudioDeviceTransportTypeUSB
The transport type ID for AudioDevices connected via USB.
@constant kAudioDeviceTransportTypeFireWire
The transport type ID for AudioDevices connected via FireWire.
@constant kAudioDeviceTransportTypeBluetooth
The transport type ID for AudioDevices connected via Bluetooth.
@constant kAudioDeviceTransportTypeBluetoothLE
The transport type ID for AudioDevices connected via Bluetooth Low Energy.
@constant kAudioDeviceTransportTypeHDMI
The transport type ID for AudioDevices connected via HDMI.
@constant kAudioDeviceTransportTypeDisplayPort
The transport type ID for AudioDevices connected via DisplayPort.
@constant kAudioDeviceTransportTypeAirPlay
The transport type ID for AudioDevices connected via AirPlay.
@constant kAudioDeviceTransportTypeAVB
The transport type ID for AudioDevices connected via AVB.
@constant kAudioDeviceTransportTypeThunderbolt
The transport type ID for AudioDevices connected via Thunderbolt.
*/
CF_ENUM(UInt32)
{
kAudioDeviceTransportTypeUnknown = 0,
kAudioDeviceTransportTypeBuiltIn = 'bltn',
kAudioDeviceTransportTypeAggregate = 'grup',
kAudioDeviceTransportTypeVirtual = 'virt',
kAudioDeviceTransportTypePCI = 'pci ',
kAudioDeviceTransportTypeUSB = 'usb ',
kAudioDeviceTransportTypeFireWire = '1394',
kAudioDeviceTransportTypeBluetooth = 'blue',
kAudioDeviceTransportTypeBluetoothLE = 'blea',
kAudioDeviceTransportTypeHDMI = 'hdmi',
kAudioDeviceTransportTypeDisplayPort = 'dprt',
kAudioDeviceTransportTypeAirPlay = 'airp',
kAudioDeviceTransportTypeAVB = 'eavb',
kAudioDeviceTransportTypeThunderbolt = 'thun'
};
//==================================================================================================
#pragma mark AudioDevice Properties
/*!
@enum AudioDevice Properties
@abstract AudioObjectPropertySelector values provided by the AudioDevice class.
@discussion The AudioDevice class is a subclass of the AudioObjectClass. The class has four
scopes, kAudioObjectPropertyScopeGlobal, kAudioObjectPropertyScopeInput,
kAudioObjectPropertyScopeOutput, and kAudioObjectPropertyScopePlayThrough. The
class has a master element and an element for each channel in each stream
numbered according to the starting channel number of each stream.
@constant 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.
@constant 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. The caller is responsible for releasing the returned CFObject.
@constant 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. The caller is
responsible for releasing the returned CFObject.
@constant 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 the enum
in the AudioDevice Constants section of this file.
@constant kAudioDevicePropertyRelatedDevices
An array of AudioDeviceIDs for devices related to the AudioDevice. For
IOAudio-based devices, AudioDevices are related if they share the same
IOAudioDevice object.
@constant 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.
@constant 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.
@constant 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.
@constant kAudioDevicePropertyDeviceCanBeDefaultDevice
A UInt32 where 1 means that the AudioDevice is a possible selection for
kAudioHardwarePropertyDefaultInputDevice or
kAudioHardwarePropertyDefaultOutputDevice depending on the scope.
@constant kAudioDevicePropertyDeviceCanBeDefaultSystemDevice
A UInt32 where 1 means that the AudioDevice is a possible selection for
kAudioHardwarePropertyDefaultSystemOutputDevice.
@constant 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.
@constant 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.
@constant kAudioObjectPropertyControlList
An array of AudioObjectIDs that represent the AudioControls of the
AudioDevice. Note that if a notification is received for this property, any
cached AudioObjectIDs for the device become invalid and need to be
re-fetched.
@constant 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.
@constant kAudioDevicePropertyNominalSampleRate
A Float64 that indicates the current nominal sample rate of the AudioDevice.
@constant kAudioDevicePropertyAvailableNominalSampleRates
An array of AudioValueRange structs that indicates the valid ranges for the
nominal sample rate of the AudioDevice.
@constant kAudioDevicePropertyIcon
A CFURLRef that indicates an image file that can be used to represent the
device visually. The caller is responsible for releasing the returned
CFObject.
@constant kAudioDevicePropertyIsHidden
A UInt32 where a non-zero value indicates that the device is not included
in the normal list of devices provided by kAudioHardwarePropertyDevices nor
can it be the default device. Hidden devices can only be discovered by
knowing their UID and using kAudioHardwarePropertyDeviceForUID.
@constant 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.
@constant kAudioDevicePropertyPreferredChannelLayout
An AudioChannelLayout that indicates how each channel of the AudioDevice
should be used.
*/
CF_ENUM(AudioObjectPropertySelector)
{
kAudioDevicePropertyConfigurationApplication = 'capp',
kAudioDevicePropertyDeviceUID = 'uid ',
kAudioDevicePropertyModelUID = 'muid',
kAudioDevicePropertyTransportType = 'tran',
kAudioDevicePropertyRelatedDevices = 'akin',
kAudioDevicePropertyClockDomain = 'clkd',
kAudioDevicePropertyDeviceIsAlive = 'livn',
kAudioDevicePropertyDeviceIsRunning = 'goin',
kAudioDevicePropertyDeviceCanBeDefaultDevice = 'dflt',
kAudioDevicePropertyDeviceCanBeDefaultSystemDevice = 'sflt',
kAudioDevicePropertyLatency = 'ltnc',
kAudioDevicePropertyStreams = 'stm#',
kAudioObjectPropertyControlList = 'ctrl',
kAudioDevicePropertySafetyOffset = 'saft',
kAudioDevicePropertyNominalSampleRate = 'nsrt',
kAudioDevicePropertyAvailableNominalSampleRates = 'nsr#',
kAudioDevicePropertyIcon = 'icon',
kAudioDevicePropertyIsHidden = 'hidn',
kAudioDevicePropertyPreferredChannelsForStereo = 'dch2',
kAudioDevicePropertyPreferredChannelLayout = 'srnd'
};
//==================================================================================================
#pragma mark -
#pragma mark AudioClockDevice Constants
/*!
@enum AudioClockDevice Class Constants
@abstract Various constants related to the AudioClockDevice class.
@constant kAudioClockDeviceClassID
The AudioClassID that identifies the AudioClockDevice class.
*/
CF_ENUM(AudioObjectPropertySelector)
{
kAudioClockDeviceClassID = 'aclk'
};
//==================================================================================================
#pragma mark AudioClockDevice Properties
/*!
@enum AudioClockDevice Properties
@abstract AudioObjectPropertySelector values provided by the AudioClockDevice class.
@discussion The AudioClockDevice class is a subclass of the AudioObject class. The class has just
the global scope, kAudioObjectPropertyScopeGlobal, and only a master element.
@constant kAudioClockDevicePropertyDeviceUID
A CFString that contains a persistent identifier for the AudioClockDevice.
An AudioClockDevice'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 clock's hardware or unique to the CPU. Therefore
they are not suitable for passing between CPUs or for identifying similar
models of hardware. The caller is responsible for releasing the returned
CFObject.
@constant kAudioClockDevicePropertyTransportType
A UInt32 whose value indicates how the AudioClockDevice is connected to the
CPU. Constants for some of the values for this property can be found in the
enum in the AudioDevice Constants section of this file.
@constant kAudioClockDevicePropertyClockDomain
A UInt32 whose value indicates the clock domain to which this
AudioClockDevice belongs. AudioClockDevices and 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.
@constant kAudioClockDevicePropertyDeviceIsAlive
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.
@constant kAudioClockDevicePropertyDeviceIsRunning
A UInt32 where a value of 0 means the AudioClockDevice is not providing
times and a value of 1 means that it is. Note that the notification for this
property is usually sent from the AudioClockDevice's IO thread.
@constant kAudioClockDevicePropertyLatency
A UInt32 containing the number of frames of latency in the AudioClockDevice.
@constant kAudioClockDevicePropertyControlList
An array of AudioObjectIDs that represent the AudioControls of the
AudioClockDevice. Note that if a notification is received for this property,
any cached AudioObjectIDs for the device become invalid and need to be
re-fetched.
@constant kAudioClockDevicePropertyNominalSampleRate
A Float64 that indicates the current nominal sample rate of the
AudioClockDevice.
@constant kAudioClockDevicePropertyAvailableNominalSampleRates
An array of AudioValueRange structs that indicates the valid ranges for the
nominal sample rate of the AudioClockDevice.
*/
CF_ENUM(AudioObjectPropertySelector)
{
kAudioClockDevicePropertyDeviceUID = 'cuid',
kAudioClockDevicePropertyTransportType = 'tran',
kAudioClockDevicePropertyClockDomain = 'clkd',
kAudioClockDevicePropertyDeviceIsAlive = 'livn',
kAudioClockDevicePropertyDeviceIsRunning = 'goin',
kAudioClockDevicePropertyLatency = 'ltnc',
kAudioClockDevicePropertyControlList = 'ctrl',
kAudioClockDevicePropertyNominalSampleRate = 'nsrt',
kAudioClockDevicePropertyAvailableNominalSampleRates = 'nsr#'
};
//==================================================================================================
#pragma mark -
#pragma mark AudioEndPointDevice Constants
/*!
@enum AudioEndPointDevice Class Constants
@abstract Various constants related to the AudioEndPointDevice class.
@constant kAudioEndPointDeviceClassID
The AudioClassID that identifies the AudioEndPointDevice class.
*/
CF_ENUM(AudioClassID)
{
kAudioEndPointDeviceClassID = 'edev'
};
/*!
@defined kAudioEndPointDeviceUIDKey
@discussion The key used in a CFDictionary that describes the composition of an
AudioEndPointDevice. The value for this key is a CFString that contains the UID
of the AudioEndPointDevice.
*/
#define kAudioEndPointDeviceUIDKey "uid"
/*!
@defined kAudioEndPointDeviceNameKey
@discussion The key used in a CFDictionary that describes the composition of an
AudioEndPointDevice. The value for this key is a CFString that contains the
human readable name of the AudioEndPointDevice.
*/
#define kAudioEndPointDeviceNameKey "name"
/*!
@defined kAudioEndPointDeviceEndPointListKey
@discussion The key used in a CFDictionary that describes the composition of an
AudioEndPointDevice. The value for this key is a CFArray of CFDictionaries that
describe each AudioEndPoint in the AudioEndPointDevice. The keys for this
CFDictionary are defined in the AudioEndPoint Constants section.
*/
#define kAudioEndPointDeviceEndPointListKey "endpoints"
/*!
@defined kAudioEndPointDeviceMasterEndPointKey
@discussion The key used in a CFDictionary that describes the composition of an
AudioEndPointDevice. The value for this key is a CFString that contains the UID
for the AudioEndPoint that is the master time source for the
AudioEndPointDevice.
*/
#define kAudioEndPointDeviceMasterEndPointKey "master"
/*!
@defined kAudioEndPointDeviceIsPrivateKey
@discussion The key used in a CFDictionary that describes the composition of an
AudioEndPointDevice. The value for this key is a CFNumber where a value of 0
means that the AudioEndPointDevice is to be published to the entire system and a
value of 1 means that the AudioEndPointDevice is private to the process that
created it. Note that a private AudioEndPointDevice is not persistent across
launches of the process that created it. Note that if this key is not present,
it implies that the AudioEndPointDevice is published to the entire system.
*/
#define kAudioEndPointDeviceIsPrivateKey "private"
//==================================================================================================
#pragma mark AudioEndPointDevice Properties
/*!
@enum AudioEndPointDevice Properties
@abstract AudioObjectPropertySelector values provided by the AudioEndPointDevice class.
@discussion AudioEndPointDevice is a subclass of AudioDevice and has the same scope and
element structure.
@constant kAudioEndPointDevicePropertyComposition
A CFDictionary that describes the composition of the AudioEndPointDevice.
The keys for this CFDicitionary are defined in the AudioEndPointDevice
Constants section. The caller is responsible for releasing the returned
CFObject.
@constant kAudioEndPointDevicePropertyEndPointList
An array of AudioObjectIDs for all the AudioEndPoints in the device.
@constant kAudioEndPointDevicePropertyIsPrivate
A pid_t where a value of 0 indicates that the device is public and a non-zero
value indicates the pid of the process that owns the device.
*/
CF_ENUM(AudioObjectPropertySelector)
{
kAudioEndPointDevicePropertyComposition = 'acom',
kAudioEndPointDevicePropertyEndPointList = 'agrp',
kAudioEndPointDevicePropertyIsPrivate = 'priv'
};
//==================================================================================================
#pragma mark -
#pragma mark AudioEndPoint Constants
/*!
@enum AudioEndPoint Class Constants
@abstract Various constants related to the AudioEndPoint class.
@discussion The AudioEndPoint class is a subclass of AudioDevice class and has the same
scope and element structure. However, AudioEndPoint objects do not implement an
IO path of their own and as such do not implement any AudioDevice properties
associated with the IO path.
@constant kAudioEndPointDeviceClassID
The AudioClassID that identifies the AudioEndPointDevice class.
*/
CF_ENUM(AudioClassID)
{
kAudioEndPointClassID = 'endp'
};
/*!
@defined kAudioEndPointUIDKey
@discussion The key used in a CFDictionary that describes the state of an AudioEndPoint in a
description dictionary for an AudioEndPointDevice. The value for this key is a
CFString that contains the UID for the AudioEndPoint.
*/
#define kAudioEndPointUIDKey "uid"
/*!
@defined kAudioEndPointNameKey
@discussion The key used in a CFDictionary that describes the state of an AudioEndPoint in a
description dictionary for an AudioEndPointDevice. The value for this key is a
CFString that contains the human readable name of the AudioEndPoint.
*/
#define kAudioEndPointNameKey "name"
/*!
@defined kAudioEndPointInputChannelsKey
@discussion The key used in a CFDictionary that describes the state of an AudioEndPoint in a
description dictionary for an AudioEndPointDevice. The value for this key is a
CFNumber that indicates the total number of input channels for the
AudioEndPoint.
*/
#define kAudioEndPointInputChannelsKey "channels-in"
/*!
@defined kAudioEndPointOutputChannelsKey
@discussion The key used in a CFDictionary that describes the state of an AudioEndPoint in a
description dictionary for an AudioEndPointDevice. The value for this key is a
CFNumber that indicates the total number of output channels for the
AudioEndPoint.
*/
#define kAudioEndPointOutputChannelsKey "channels-out"
//==================================================================================================
#pragma mark -
#pragma mark AudioStream Types
/*!
@struct AudioStreamRangedDescription
@abstract This structure allows a specific sample rate range to be associated with an
AudioStreamBasicDescription that specifies its sample rate as
kAudioStreamAnyRate.
@discussion Note that this structure is only used to describe the the available formats
for a stream. It is not used for the current format.
@field 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.
@field 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.
*/
struct AudioStreamRangedDescription
{
AudioStreamBasicDescription mFormat;
AudioValueRange mSampleRateRange;
};
typedef struct AudioStreamRangedDescription AudioStreamRangedDescription;
//==================================================================================================
#pragma mark AudioStream Constants
/*!
@enum AudioStream Class Constants
@abstract Various constants related to the AudioStream class.
@constant kAudioStreamClassID
The AudioClassID that identifies the AudioStream class.
*/
CF_ENUM(AudioClassID)
{
kAudioStreamClassID = 'astr'
};
/*!
@enum AudioStream Terminal Types
@abstract Various constants that describe the terminal type of an AudioStream.
@constant kAudioStreamTerminalTypeUnknown
The ID used when the terminal type for the AudioStream is non known.
@constant kAudioStreamTerminalTypeLine
The ID for a terminal type of a line level stream. Note that this applies to
both input streams and output streams
@constant kAudioStreamTerminalTypeDigitalAudioInterface
The ID for a terminal type of stream from/to a digital audio interface as
defined by ISO 60958 (aka SPDIF or AES/EBU). Note that this applies to both
input streams and output streams
@constant kAudioStreamTerminalTypeSpeaker
The ID for a terminal type of a speaker.
@constant kAudioStreamTerminalTypeHeadphones
The ID for a terminal type of headphones.
@constant kAudioStreamTerminalTypeLFESpeaker
The ID for a terminal type of a speaker for low frequency effects.
@constant kAudioStreamTerminalTypeReceiverSpeaker
The ID for a terminal type of a speaker on a telephone handset receiver.
@constant kAudioStreamTerminalTypeMicrophone
The ID for a terminal type of a microphone.
@constant kAudioStreamTerminalTypeHeadsetMicrophone
The ID for a terminal type of a microphone attached to an headset.
@constant kAudioStreamTerminalTypeReceiverMicrophone
The ID for a terminal type of a microphone on a telephone handset receiver.
@constant kAudioStreamTerminalTypeTTY
The ID for a terminal type of a device providing a TTY signal.
@constant kAudioStreamTerminalTypeHDMI
The ID for a terminal type of a stream from/to an HDMI port.
@constant kAudioStreamTerminalTypeDisplayPort
The ID for a terminal type of a stream from/to an DisplayPort port.
*/
CF_ENUM(UInt32)
{
kAudioStreamTerminalTypeUnknown = 0,
kAudioStreamTerminalTypeLine = 'line',
kAudioStreamTerminalTypeDigitalAudioInterface = 'spdf',
kAudioStreamTerminalTypeSpeaker = 'spkr',
kAudioStreamTerminalTypeHeadphones = 'hdph',
kAudioStreamTerminalTypeLFESpeaker = 'lfes',
kAudioStreamTerminalTypeReceiverSpeaker = 'rspk',
kAudioStreamTerminalTypeMicrophone = 'micr',
kAudioStreamTerminalTypeHeadsetMicrophone = 'hmic',
kAudioStreamTerminalTypeReceiverMicrophone = 'rmic',
kAudioStreamTerminalTypeTTY = 'tty_',
kAudioStreamTerminalTypeHDMI = 'hdmi',
kAudioStreamTerminalTypeDisplayPort = 'dprt'
};
//==================================================================================================
#pragma mark AudioStream Properties
/*!
@enum AudioStream Properties
@abstract AudioObjectPropertySelector values provided by the AudioStream class.
@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.
@constant kAudioStreamPropertyIsActive
A UInt32 where a non-zero value indicates that the stream is enabled and
doing IO.
@constant 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.
@constant kAudioStreamPropertyTerminalType
A UInt32 whose value describes the general kind of functionality attached
to the AudioStream.
@constant kAudioStreamPropertyStartingChannel
A UInt32 that specifies the first element in the owning device that
corresponds to element one of this stream.
@constant 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.
@constant 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.
@constant 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.
@constant 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 its IO transactions.
@constant 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 its IO
transactions.
*/
CF_ENUM(AudioObjectPropertySelector)
{
kAudioStreamPropertyIsActive = 'sact',
kAudioStreamPropertyDirection = 'sdir',
kAudioStreamPropertyTerminalType = 'term',
kAudioStreamPropertyStartingChannel = 'schn',
kAudioStreamPropertyLatency = kAudioDevicePropertyLatency,
kAudioStreamPropertyVirtualFormat = 'sfmt',
kAudioStreamPropertyAvailableVirtualFormats = 'sfma',
kAudioStreamPropertyPhysicalFormat = 'pft ',
kAudioStreamPropertyAvailablePhysicalFormats = 'pfta'
};
//==================================================================================================
#pragma mark -
#pragma mark AudioControl Constants
/*!
@enum AudioControl Class Constants
@abstract Various constants related to the AudioControl class.
@constant kAudioControlClassID
The AudioClassID that identifies the AudioControl class.
*/
CF_ENUM(AudioClassID)
{
kAudioControlClassID = 'actl'
};
/*!
@enum AudioControl Property Selectors
@abstract AudioObjectPropertySelector values provided by the AudioControl class.
@discussion The AudioControl class is a subclass of the AudioObject class. The class has
just the global scope, kAudioObjectPropertyScopeGlobal, and only a master
element.
@constant kAudioControlPropertyScope
An AudioServerPlugIn_PropertyScope that indicates which part of a device the
control applies to.
@constant kAudioControlPropertyElement
An AudioServerPlugIn_PropertyElement that indicates which element of the
device the control applies to.
*/
CF_ENUM(AudioObjectPropertySelector)
{
kAudioControlPropertyScope = 'cscp',
kAudioControlPropertyElement = 'celm'
};
//==================================================================================================
#pragma mark -
#pragma mark AudioSliderControl Constants
/*!
@enum AudioSliderControl Class Constants
@abstract Various constants related to the AudioSliderControl class.
@constant kAudioSliderControlClassID
The AudioClassID that identifies the AudioSliderControl class.
*/
CF_ENUM(AudioClassID)
{
kAudioSliderControlClassID = 'sldr'
};
/*!
@enum AudioSliderControl Property Selectors
@abstract AudioObjectPropertySelector values provided by the AudioSliderControl class.
@discussion The AudioSliderControl class is a subclass of the AudioControl class and has the
same scope and element structure.
@constant kAudioSliderControlPropertyValue
A UInt32 that represents the value of the slider control.
@constant kAudioSliderControlPropertyRange
An array of two UInt32s that represents the inclusive range of values the
slider control can take.
*/
CF_ENUM(AudioObjectPropertySelector)
{
kAudioSliderControlPropertyValue = 'sdrv',
kAudioSliderControlPropertyRange = 'sdrr'
};
//==================================================================================================
#pragma mark -
#pragma mark AudioLevelControl Constants
/*!
@enum AudioLevelControl Class Constants
@abstract Various constants related to the AudioLevelControl class.
@constant kAudioLevelControlClassID
The AudioClassID that identifies the LevelControl class.
@constant kAudioVolumeControlClassID
A subclass of the LevelControl class that implements a general
gain/attenuation stage.
@constant kAudioLFEVolumeControlClassID
A subclass of the LevelControl class for an LFE channel that results from
bass management. Note that LFE channels that are represented as normal audio
channels must use kAudioVolumeControlClassID to manipulate the level.
*/
CF_ENUM(AudioClassID)
{
kAudioLevelControlClassID = 'levl',
kAudioVolumeControlClassID = 'vlme',
kAudioLFEVolumeControlClassID = 'subv'
};
/*!
@enum AudioLevelControl Property Selectors
@abstract AudioObjectPropertySelector values provided by the AudioLevelControl class.
@discussion The AudioLevelControl class is a subclass of the AudioControl class and has the
same scope and element structure.
@constant kAudioLevelControlPropertyScalarValue
A Float32 that represents the value of the volume control. The range is
between 0.0 and 1.0 (inclusive). Note that the set of all Float32 values
between 0.0 and 1.0 inclusive is much larger than the set of actual values
that the hardware can select. This means that the Float32 range has a many
to one mapping with the underlying hardware values. As such, setting a
scalar value will result in the control taking on the value nearest to what
was set.
@constant kAudioLevelControlPropertyDecibelValue
A Float32 that represents the value of the volume control in dB. Note that
the set of all Float32 values in the dB range for the control is much larger
than the set of actual values that the hardware can select. This means that
the Float32 range has a many to one mapping with the underlying hardware
values. As such, setting a dB value will result in the control taking on the
value nearest to what was set.
@constant kAudioLevelControlPropertyDecibelRange
An AudioValueRange that contains the minimum and maximum dB values the
control can have.
@constant kAudioLevelControlPropertyConvertScalarToDecibels
A Float32 that on input contains a scalar volume value for the and on exit
contains the equivalent dB value.
@constant kAudioLevelControlPropertyConvertDecibelsToScalar
A Float32 that on input contains a dB volume value for the and on exit
contains the equivalent scalar value.
*/
CF_ENUM(AudioObjectPropertySelector)
{
kAudioLevelControlPropertyScalarValue = 'lcsv',
kAudioLevelControlPropertyDecibelValue = 'lcdv',
kAudioLevelControlPropertyDecibelRange = 'lcdr',
kAudioLevelControlPropertyConvertScalarToDecibels = 'lcsd',
kAudioLevelControlPropertyConvertDecibelsToScalar = 'lcds'
};
//==================================================================================================
#pragma mark -
#pragma mark AudioBooleanControl Constants
/*!
@enum AudioBooleanControl Class Constants
@abstract Various constants related to the AudioBooleanControl class.
@constant kAudioBooleanControlClassID
The AudioClassID that identifies the BooleanControl class.
@constant kAudioMuteControlClassID
A subclass of the AudioBooleanControl class where a true value means that
mute is enabled making that element inaudible.
@constant kAudioSoloControlClassID
A subclass of the AudioBooleanControl class where a true value means that
solo is enabled making just that element audible and the other elements
inaudible.
@constant kAudioJackControlClassID
A subclass of the AudioBooleanControl class where a true value means
something is plugged into that element.
@constant kAudioLFEMuteControlClassID
A subclass of the AudioBooleanControl class where true means that mute is
enabled making that LFE element inaudible. This control is for LFE channels
that result from bass management. Note that LFE channels that are
represented as normal audio channels must use an AudioMuteControl.
@constant kAudioPhantomPowerControlClassID
A subclass of the AudioBooleanControl class where true means that the
element's hardware has phantom power enabled.
@constant kAudioPhaseInvertControlClassID
A subclass of the AudioBooleanControl class where true means that the phase
of the signal on the given element is being inverted by 180 degrees.
@constant kAudioClipLightControlClassID
A subclass of the AudioBooleanControl class where true means that the signal
for the element has exceeded the sample range. Once a clip light is turned
on, it is to stay on until either the value of the control is set to false
or the current IO session stops and a new IO session starts.
@constant kAudioTalkbackControlClassID
An AudioBooleanControl where true means that the talkback channel is
enabled. This control is for talkback channels that are handled outside of
the regular IO channels. If the talkback channel is among the normal IO
channels, it will use AudioMuteControl.
@constant kAudioListenbackControlClassID
An AudioBooleanControl where true means that the listenback channel is
audible. This control is for listenback channels that are handled outside of
the regular IO channels. If the listenback channel is among the normal IO
channels, it will use AudioMuteControl.
*/
CF_ENUM(AudioClassID)
{
kAudioBooleanControlClassID = 'togl',
kAudioMuteControlClassID = 'mute',
kAudioSoloControlClassID = 'solo',
kAudioJackControlClassID = 'jack',
kAudioLFEMuteControlClassID = 'subm',
kAudioPhantomPowerControlClassID = 'phan',
kAudioPhaseInvertControlClassID = 'phsi',
kAudioClipLightControlClassID = 'clip',
kAudioTalkbackControlClassID = 'talb',
kAudioListenbackControlClassID = 'lsnb'
};
/*!
@enum AudioBooleanControl Property Selectors
@abstract AudioObjectPropertySelector values provided by the AudioBooleanControl class.
@discussion The AudioBooleanControl class is a subclass of the AudioControl class and has
the same scope and element structure.
@constant kAudioBooleanControlPropertyValue
A UInt32 where 0 means off/false and non-zero means on/true.
*/
CF_ENUM(AudioObjectPropertySelector)
{
kAudioBooleanControlPropertyValue = 'bcvl'
};
//==================================================================================================
#pragma mark -
#pragma mark AudioSelectorControl Constants
/*!
@enum AudioSelectorControl Class Constants
@abstract Various constants related to the AudioSelectorControl class.
@constant kAudioSelectorControlClassID
The AudioClassID that identifies the AudioSelectorControl class.
@constant kAudioDataSourceControlClassID
A subclass of the AudioSelectorControl class that identifies where the data
for the element is coming from.
@constant kAudioDataDestinationControlClassID
A subclass of the AudioSelectorControl class that identifies where the data
for the element is going.
@constant kAudioClockSourceControlClassID
A subclass of the AudioSelectorControl class that identifies where the
timing info for the object is coming from.
@constant kAudioLineLevelControlClassID
A subclass of the AudioSelectorControl class 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.
@constant kAudioHighPassFilterControlClassID
A subclass of the AudioSelectorControl class that indicates the setting for
the high pass filter on the given element.
*/
CF_ENUM(AudioClassID)
{
kAudioSelectorControlClassID = 'slct',
kAudioDataSourceControlClassID = 'dsrc',
kAudioDataDestinationControlClassID = 'dest',
kAudioClockSourceControlClassID = 'clck',
kAudioLineLevelControlClassID = 'nlvl',
kAudioHighPassFilterControlClassID = 'hipf'
};
/*!
@enum AudioSelectorControl Property Selectors
@abstract AudioObjectPropertySelector values provided by the AudioSelectorControl class.
@discussion The AudioSelectorControl class is a subclass of the AudioControl class and has
the same scope and element structure.
@constant kAudioSelectorControlPropertyCurrentItem
An array of UInt32s that are the IDs of the items currently selected.
@constant kAudioSelectorControlPropertyAvailableItems
An array of UInt32s that represent the IDs of all the items available.
@constant 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.
@constant kAudioSelectorControlPropertyItemKind
This property returns a UInt32 that identifies the kind of selector item the
item ID refers to. The qualifier contains the ID of the item. Note that this
property is optional for selector controls and that the meaning of the value
depends on the specific subclass being queried.
*/
CF_ENUM(AudioObjectPropertySelector)
{
kAudioSelectorControlPropertyCurrentItem = 'scci',
kAudioSelectorControlPropertyAvailableItems = 'scai',
kAudioSelectorControlPropertyItemName = 'scin',
kAudioSelectorControlPropertyItemKind = 'clkk'
};
/*!
@enum Constants for the value of the property, kAudioSelectorControlPropertyItemKind
for any selector control item
@constant kAudioSelectorControlItemKindSpacer
This ID represents an item in a selector control's range that represents a
spacer item in a pop-up menu. Items with this kind are not be selectable.
*/
CF_ENUM(UInt32)
{
kAudioSelectorControlItemKindSpacer = 'spcr'
};
/*!
@enum Constants for the value of the property, kAudioSelectorControlPropertyItemKind
for AudioClockSourceControls.
@constant kAudioClockSourceItemKindInternal
This ID represents the device's internal clock.
*/
CF_ENUM(UInt32)
{
kAudioClockSourceItemKindInternal = 'int '
};
//==================================================================================================
#pragma mark -
#pragma mark AudioStereoPanControl Constants
/*!
@enum AudioStereoPanControl Class Constants
@abstract Various constants related to the AudioStereoPanControl class.
@constant kAudioStereoPanControlClassID
The AudioClassID that identifies the StereoPanControl class.
*/
CF_ENUM(AudioClassID)
{
kAudioStereoPanControlClassID = 'span'
};
/*!
@enum AudioStereoPanControl Property Selectors
@abstract AudioObjectPropertySelector values provided by the AudioStereoPanControl class.
@discussion The AudioStereoPanControl class is a subclass of the AudioControl class and has
the same scope and element structure.
@constant kAudioStereoPanControlPropertyValue
A Float32 where 0.0 is full left, 1.0 is full right, and 0.5 is center.
@constant kAudioStereoPanControlPropertyPanningChannels
An array of two UInt32s that indicate which elements of the device the
signal is being panned between.
*/
CF_ENUM(AudioObjectPropertySelector)
{
kAudioStereoPanControlPropertyValue = 'spcv',
kAudioStereoPanControlPropertyPanningChannels = 'spcc'
};
//==================================================================================================
#if defined(__cplusplus)
}
#endif
CF_ASSUME_NONNULL_END
#endif // CoreAudio_AudioHardwareBase_h
Raw
CoreAudioTypes.h
/*==================================================================================================
File: CoreAudio/CoreAudioTypes.h
Contains: Definitions types common to the Core Audio APIs
Copyright: (c) 1985-2010 by Apple, Inc., all rights reserved.
Bugs?: For bug reports, consult the following page on
the World Wide Web:
http://developer.apple.com/bugreporter/
==================================================================================================*/
#if !defined(CoreAudio_CoreAudioTypes_h)
#define CoreAudio_CoreAudioTypes_h
/*!
@header CoreAudioTypes
This header defines the types and constants that all the CoreAudio APIs have in common.
*/
//==================================================================================================
#pragma mark -
#pragma mark Includes
#define COREAUDIOTYPES_VERSION 20150414
#include <TargetConditionals.h>
#if !defined(__COREAUDIO_USE_FLAT_INCLUDES__)
#include <CoreFoundation/CFBase.h>
#else
#include <CFBase.h>
#endif
// CA_PREFER_FIXED_POINT is true on iOS, but this is no longer true in general. This symbol may
// be removed in a future release.
#if !defined(CA_PREFER_FIXED_POINT)
#if TARGET_OS_IPHONE
#if (TARGET_CPU_X86 || TARGET_CPU_X86_64 || TARGET_CPU_PPC || TARGET_CPU_PPC64) && !TARGET_OS_SIMULATOR
#define CA_PREFER_FIXED_POINT 0
#else
#define CA_PREFER_FIXED_POINT 1
#endif
#else
#define CA_PREFER_FIXED_POINT 0
#endif
#endif
#if defined(__has_feature) && __has_feature(attribute_deprecated_with_message)
#define CA_CANONICAL_DEPRECATED __attribute__((deprecated("The concept of canonical formats is deprecated")))
#else
#define CA_CANONICAL_DEPRECATED
#endif
#if defined(__cplusplus)
#include <string.h>
#endif
//==================================================================================================
#if defined(__cplusplus)
extern "C"
{
#endif
//==================================================================================================
#pragma mark -
#pragma mark General Error Codes
/*!
@enum General Audio error codes
@abstract These are the error codes returned from the APIs found through Core Audio related frameworks.
@constant kAudio_UnimplementedError
Unimplemented core routine.
@constant kAudio_FileNotFoundError
File not found.
@constant kAudio_FilePermissionError
File cannot be opened due to either file, directory, or sandbox permissions.
@constant kAudio_TooManyFilesOpenError
File cannot be opened because too many files are already open.
@constant kAudio_BadFilePathError
File cannot be opened because the specified path is malformed.
@constant kAudio_ParamError
Error in user parameter list.
@constant kAudio_MemFullError
Not enough room in heap zone.
*/
CF_ENUM(OSStatus)
{
kAudio_UnimplementedError = -4,
kAudio_FileNotFoundError = -43,
kAudio_FilePermissionError = -54,
kAudio_TooManyFilesOpenError = -42,
kAudio_BadFilePathError = '!pth', // 0x21707468, 561017960
kAudio_ParamError = -50,
kAudio_MemFullError = -108
};
//==================================================================================================
#pragma mark -
#pragma mark AudioValueRange
/*!
@struct AudioValueRange
@abstract This structure holds a pair of numbers that represent a continuous range of
values.
@field mMinimum
The minimum value.
@field mMaximum
The maximum value.
*/
struct AudioValueRange
{
Float64 mMinimum;
Float64 mMaximum;
};
typedef struct AudioValueRange AudioValueRange;
//==================================================================================================
#pragma mark -
#pragma mark AudioValueTranslation
/*!
@struct AudioValueTranslation
@abstract This stucture holds the buffers necessary for translation operations.
@field mInputData
The buffer containing the data to be translated.
@field mInputDataSize
The number of bytes in the buffer pointed at by mInputData.
@field mOutputData
The buffer to hold the result of the translation.
@field mOutputDataSize
The number of bytes in the buffer pointed at by mOutputData.
*/
struct AudioValueTranslation
{
void* __nonnull mInputData;
UInt32 mInputDataSize;
void* __nonnull mOutputData;
UInt32 mOutputDataSize;
};
typedef struct AudioValueTranslation AudioValueTranslation;
//==================================================================================================
#pragma mark -
#pragma mark AudioBuffer/AudioBufferList
/*!
@struct AudioBuffer
@abstract A structure to hold a buffer of audio data.
@field mNumberChannels
The number of interleaved channels in the buffer.
@field mDataByteSize
The number of bytes in the buffer pointed at by mData.
@field mData
A pointer to the buffer of audio data.
*/
struct AudioBuffer
{
UInt32 mNumberChannels;
UInt32 mDataByteSize;
void* __nullable mData;
};
typedef struct AudioBuffer AudioBuffer;
/*!
@struct AudioBufferList
@abstract A variable length array of AudioBuffer structures.
@field mNumberBuffers
The number of AudioBuffers in the mBuffers array.
@field mBuffers
A variable length array of AudioBuffers.
*/
struct AudioBufferList
{
UInt32 mNumberBuffers;
AudioBuffer mBuffers[1]; // this is a variable length array of mNumberBuffers elements
#if defined(__cplusplus) && defined(CA_STRICT) && CA_STRICT
public:
AudioBufferList() {}
private:
// Copying and assigning a variable length struct is problematic; generate a compile error.
AudioBufferList(const AudioBufferList&);
AudioBufferList& operator=(const AudioBufferList&);
#endif
};
typedef struct AudioBufferList AudioBufferList;
//==================================================================================================
#pragma mark -
#pragma mark Audio Formats
/*!
@typedef AudioSampleType
@abstract The canonical audio sample type used by the various CoreAudio APIs
@discussion
These types are deprecated. Code performing signal processing should use concrete types
(e.g. float, Float32, SInt16, SInt32). Format-agnostic code, instead of relying on the sizes
of these types, should calculate the size of a sample from an AudioStreamBasicDescription's
mBytesPerChannel, mChannelsPerFrame, and (mFlags & kLinearPCMFormatFlagIsNonInterleaved).
For interleaved formats, the size of a sample is mBytesPerFrame / mChannelsPerFrame.
For non-interleaved formats, it is simply mBytesPerFrame.
*/
#if !CA_PREFER_FIXED_POINT
CA_CANONICAL_DEPRECATED typedef Float32 AudioSampleType;
CA_CANONICAL_DEPRECATED typedef Float32 AudioUnitSampleType;
#else
CA_CANONICAL_DEPRECATED typedef SInt16 AudioSampleType;
CA_CANONICAL_DEPRECATED typedef SInt32 AudioUnitSampleType;
#define kAudioUnitSampleFractionBits 24
#endif
/*!
@typedef AudioFormatID
@abstract A four char code indicating the general kind of data in the stream.
*/
typedef UInt32 AudioFormatID;
/*!
@typedef AudioFormatFlags
@abstract Flags that are specific to each format.
*/
typedef UInt32 AudioFormatFlags;
/*!
@struct AudioStreamBasicDescription
@abstract This structure encapsulates all the information for describing the basic
format properties of a stream of audio data.
@discussion This structure is sufficient to describe any constant bit rate format that has
channels that are the same size. Extensions are required for variable bit rate
data and for constant bit rate data where the channels have unequal sizes.
However, where applicable, the appropriate fields will be filled out correctly
for these kinds of formats (the extra data is provided via separate properties).
In all fields, a value of 0 indicates that the field is either unknown, not
applicable or otherwise is inapproprate for the format and should be ignored.
Note that 0 is still a valid value for most formats in the mFormatFlags field.
In audio data a frame is one sample across all channels. In non-interleaved
audio, the per frame fields identify one channel. In interleaved audio, the per
frame fields identify the set of n channels. In uncompressed audio, a Packet is
one frame, (mFramesPerPacket == 1). In compressed audio, a Packet is an
indivisible chunk of compressed data, for example an AAC packet will contain
1024 sample frames.
@field mSampleRate
The number of sample frames per second of the data in the stream.
@field mFormatID
The AudioFormatID indicating the general kind of data in the stream.
@field mFormatFlags
The AudioFormatFlags for the format indicated by mFormatID.
@field mBytesPerPacket
The number of bytes in a packet of data.
@field mFramesPerPacket
The number of sample frames in each packet of data.
@field mBytesPerFrame
The number of bytes in a single sample frame of data.
@field mChannelsPerFrame
The number of channels in each frame of data.
@field mBitsPerChannel
The number of bits of sample data for each channel in a frame of data.
@field mReserved
Pads the structure out to force an even 8 byte alignment.
*/
struct AudioStreamBasicDescription
{
Float64 mSampleRate;
AudioFormatID mFormatID;
AudioFormatFlags mFormatFlags;
UInt32 mBytesPerPacket;
UInt32 mFramesPerPacket;
UInt32 mBytesPerFrame;
UInt32 mChannelsPerFrame;
UInt32 mBitsPerChannel;
UInt32 mReserved;
};
typedef struct AudioStreamBasicDescription AudioStreamBasicDescription;
/*!
@enum AudioStreamBasicDescription Constants
@constant kAudioStreamAnyRate
The format can use any sample rate. Note that this constant can only appear
in listings of supported formats. It will never appear in a current format.
*/
static const Float64 kAudioStreamAnyRate = 0.0;
/*!
@enum Format IDs
@abstract The AudioFormatIDs used to identify individual formats of audio data.
@constant kAudioFormatLinearPCM
Linear PCM, uses the standard flags.
@constant kAudioFormatAC3
AC-3, has no flags.
@constant kAudioFormat60958AC3
AC-3 packaged for transport over an IEC 60958 compliant digital audio
interface. Uses the standard flags.
@constant kAudioFormatAppleIMA4
Apples implementation of IMA 4:1 ADPCM, has no flags.
@constant kAudioFormatMPEG4AAC
MPEG-4 Low Complexity AAC audio object, has no flags.
@constant kAudioFormatMPEG4CELP
MPEG-4 CELP audio object, has no flags.
@constant kAudioFormatMPEG4HVXC
MPEG-4 HVXC audio object, has no flags.
@constant kAudioFormatMPEG4TwinVQ
MPEG-4 TwinVQ audio object type, has no flags.
@constant kAudioFormatMACE3
MACE 3:1, has no flags.
@constant kAudioFormatMACE6
MACE 6:1, has no flags.
@constant kAudioFormatULaw
�Law 2:1, has no flags.
@constant kAudioFormatALaw
aLaw 2:1, has no flags.
@constant kAudioFormatQDesign
QDesign music, has no flags
@constant kAudioFormatQDesign2
QDesign2 music, has no flags
@constant kAudioFormatQUALCOMM
QUALCOMM PureVoice, has no flags
@constant kAudioFormatMPEGLayer1
MPEG-1/2, Layer 1 audio, has no flags
@constant kAudioFormatMPEGLayer2
MPEG-1/2, Layer 2 audio, has no flags
@constant kAudioFormatMPEGLayer3
MPEG-1/2, Layer 3 audio, has no flags
@constant kAudioFormatTimeCode
A stream of IOAudioTimeStamps, uses the IOAudioTimeStamp flags (see
IOKit/audio/IOAudioTypes.h).
@constant kAudioFormatMIDIStream
A stream of MIDIPacketLists where the time stamps in the MIDIPacketList are
sample offsets in the stream. The mSampleRate field is used to describe how
time is passed in this kind of stream and an AudioUnit that receives or
generates this stream can use this sample rate, the number of frames it is
rendering and the sample offsets within the MIDIPacketList to define the
time for any MIDI event within this list. It has no flags.
@constant kAudioFormatParameterValueStream
A "side-chain" of Float32 data that can be fed or generated by an AudioUnit
and is used to send a high density of parameter value control information.
An AU will typically run a ParameterValueStream at either the sample rate of
the AudioUnit's audio data, or some integer divisor of this (say a half or a
third of the sample rate of the audio). The Sample Rate of the ASBD
describes this relationship. It has no flags.
@constant kAudioFormatAppleLossless
Apple Lossless, the flags indicate the bit depth of the source material.
@constant kAudioFormatMPEG4AAC_HE
MPEG-4 High Efficiency AAC audio object, has no flags.
@constant kAudioFormatMPEG4AAC_LD
MPEG-4 AAC Low Delay audio object, has no flags.
@constant kAudioFormatMPEG4AAC_ELD
MPEG-4 AAC Enhanced Low Delay audio object, has no flags. This is the formatID of
the base layer without the SBR extension. See also kAudioFormatMPEG4AAC_ELD_SBR
@constant kAudioFormatMPEG4AAC_ELD_SBR
MPEG-4 AAC Enhanced Low Delay audio object with SBR extension layer, has no flags.
@constant kAudioFormatMPEG4AAC_HE_V2
MPEG-4 High Efficiency AAC Version 2 audio object, has no flags.
@constant kAudioFormatMPEG4AAC_Spatial
MPEG-4 Spatial Audio audio object, has no flags.
@constant kAudioFormatAMR
The AMR Narrow Band speech codec.
@constant kAudioFormatAMR_WB
The AMR Wide Band speech codec.
@constant kAudioFormatAudible
The format used for Audible audio books. It has no flags.
@constant kAudioFormatiLBC
The iLBC narrow band speech codec. It has no flags.
@constant kAudioFormatDVIIntelIMA
DVI/Intel IMA ADPCM - ACM code 17.
@constant kAudioFormatMicrosoftGSM
Microsoft GSM 6.10 - ACM code 49.
@constant kAudioFormatAES3
This format is defined by AES3-2003, and adopted into MXF and MPEG-2
containers and SDTI transport streams with SMPTE specs 302M-2002 and
331M-2000. It has no flags.
@constant kAudioFormatEnhancedAC3
Enhanced AC-3, has no flags.
@constant kAudioFormatFLAC
Free Lossless Audio Codec, the flags indicate the bit depth of the source material.
@constant kAudioFormatOpus
Opus codec, has no flags.
*/
CF_ENUM(AudioFormatID)
{
kAudioFormatLinearPCM = 'lpcm',
kAudioFormatAC3 = 'ac-3',
kAudioFormat60958AC3 = 'cac3',
kAudioFormatAppleIMA4 = 'ima4',
kAudioFormatMPEG4AAC = 'aac ',
kAudioFormatMPEG4CELP = 'celp',
kAudioFormatMPEG4HVXC = 'hvxc',
kAudioFormatMPEG4TwinVQ = 'twvq',
kAudioFormatMACE3 = 'MAC3',
kAudioFormatMACE6 = 'MAC6',
kAudioFormatULaw = 'ulaw',
kAudioFormatALaw = 'alaw',
kAudioFormatQDesign = 'QDMC',
kAudioFormatQDesign2 = 'QDM2',
kAudioFormatQUALCOMM = 'Qclp',
kAudioFormatMPEGLayer1 = '.mp1',
kAudioFormatMPEGLayer2 = '.mp2',
kAudioFormatMPEGLayer3 = '.mp3',
kAudioFormatTimeCode = 'time',
kAudioFormatMIDIStream = 'midi',
kAudioFormatParameterValueStream = 'apvs',
kAudioFormatAppleLossless = 'alac',
kAudioFormatMPEG4AAC_HE = 'aach',
kAudioFormatMPEG4AAC_LD = 'aacl',
kAudioFormatMPEG4AAC_ELD = 'aace',
kAudioFormatMPEG4AAC_ELD_SBR = 'aacf',
kAudioFormatMPEG4AAC_ELD_V2 = 'aacg',
kAudioFormatMPEG4AAC_HE_V2 = 'aacp',
kAudioFormatMPEG4AAC_Spatial = 'aacs',
kAudioFormatAMR = 'samr',
kAudioFormatAMR_WB = 'sawb',
kAudioFormatAudible = 'AUDB',
kAudioFormatiLBC = 'ilbc',
kAudioFormatDVIIntelIMA = 0x6D730011,
kAudioFormatMicrosoftGSM = 0x6D730031,
kAudioFormatAES3 = 'aes3',
kAudioFormatEnhancedAC3 = 'ec-3',
kAudioFormatFLAC = 'flac',
kAudioFormatOpus = 'opus'
};
/*!
@enum Standard AudioFormatFlags Values for AudioStreamBasicDescription
@abstract These are the standard AudioFormatFlags for use in the mFormatFlags field of the
AudioStreamBasicDescription structure.
@discussion Typically, when an ASBD is being used, the fields describe the complete layout
of the sample data in the buffers that are represented by this description -
where typically those buffers are represented by an AudioBuffer that is
contained in an AudioBufferList.
However, when an ASBD has the kAudioFormatFlagIsNonInterleaved flag, the
AudioBufferList has a different structure and semantic. In this case, the ASBD
fields will describe the format of ONE of the AudioBuffers that are contained in
the list, AND each AudioBuffer in the list is determined to have a single (mono)
channel of audio data. Then, the ASBD's mChannelsPerFrame will indicate the
total number of AudioBuffers that are contained within the AudioBufferList -
where each buffer contains one channel. This is used primarily with the
AudioUnit (and AudioConverter) representation of this list - and won't be found
in the AudioHardware usage of this structure.
@constant kAudioFormatFlagIsFloat
Set for floating point, clear for integer.
@constant kAudioFormatFlagIsBigEndian
Set for big endian, clear for little endian.
@constant kAudioFormatFlagIsSignedInteger
Set for signed integer, clear for unsigned integer. This is only valid if
kAudioFormatFlagIsFloat is clear.
@constant kAudioFormatFlagIsPacked
Set if the sample bits occupy the entire available bits for the channel,
clear if they are high or low aligned within the channel. Note that even if
this flag is clear, it is implied that this flag is set if the
AudioStreamBasicDescription is filled out such that the fields have the
following relationship:
((mBitsPerSample / 8) * mChannelsPerFrame) == mBytesPerFrame
@constant kAudioFormatFlagIsAlignedHigh
Set if the sample bits are placed into the high bits of the channel, clear
for low bit placement. This is only valid if kAudioFormatFlagIsPacked is
clear.
@constant kAudioFormatFlagIsNonInterleaved
Set if the samples for each channel are located contiguously and the
channels are layed out end to end, clear if the samples for each frame are
layed out contiguously and the frames layed out end to end.
@constant kAudioFormatFlagIsNonMixable
Set to indicate when a format is non-mixable. Note that this flag is only
used when interacting with the HAL's stream format information. It is not a
valid flag for any other uses.
@constant kAudioFormatFlagsAreAllClear
Set if all the flags would be clear in order to preserve 0 as the wild card
value.
@constant kLinearPCMFormatFlagIsFloat
Synonym for kAudioFormatFlagIsFloat.
@constant kLinearPCMFormatFlagIsBigEndian
Synonym for kAudioFormatFlagIsBigEndian.
@constant kLinearPCMFormatFlagIsSignedInteger
Synonym for kAudioFormatFlagIsSignedInteger.
@constant kLinearPCMFormatFlagIsPacked
Synonym for kAudioFormatFlagIsPacked.
@constant kLinearPCMFormatFlagIsAlignedHigh
Synonym for kAudioFormatFlagIsAlignedHigh.
@constant kLinearPCMFormatFlagIsNonInterleaved
Synonym for kAudioFormatFlagIsNonInterleaved.
@constant kLinearPCMFormatFlagIsNonMixable
Synonym for kAudioFormatFlagIsNonMixable.
@constant kLinearPCMFormatFlagsAreAllClear
Synonym for kAudioFormatFlagsAreAllClear.
@constant kLinearPCMFormatFlagsSampleFractionShift
The linear PCM flags contain a 6-bit bitfield indicating that an integer
format is to be interpreted as fixed point. The value indicates the number
of bits are used to represent the fractional portion of each sample value.
This constant indicates the bit position (counting from the right) of the
bitfield in mFormatFlags.
@constant kLinearPCMFormatFlagsSampleFractionMask
number_fractional_bits = (mFormatFlags &
kLinearPCMFormatFlagsSampleFractionMask) >>
kLinearPCMFormatFlagsSampleFractionShift
@constant kAppleLosslessFormatFlag_16BitSourceData
This flag is set for Apple Lossless data that was sourced from 16 bit native
endian signed integer data.
@constant kAppleLosslessFormatFlag_20BitSourceData
This flag is set for Apple Lossless data that was sourced from 20 bit native
endian signed integer data aligned high in 24 bits.
@constant kAppleLosslessFormatFlag_24BitSourceData
This flag is set for Apple Lossless data that was sourced from 24 bit native
endian signed integer data.
@constant kAppleLosslessFormatFlag_32BitSourceData
This flag is set for Apple Lossless data that was sourced from 32 bit native
endian signed integer data.
*/
CF_ENUM(AudioFormatFlags)
{
kAudioFormatFlagIsFloat = (1U << 0), // 0x1
kAudioFormatFlagIsBigEndian = (1U << 1), // 0x2
kAudioFormatFlagIsSignedInteger = (1U << 2), // 0x4
kAudioFormatFlagIsPacked = (1U << 3), // 0x8
kAudioFormatFlagIsAlignedHigh = (1U << 4), // 0x10
kAudioFormatFlagIsNonInterleaved = (1U << 5), // 0x20
kAudioFormatFlagIsNonMixable = (1U << 6), // 0x40
kAudioFormatFlagsAreAllClear = 0x80000000,
kLinearPCMFormatFlagIsFloat = kAudioFormatFlagIsFloat,
kLinearPCMFormatFlagIsBigEndian = kAudioFormatFlagIsBigEndian,
kLinearPCMFormatFlagIsSignedInteger = kAudioFormatFlagIsSignedInteger,
kLinearPCMFormatFlagIsPacked = kAudioFormatFlagIsPacked,
kLinearPCMFormatFlagIsAlignedHigh = kAudioFormatFlagIsAlignedHigh,
kLinearPCMFormatFlagIsNonInterleaved = kAudioFormatFlagIsNonInterleaved,
kLinearPCMFormatFlagIsNonMixable = kAudioFormatFlagIsNonMixable,
kLinearPCMFormatFlagsSampleFractionShift = 7,
kLinearPCMFormatFlagsSampleFractionMask = (0x3F << kLinearPCMFormatFlagsSampleFractionShift),
kLinearPCMFormatFlagsAreAllClear = kAudioFormatFlagsAreAllClear,
kAppleLosslessFormatFlag_16BitSourceData = 1,
kAppleLosslessFormatFlag_20BitSourceData = 2,
kAppleLosslessFormatFlag_24BitSourceData = 3,
kAppleLosslessFormatFlag_32BitSourceData = 4
};
/*!
@enum Commonly Used Combinations of AudioFormatFlags
@abstract Some commonly used combinations of flags for AudioStreamBasicDescriptions.
@constant kAudioFormatFlagsNativeEndian
Defined to set or clear kAudioFormatFlagIsBigEndian depending on the
endianness of the processor at build time.
@constant kAudioFormatFlagsCanonical
The flags for the canonical audio sample type. This matches AudioSampleType.
@constant kAudioFormatFlagsAudioUnitCanonical
The flags for the canonical audio unit sample type. This matches
AudioUnitSampleType.
@constant kAudioFormatFlagsNativeFloatPacked
The flags for fully packed, native endian floating point data.
@discussion
The "canonical" flags are deprecated. CA_PREFER_FIXED_POINT is discouraged because floating-
point performance on iOS is such that fixed point is no longer truly preferred. All Apple-
supplied AudioUnits support floating point. Replacement should be done with careful
consideration of the format being specified or expected, but often
kAudioFormatFlagsCanonical can be replaced with kAudioFormatFlagsNativeFloatPacked, and
kAudioFormatFlagsAudioUnitCanonical with kAudioFormatFlagsNativeFloatPacked |
kAudioFormatFlagIsNonInterleaved.
*/
CF_ENUM(AudioFormatFlags)
{
#if TARGET_RT_BIG_ENDIAN
kAudioFormatFlagsNativeEndian = kAudioFormatFlagIsBigEndian,
#else
kAudioFormatFlagsNativeEndian = 0,
#endif
#if !CA_PREFER_FIXED_POINT
kAudioFormatFlagsCanonical CA_CANONICAL_DEPRECATED = kAudioFormatFlagIsFloat | kAudioFormatFlagsNativeEndian | kAudioFormatFlagIsPacked,
kAudioFormatFlagsAudioUnitCanonical CA_CANONICAL_DEPRECATED = kAudioFormatFlagIsFloat | kAudioFormatFlagsNativeEndian | kAudioFormatFlagIsPacked | kAudioFormatFlagIsNonInterleaved,
#else
kAudioFormatFlagsCanonical CA_CANONICAL_DEPRECATED = kAudioFormatFlagIsSignedInteger | kAudioFormatFlagsNativeEndian | kAudioFormatFlagIsPacked,
kAudioFormatFlagsAudioUnitCanonical CA_CANONICAL_DEPRECATED = kAudioFormatFlagIsSignedInteger | kAudioFormatFlagsNativeEndian | kAudioFormatFlagIsPacked | kAudioFormatFlagIsNonInterleaved | (kAudioUnitSampleFractionBits << kLinearPCMFormatFlagsSampleFractionShift),
#endif
kAudioFormatFlagsNativeFloatPacked = kAudioFormatFlagIsFloat | kAudioFormatFlagsNativeEndian | kAudioFormatFlagIsPacked
};
/*!
@defined TestAudioFormatNativeEndian
@abstract A macro for checking if an ASBD indicates native endian linear PCM data.
*/
#define TestAudioFormatNativeEndian(f) ((f.mFormatID == kAudioFormatLinearPCM) && ((f.mFormatFlags & kAudioFormatFlagIsBigEndian) == kAudioFormatFlagsNativeEndian))
/*!
@function IsAudioFormatNativeEndian
@abstract A C++ inline function for checking if an ASBD indicates native endian linear PCM
data.
@param f
The AudioStreamBasicDescription to examine.
@result Whether or not the ASBD indicates native endian linear PCM data.
*/
#if defined(__cplusplus)
static inline bool IsAudioFormatNativeEndian(const AudioStreamBasicDescription& f) { return (f.mFormatID == kAudioFormatLinearPCM) && ((f.mFormatFlags & kAudioFormatFlagIsBigEndian) == kAudioFormatFlagsNativeEndian); }
#endif
/*!
@function CalculateLPCMFlags
@abstract A C++ inline function for calculating the mFormatFlags for linear PCM data. Note
that this function does not support specifying sample formats that are either
unsigned integer or low-aligned.
@param inSampleRate
@param inValidBitsPerChannel
The number of valid bits in each sample.
@param inTotalBitsPerChannel
The total number of bits in each sample.
@param inIsFloat
Whether or not the samples are represented with floating point numbers.
@param isIsBigEndian
Whether the samples are big endian or little endian.
@result A UInt32 containing the format flags.
*/
#if defined(__cplusplus)
static inline AudioFormatFlags CalculateLPCMFlags(UInt32 inValidBitsPerChannel, UInt32 inTotalBitsPerChannel, bool inIsFloat, bool inIsBigEndian, bool inIsNonInterleaved = false) { return (inIsFloat ? kAudioFormatFlagIsFloat : kAudioFormatFlagIsSignedInteger) | (inIsBigEndian ? ((UInt32)kAudioFormatFlagIsBigEndian) : 0) | ((inValidBitsPerChannel == inTotalBitsPerChannel) ? kAudioFormatFlagIsPacked : kAudioFormatFlagIsAlignedHigh) | (inIsNonInterleaved ? ((UInt32)kAudioFormatFlagIsNonInterleaved) : 0); }
#endif
/*!
@function FillOutASBDForLPCM
@abstract A C++ inline function for filling out an AudioStreamBasicDescription to describe
linear PCM data. Note that this function does not support specifying sample formats
that are either unsigned integer or low-aligned.
@param outASBD
The AudioStreamBasicDescription to fill out.
@param inSampleRate
The number of sample frames per second of the data in the stream.
@param inChannelsPerFrame
The number of channels in each frame of data.
@param inValidBitsPerChannel
The number of valid bits in each sample.
@param inTotalBitsPerChannel
The total number of bits in each sample.
@param inIsFloat
Whether or not the samples are represented with floating point numbers.
@param isIsBigEndian
Whether the samples are big endian or little endian.
*/
#if defined(__cplusplus)
static inline void FillOutASBDForLPCM(AudioStreamBasicDescription& outASBD, Float64 inSampleRate, UInt32 inChannelsPerFrame, UInt32 inValidBitsPerChannel, UInt32 inTotalBitsPerChannel, bool inIsFloat, bool inIsBigEndian, bool inIsNonInterleaved = false) { outASBD.mSampleRate = inSampleRate; outASBD.mFormatID = kAudioFormatLinearPCM; outASBD.mFormatFlags = CalculateLPCMFlags(inValidBitsPerChannel, inTotalBitsPerChannel, inIsFloat, inIsBigEndian, inIsNonInterleaved); outASBD.mBytesPerPacket = (inIsNonInterleaved ? 1 : inChannelsPerFrame) * (inTotalBitsPerChannel / 8); outASBD.mFramesPerPacket = 1; outASBD.mBytesPerFrame = (inIsNonInterleaved ? 1 : inChannelsPerFrame) * (inTotalBitsPerChannel / 8); outASBD.mChannelsPerFrame = inChannelsPerFrame; outASBD.mBitsPerChannel = inValidBitsPerChannel; }
#endif
/*!
@struct AudioStreamPacketDescription
@abstract This structure describes the packet layout of a buffer of data where the size of
each packet may not be the same or where there is extraneous data between
packets.
@field mStartOffset
The number of bytes from the start of the buffer to the beginning of the
packet.
@field mVariableFramesInPacket
The number of sample frames of data in the packet. For formats with a
constant number of frames per packet, this field is set to 0.
@field mDataByteSize
The number of bytes in the packet.
*/
struct AudioStreamPacketDescription
{
SInt64 mStartOffset;
UInt32 mVariableFramesInPacket;
UInt32 mDataByteSize;
};
typedef struct AudioStreamPacketDescription AudioStreamPacketDescription;
//==================================================================================================
#pragma mark -
#pragma mark Audio Time Stamps
// SMPTETime is also defined in the CoreVideo headers.
#if !defined(__SMPTETime__)
#define __SMPTETime__
/*!
@enum SMPTE Time Types
@abstract Constants that describe the type of SMPTE time.
@constant kSMPTETimeType24
24 Frame
@constant kSMPTETimeType25
25 Frame
@constant kSMPTETimeType30Drop
30 Drop Frame
@constant kSMPTETimeType30
30 Frame
@constant kSMPTETimeType2997
29.97 Frame
@constant kSMPTETimeType2997Drop
29.97 Drop Frame
@constant kSMPTETimeType60
60 Frame
@constant kSMPTETimeType5994
59.94 Frame
@constant kSMPTETimeType60Drop
60 Drop Frame
@constant kSMPTETimeType5994Drop
59.94 Drop Frame
@constant kSMPTETimeType50
50 Frame
@constant kSMPTETimeType2398
23.98 Frame
*/
typedef CF_ENUM(UInt32, SMPTETimeType)
{
kSMPTETimeType24 = 0,
kSMPTETimeType25 = 1,
kSMPTETimeType30Drop = 2,
kSMPTETimeType30 = 3,
kSMPTETimeType2997 = 4,
kSMPTETimeType2997Drop = 5,
kSMPTETimeType60 = 6,
kSMPTETimeType5994 = 7,
kSMPTETimeType60Drop = 8,
kSMPTETimeType5994Drop = 9,
kSMPTETimeType50 = 10,
kSMPTETimeType2398 = 11
};
/*!
@enum SMPTE State Flags
@abstract Flags that describe the SMPTE time state.
@constant kSMPTETimeValid
The full time is valid.
@constant kSMPTETimeRunning
Time is running.
*/
typedef CF_OPTIONS(UInt32, SMPTETimeFlags)
{
kSMPTETimeUnknown = 0,
kSMPTETimeValid = (1U << 0),
kSMPTETimeRunning = (1U << 1)
};
/*!
@struct SMPTETime
@abstract A structure for holding a SMPTE time.
@field mSubframes
The number of subframes in the full message.
@field mSubframeDivisor
The number of subframes per frame (typically 80).
@field mCounter
The total number of messages received.
@field mType
The kind of SMPTE time using the SMPTE time type constants.
@field mFlags
A set of flags that indicate the SMPTE state.
@field mHours
The number of hours in the full message.
@field mMinutes
The number of minutes in the full message.
@field mSeconds
The number of seconds in the full message.
@field mFrames
The number of frames in the full message.
*/
struct SMPTETime
{
SInt16 mSubframes;
SInt16 mSubframeDivisor;
UInt32 mCounter;
SMPTETimeType mType;
SMPTETimeFlags mFlags;
SInt16 mHours;
SInt16 mMinutes;
SInt16 mSeconds;
SInt16 mFrames;
};
typedef struct SMPTETime SMPTETime;
#endif
/*!
@enum AudioTimeStamp Flags
@abstract The flags that indicate which fields in an AudioTimeStamp structure are valid.
@constant kAudioTimeStampSampleTimeValid
The sample frame time is valid.
@constant kAudioTimeStampHostTimeValid
The host time is valid.
@constant kAudioTimeStampRateScalarValid
The rate scalar is valid.
@constant kAudioTimeStampWordClockTimeValid
The word clock time is valid.
@constant kAudioTimeStampSMPTETimeValid
The SMPTE time is valid.
@constant kAudioTimeStampSampleHostTimeValid
The sample frame time and the host time are valid.
*/
typedef CF_OPTIONS(UInt32, AudioTimeStampFlags)
{
kAudioTimeStampNothingValid = 0,
kAudioTimeStampSampleTimeValid = (1U << 0),
kAudioTimeStampHostTimeValid = (1U << 1),
kAudioTimeStampRateScalarValid = (1U << 2),
kAudioTimeStampWordClockTimeValid = (1U << 3),
kAudioTimeStampSMPTETimeValid = (1U << 4),
kAudioTimeStampSampleHostTimeValid = (kAudioTimeStampSampleTimeValid | kAudioTimeStampHostTimeValid)
};
/*!
@struct AudioTimeStamp
@abstract A structure that holds different representations of the same point in time.
@field mSampleTime
The absolute sample frame time.
@field mHostTime
The host machine's time base, mach_absolute_time.
@field mRateScalar
The ratio of actual host ticks per sample frame to the nominal host ticks
per sample frame.
@field mWordClockTime
The word clock time.
@field mSMPTETime
The SMPTE time.
@field mFlags
A set of flags indicating which representations of the time are valid.
@field mReserved
Pads the structure out to force an even 8 byte alignment.
*/
struct AudioTimeStamp
{
Float64 mSampleTime;
UInt64 mHostTime;
Float64 mRateScalar;
UInt64 mWordClockTime;
SMPTETime mSMPTETime;
AudioTimeStampFlags mFlags;
UInt32 mReserved;
};
typedef struct AudioTimeStamp AudioTimeStamp;
/*!
@function FillOutAudioTimeStampWithSampleTime
@abstract A C++ inline function for filling out an AudioTimeStamp with a sample time
@param outATS
The AudioTimeStamp to fill out.
@param inSampleTime
The sample time to put in the AudioTimeStamp.
*/
#if defined(__cplusplus)
static inline void FillOutAudioTimeStampWithSampleTime(AudioTimeStamp& outATS, Float64 inSampleTime) { outATS.mSampleTime = inSampleTime; outATS.mHostTime = 0; outATS.mRateScalar = 0; outATS.mWordClockTime = 0; memset(&outATS.mSMPTETime, 0, sizeof(SMPTETime)); outATS.mFlags = kAudioTimeStampSampleTimeValid; }
#endif
/*!
@function FillOutAudioTimeStampWithHostTime
@abstract A C++ inline function for filling out an AudioTimeStamp with a host time
@param outATS
The AudioTimeStamp to fill out.
@param inHostTime
The host time to put in the AudioTimeStamp.
*/
#if defined(__cplusplus)
static inline void FillOutAudioTimeStampWithHostTime(AudioTimeStamp& outATS, UInt64 inHostTime) { outATS.mSampleTime = 0; outATS.mHostTime = inHostTime; outATS.mRateScalar = 0; outATS.mWordClockTime = 0; memset(&outATS.mSMPTETime, 0, sizeof(SMPTETime)); outATS.mFlags = kAudioTimeStampHostTimeValid; }
#endif
/*!
@function FillOutAudioTimeStampWithSampleAndHostTime
@abstract A C++ inline function for filling out an AudioTimeStamp with a sample time and a
host time
@param outATS
The AudioTimeStamp to fill out.
@param inSampleTime
The sample time to put in the AudioTimeStamp.
@param inHostTime
The host time to put in the AudioTimeStamp.
*/
#if defined(__cplusplus)
static inline void FillOutAudioTimeStampWithSampleAndHostTime(AudioTimeStamp& outATS, Float64 inSampleTime, UInt64 inHostTime) { outATS.mSampleTime = inSampleTime; outATS.mHostTime = inHostTime; outATS.mRateScalar = 0; outATS.mWordClockTime = 0; memset(&outATS.mSMPTETime, 0, sizeof(SMPTETime)); outATS.mFlags = kAudioTimeStampSampleTimeValid | kAudioTimeStampHostTimeValid; }
#endif
//==================================================================================================
#pragma mark -
#pragma mark AudioClassDescription
/*!
@struct AudioClassDescription
@abstract This structure is used to describe codecs installed on the system.
@field mType
The four char code codec type.
@field mSubType
The four char code codec subtype.
@field mManufacturer
The four char code codec manufacturer.
*/
struct AudioClassDescription {
OSType mType;
OSType mSubType;
OSType mManufacturer;
};
typedef struct AudioClassDescription AudioClassDescription;
//==================================================================================================
#pragma mark -
#pragma mark Audio Channel Layout
/*!
@typedef AudioChannelLabel
@abstract A tag identifying how the channel is to be used.
*/
typedef UInt32 AudioChannelLabel;
/*!
@typedef AudioChannelLayoutTag
@abstract A tag identifying a particular pre-defined channel layout.
*/
typedef UInt32 AudioChannelLayoutTag;
/*!
@enum AudioChannelLabel Constants
@abstract These constants are for use in the mChannelLabel field of an
AudioChannelDescription structure.
@discussion These channel labels attempt to list all labels in common use. Due to the
ambiguities in channel labeling by various groups, there may be some overlap or
duplication in the labels below. Use the label which most clearly describes what
you mean.
WAVE files seem to follow the USB spec for the channel flags. A channel map lets
you put these channels in any order, however a WAVE file only supports labels
1-18 and if present, they must be in the order given below. The integer values
for the labels below match the bit position of the label in the USB bitmap and
thus also the WAVE file bitmap.
*/
CF_ENUM(AudioChannelLabel)
{
kAudioChannelLabel_Unknown = 0xFFFFFFFF, // unknown or unspecified other use
kAudioChannelLabel_Unused = 0, // channel is present, but has no intended use or destination
kAudioChannelLabel_UseCoordinates = 100, // channel is described by the mCoordinates fields.
kAudioChannelLabel_Left = 1,
kAudioChannelLabel_Right = 2,
kAudioChannelLabel_Center = 3,
kAudioChannelLabel_LFEScreen = 4,
kAudioChannelLabel_LeftSurround = 5, // WAVE: "Back Left"
kAudioChannelLabel_RightSurround = 6, // WAVE: "Back Right"
kAudioChannelLabel_LeftCenter = 7,
kAudioChannelLabel_RightCenter = 8,
kAudioChannelLabel_CenterSurround = 9, // WAVE: "Back Center" or plain "Rear Surround"
kAudioChannelLabel_LeftSurroundDirect = 10, // WAVE: "Side Left"
kAudioChannelLabel_RightSurroundDirect = 11, // WAVE: "Side Right"
kAudioChannelLabel_TopCenterSurround = 12,
kAudioChannelLabel_VerticalHeightLeft = 13, // WAVE: "Top Front Left"
kAudioChannelLabel_VerticalHeightCenter = 14, // WAVE: "Top Front Center"
kAudioChannelLabel_VerticalHeightRight = 15, // WAVE: "Top Front Right"
kAudioChannelLabel_TopBackLeft = 16,
kAudioChannelLabel_TopBackCenter = 17,
kAudioChannelLabel_TopBackRight = 18,
kAudioChannelLabel_RearSurroundLeft = 33,
kAudioChannelLabel_RearSurroundRight = 34,
kAudioChannelLabel_LeftWide = 35,
kAudioChannelLabel_RightWide = 36,
kAudioChannelLabel_LFE2 = 37,
kAudioChannelLabel_LeftTotal = 38, // matrix encoded 4 channels
kAudioChannelLabel_RightTotal = 39, // matrix encoded 4 channels
kAudioChannelLabel_HearingImpaired = 40,
kAudioChannelLabel_Narration = 41,
kAudioChannelLabel_Mono = 42,
kAudioChannelLabel_DialogCentricMix = 43,
kAudioChannelLabel_CenterSurroundDirect = 44, // back center, non diffuse
kAudioChannelLabel_Haptic = 45,
// first order ambisonic channels
kAudioChannelLabel_Ambisonic_W = 200,
kAudioChannelLabel_Ambisonic_X = 201,
kAudioChannelLabel_Ambisonic_Y = 202,
kAudioChannelLabel_Ambisonic_Z = 203,
// Mid/Side Recording
kAudioChannelLabel_MS_Mid = 204,
kAudioChannelLabel_MS_Side = 205,
// X-Y Recording
kAudioChannelLabel_XY_X = 206,
kAudioChannelLabel_XY_Y = 207,
// Binaural Recording
kAudioChannelLabel_BinauralLeft = 208,
kAudioChannelLabel_BinauralRight = 209,
// other
kAudioChannelLabel_HeadphonesLeft = 301,
kAudioChannelLabel_HeadphonesRight = 302,
kAudioChannelLabel_ClickTrack = 304,
kAudioChannelLabel_ForeignLanguage = 305,
// generic discrete channel
kAudioChannelLabel_Discrete = 400,
// numbered discrete channel
kAudioChannelLabel_Discrete_0 = (1U<<16) | 0,
kAudioChannelLabel_Discrete_1 = (1U<<16) | 1,
kAudioChannelLabel_Discrete_2 = (1U<<16) | 2,
kAudioChannelLabel_Discrete_3 = (1U<<16) | 3,
kAudioChannelLabel_Discrete_4 = (1U<<16) | 4,
kAudioChannelLabel_Discrete_5 = (1U<<16) | 5,
kAudioChannelLabel_Discrete_6 = (1U<<16) | 6,
kAudioChannelLabel_Discrete_7 = (1U<<16) | 7,
kAudioChannelLabel_Discrete_8 = (1U<<16) | 8,
kAudioChannelLabel_Discrete_9 = (1U<<16) | 9,
kAudioChannelLabel_Discrete_10 = (1U<<16) | 10,
kAudioChannelLabel_Discrete_11 = (1U<<16) | 11,
kAudioChannelLabel_Discrete_12 = (1U<<16) | 12,
kAudioChannelLabel_Discrete_13 = (1U<<16) | 13,
kAudioChannelLabel_Discrete_14 = (1U<<16) | 14,
kAudioChannelLabel_Discrete_15 = (1U<<16) | 15,
kAudioChannelLabel_Discrete_65535 = (1U<<16) | 65535,
// generic HOA ACN channel
kAudioChannelLabel_HOA_ACN = 500,
// numbered HOA ACN channels
kAudioChannelLabel_HOA_ACN_0 = (2U << 16) | 0,
kAudioChannelLabel_HOA_ACN_1 = (2U << 16) | 1,
kAudioChannelLabel_HOA_ACN_2 = (2U << 16) | 2,
kAudioChannelLabel_HOA_ACN_3 = (2U << 16) | 3,
kAudioChannelLabel_HOA_ACN_4 = (2U << 16) | 4,
kAudioChannelLabel_HOA_ACN_5 = (2U << 16) | 5,
kAudioChannelLabel_HOA_ACN_6 = (2U << 16) | 6,
kAudioChannelLabel_HOA_ACN_7 = (2U << 16) | 7,
kAudioChannelLabel_HOA_ACN_8 = (2U << 16) | 8,
kAudioChannelLabel_HOA_ACN_9 = (2U << 16) | 9,
kAudioChannelLabel_HOA_ACN_10 = (2U << 16) | 10,
kAudioChannelLabel_HOA_ACN_11 = (2U << 16) | 11,
kAudioChannelLabel_HOA_ACN_12 = (2U << 16) | 12,
kAudioChannelLabel_HOA_ACN_13 = (2U << 16) | 13,
kAudioChannelLabel_HOA_ACN_14 = (2U << 16) | 14,
kAudioChannelLabel_HOA_ACN_15 = (2U << 16) | 15,
kAudioChannelLabel_HOA_ACN_65024 = (2U << 16) | 65024, // 254th order uses 65025 channels
kAudioChannelLabel_BeginReserved = 0xF0000000, // Channel label values in this range are reserved for internal use
kAudioChannelLabel_EndReserved = 0xFFFFFFFE
};
/*!
@enum Channel Bitmap Constants
@abstract These constants are for use in the mChannelBitmap field of an
AudioChannelLayout structure.
*/
typedef CF_OPTIONS(UInt32, AudioChannelBitmap)
{
kAudioChannelBit_Left = (1U<<0),
kAudioChannelBit_Right = (1U<<1),
kAudioChannelBit_Center = (1U<<2),
kAudioChannelBit_LFEScreen = (1U<<3),
kAudioChannelBit_LeftSurround = (1U<<4), // WAVE: "Back Left"
kAudioChannelBit_RightSurround = (1U<<5), // WAVE: "Back Right"
kAudioChannelBit_LeftCenter = (1U<<6),
kAudioChannelBit_RightCenter = (1U<<7),
kAudioChannelBit_CenterSurround = (1U<<8), // WAVE: "Back Center"
kAudioChannelBit_LeftSurroundDirect = (1U<<9), // WAVE: "Side Left"
kAudioChannelBit_RightSurroundDirect = (1U<<10), // WAVE: "Side Right"
kAudioChannelBit_TopCenterSurround = (1U<<11),
kAudioChannelBit_VerticalHeightLeft = (1U<<12), // WAVE: "Top Front Left"
kAudioChannelBit_VerticalHeightCenter = (1U<<13), // WAVE: "Top Front Center"
kAudioChannelBit_VerticalHeightRight = (1U<<14), // WAVE: "Top Front Right"
kAudioChannelBit_TopBackLeft = (1U<<15),
kAudioChannelBit_TopBackCenter = (1U<<16),
kAudioChannelBit_TopBackRight = (1U<<17)
};
/*!
@enum Channel Coordinate Flags
@abstract These constants are used in the mChannelFlags field of an
AudioChannelDescription structure.
@constant kAudioChannelFlags_RectangularCoordinates
The channel is specified by the cartesioan coordinates of the speaker
position. This flag is mutally exclusive with
kAudioChannelFlags_SphericalCoordinates.
@constant kAudioChannelFlags_SphericalCoordinates
The channel is specified by the spherical coordinates of the speaker
position. This flag is mutally exclusive with
kAudioChannelFlags_RectangularCoordinates.
@constant kAudioChannelFlags_Meters
Set to indicate the units are in meters, clear to indicate the units are
relative to the unit cube or unit sphere.
*/
typedef CF_OPTIONS(UInt32, AudioChannelFlags)
{
kAudioChannelFlags_AllOff = 0,
kAudioChannelFlags_RectangularCoordinates = (1U<<0),
kAudioChannelFlags_SphericalCoordinates = (1U<<1),
kAudioChannelFlags_Meters = (1U<<2)
};
// these are indices for acessing the mCoordinates array in struct AudioChannelDescription
/*!
@enum Channel Coordinate Index Constants
@abstract Constants for indexing the mCoordinates array in an AudioChannelDescription
structure.
@constant kAudioChannelCoordinates_LeftRight
For rectangulare coordinates, negative is left and positive is right.
@constant kAudioChannelCoordinates_BackFront
For rectangulare coordinates, negative is back and positive is front.
@constant kAudioChannelCoordinates_DownUp
For rectangulare coordinates, negative is below ground level, 0 is ground
level, and positive is above ground level.
@constant kAudioChannelCoordinates_Azimuth
For spherical coordinates, 0 is front center, positive is right, negative is
left. This is measured in degrees.
@constant kAudioChannelCoordinates_Elevation
For spherical coordinates, +90 is zenith, 0 is horizontal, -90 is nadir.
This is measured in degrees.
@constant kAudioChannelCoordinates_Distance
For spherical coordinates, the units are described by flags.
*/
typedef CF_ENUM(UInt32, AudioChannelCoordinateIndex)
{
kAudioChannelCoordinates_LeftRight = 0,
kAudioChannelCoordinates_BackFront = 1,
kAudioChannelCoordinates_DownUp = 2,
kAudioChannelCoordinates_Azimuth = 0,
kAudioChannelCoordinates_Elevation = 1,
kAudioChannelCoordinates_Distance = 2
};
/*!
@enum AudioChannelLayoutTag Constants
@abstract These constants are used in the mChannelLayoutTag field of an AudioChannelLayout
structure.
*/
CF_ENUM(AudioChannelLayoutTag)
{
// Some channel abbreviations used below:
// L - left
// R - right
// C - center
// Ls - left surround
// Rs - right surround
// Cs - center surround
// Rls - rear left surround
// Rrs - rear right surround
// Lw - left wide
// Rw - right wide
// Lsd - left surround direct
// Rsd - right surround direct
// Lc - left center
// Rc - right center
// Ts - top surround
// Vhl - vertical height left
// Vhc - vertical height center
// Vhr - vertical height right
// Lt - left matrix total. for matrix encoded stereo.
// Rt - right matrix total. for matrix encoded stereo.
// General layouts
kAudioChannelLayoutTag_UseChannelDescriptions = (0U<<16) | 0, // use the array of AudioChannelDescriptions to define the mapping.
kAudioChannelLayoutTag_UseChannelBitmap = (1U<<16) | 0, // use the bitmap to define the mapping.
kAudioChannelLayoutTag_Mono = (100U<<16) | 1, // a standard mono stream
kAudioChannelLayoutTag_Stereo = (101U<<16) | 2, // a standard stereo stream (L R) - implied playback
kAudioChannelLayoutTag_StereoHeadphones = (102U<<16) | 2, // a standard stereo stream (L R) - implied headphone playback
kAudioChannelLayoutTag_MatrixStereo = (103U<<16) | 2, // a matrix encoded stereo stream (Lt, Rt)
kAudioChannelLayoutTag_MidSide = (104U<<16) | 2, // mid/side recording
kAudioChannelLayoutTag_XY = (105U<<16) | 2, // coincident mic pair (often 2 figure 8's)
kAudioChannelLayoutTag_Binaural = (106U<<16) | 2, // binaural stereo (left, right)
kAudioChannelLayoutTag_Ambisonic_B_Format = (107U<<16) | 4, // W, X, Y, Z
kAudioChannelLayoutTag_Quadraphonic = (108U<<16) | 4, // L R Ls Rs -- 90 degree speaker separation
kAudioChannelLayoutTag_Pentagonal = (109U<<16) | 5, // L R Ls Rs C -- 72 degree speaker separation
kAudioChannelLayoutTag_Hexagonal = (110U<<16) | 6, // L R Ls Rs C Cs -- 60 degree speaker separation
kAudioChannelLayoutTag_Octagonal = (111U<<16) | 8, // L R Ls Rs C Cs Lw Rw -- 45 degree speaker separation
kAudioChannelLayoutTag_Cube = (112U<<16) | 8, // left, right, rear left, rear right
// top left, top right, top rear left, top rear right
// MPEG defined layouts
kAudioChannelLayoutTag_MPEG_1_0 = kAudioChannelLayoutTag_Mono, // C
kAudioChannelLayoutTag_MPEG_2_0 = kAudioChannelLayoutTag_Stereo, // L R
kAudioChannelLayoutTag_MPEG_3_0_A = (113U<<16) | 3, // L R C
kAudioChannelLayoutTag_MPEG_3_0_B = (114U<<16) | 3, // C L R
kAudioChannelLayoutTag_MPEG_4_0_A = (115U<<16) | 4, // L R C Cs
kAudioChannelLayoutTag_MPEG_4_0_B = (116U<<16) | 4, // C L R Cs
kAudioChannelLayoutTag_MPEG_5_0_A = (117U<<16) | 5, // L R C Ls Rs
kAudioChannelLayoutTag_MPEG_5_0_B = (118U<<16) | 5, // L R Ls Rs C
kAudioChannelLayoutTag_MPEG_5_0_C = (119U<<16) | 5, // L C R Ls Rs
kAudioChannelLayoutTag_MPEG_5_0_D = (120U<<16) | 5, // C L R Ls Rs
kAudioChannelLayoutTag_MPEG_5_1_A = (121U<<16) | 6, // L R C LFE Ls Rs
kAudioChannelLayoutTag_MPEG_5_1_B = (122U<<16) | 6, // L R Ls Rs C LFE
kAudioChannelLayoutTag_MPEG_5_1_C = (123U<<16) | 6, // L C R Ls Rs LFE
kAudioChannelLayoutTag_MPEG_5_1_D = (124U<<16) | 6, // C L R Ls Rs LFE
kAudioChannelLayoutTag_MPEG_6_1_A = (125U<<16) | 7, // L R C LFE Ls Rs Cs
kAudioChannelLayoutTag_MPEG_7_1_A = (126U<<16) | 8, // L R C LFE Ls Rs Lc Rc
kAudioChannelLayoutTag_MPEG_7_1_B = (127U<<16) | 8, // C Lc Rc L R Ls Rs LFE (doc: IS-13818-7 MPEG2-AAC Table 3.1)
kAudioChannelLayoutTag_MPEG_7_1_C = (128U<<16) | 8, // L R C LFE Ls Rs Rls Rrs
kAudioChannelLayoutTag_Emagic_Default_7_1 = (129U<<16) | 8, // L R Ls Rs C LFE Lc Rc
kAudioChannelLayoutTag_SMPTE_DTV = (130U<<16) | 8, // L R C LFE Ls Rs Lt Rt
// (kAudioChannelLayoutTag_ITU_5_1 plus a matrix encoded stereo mix)
// ITU defined layouts
kAudioChannelLayoutTag_ITU_1_0 = kAudioChannelLayoutTag_Mono, // C
kAudioChannelLayoutTag_ITU_2_0 = kAudioChannelLayoutTag_Stereo, // L R
kAudioChannelLayoutTag_ITU_2_1 = (131U<<16) | 3, // L R Cs
kAudioChannelLayoutTag_ITU_2_2 = (132U<<16) | 4, // L R Ls Rs
kAudioChannelLayoutTag_ITU_3_0 = kAudioChannelLayoutTag_MPEG_3_0_A, // L R C
kAudioChannelLayoutTag_ITU_3_1 = kAudioChannelLayoutTag_MPEG_4_0_A, // L R C Cs
kAudioChannelLayoutTag_ITU_3_2 = kAudioChannelLayoutTag_MPEG_5_0_A, // L R C Ls Rs
kAudioChannelLayoutTag_ITU_3_2_1 = kAudioChannelLayoutTag_MPEG_5_1_A, // L R C LFE Ls Rs
kAudioChannelLayoutTag_ITU_3_4_1 = kAudioChannelLayoutTag_MPEG_7_1_C, // L R C LFE Ls Rs Rls Rrs
// DVD defined layouts
kAudioChannelLayoutTag_DVD_0 = kAudioChannelLayoutTag_Mono, // C (mono)
kAudioChannelLayoutTag_DVD_1 = kAudioChannelLayoutTag_Stereo, // L R
kAudioChannelLayoutTag_DVD_2 = kAudioChannelLayoutTag_ITU_2_1, // L R Cs
kAudioChannelLayoutTag_DVD_3 = kAudioChannelLayoutTag_ITU_2_2, // L R Ls Rs
kAudioChannelLayoutTag_DVD_4 = (133U<<16) | 3, // L R LFE
kAudioChannelLayoutTag_DVD_5 = (134U<<16) | 4, // L R LFE Cs
kAudioChannelLayoutTag_DVD_6 = (135U<<16) | 5, // L R LFE Ls Rs
kAudioChannelLayoutTag_DVD_7 = kAudioChannelLayoutTag_MPEG_3_0_A, // L R C
kAudioChannelLayoutTag_DVD_8 = kAudioChannelLayoutTag_MPEG_4_0_A, // L R C Cs
kAudioChannelLayoutTag_DVD_9 = kAudioChannelLayoutTag_MPEG_5_0_A, // L R C Ls Rs
kAudioChannelLayoutTag_DVD_10 = (136U<<16) | 4, // L R C LFE
kAudioChannelLayoutTag_DVD_11 = (137U<<16) | 5, // L R C LFE Cs
kAudioChannelLayoutTag_DVD_12 = kAudioChannelLayoutTag_MPEG_5_1_A, // L R C LFE Ls Rs
// 13 through 17 are duplicates of 8 through 12.
kAudioChannelLayoutTag_DVD_13 = kAudioChannelLayoutTag_DVD_8, // L R C Cs
kAudioChannelLayoutTag_DVD_14 = kAudioChannelLayoutTag_DVD_9, // L R C Ls Rs
kAudioChannelLayoutTag_DVD_15 = kAudioChannelLayoutTag_DVD_10, // L R C LFE
kAudioChannelLayoutTag_DVD_16 = kAudioChannelLayoutTag_DVD_11, // L R C LFE Cs
kAudioChannelLayoutTag_DVD_17 = kAudioChannelLayoutTag_DVD_12, // L R C LFE Ls Rs
kAudioChannelLayoutTag_DVD_18 = (138U<<16) | 5, // L R Ls Rs LFE
kAudioChannelLayoutTag_DVD_19 = kAudioChannelLayoutTag_MPEG_5_0_B, // L R Ls Rs C
kAudioChannelLayoutTag_DVD_20 = kAudioChannelLayoutTag_MPEG_5_1_B, // L R Ls Rs C LFE
// These layouts are recommended for AudioUnit usage
// These are the symmetrical layouts
kAudioChannelLayoutTag_AudioUnit_4 = kAudioChannelLayoutTag_Quadraphonic,
kAudioChannelLayoutTag_AudioUnit_5 = kAudioChannelLayoutTag_Pentagonal,
kAudioChannelLayoutTag_AudioUnit_6 = kAudioChannelLayoutTag_Hexagonal,
kAudioChannelLayoutTag_AudioUnit_8 = kAudioChannelLayoutTag_Octagonal,
// These are the surround-based layouts
kAudioChannelLayoutTag_AudioUnit_5_0 = kAudioChannelLayoutTag_MPEG_5_0_B, // L R Ls Rs C
kAudioChannelLayoutTag_AudioUnit_6_0 = (139U<<16) | 6, // L R Ls Rs C Cs
kAudioChannelLayoutTag_AudioUnit_7_0 = (140U<<16) | 7, // L R Ls Rs C Rls Rrs
kAudioChannelLayoutTag_AudioUnit_7_0_Front = (148U<<16) | 7, // L R Ls Rs C Lc Rc
kAudioChannelLayoutTag_AudioUnit_5_1 = kAudioChannelLayoutTag_MPEG_5_1_A, // L R C LFE Ls Rs
kAudioChannelLayoutTag_AudioUnit_6_1 = kAudioChannelLayoutTag_MPEG_6_1_A, // L R C LFE Ls Rs Cs
kAudioChannelLayoutTag_AudioUnit_7_1 = kAudioChannelLayoutTag_MPEG_7_1_C, // L R C LFE Ls Rs Rls Rrs
kAudioChannelLayoutTag_AudioUnit_7_1_Front = kAudioChannelLayoutTag_MPEG_7_1_A, // L R C LFE Ls Rs Lc Rc
kAudioChannelLayoutTag_AAC_3_0 = kAudioChannelLayoutTag_MPEG_3_0_B, // C L R
kAudioChannelLayoutTag_AAC_Quadraphonic = kAudioChannelLayoutTag_Quadraphonic, // L R Ls Rs
kAudioChannelLayoutTag_AAC_4_0 = kAudioChannelLayoutTag_MPEG_4_0_B, // C L R Cs
kAudioChannelLayoutTag_AAC_5_0 = kAudioChannelLayoutTag_MPEG_5_0_D, // C L R Ls Rs
kAudioChannelLayoutTag_AAC_5_1 = kAudioChannelLayoutTag_MPEG_5_1_D, // C L R Ls Rs Lfe
kAudioChannelLayoutTag_AAC_6_0 = (141U<<16) | 6, // C L R Ls Rs Cs
kAudioChannelLayoutTag_AAC_6_1 = (142U<<16) | 7, // C L R Ls Rs Cs Lfe
kAudioChannelLayoutTag_AAC_7_0 = (143U<<16) | 7, // C L R Ls Rs Rls Rrs
kAudioChannelLayoutTag_AAC_7_1 = kAudioChannelLayoutTag_MPEG_7_1_B, // C Lc Rc L R Ls Rs Lfe
kAudioChannelLayoutTag_AAC_7_1_B = (183U<<16) | 8, // C L R Ls Rs Rls Rrs LFE
kAudioChannelLayoutTag_AAC_7_1_C = (184U<<16) | 8, // C L R Ls Rs LFE Vhl Vhr
kAudioChannelLayoutTag_AAC_Octagonal = (144U<<16) | 8, // C L R Ls Rs Rls Rrs Cs
kAudioChannelLayoutTag_TMH_10_2_std = (145U<<16) | 16, // L R C Vhc Lsd Rsd Ls Rs Vhl Vhr Lw Rw Csd Cs LFE1 LFE2
kAudioChannelLayoutTag_TMH_10_2_full = (146U<<16) | 21, // TMH_10_2_std plus: Lc Rc HI VI Haptic
kAudioChannelLayoutTag_AC3_1_0_1 = (149U<<16) | 2, // C LFE
kAudioChannelLayoutTag_AC3_3_0 = (150U<<16) | 3, // L C R
kAudioChannelLayoutTag_AC3_3_1 = (151U<<16) | 4, // L C R Cs
kAudioChannelLayoutTag_AC3_3_0_1 = (152U<<16) | 4, // L C R LFE
kAudioChannelLayoutTag_AC3_2_1_1 = (153U<<16) | 4, // L R Cs LFE
kAudioChannelLayoutTag_AC3_3_1_1 = (154U<<16) | 5, // L C R Cs LFE
kAudioChannelLayoutTag_EAC_6_0_A = (155U<<16) | 6, // L C R Ls Rs Cs
kAudioChannelLayoutTag_EAC_7_0_A = (156U<<16) | 7, // L C R Ls Rs Rls Rrs
kAudioChannelLayoutTag_EAC3_6_1_A = (157U<<16) | 7, // L C R Ls Rs LFE Cs
kAudioChannelLayoutTag_EAC3_6_1_B = (158U<<16) | 7, // L C R Ls Rs LFE Ts
kAudioChannelLayoutTag_EAC3_6_1_C = (159U<<16) | 7, // L C R Ls Rs LFE Vhc
kAudioChannelLayoutTag_EAC3_7_1_A = (160U<<16) | 8, // L C R Ls Rs LFE Rls Rrs
kAudioChannelLayoutTag_EAC3_7_1_B = (161U<<16) | 8, // L C R Ls Rs LFE Lc Rc
kAudioChannelLayoutTag_EAC3_7_1_C = (162U<<16) | 8, // L C R Ls Rs LFE Lsd Rsd
kAudioChannelLayoutTag_EAC3_7_1_D = (163U<<16) | 8, // L C R Ls Rs LFE Lw Rw
kAudioChannelLayoutTag_EAC3_7_1_E = (164U<<16) | 8, // L C R Ls Rs LFE Vhl Vhr
kAudioChannelLayoutTag_EAC3_7_1_F = (165U<<16) | 8, // L C R Ls Rs LFE Cs Ts
kAudioChannelLayoutTag_EAC3_7_1_G = (166U<<16) | 8, // L C R Ls Rs LFE Cs Vhc
kAudioChannelLayoutTag_EAC3_7_1_H = (167U<<16) | 8, // L C R Ls Rs LFE Ts Vhc
kAudioChannelLayoutTag_DTS_3_1 = (168U<<16) | 4, // C L R LFE
kAudioChannelLayoutTag_DTS_4_1 = (169U<<16) | 5, // C L R Cs LFE
kAudioChannelLayoutTag_DTS_6_0_A = (170U<<16) | 6, // Lc Rc L R Ls Rs
kAudioChannelLayoutTag_DTS_6_0_B = (171U<<16) | 6, // C L R Rls Rrs Ts
kAudioChannelLayoutTag_DTS_6_0_C = (172U<<16) | 6, // C Cs L R Rls Rrs
kAudioChannelLayoutTag_DTS_6_1_A = (173U<<16) | 7, // Lc Rc L R Ls Rs LFE
kAudioChannelLayoutTag_DTS_6_1_B = (174U<<16) | 7, // C L R Rls Rrs Ts LFE
kAudioChannelLayoutTag_DTS_6_1_C = (175U<<16) | 7, // C Cs L R Rls Rrs LFE
kAudioChannelLayoutTag_DTS_7_0 = (176U<<16) | 7, // Lc C Rc L R Ls Rs
kAudioChannelLayoutTag_DTS_7_1 = (177U<<16) | 8, // Lc C Rc L R Ls Rs LFE
kAudioChannelLayoutTag_DTS_8_0_A = (178U<<16) | 8, // Lc Rc L R Ls Rs Rls Rrs
kAudioChannelLayoutTag_DTS_8_0_B = (179U<<16) | 8, // Lc C Rc L R Ls Cs Rs
kAudioChannelLayoutTag_DTS_8_1_A = (180U<<16) | 9, // Lc Rc L R Ls Rs Rls Rrs LFE
kAudioChannelLayoutTag_DTS_8_1_B = (181U<<16) | 9, // Lc C Rc L R Ls Cs Rs LFE
kAudioChannelLayoutTag_DTS_6_1_D = (182U<<16) | 7, // C L R Ls Rs LFE Cs
kAudioChannelLayoutTag_HOA_ACN_SN3D = (190U<<16) | 0, // Higher Order Ambisonics, Ambisonics Channel Number, SN3D normalization
// needs to be ORed with the actual number of channels (not the HOA order)
kAudioChannelLayoutTag_HOA_ACN_N3D = (191U<<16) | 0, // Higher Order Ambisonics, Ambisonics Channel Number, N3D normalization
// needs to be ORed with the actual number of channels (not the HOA order)
kAudioChannelLayoutTag_DiscreteInOrder = (147U<<16) | 0, // needs to be ORed with the actual number of channels
kAudioChannelLayoutTag_BeginReserved = 0xF0000000, // Channel layout tag values in this range are reserved for internal use
kAudioChannelLayoutTag_EndReserved = 0xFFFEFFFF,
kAudioChannelLayoutTag_Unknown = 0xFFFF0000 // needs to be ORed with the actual number of channels
};
/*!
@struct AudioChannelDescription
@abstract This structure describes a single channel.
@field mChannelLabel
The AudioChannelLabel that describes the channel.
@field mChannelFlags
Flags that control the interpretation of mCoordinates.
@field mCoordinates
An ordered triple that specifies a precise speaker location.
*/
struct AudioChannelDescription
{
AudioChannelLabel mChannelLabel;
AudioChannelFlags mChannelFlags;
Float32 mCoordinates[3];
};
typedef struct AudioChannelDescription AudioChannelDescription;
/*!
@struct AudioChannelLayout
@abstract This structure is used to specify channel layouts in files and hardware.
@field mChannelLayoutTag
The AudioChannelLayoutTag that indicates the layout.
@field mChannelBitmap
If mChannelLayoutTag is set to kAudioChannelLayoutTag_UseChannelBitmap, this
field is the channel usage bitmap.
@field mNumberChannelDescriptions
The number of items in the mChannelDescriptions array.
@field mChannelDescriptions
A variable length array of AudioChannelDescriptions that describe the
layout.
*/
struct AudioChannelLayout
{
AudioChannelLayoutTag mChannelLayoutTag;
AudioChannelBitmap mChannelBitmap;
UInt32 mNumberChannelDescriptions;
AudioChannelDescription mChannelDescriptions[1]; // this is a variable length array of mNumberChannelDescriptions elements
#if defined(__cplusplus) && CA_STRICT
public:
AudioChannelLayout() {}
private:
// Copying and assigning a variable length struct is problematic so turn their use into a
// compile time error for easy spotting.
AudioChannelLayout(const AudioChannelLayout&);
AudioChannelLayout& operator=(const AudioChannelLayout&);
#endif
};
typedef struct AudioChannelLayout AudioChannelLayout;
/*!
@function AudioChannelLayoutTag_GetNumberOfChannels
@abstract A macro to get the number of channels out of an AudioChannelLayoutTag
@discussion The low 16 bits of an AudioChannelLayoutTag gives the number of channels except
for kAudioChannelLayoutTag_UseChannelDescriptions and
kAudioChannelLayoutTag_UseChannelBitmap.
@param layoutTag
The AudioChannelLayoutTag to examine.
@result The number of channels the tag indicates.
*/
#ifdef CF_INLINE
CF_INLINE UInt32 AudioChannelLayoutTag_GetNumberOfChannels(AudioChannelLayoutTag inLayoutTag) { return (UInt32)(inLayoutTag & 0x0000FFFF); }
#else
#define AudioChannelLayoutTag_GetNumberOfChannels(layoutTag) ((UInt32)((layoutTag) & 0x0000FFFF))
#endif
// Deprecated constants
/*! @enum MPEG-4 Audio Object IDs
@deprecated in version 10.5
@abstract Constants that describe the various kinds of MPEG-4 audio data.
@discussion These constants are used in the flags field of an AudioStreamBasicDescription
that describes an MPEG-4 audio stream.
*/
typedef CF_ENUM(long, MPEG4ObjectID)
{
kMPEG4Object_AAC_Main = 1,
kMPEG4Object_AAC_LC = 2,
kMPEG4Object_AAC_SSR = 3,
kMPEG4Object_AAC_LTP = 4,
kMPEG4Object_AAC_SBR = 5,
kMPEG4Object_AAC_Scalable = 6,
kMPEG4Object_TwinVQ = 7,
kMPEG4Object_CELP = 8,
kMPEG4Object_HVXC = 9
};
//==================================================================================================
#if defined(__cplusplus)
}
#endif
#endif // CoreAudio_CoreAudioTypes_h
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment