MTCoreAudioStream
An MTCoreAudioStream instance represents one audio stream
of an audio device. Audio streams have an implicit direction (either record
or playback). For more information about what exactly an audio
stream is, see
AudioHardware.h
and Apple's
CoreAudio library documentation.
MTCoreAudioStreams control the audio data formats used to
communicate between the the application and the driver
(kMTCoreAudioStreamLogicalSide)
and between the driver and the audio hardware device
(kMTCoreAudioStreamPhysicalSide).
Method Types
- Creating instances
- Working with delegates
- A stream's identifying information
- Working with sources
- Working with stream formats
- Working with volume
Instance Methods
- (Boolean) canSetDataSource
Returns YES if the source for this stream can be
changed by
setDataSource:
to one of the values returned by
dataSources,
and NO if that property can't be set under program control.
If this method returns NO but dataSources
returns multiple sources, then the value of
dataSource
is informational, and reflects an externally-controlled choice, such
as Headphones vs. Internal Speakers.
- (NSString *) clockSource
Returns the current clock source
for this stream.
Returns nil if this stream does not define a clock source.
Typically, sources won't be defined if a device has only one clock source.
- (NSArray *) clockSources
Returns an NSArray of NSStrings representing the available clock sources for this
stream. Returns nil if the stream
doesn't feel like it defines any clock sources.
- (NSString *) dataSource
Returns the current data source (such as "Internal Microphone" or "Line in")
for this stream.
Returns nil if this stream does not define a source.
Typically, sources won't be defined if a device has only one port.
- (NSArray *) dataSources
Returns an NSArray of NSStrings representing the available sources for this
stream. 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) deviceStartingChannel
Returns the channel of the owning MTCoreAudioDevice corresponding
to the first channel of this stream.
- (MTCoreAudioDirection) direction
Returns the direction
of this stream.
- (MTCoreAudioStream *) initWithStreamID:(AudioStreamID)theID withOwningDevice:(id)theOwningDevice
Initializes a new instance. You shouldn't call this method directly; use
streamsForDirection:
(MTCoreAudioDevice) to obtain the streams for a device's
direction.
- (MTCoreAudioStreamDescription *) matchStreamDescription:(MTCoreAudioStreamDescription *)theDescription forSide:(MTCoreAudioStreamSide)theSide
Returns a new MTCoreAudioStreamDescription
that's the device's best match to an available stream format on
theSide. Matching is done at the discretion of the device driver; returned
formats may be significantly different than that passed in.
- (UInt32) numberChannels
Returns the number of channels in this stream.
- (id) owningDevice
Returns the MTCoreAudioDevice instance to which
this stream belongs.
- (void) setClockSource:(NSString *)theSource
Sets the clock source for this stream. theSource should
be one of the values returned by clockSources.
This method has no effect if theSource is not an available clock source.
- (void) setDataSource:(NSString *)theSource
Sets the source for this stream. theSource should
be one of the values returned by dataSources.
This method has no effect if theSource is not an available source.
- (void) setDelegate:(id)theDelegate
Sets the delegate of the instance to theDelegate. Does
not retain theDelegate, so make sure you change or remove the delegate
before deallocating theDelegate. If the instance does not have a
delegate, then the owning device's delegate is
tried instead.
- (void) setMute:(BOOL)isMuted forChannel:(UInt32)theChannel
If isMuted is true, mute theChannel,
otherwise, unmute it.
- (void) setPlayThru:(BOOL)isPlayingThru forChannel:(UInt32)theChannel
If isPlayingThru is true, enable Play-Thru mode on theChannel,
otherwise, disable it.
- (Boolean) setStreamDescription:(MTCoreAudioStreamDescription *)theDescription forSide:(MTCoreAudioStreamSide)theSide
Sets the format of theSide side of the stream to theDescription. Typically,
on the kMTCoreAudioStreamPhysicalSide
side, attributes of the stream format must exactly match an available format.
Returns true if the stream format was changed successfully, and
false if not.
- (void) setVolume:(Float32)theVolume forChannel:(UInt32)theChannel
Sets the volume of theChannel to theVolume, which should
be between 0.0 and 1.0.
- (void) setVolumeDecibels:(Float32)theVolumeDecibels forChannel:(UInt32)theChannel
Sets the volume of theChannel to theVolumeDecibels.
- (MTCoreAudioStreamDescription *) streamDescriptionForSide:(MTCoreAudioStreamSide)theSide
Returns the current stream format for
side theSide of the stream.
- (NSArray *) streamDescriptionsForSide:(MTCoreAudioStreamSide)theSide
Returns an NSArray of MTCoreAudioStreamDescriptions
of all of the stream formats supported by theSide of the stream.
- (AudioStreamID) streamID
Returns the AudioStreamID (UInt32) of the current stream,
in case you need to do anything the Hard Way.
- (NSString *) streamName
The human-readable name of this stream, if any. Returns nil if this stream doesn't have a name.
- (Float32) volumeForChannel:(UInt32)theChannel
Returns the current volume of theChannel as a Float32 between 0.0 and 1.0.
- (Float32) volumeForVolumeInDecibels:(Float32)theVolumeDecibels forChannel:(UInt32)theChannel
Convert from decibels to linear volume, according to the device's channel's characteristics.
- (Float32) volumeInDecibelsForChannel:(UInt32)theChannel
Returns the volume of theChannel as a Float32, measured
in decibels.
- (Float32) volumeInDecibelsForVolume:(Float32)theVolume forChannel:(UInt32)theChannel
Convert from linear volume to decibels, according to the device's channel's characteristics.
- (MTCoreAudioVolumeInfo) volumeInfoForChannel:(UInt32)theChannel
Returns an MTCoreAudioVolumeInfo structure
which collects all the interesting volume-related information about theChannel
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) audioStreamClockSourceDidChange:(MTCoreAudioStream *)theStream
Sent when the clock source for theStream changes.
- (void) audioStreamMuteDidChange:(MTCoreAudioStream *)theStream forChannel:(UInt32)theChannel
Sent when the mute setting for theChannel changes. If the delegate doesn't
implement this method but does implement
audioStreamVolumeInfoDidChange:forChannel:,
that method is called.
- (void) audioStreamPlayThruDidChange:(MTCoreAudioStream *)theStream forChannel:(UInt32)theChannel
Sent when the Play-Thru setting for theChannel changes. If the delegate doesn't
implement this method but does implement
audioStreamVolumeInfoDidChange:forChannel:,
that method is called.
- (void) audioStreamSourceDidChange:(MTCoreAudioStream *)theStream
Sent when the data source for theStream changes.
- (void) audioStreamStreamDescriptionDidChange:(MTCoreAudioStream *)theStream forSide:(MTCoreAudioStreamSide)theSide
Sent when the stream format of the stream changes. Note that, in real life, this will
probably never get sent, because CoreAudio resets the stream IDs when the format
changes, at least on my audio hardware. See
audioDeviceStreamDescriptionDidChange:forChannel:forDirection:
and
audioDeviceStreamsListDidChange:
(MTCoreAudioDevice instance delegate methods) for more reliable means
of detecting stream format changes.
- (void) audioStreamVolumeDidChange:(MTCoreAudioStream *)theStream forChannel:(UInt32)theChannel
Sent when the volume for theChannel changes. If the delegate doesn't
implement this method but does implement
audioStreamVolumeInfoDidChange:forChannel:,
that method is called.
audioStreamVolumeInfoDidChange:forChannel:
- (void) audioStreamVolumeInfoDidChange:(MTCoreAudioStream *)theStream forChannel:(UInt32)theChannel
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
audioStreamVolumeDidChange:forChannel:,
audioStreamMuteDidChange:forChannel: and
audioStreamPlayThruDidChange:forChannel:.
Mike >
Mac OS X >
MTCoreAudio.framework >
MTCoreAudioStream