iOS Developer Library

Developer

AVFoundation Framework Reference AVAudioSessionDataSourceDescription Class Reference

Options
Deployment Target:

On This Page
Language:

AVAudioSessionDataSourceDescription

Inherits From


  • NSObject
  • AVAudioSessionDataSourceDescription

Conforms To


Import Statement


Swift

import AVFoundation

Objective-C

@import AVFoundation;

Availability


Available in iOS 6.0 and later

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”.)

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

    Declaration

    Swift

    var dataSourceID: NSNumber! { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later

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

    Declaration

    Swift

    var dataSourceName: String! { get }

    Objective-C

    @property(readonly) NSString *dataSourceName

    Discussion

    This name may be displayed to the user.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later

  • location location Property

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

    Declaration

    Swift

    var location: String! { get }

    Objective-C

    @property(readonly) NSString *location

    Discussion

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

    See “Data Source Locations” for possible values.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later

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

    Declaration

    Swift

    var orientation: String! { get }

    Objective-C

    @property(readonly) NSString *orientation

    Discussion

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

    See “Data Source Orientations” for possible values.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later

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

    Declaration

    Swift

    var selectedPolarPattern: String! { get }

    Objective-C

    @property(readonly) NSString *selectedPolarPattern

    Discussion

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later

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

    Declaration

    Swift

    var supportedPolarPatterns: [AnyObject]! { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later

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

    Declaration

    Swift

    var preferredPolarPattern: String! { get }

    Objective-C

    @property(readonly) NSString *preferredPolarPattern

    Discussion

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later

  • Selects the preferred directivity configuration for the data source.

    Declaration

    Swift

    func setPreferredPolarPattern(_ pattern: String!, error outError: NSErrorPointer) -> Bool

    Objective-C

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

    YEStrue if a request was successfully made, or NOfalse 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.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later

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

    Declaration

    Swift

    let AVAudioSessionLocationUpper: String let AVAudioSessionLocationLower: String

    Objective-C

    NSString *const AVAudioSessionLocationUpper; NSString *const AVAudioSessionLocationLower;

    Constants

    • AVAudioSessionLocationUpper

      AVAudioSessionLocationUpper

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

      Available in iOS 7.0 and later

    • AVAudioSessionLocationLower

      AVAudioSessionLocationLower

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

      Available in iOS 7.0 and later

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

    Declaration

    Swift

    let AVAudioSessionOrientationTop: String let AVAudioSessionOrientationBottom: String let AVAudioSessionOrientationFront: String let AVAudioSessionOrientationBack: String

    Objective-C

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

    Constants

    • AVAudioSessionOrientationTop

      AVAudioSessionOrientationTop

      The data source points upward.

      Available in iOS 7.0 and later

    • AVAudioSessionOrientationBottom

      AVAudioSessionOrientationBottom

      The data source points downward.

      Available in iOS 7.0 and later

    • AVAudioSessionOrientationFront

      AVAudioSessionOrientationFront

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

      Available in iOS 7.0 and later

    • AVAudioSessionOrientationBack

      AVAudioSessionOrientationBack

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

      Available in iOS 7.0 and later

  • Constants that describe options for microphone directivity.

    Declaration

    Swift

    let AVAudioSessionPolarPatternOmnidirectional: String let AVAudioSessionPolarPatternCardioid: String let AVAudioSessionPolarPatternSubcardioid: String

    Objective-C

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

    Constants

    • AVAudioSessionPolarPatternOmnidirectional

      AVAudioSessionPolarPatternOmnidirectional

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

      Available in iOS 7.0 and later

    • AVAudioSessionPolarPatternCardioid

      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

    • AVAudioSessionPolarPatternSubcardioid

      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

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