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


Instance Methods


canSetDataSource

- (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.


clockSource

- (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.


clockSources

- (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.


dataSource

- (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.


dataSources

- (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.


delegate

- (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.


deviceStartingChannel

- (UInt32) deviceStartingChannel

Returns the channel of the owning MTCoreAudioDevice corresponding to the first channel of this stream.


direction

- (MTCoreAudioDirection) direction

Returns the direction of this stream.


initWithStreamID:withOwningDevice:

- (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.


matchStreamDescription:forSide:

- (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.


numberChannels

- (UInt32) numberChannels

Returns the number of channels in this stream.


owningDevice

- (id) owningDevice

Returns the MTCoreAudioDevice instance to which this stream belongs.


setClockSource:

- (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.


setDataSource:

- (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.


setDelegate:

- (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.


setMute:forChannel:

- (void) setMute:(BOOL)isMuted forChannel:(UInt32)theChannel

If isMuted is true, mute theChannel, otherwise, unmute it.


setPlayThru:forChannel:

- (void) setPlayThru:(BOOL)isPlayingThru forChannel:(UInt32)theChannel

If isPlayingThru is true, enable Play-Thru mode on theChannel, otherwise, disable it.


setStreamDescription:forSide:

- (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.


setVolume:forChannel:

- (void) setVolume:(Float32)theVolume forChannel:(UInt32)theChannel

Sets the volume of theChannel to theVolume, which should be between 0.0 and 1.0.


setVolumeDecibels:forChannel:

- (void) setVolumeDecibels:(Float32)theVolumeDecibels forChannel:(UInt32)theChannel

Sets the volume of theChannel to theVolumeDecibels.


streamDescriptionForSide:

- (MTCoreAudioStreamDescription *) streamDescriptionForSide:(MTCoreAudioStreamSide)theSide

Returns the current stream format for side theSide of the stream.


streamDescriptionsForSide:

- (NSArray *) streamDescriptionsForSide:(MTCoreAudioStreamSide)theSide

Returns an NSArray of MTCoreAudioStreamDescriptions of all of the stream formats supported by theSide of the stream.


streamID

- (AudioStreamID) streamID

Returns the AudioStreamID (UInt32) of the current stream, in case you need to do anything the Hard Way.


streamName

- (NSString *) streamName

The human-readable name of this stream, if any. Returns nil if this stream doesn't have a name.


volumeForChannel:

- (Float32) volumeForChannel:(UInt32)theChannel

Returns the current volume of theChannel as a Float32 between 0.0 and 1.0.


volumeForVolumeInDecibels:forChannel:

- (Float32) volumeForVolumeInDecibels:(Float32)theVolumeDecibels forChannel:(UInt32)theChannel

Convert from decibels to linear volume, according to the device's channel's characteristics.


volumeInDecibelsForChannel:

- (Float32) volumeInDecibelsForChannel:(UInt32)theChannel

Returns the volume of theChannel as a Float32, measured in decibels.


volumeInDecibelsForVolume:forChannel:

- (Float32) volumeInDecibelsForVolume:(Float32)theVolume forChannel:(UInt32)theChannel

Convert from linear volume to decibels, according to the device's channel's characteristics.


volumeInfoForChannel:

- (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.



Methods implemented by the delegate


audioStreamClockSourceDidChange:

- (void) audioStreamClockSourceDidChange:(MTCoreAudioStream *)theStream

Sent when the clock source for theStream changes.


audioStreamMuteDidChange:forChannel:

- (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.


audioStreamPlayThruDidChange:forChannel:

- (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.


audioStreamSourceDidChange:

- (void) audioStreamSourceDidChange:(MTCoreAudioStream *)theStream

Sent when the data source for theStream changes.


audioStreamStreamDescriptionDidChange:forSide:

- (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.


audioStreamVolumeDidChange:forChannel:

- (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