AVAudioSession Class Reference

Constants

Audio Session Categories

Category identifiers for audio sessions, used as values for the setCategory:error: method.

NSString *const AVAudioSessionCategoryAmbient;
NSString *const AVAudioSessionCategorySoloAmbient;
NSString *const AVAudioSessionCategoryPlayback;
NSString *const AVAudioSessionCategoryRecord;
NSString *const AVAudioSessionCategoryPlayAndRecord;
NSString *const AVAudioSessionCategoryAudioProcessing;
NSString *const AVAudioSessionCategoryMultiRoute;

Constants

AVAudioSessionCategoryAmbient

For an app in which sound playback is nonprimary—that is, your app can be used successfully with the sound turned off.

This category is also appropriate for “play along” style apps, such as a virtual piano that a user plays over iPod audio. When you use this category, audio from other apps mixes with your audio. Your audio is silenced by screen locking and by the Silent switch (called the Ring/Silent switch on iPhone).

Available in iOS 3.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionCategorySoloAmbient

The default category; used unless you set a category with the setCategory:error: method.

When you use this category, audio from other apps is silenced. Your audio is silenced by screen locking and by the Silent switch (called the Ring/Silent switch on iPhone).

Available in iOS 3.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionCategoryPlayback

For playing recorded music or other sounds that are central to the successful use of your app.

When using this category, your app audio continues with the Silent switch set to silent or when the screen locks. (The switch is called the Ring/Silent switch on iPhone.) To continue playing audio when your app transitions to the background (for example, when the screen locks), you need to add the audio value to the “UIBackgroundModes” in Information Property List Key Reference key in your information property list file.

This category normally prevents audio from other apps from mixing with your app's audio. To allow mixing for this category, use the kAudioSessionProperty_OverrideCategoryMixWithOthers property.

Available in iOS 3.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionCategoryRecord

For recording audio; this category silences playback audio. Recording continues with the screen locked.

Available in iOS 3.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionCategoryPlayAndRecord

Allows recording (input) and playback (output) of audio, such as for a VOIP (voice over IP) app.

Your audio continues with the Silent switch set to silent and with the screen locked. (The switch is called the Ring/Silent switch on iPhone.) To continue playing audio when your app transitions to the background (for example, when the screen locks), you need to add the audio value to the “UIBackgroundModes” in Information Property List Key Reference key in your information property list file.

This category is appropriate for simultaneous recording and playback, and also for apps that record and play back but not simultaneously. If you want to ensure that sounds such as Messages alerts do not play while your app is recording, use the AVAudioSessionCategoryRecord category instead.

This category normally prevents audio from other apps from mixing with your app's audio. To allow mixing when using this category, use the kAudioSessionProperty_OverrideCategoryMixWithOthers property.

Available in iOS 3.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionCategoryAudioProcessing

For using an audio hardware codec or signal processor while not playing or recording audio. Use this category, for example, when performing offline audio format conversion.

This category disables playback (audio output) and disables recording (audio input).

Audio processing does not normally continue when your app is in the background. However, when your app moves to the background, you can request additional time to complete processing. For more information, see iOS App Programming Guide.

Available in iOS 3.1 and later.

Declared in AVAudioSession.h.

AVAudioSessionCategoryMultiRoute

Allows you to output distinct streams of audio data to different output devices at the same time. For example, you would use this category to route audio to both a USB device and a set of headphones. Use of this category requires a more detailed knowledge of, and interaction with, the capabilities of the available audio routes.

This category may be used for input, output, or both.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionCategoryOptions

Constants that specify optional audio behaviors.

typedef NS_OPTIONS(NSUInteger,
   AVAudioSessionCategoryOptions)
{
   AVAudioSessionCategoryOptionMixWithOthers = 1,
   AVAudioSessionCategoryOptionDuckOthers = 2,
   AVAudioSessionCategoryOptionAllowBluetooth = 4,
   AVAudioSessionCategoryOptionDefaultToSpeaker = 8
};

Constants

AVAudioSessionCategoryOptionMixWithOthers

Allow audio in this session to be mixed with audio from other active sessions. This option is only valid if the session category is AVAudioSessionCategoryPlayAndRecord or AVAudioSessionCategoryPlayback.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionCategoryOptionDuckOthers

Allow audio in this session to duck under the audio for other active sessions. This option is only valid if the session category is AVAudioSessionCategoryPlayAndRecord.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionCategoryOptionAllowBluetooth

