MTCoreAudioDevice
An MTCoreAudioDevice instance represents an audio device connected to
the system. The instance may have a delegate, and may have an
AudioDeviceIOProc
or an IOTarget.
Additionally, the class itself may have a delegate to be notified of changes
to the global audio hardware environment.
There may be more than one instance that refers to the same physical audio
hardware device.
The first time a message is sent to this class, services of MTCoreAudio such as
hardware notifications and
value transformers
will be initialized and registered with the appropriate Cocoa components.
Method Types
- Creating instances
- Working with delegates
- A device's identifying information
- Working with streams
- Working with sources
- Working with buffering
- Working with volume
- Working with stream formats
- Working with sample rates
- Working with IO
Class Methods
+ (NSArray *) allDevices
Returns an NSArray of all audio devices attached to the system. Instances are ordered by ascending device name,
with device UID as the tie-breaker.
+ (NSArray *) allDevicesByRelation
Returns all of the audio devices attached to the system, as an NSArray of NSArrays of audio devices. Each sub-array groups all devices that are related, as determined by the respective audio drivers. The devices in each sub-array are ordered in the manner of +allDevices, and the order of the sub-arrays is deternmined using the same ordering rules, by the first device in each sub-array.
+ (void) attachNotificationsToThisThread
Instructs the HAL to move its notifications to the run loop of the thread from which this message was sent. It's recommended that the HAL's notifications should be attached to the main thread in Cocoa graphical applications.
+ (MTCoreAudioDevice *) defaultInputDevice
Returns a new instance representing the system's default input device.
+ (MTCoreAudioDevice *) defaultOutputDevice
Returns a new instance representing the system's default output device for normal audio.
+ (MTCoreAudioDevice *) defaultSystemOutputDevice
Returns a new instance representing the system's default output device for system
services, such as SysBeep().
+ (id) delegate
Returns the delegate for the class. See
methods implemented by the class's delegate.
Does not retain the delegate, so make sure you change or remove the delegate
before deallocating theDelegate.
+ (NSArray *) devicesWithName:(NSString *)theName havingStreamsForDirection:(MTCoreAudioDirection)theDirection
Returns a (possibly empty) NSArray of device instances, each of which
represents an attached audio device with name theName and at least one stream/channel for theDirection.
Devices are ordered by ascending device UID.
+ (MTCoreAudioDevice *) deviceWithID:(AudioDeviceID)theID
Returns a new instance representing the audio device with ID theID.
+ (MTCoreAudioDevice *) deviceWithUID:(NSString *)theUID
Returns a new instance representing the audio device with Unique Identifier theUID.
Audio device Unique Identifiers are persistent across runs of a program and system
restarts.
+ (void) setDelegate:(id)theDelegate
Sets the class's delegate to theDelegate. See
methods implemented by the class's delegate.
Does not retain the delegate, so make sure you change or remove the delegate
before deallocating theDelegate. If theDelegate is nil,
the class's delegate is removed.
Instance Methods
- (Float64) actualSampleRate
Returns the actual sampling rate at which the device is currently
running, or the nominal sampling rate if the device is not running
right now.
- (Boolean) canSetDataSourceForDirection:(MTCoreAudioDirection)theDirection
Returns YES if the device's master source in theDirection can be
changed by
setDataSource:forDirection:
to one of the values returned by
dataSourcesForDirection:,
and NO if that property can't be set under program control.
If this method returns NO but dataSourcesForDirection:
returns multiple sources, then the value of
dataSourceForDirection:
is informational, and reflects an externally-controlled choice, such
as Headphones vs. Internal Speakers.
- (NSArray *) channelsByStreamForDirection:(MTCoreAudioDirection)theDirection
Returns an NSArray of NSNumbers. Each element of the array represents the
number of channels in the corresponding stream.
- (UInt32) channelsForDirection:(MTCoreAudioDirection)theDirection
Returns the number of channels in theDirection. Returns 0 if the device
doesn't support the requested direction.
- (NSString *) clockSourceForChannel:(UInt32)theChannel forDirection:(MTCoreAudioDirection)theDirection
Returns the current clock source
for channel theChannel of direction theDirection.
Returns nil if this device or channel does not define a clock source in the direction.
Typically, sources won't be defined if a device has only one clock in the direction.
- (NSArray *) clockSourcesForChannel:(UInt32)theChannel forDirection:(MTCoreAudioDirection)theDirection
Returns an NSArray of NSStrings representing the available clock sources for the
given channel in the given direction. Returns nil if the device
doesn't feel like it defines any clock sources.
- (MTCoreAudioDevice *) clone
Returns a new, autoreleased MTCoreAudioDevice instance that refers to the same audio device
as the receiver. The new instance's delegate and AudioIOProc, if any, are not copied.
- (NSString *) dataSourceForDirection:(MTCoreAudioDirection)theDirection
Returns the current device master data source (such as "Internal Microphone" or "Line in")
for direction theDirection.
Returns nil if this device does not define a master source in the direction.
Typically, sources won't be defined if a device has only one port in the direction.
- (NSArray *) dataSourcesForDirection:(MTCoreAudioDirection)theDirection
Returns an NSArray of NSStrings representing the available device master sources for the
given direction. Returns an empty NSArray if the device
doesn't feel like it defines a master source.
- (id) delegate
Returns the delegate for the instance. See
methods implemented by the delegate.
Does not retain the delegate, so make sure you change or remove the delegate
before deallocating theDelegate.
- (UInt32) deviceBufferSizeInFrames
Returns the current length in frames of the buffers that will be used with the IOProc.
If the sizes of the IO buffers may vary by a small amount from IO cycle to IO cycle,
then this will indicate the smallest buffer that will be passed.
This, along with the sample rate, defines the minumum length of time represented by
one IO cycle.
- (AudioDeviceID) deviceID
Returns the AudioDeviceID (a UInt32) with which this instance is associated.
This identifier is not persistent across runs of a program or system restarts.
See deviceUID for a persistent device identifier.
- (UInt32) deviceLatencyFramesForDirection:(MTCoreAudioDirection)theDirection
Returns the number of frames of latency in theDirection.
- (NSString *) deviceManufacturer
The manufacturer of this device, such as "Apple".
- (UInt32) deviceMaxBufferSizeInFrames
Returns the largest permissible IO buffer size, in frames.
- (UInt32) deviceMaxVariableBufferSizeInFrames
If the sizes of the IO buffers may vary by a small amount from IO cycle to IO cycle,
to accommodate the natural rhythms of the device, this will indicate the largest buffer
that will be passed. If the size of the IO buffers will not vary from cycle to cycle,
this value will be identical to deviceBufferSizeInFrames.
This, along with the sample rate, defines the maximum length of time represented by
one IO cycle.
- (UInt32) deviceMinBufferSizeInFrames
Returns the smallest permissible IO buffer size, in frames.
- (NSString *) deviceName
The human-readable name of this device, such as "Built-in audio controller".
- (UInt32) deviceSafetyOffsetFramesForDirection:(MTCoreAudioDirection)theDirection
Returns the number of frames ahead (playback) or behind (recording) the head that it is safe to start reading or writing.
- (Boolean) deviceStart
Attempts to start IO cycles for the device using the instance's IOProc
or IOTarget. Returns true if
IO cycles will start or are already started, and false if the device can't be started. If the device can't
be started, the delegate will be sent audioDeviceStartDidFail:forReason:.
- (void) deviceStop
Halts IO cycles for the receiver. An in-progress IO cycle will complete before this method completes.
The IOProc/IOTarget is also halted when the instance is deallocated.
- (NSString *) deviceUID
Returns the Unique Identifier of this device.
Audio device Unique Identifiers are persistent across runs of a program and system
restarts. See also deviceWithUID:.
- (MTCoreAudioDevice *) initWithDeviceID:(AudioDeviceID)theID
Initializes a new instance representing the audio device with ID theID.
- (BOOL) isEqual:(id)other
Returns YES if the receiver and other refer to the
same Actual Audio Device, and NO if they do not.
- (MTCoreAudioStreamDescription *) matchStreamDescription:(MTCoreAudioStreamDescription *)theDescription forChannel:(UInt32)theChannel forDirection:(MTCoreAudioDirection)theDirection
Returns a new MTCoreAudioStreamDescription
that's the device's best match to an available stream format on theChannel in
theDirection. Matching is done at the discretion of the device driver; returned
formats may be significantly different than that passed in.
- (Float64) nominalSampleRate
Returns the nominal sampling rate to which the device is currently set.
- (NSArray *) nominalSampleRates
Returns the ranges of available sampling rates supported by the device.
Each entry of the returned NSArray is itself an NSArray consisting of
two NSNumbers. The first NSNumber is the minimum sampling rate in
a range, the second is the maximum sampling rate in that same range.
The device may support multiple, disjoint ranges of sampling rates,
such as (for example) 4000-8000Hz, 24000-24000Hz, 32000-48000Hz.
- (NSArray *) relatedDevices
Returns an NSArray, ordered in the manner of +allDevices, of all audio devices attached to the system that are related to the receiver. Relationship is determined by the respective drivers. Includes the receiver.
- (void) removeIOProc
Removes the instance's IOProc
or IOTarget,
if it had one. If the device was running the instance's
IOProc or IOTarget, it is stopped. The instance's IOProc/IOTarget is removed automatically when
the instance is deallocated.
- (void) removeIOTarget
This is equivalent to removeIOProc, and is provided
for consistency.
- (void) setClockSource:(NSString *)theSource forChannel:(UInt32)theChannel forDirection:(MTCoreAudioDirection)theDirection
Sets the clock source for theChannel in theDirection. theSource should
be one of the values returned by clockSourcesForChannel:forDirection:.
This method has no effect if theSource is not an available clock source.
- (void) setDataSource:(NSString *)theSource forDirection:(MTCoreAudioDirection)theDirection
Sets the device master source for theDirection. theSource should
be one of the values returned by dataSourcesForDirection:.
This method has no effect if theSource is not an available source.
- (void) setDelegate:(id)theDelegate
Sets the delegate to theDelegate. See
methods implemented by the delegate.
Does not retain the delegate, so make sure you change or remove the delegate
before deallocating theDelegate. If theDelegate is nil,
the delegate is removed.
- (void) setDeviceBufferSizeInFrames:(UInt32)numFrames
Sets the length in frames of the buffers that will be passed to the IOProc.
This, along with the sample rate, defines the length of time represented by
one IO cycle.
- (void) setDevicePaused:(Boolean)shouldPause
If shouldPause is true, then the receiver's IOProc/IOTarget will not run (and an in-progress one will be complete) after this method completes. If false, then the IOProc/IOTarget may again be run. Pausing the device keeps its IO cycles and timing running, and only prevents the IOProc/IOTarget from running. This may be useful if changes to data used by an IOProc must be made asynchronously, without disturbing the IO timing or incurring the overhead of stopping and restarting the device's IO. The paused state of a device is independent of its running state, as set by deviceStart and deviceStop.
- (void) setIOProc:(AudioDeviceIOProc)theIOProc withClientData:(void *)theClientData
Sets the instance's IOProc to theIOProc, which will be passed theClientData when running.
An instance may have only one IOProc (or target/selector) at a time; if one is set and this method
is called again, the old one will be replaced. This method also issues
deviceStop.
Multiple instances representing the
same physical device may each have their own IOProcs (or targets/selectors), which may be
the same or distinct.
See
AudioDeviceIOProc
for more information.
- (void) setIOTarget:(id)theTarget withSelector:(SEL)theSelector withClientData:(void *)theClientData
This is the object analogue to setIOProc:withClientData:; the
difference being that, during the IO cycle, the device instance will send theSelector to
theTarget, rather than calling a C function. The signature of theSelector must be the
same as:
- (OSStatus) ioCycleForDevice:(MTCoreAudioDevice *)theDevice timeStamp:(const AudioTimeStamp *)inNow inputData:(const AudioBufferList *)inInputData inputTime:(const AudioTimeStamp *)inInputTime outputData:(AudioBufferList *)outOutputData outputTime:(const AudioTimeStamp *)inOutputTime clientData:(void *)inClientData
That is, the parameters must have the same type and be in the same order as the above, although they may have different
names. This is done, rather than using a fixed selector, so that one object can respond
to the IO cycles of multiple devices in different ways. The parameters of this method
have the same sense as those of an AudioDeviceIOProc.
An instance may have only one target/selector (or IOProc) at a time; if one is set and this method
is called again, the old one will be replaced. This method also issues
deviceStop.
Multiple instances representing the
same physical device may each have their own targets/selectors (or IOProcs), which may be
the same or distinct.
Important note: there is no autorelease pool provided by the IOTarget dispatcher; if
you require one, you must create one yourself. However, it is strongly recommended that you avoid object
creation and memory allocation during the IO cycle, to avoid dropouts and overloading.
- (void) setMute:(BOOL)isMuted forChannel:(UInt32)theChannel forDirection:(MTCoreAudioDirection)theDirection
If isMuted is true, mute theChannel in theDirection,
otherwise, unmute it.
- (Boolean) setNominalSampleRate:(Float64)theRate
Attempt to set the nominal sampling rate of the device to theRate. Returns
YES if successful, and NO if unsuccessful.
- (void) setPlayThru:(BOOL)isPlayingThru forChannel:(UInt32)theChannel
If isPlayingThru is TRUE, turn on Play-Thru mode on theChannel.
Otherwise, turn off Play-Thru mode.
- (Boolean) setStreamDescription:(MTCoreAudioStreamDescription *)theDescription forChannel:(UInt32)theChannel forDirection:(MTCoreAudioDirection)theDirection
Sets the stream format of the stream containing theChannel in theDirection
to theDescription.
Returns true if the stream format was changed successfully, and false if not.
See the caveat for streamDescriptionForChannel:forDirection:.
- (void) setVolume:(Float32)theVolume forChannel:(UInt32)theChannel forDirection:(MTCoreAudioDirection)theDirection
Sets the volume of theChannel in theDirection to theVolume, which should
be between 0.0 and 1.0.
- (void) setVolumeDecibels:(Float32)theVolumeDecibels forChannel:(UInt32)theChannel forDirection:(MTCoreAudioDirection)theDirection
Sets the volume of theChannel in theDirection to theVolumeDecibels.
- (Class) streamDescriptionFactory
Returns the factory object for MTCoreAudioStreamDescriptions.
Subclasses may override this method in order to also subclass the MTCoreAudioStreamDescription class.
- (MTCoreAudioStreamDescription *) streamDescriptionForChannel:(UInt32)theChannel forDirection:(MTCoreAudioDirection)theDirection
Return the current logical
stream format
for the stream containing theChannel in theDirection.
Note that stream formats returned by queries to MTCoreAudioDevices are always
for the kMTCoreAudioStreamLogicalSide
side of a stream, and are therefore 32-bit floating point. Use
MTCoreAudioStreams to query or set the
kMTCoreAudioStreamPhysicalSide
side of a stream.
- (NSArray *) streamDescriptionsForChannel:(UInt32)theChannel forDirection:(MTCoreAudioDirection)theDirection
Returns an NSArray of
MTCoreAudioStreamDescriptions
available on the stream containing theChannel in theDirection.
See the caveat for streamDescriptionForChannel:forDirection:.
- (Class) streamFactory
Returns the factory object for MTCoreAudioStreams.
Subclasses may override this method in order to also subclass the MTCoreAudioStream class.
- (NSArray *) streamsForDirection:(MTCoreAudioDirection)theDirection
Returns an NSArray of
MTCoreAudioStreams for direction theDirection.
Note that a device may have no streams in one direction or another if it is
a record-only or playback-only device.
- (Boolean) supportsNominalSampleRate:(Float64)theRate
Returns YES if theRate falls within one of the ranges reported by
nominalSampleRates, and NO if not.
- (Float32) volumeForChannel:(UInt32)theChannel forDirection:(MTCoreAudioDirection)theDirection
Returns the current volume of theChannel in theDirection as a Float32 between
0.0 and 1.0.
- (Float32) volumeForVolumeInDecibels:(Float32)theVolumeDecibels forChannel:(UInt32)theChannel forDirection:(MTCoreAudioDirection)theDirection
Convert from decibels to linear volume, according to the device's channel's characteristics.
- (Float32) volumeInDecibelsForChannel:(UInt32)theChannel forDirection:(MTCoreAudioDirection)theDirection
Returns the volume of theChannel in theDirection as a Float32, measured
in decibels.
- (Float32) volumeInDecibelsForVolume:(Float32)theVolume forChannel:(UInt32)theChannel forDirection:(MTCoreAudioDirection)theDirection
Convert from linear volume to decibels, according to the device's channel's characteristics.
- (MTCoreAudioVolumeInfo) volumeInfoForChannel:(UInt32)theChannel forDirection:(MTCoreAudioDirection)theDirection
Returns an MTCoreAudioVolumeInfo structure
which collects all the interesting volume-related information about theChannel in
theDirection together, including whether the channel has a volume control, whether
it can be muted, whether it is muted, the current volume setting, and more.
- (void) audioHardwareDefaultInputDeviceDidChange
Sent when the default input device is changed by the user.
- (void) audioHardwareDefaultOutputDeviceDidChange
Sent when the default output device is changed by the user.
- (void) audioHardwareDefaultSystemOutputDeviceDidChange
Sent when the default output device for system audio services, such as SysBeep(),
is changed by the user.
- (void) audioHardwareDeviceListDidChange
Sent when an audio device is added or removed from the system.
- (void) audioDeviceBufferSizeInFramesDidChange:(MTCoreAudioDevice *)theDevice
Sent when the length in frames of the IO buffers passed to the IOProc
have changed. If the length in frames of the IO buffers are variable
from IO cycle to IO cycle, then this will be sent if either the minimum
or maximum size changes.
- (void) audioDeviceChannelsByStreamDidChange:(MTCoreAudioDevice *)theDevice forDirection:(MTCoreAudioDirection)theDirection
Sent when the channel configuration of the device changes in theDirection. Any information about
about a device's channel configuration should be discarded and refreshed.
- (void) audioDeviceClockSourceDidChange:(MTCoreAudioDevice *)theDevice forChannel:(UInt32)theChannel forDirection:(MTCoreAudioDirection)theDirection
Sent when the clock source for theChannel in theDirection changes.
- (void) audioDeviceDidDie:(MTCoreAudioDevice *)theDevice
Sent when an audio device is removed from the system or otherwise
becomes unavailable. Once this has been received, nothing further
should be attempted with the device.
- (void) audioDeviceDidOverload:(MTCoreAudioDevice *)theDevice
Adapted from the description for kAudioDeviceProcessorOverload.
Sent when the device's IO thread has been overloaded; that is, when
the combined processing time for all of the device's IOProcs exceeds the duration of
the buffer. Overloading will cause the HAL to resync itself and restart
the IO cycle to be sure that the IO thread goes to sleep.
- (void) audioDeviceMuteDidChange:(MTCoreAudioDevice *)theDevice forChannel:(UInt32)theChannel forDirection:(MTCoreAudioDirection)theDirection
Sent when the mute setting for theChannel in theDirection changes. If the delegate doesn't
implement this method but does implement
audioDeviceVolumeInfoDidChange:forChannel:forDirection:,
that method is called.
- (void) audioDeviceNominalSampleRateDidChange:(MTCoreAudioDevice *)theDevice
Sent when the nominal sampling rate for the device changes.
- (void) audioDeviceNominalSampleRatesDidChange:(MTCoreAudioDevice *)theDevice
Sent when the list of available nominal sampling rate ranges for the device changes. I don't
know if this would ever get sent by a device, but just in case!
- (void) audioDevicePlayThruDidChange:(MTCoreAudioDevice *)theDevice forChannel:(UInt32)theChannel forDirection:(MTCoreAudioDirection)theDirection
Sent when the Play-Thru setting for theChannel in theDirection changes. If the delegate doesn't
implement this method but does implement
audioDeviceVolumeInfoDidChange:forChannel:forDirection:,
that method is called.
- (void) audioDeviceSomethingDidChange:(MTCoreAudioDevice *)theDevice
Description paraphrased from AudioHardware.h.
Sent when a change occurs to a device in a way that can't be conveyed by other means, such as controls appearing or disappearing. The delegate should re-evaluate everything about the device when this message is receieved; in particular, the layout and values of controls.
- (void) audioDeviceSourceDidChange:(MTCoreAudioDevice *)theDevice forDirection:(MTCoreAudioDirection)theDirection
Sent when the device master data source for theDirection changes.
- (void) audioDeviceStartDidFail:(MTCoreAudioDevice *)theDevice forReason:(OSStatus)theReason
Sent when deviceStart fails.
- (void) audioDeviceStreamDescriptionDidChange:(MTCoreAudioDevice *)theDevice forChannel:(UInt32)theChannel forDirection:(MTCoreAudioDirection)theDirection
Sent when the stream format for the indicated channel and direction changes in any way
(such as a sample rate change).
- (void) audioDeviceStreamsListDidChange:(MTCoreAudioDevice *)theDevice
Sent when the stream configuration changes. Any information obtained
from MTCoreAudioStreams, and the list
of MTCoreAudioStreams themselves, should be discarded and refreshed.
- (void) audioDeviceVolumeDidChange:(MTCoreAudioDevice *)theDevice forChannel:(UInt32)theChannel forDirection:(MTCoreAudioDirection)theDirection
Sent when the volume for theChannel in theDirection changes. If the delegate doesn't
implement this method but does implement
audioDeviceVolumeInfoDidChange:forChannel:forDirection:,
that method is called.
- (void) audioDeviceVolumeInfoDidChange:(MTCoreAudioDevice *)theDevice forChannel:(UInt32)theChannel forDirection:(MTCoreAudioDirection)theDirection
Sent when any of the channel's volume, mute, or Play-Thru settings changes, if the more specific
methods don't exist in the delegate. See
audioDeviceVolumeDidChange:forChannel:forDirection:,
audioDeviceMuteDidChange:forChannel:forDirection: and
audioDevicePlayThruDidChange:forChannel:forDirection:.
Important note: These notifications will not be sent until class MTCoreAudioDevice is used for the first time; that is,
until the Objective-C Runtime has sent the +initialize message to the class. See the description of +initialize (NSObject)
for more information.
MTCoreAudioHardwareDefaultInputDeviceDidChangeNotification
Posted when the default input device is changed by the user.
MTCoreAudioHardwareDefaultOutputDeviceDidChangeNotification
Posted when the default output device is changed by the user.
MTCoreAudioHardwareDefaultSystemOutputDeviceDidChangeNotification
Posted when the default output device for system audio services, such as SysBeep(),
is changed by the user.
MTCoreAudioHardwareDeviceListDidChangeNotification
Posted when an audio device is added or removed from the system.
Mike >
Mac OS X >
MTCoreAudio.framework >
MTCoreAudioDevice