AVAudioSessionDataSourceDescription Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AVFoundation.framework
Availability
Available in iOS 6.0 and later.
Declared in
AVAudioSession.h

Overview

The AVAudioSessionDataSourceDescription class defines a data source for an audio input or output, providing information such as the source’s name, location and orientation.

You obtain data source descriptions from the shared AVAudioSession object or the AVAudioSessionPortDescription objects corresponding to its input and output ports. Only built-in microphone ports on certain devices support the location, orientation, and polar pattern properties; if a port does not support these features, the value of its dataSources property is nil.

This class is especially useful for differentiating between microphone configurations on devices having more than one built-in microphone. Such devices may also support signal processing features for spatial filtering, or beamforming, in which the device is made more sensitive to audio signals from a particular direction. (See “Data Source Polar Patterns”.)

Tasks

Getting Data Source Information

Configuring Microphone Directivity

Properties

dataSourceID

The system-assigned identifier for the data source. (read-only)

@property(readonly) NSNumber *dataSourceID
Discussion

You can use the value of this property to assign a specific data source to some input or output within an audio session.

Availability
  • Available in iOS 6.0 and later.
Declared In
AVAudioSession.h

dataSourceName

A human-readable name for the data source. (read-only)

@property(readonly) NSString *dataSourceName
Discussion

This name may be displayed to the user.

Availability
  • Available in iOS 6.0 and later.
Declared In
AVAudioSession.h

location

The location of the data source on the device. (read-only)

@property(readonly) NSString *location
Discussion

If nil, the data source’s location is not known.

See “Data Source Locations” for possible values.

Availability
  • Available in iOS 7.0 and later.
Declared In
AVAudioSession.h

orientation

The orientation of the data source relative to the device’s natural orientation. (read-only)

@property(readonly) NSString *orientation
Discussion

If nil, the data source’s orientation is not known.

See “Data Source Orientations” for possible values.

Availability
  • Available in iOS 7.0 and later.
Declared In
AVAudioSession.h

preferredPolarPattern

The preferred directivity configuration for the data source. (read-only)

@property(readonly) NSString *preferredPolarPattern
Discussion

If nil, the data source does not support directivity configuration, or no preferred polar pattern has been selected.

Availability
  • Available in iOS 7.0 and later.
Declared In
AVAudioSession.h

selectedPolarPattern

The directivity configuration currently in use by the data source. (read-only)

@property(readonly) NSString *selectedPolarPattern
Discussion

If nil, the data source does not support directivity configuration.

Availability
  • Available in iOS 7.0 and later.
Declared In
AVAudioSession.h

supportedPolarPatterns

The set of directivity configurations supported by the data source. (read-only)

@property(readonly) NSArray *supportedPolarPatterns
Discussion

One or more of the constants in “Data Source Polar Patterns”, or nil if the data source does not support directivity configuration. This feature is available only on the built-in microphone port for certain devices.

Availability
  • Available in iOS 7.0 and later.
Declared In
AVAudioSession.h

Instance Methods

setPreferredPolarPattern:error:

Selects the preferred directivity configuration for the data source.

- (BOOL)setPreferredPolarPattern:(NSString *)pattern error:(NSError **)outError
Parameters
pattern

The directivity configuration to be used.

outError

On input, a pointer to an error object. If an error occurs, the pointer is set to an NSError object that describes the error. If you do not want error information, pass in nil.

Return Value

YES if a request was successfully made, or NO otherwise.

Discussion

Requests a change to the selected polar pattern; to determine whether the change takes effect, use the selectedPolarPattern property. (See “Configuring the Audio Session” in the AVAudioSession class reference for details.)

If the data source and its owning port are in use, using this method to change the directivity configuration will likely result in a route reconfiguration.

Set a preferred polar pattern only after setting the audio session’s category and mode and activating the session.

Availability
  • Available in iOS 7.0 and later.
Declared In
AVAudioSession.h

Constants

Data Source Locations

The location of a data source on a device, relative to the device’s natural orientation.

NSString *const AVAudioSessionLocationUpper;
NSString *const AVAudioSessionLocationLower;
Constants
AVAudioSessionLocationUpper

The data source is located near the top end of the device.

Available in iOS 7.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionLocationLower

The data source is located near the bottom end of the device.

Available in iOS 7.0 and later.

Declared in AVAudioSession.h.

Data Source Orientations

The direction in which a data source points, relative to the device’s natural orientation.

NSString *const AVAudioSessionOrientationTop;
NSString *const AVAudioSessionOrientationBottom;
NSString *const AVAudioSessionOrientationFront;
NSString *const AVAudioSessionOrientationBack;
Constants
AVAudioSessionOrientationTop

The data source points upward.

Available in iOS 7.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionOrientationBottom

The data source points downward.

Available in iOS 7.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionOrientationFront

The data source points outward from the front of the device, toward the user.

Available in iOS 7.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionOrientationBack

The data source points outward from the back of the device, away from the user.

Available in iOS 7.0 and later.

Declared in AVAudioSession.h.

Data Source Polar Patterns

Constants that describe options for microphone directivity.

NSString *const AVAudioSessionPolarPatternOmnidirectional;
NSString *const AVAudioSessionPolarPatternCardioid;
NSString *const AVAudioSessionPolarPatternSubcardioid;
   
Constants
AVAudioSessionPolarPatternOmnidirectional

The data source is equally sensitive to sound from any direction.

Available in iOS 7.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionPolarPatternCardioid

The data source is most sensitive to sound from the direction in which the data source points and is (nearly) insensitive to sound from the opposite direction.

Available in iOS 7.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionPolarPatternSubcardioid

The data source is most sensitive to sound from the direction in which the data source points and is less sensitive to sound from the opposite direction.

Available in iOS 7.0 and later.

Declared in AVAudioSession.h.

Discussion

Note that the direction of a polar pattern is relative to the orientation of the data source. For example, you can use the cardioid pattern with a back-facing data source to more clearly record sound from behind the device, or with a front-facing data source to more clearly record sound from in front of the device (such as the user’s voice).