Allow audio in this session to be received from or sent to a Bluetooth device. This option is only valid if the session category is AVAudioSessionCategoryPlayAndRecord or AVAudioSessionCategoryRecord.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionCategoryOptionDefaultToSpeaker

Allow audio in this session to route to the built-in speaker by default. This option is only valid if the session category is AVAudioSessionCategoryPlayAndRecord.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

Audio Session Modes

Mode identifiers for audio sessions, used as values for the setMode:error: method.

NSString *const AVAudioSessionModeDefault;
NSString *const AVAudioSessionModeVoiceChat;
NSString *const AVAudioSessionModeGameChat
NSString *const AVAudioSessionModeVideoRecording;
NSString *const AVAudioSessionModeMeasurement;
NSString *const AVAudioSessionModeMoviePlayback;

Constants

AVAudioSessionModeDefault

The default mode; used unless you set a mode with the setMode:error: method.

When this mode is in use, audio session behavior matches that of iOS versions prior to iOS 5.0. You can use this mode with every audio session category. On devices more than one built-in microphone, the primary microphone is used.

Available in iOS 5.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionModeVoiceChat

Specify this mode if your app is performing two-way voice communication, such as using Voice over Internet Protocol (VoIP).

When this mode is in use, the device’s tonal equalization is optimized for voice. For use with the AVAudioSessionCategoryPlayAndRecord audio session category. On devices with more than one built-in microphone, the primary microphone is used.

Using this mode has the side effect of setting the kAudioSessionProperty_OverrideCategoryEnableBluetoothInput category override to TRUE.

Available in iOS 5.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionModeGameChat

Do not set this mode directly. This mode is set by Game Kit on behalf of an application that uses a GKVoiceChat object. This mode is valid only with the AVAudioSessionCategoryPlayAndRecord category.

If you need similar behavior and are not using a GKVoiceChat object, use AVAudioSessionModeVoiceChat instead.

Available in iOS 5.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionModeVideoRecording

Specify this mode if your app is recording a movie.

For use with the AVAudioSessionCategoryRecord audio session category. Also works with the AVAudioSessionCategoryPlayAndRecord category. On devices with more than one built-in microphone, the microphone closest to the video camera is used.

Using this mode may result in the system providing appropriate audio signal processing.

Available in iOS 5.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionModeMeasurement

Specify this mode if your app is performing measurement of incoming audio.

When this mode is in use, the device does not perform automatic gain adjustment on incoming audio. For use with the AVAudioSessionCategoryRecord or AVAudioSessionCategoryPlayAndRecord audio session categories. On devices with more than one built-in microphone, the primary microphone is used.

Available in iOS 5.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionModeMoviePlayback

Specify this mode if your app is playing back movie content.

When this mode is in use, the device engages any appropriate signal processing hardware to improve audio content played over the built-in speaker.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionInterruptionOptions

Constant that indicates the state of the audio session following an interruption

typedef NS_OPTIONS(NSUInteger,
   AVAudioSessionInterruptionOptions)
{
   AVAudioSessionInterruptionOptionShouldResume = 1
};

Constants

AVAudioSessionInterruptionOptionShouldResume

Indicates that the audio session is active and immediately ready to be used. Your app can resume the audio operation that was interrupted.

Look for this flag in the flags parameter when your audio session delegate’s endInterruptionWithFlags: method is invoked.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionSetActiveOptions

A flag that provides additional information about your app’s audio intentions upon session activation or deactivation.

typedef NS_OPTIONS(NSUInteger,
   AVAudioSessionSetActiveOptions)
{
   AVAudioSessionSetActiveOptionNotifyOthersOnDeactivation = 1
};

Constants

AVAudioSessionSetActiveOptionNotifyOthersOnDeactivation

When passed in the flags parameter of the setActive:withFlags:error: instance method, indicates that when your audio session deactivates, other audio sessions that had been interrupted by your session can return to their active state.

This flag is used only when deactivating your audio session; that is, when you pass a value of NO in the beActive parameter of the setActive:withFlags:error: instance method.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionPortOverride

Constants to use when overriding the output audio port.

typedef NS_ENUM(NSUInteger,
   AVAudioSessionPortOverride)
{
   AVAudioSessionPortOverrideNone    = 0,
   AVAudioSessionPortOverrideSpeaker = 'spkr'
};

Constants

AVAudioSessionPortOverrideNone

Do not override the output audio port. Use this option to route audio to the intended outputs.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionPortOverrideSpeaker

Override the current outputs and route audio to the built-in speaker. Use this override only in conjunction with the AVAudioSessionCategoryPlayAndRecord category.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionRouteChangeReason

