AVAudioSessionPortDescription 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

An AVAudioSessionPortDescription object describes a single input or output port associated with an audio route. You can use the information in this class to obtain information about the capabilities of the port and the hardware channels it supports.

Examples of audio ports include a device’s built-in speaker, a microphone on a wired headset, and a Bluetooth device supporting the Advanced Audio Distribution Profile (A2DP).

You can use port descriptions with the shared AVAudioSession object:

For example, on a device with a wired headset attached, the audio session’s availableInputs array may contain two port descriptions: one for the headset microphone and one for the device’s built-in microphone. You can use the audio session’s setPreferredInput:error: method to select the headset or built-in microphone for audio input.

Tasks

Getting the Port Attributes

Managing a Port’s Data Sources

Properties

channels

An array of channel objects that describe the port’s input or output channels. (read-only)

@property(readonly) NSArray *channels
Discussion

An array of AVAudioSessionChannelDescription objects, each of which represents a single audio input or output channel. The contents of this array may change if the input or output channel count is changed for the AVAudioSession object owning the port.

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

dataSources

The available data sources for the port. (read-only)

@property(readonly) NSArray *dataSources
Discussion

If nil, the port does not support selecting between multiple data sources. This feature is only supported on certain devices and peripherals; for example, the data sources represent front- and rear-facing microphones on an iPhone equipped with such.

The contents of this array may change if the mode is changed for the AVAudioSession object owning the port.

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

portName

A descriptive name for the port. (read-only)

@property(readonly) NSString *portName
Discussion

This name may be displayed to the user.

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

portType

The type of the port. (read-only)

@property(readonly) NSString *portType
Discussion

The value of this property can be any of the constants declared in “Input or Output Port Types”, “Input Port Types”, or “Output Port Types”.

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

preferredDataSource

The preferred audio data source for the port. (read-only)

@property(readonly) AVAudioSessionDataSourceDescription *preferredDataSource
Discussion

The value of this property indicates the data source selected using the setPreferredDataSource:error: method. To see the actual data source, use the selectedDataSource property.

If nil, the port does not support selecting between multiple data sources or no preferred data source has been selected.

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

selectedDataSource

The currently selected audio data source for the port. (read-only)

@property(readonly) AVAudioSessionDataSourceDescription *selectedDataSource
Discussion

If nil, the port does not support selecting between multiple data sources.

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

UID

A system-assigned unique identifier (UID) for the port. (read-only)

@property(readonly) NSString *UID
Discussion

The value of this property matches that of the the owningPortUID property of every AVAudioSessionChannelDescription object in the port’s channels array.

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

Instance Methods

setPreferredDataSource:error:

Sets the preferred audio data source for the port.

- (BOOL)setPreferredDataSource:(AVAudioSessionDataSourceDescription *)dataSource error:(NSError **)outError
Parameters
dataSource

The data source 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 of data source; to determine whether the change takes effect, use the selectedDataSource property. (See “Configuring the Audio Session” in the AVAudioSession class reference for details.)

If the port is in use, changing this setting will likely result in a route reconfiguration.

Set a preferred data source 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

Input or Output Port Types

Devices that can be used for either input or output.

NSString *const AVAudioSessionPortBluetoothHFP;
NSString *const AVAudioSessionPortUSBAudio;
Constants
AVAudioSessionPortBluetoothHFP

A Bluetooth enabled device supporting the Hands-Free Profile (HFP).

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionPortUSBAudio

A USB device.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

Input Port Types

Constants that indicate the audio input to the device.

NSString *const AVAudioSessionPortLineIn;
NSString *const AVAudioSessionPortBuiltInMic;
NSString *const AVAudioSessionPortHeadsetMic;
Constants
AVAudioSessionPortLineIn

Line-level input from the dock connector.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionPortBuiltInMic

The built-in microphone on a device.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionPortHeadsetMic

A microphone that is built-in to a wired headset.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

Output Port Types

Constants that indicate the audio output from the device.

NSString *const AVAudioSessionPortLineOut;
NSString *const AVAudioSessionPortHeadphones;
NSString *const AVAudioSessionPortBluetoothA2DP;
NSString *const AVAudioSessionPortBuiltInReceiver;
NSString *const AVAudioSessionPortBuiltInSpeaker;
NSString *const AVAudioSessionPortHDMI;
NSString *const AVAudioSessionPortAirPlay;
NSString *const AVAudioSessionPortBluetoothLE;
   
Constants
AVAudioSessionPortLineOut

Line-level output to the dock connector.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionPortHeadphones

Output to a wired headset.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionPortBluetoothA2DP

Output to a Bluetooth A2DP device.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionPortBuiltInReceiver

Output to a speaker intended to be held near the ear. Typically, this speaker is available only on iPhone devices.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionPortBuiltInSpeaker

Output to the device’s built-in speaker.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionPortHDMI

Output to a device via the High-Definition Multimedia Interface (HDMI) specification.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionPortAirPlay

Output to a remote device over AirPlay.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionPortBluetoothLE

Output to a Bluetooth low energy peripheral.

Available in iOS 7.0 and later.

Declared in AVAudioSession.h.