| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/AVFoundation.framework/ |
| Availability | Available in iPhone OS 3.0 and later. |
| Companion guide | |
| Declared in | AVAudioSession.h |
| Related sample code |
An instance of the AVAudioSession class, called an audio session, is a singleton object that you employ to set the audio context for your application. Use this class to:
Activate or deactivate your application’s audio session
Set the audio session category
Specify your preferred audio hardware sample rate and I/O buffer duration
Starting with iPhone OS 3.0, this class provides an Objective-C alternative to Audio Session Services, described in Audio Session Services Reference. For more information on audio sessions, see Audio Session Programming Guide.
delegate property
currentHardwareInputNumberOfChannels property
currentHardwareOutputNumberOfChannels property
currentHardwareSampleRate property
inputIsAvailable property
preferredHardwareSampleRate property
preferredIOBufferDuration property
– setPreferredHardwareSampleRate:error:
– setPreferredIOBufferDuration:error:
For more about Objective-C properties, see “Properties” in The Objective-C Programming Language.
The audio session category.
@property (readonly) NSString* category;
An audio session has one of the categories listed in “Audio Session Categories.” The default category is AVAudioSessionCategorySoloAmbient.
AVAudioSession.hThe number of audio hardware input channels.
@property (readonly) NSInteger currentHardwareInputNumberOfChannels;
To respond to a change in the number of audio hardware input channels, implement the currentHardwareInputNumberOfChannelsChanged: method.
AVAudioSession.hThe number of audio hardware output channels.
@property (readonly) NSInteger currentHardwareOutputNumberOfChannels;
To respond to a change in the number of audio hardware output channels, implement the currentHardwareOutputNumberOfChannelsChanged: method.
AVAudioSession.hThe audio hardware sample rate, in hertz.
@property (readonly) double currentHardwareSampleRate;
To respond to a change in the audio hardware sample rate, implement the currentHardwareSampleRateChanged: delegate method.
AVAudioSession.hSpecifies the delegate object for the audio session.
@property (assign) id<AVAudioSessionDelegate> delegate;
The delegate object must implement the protocol described in AVAudioSessionDelegate Protocol Reference.
AVAudioSession.hA Boolean value that indicates whether audio input is available (YES), or not (NO).
@property (readonly) BOOL inputIsAvailable;
Use this method on launch to determine whether the device your application is running on supports audio input. To respond to a change in the availability of audio input, implement the inputIsAvailableChanged: delegate method.
AVAudioSession.hThe preferred hardware sample rate, in hertz.
@property (readonly) double preferredHardwareSampleRate;
AVAudioSession.hThe preferred I/O buffer duration, in seconds.
@property (readonly) NSTimeInterval preferredIOBufferDuration;
AVAudioSession.hReturns the singleton audio session.
+ (id)sharedInstance
AVAudioSession.hActivates or deactivates the audio session.
- (BOOL)setActive:(BOOL)beActive error:(NSError**)outError
Use YES to activate the audio session or NO to deactivate it.
Contains nil if the activation/deactivation call was successful; otherwise, contains an error code.
Returns YES on success or NO on failure.
AVAudioSession.hSets the audio session category.
- (BOOL)setCategory:(NSString*)theCategory error:(NSError**)outError
The audio session category you want to apply to the audio session. See “Audio Session Categories.”
Contains nil if the category was set; otherwise, contains an error code.
Returns YES on success or NO on failure.
AVAudioSession.hSets the preferred hardware sample rate for recording.
- (BOOL)setPreferredHardwareSampleRate:(double)sampleRate error:(NSError**)outError
The hardware sample rate you want to use.
On success, contains nil. On failure, contains an error code.
Returns YES on success or NO on failure.
AVAudioSession.hSets the preferred I/O buffer duration, in seconds, for recording.
- (BOOL)setPreferredIOBufferDuration:(NSTimeInterval)duration error:(NSError**)outError
The I/O buffer duration, in seconds, that you want to use.
On success, contains nil. On failure, contains an error code.
Returns YES on success or NO on failure.
AVAudioSession.hCategory 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;
AVAudioSessionCategoryAmbientFor an application in which sound playback is nonprimary—your application can be used successfully with the sound turned off. This category is also appropriate for “play along” style applications, such as a virtual piano that a user plays over iPod audio. When you use this category, other audio, such as from the iPod application, mixes with your audio. Your audio is silenced by screen locking and by the Ring/Silent switch.
Available in iPhone OS 3.0 and later.
Declared in AVAudioSession.h.
AVAudioSessionCategorySoloAmbientThe default category; used unless you set a category with the setCategory:error: method. This category silences audio from other applications, such as the iPod. Your audio is silenced by screen locking and by the Ring/Silent switch.
Available in iPhone OS 3.0 and later.
Declared in AVAudioSession.h.
AVAudioSessionCategoryPlaybackFor playing recorded music or other sounds that are central to the successful use of your application. This category silences audio from other applications, such as the iPod. You can, however, modify this category to allow mixing by using the kAudioSessionProperty_OverrideCategoryMixWithOthers property. Your audio continues with the Ring/Silent switch set to silent and with the screen locked.
Available in iPhone OS 3.0 and later.
Declared in AVAudioSession.h.
AVAudioSessionCategoryRecordFor recording audio; this category silences playback audio. Recording continues with the screen locked.
Available in iPhone OS 3.0 and later.
Declared in AVAudioSession.h.
AVAudioSessionCategoryPlayAndRecordFor recording and playback of audio—simultaneous or not—such as for a VOIP (voice over IP) application. This category silences audio from other applications, such as the iPod. You can, however, modify this category to allow mixing by using the kAudioSessionProperty_OverrideCategoryMixWithOthers property. Your audio continues with the Ring/Silent switch set to silent and with the screen locked.
Available in iPhone OS 3.0 and later.
Declared in AVAudioSession.h.
AVAudioSessionCategoryAudioProcessingFor 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.
Available in iPhone OS 3.1 and later.
Declared in AVAudioSession.h.
Each application running in iPhone OS has a single audio session, which can be active or inactive. You can change your audio session’s category while your program is running.
Use the AVAudioSessionCategoryAmbient category when you want your sounds to mix with other audio (such as from the iPod application). Use one of the other playback categories when you want iPod audio to be silenced when your session is active. For more information on audio session categories, see Audio Session Programming Guide.
Last updated: 2009-10-19