Constants indicating the reason for an audio route change.

typedef NS_ENUM(NSUInteger,
   AVAudioSessionRouteChangeReason)
{
   AVAudioSessionRouteChangeReasonUnknown = 0,
   AVAudioSessionRouteChangeReasonNewDeviceAvailable = 1,
   AVAudioSessionRouteChangeReasonOldDeviceUnavailable = 2,
   AVAudioSessionRouteChangeReasonCategoryChange = 3,
   AVAudioSessionRouteChangeReasonOverride = 4,
   AVAudioSessionRouteChangeReasonWakeFromSleep = 6,
   AVAudioSessionRouteChangeReasonNoSuitableRouteForCategory = 7
};

Constants

AVAudioSessionRouteChangeReasonUnknown

The reason for the change is unknown.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionRouteChangeReasonNewDeviceAvailable

A preferred new audio output path is now available.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionRouteChangeReasonOldDeviceUnavailable

The previous audio output path is no longer available.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionRouteChangeReasonCategoryChange

The category of the session object changed.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionRouteChangeReasonOverride

The output route was overridden by the app.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionRouteChangeReasonWakeFromSleep

The route changed when the device woke up from sleep.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionRouteChangeReasonNoSuitableRouteForCategory

The route changed because no suitable route is now available for the specified category.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionInterruptionType

Constants that describe the state of the audio interruption.

typedef NS_ENUM(NSUInteger,
   AVAudioSessionInterruptionType)
{
   AVAudioSessionInterruptionTypeBegan = 1,
   AVAudioSessionInterruptionTypeEnded = 0,
};

Constants

AVAudioSessionInterruptionTypeBegan

The system interrupted the audio session.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionInterruptionTypeEnded

The interruption ended.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

Notification User Info Keys

Keys available in the user info dictionary of an interruption notification.

NSString *const AVAudioSessionInterruptionTypeKey;
NSString *const AVAudioSessionInterruptionOptionKey;
   
NSString *const AVAudioSessionRouteChangeReasonKey;
NSString *const AVAudioSessionRouteChangePreviousRouteKey;

Constants

AVAudioSessionInterruptionTypeKey

The value for this key is an NSNumber object containing an unsigned integer that identifies the type of interruption. For a list of possible values, see “AVAudioSessionInterruptionType”.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionInterruptionOptionKey

The value for this key is an NSNumber object containing an unsigned integer that identifies any options associated with the interruption. For a list of possible flags, see “AVAudioSessionInterruptionOptions”.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionRouteChangeReasonKey

The value for this key is an NSNumber object containing an unsigned integer that identifies the reason why the route changed. For a list of possible values, see “AVAudioSessionRouteChangeReason”.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

AVAudioSessionRouteChangePreviousRouteKey

The value for this key is an AVAudioSessionRouteDescription object with the previous route information.

Available in iOS 6.0 and later.

Declared in AVAudioSession.h.

Interruption Flags

Constants that indicate the state of the audio session following an interruption. (Deprecated. Use the constants in “AVAudioSessionInterruptionOptions” instead.)

enum {
   AVAudioSessionInterruptionFlags_ShouldResume = 1
};

Constants

AVAudioSessionInterruptionFlags_ShouldResume

Indicates that your audio session is active and immediately ready to be used. Your app can resume the audio operation that was interrupted. (Deprecated. Use AVAudioSessionInterruptionOptionShouldResume instead.)

Look for this flag in the flags parameter when your audio session delegate’s endInterruptionWithFlags: method is invoked.

Available in iOS 4.0 and later.

Declared in AVAudioSession.h.

Activation Flags

Flags that provide additional information about your app’s audio intentions upon session activation or deactivation. (Deprecated. Use the constants in “AVAudioSessionSetActiveOptions” instead.)

enum {
   AVAudioSessionSetActiveFlags_NotifyOthersOnDeactivation = 1
};

Constants

AVAudioSessionSetActiveFlags_NotifyOthersOnDeactivation

When passed in the flags parameter of the setActive:withFlags:error: instance method, indicates that when your audio session deactivates, other audio sessions that had been interrupted by your session can return to their active state. (Deprecated. Use AVAudioSessionSetActiveOptionNotifyOthersOnDeactivation instead.)

This flag is used only when deactivating your audio session; that is, when you pass a value of NO in the beActive parameter of the setActive:withFlags:error: instance method.

Available in iOS 4.0 and later.

Declared in AVAudioSession.h.