# 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
  - - initWithStreamID:withOwningDevice:
- Working with delegates
  - - setDelegate:
  - - delegate
  - Methods implemented by the delegate
- A stream's identifying information
  - - streamName
  - - direction
  - - owningDevice
  - - streamID
  - - deviceStartingChannel
  - - numberChannels
- Working with sources
  - - dataSource
  - - dataSources
  - - canSetDataSource
  - - setDataSource:
  - - clockSource
  - - clockSources
  - - setClockSource:
- Working with stream formats
  - - streamDescriptionForSide:
  - - streamDescriptionsForSide:
  - - setStreamDescription:forSide:
  - - matchStreamDescription:forSide:
- Working with volume
  - - volumeInfoForChannel:
  - - volumeForChannel:
  - - volumeInDecibelsForChannel:
  - - setVolume:forChannel:
  - - setVolumeDecibels:forChannel:
  - - volumeInDecibelsForVolume:forChannel:
  - - volumeForVolumeInDecibels:forChannel:
  - - setMute:forChannel:
  - - setPlayThru:forChannel:

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