About Configuring Audio Behavior
iOS handles audio behavior at the application, inter application, and device levels using the notion of audio sessions. Using the audio session API, you implement answers to questions such as these:
Should your application’s audio be silenced by the Ring/Silent switch? The answer to this question is “Yes” if audio is not essential for effective use of your app. An example might be a note-taking app or a game that lets users discretely use the app in a meeting—without its sound disturbing others. A pronouncing dictionary, on the other hand, should ignore the Ring/Silent switch and always play—the central purpose of the app requires sound.
Should iPod audio continue when your audio starts? If your app is a virtual piano that lets users play along to songs from their iPod libraries, the answer to this question is certainly “Yes.” On the other hand, iPod audio should stop when your app starts, for example, if your app plays streaming Internet radio.
Users may plug in or unplug headsets, phone calls may arrive, and alarms may sound. Indeed, the audio environment on an iOS device is quite complex. iOS does the heavy lifting, while you employ audio session APIs to specify configuration and to respond gracefully to system requests, using very little code.
An Audio Session Encapsulates a Set of Behaviors
An audio session is the intermediary between your application and iOS for configuring audio behavior. Upon launch, your application automatically gets a singleton audio session. The behavior you specify should meet user expectations as described in “Using Sound” in iOS Human Interface Guidelines.
Categories Express Audio Roles
The primary mechanism for expressing audio intentions is to set the audio session category. A category is a key that identifies a set of audio behaviors. By setting the category, you indicate whether your audio should continue when the screen locks, whether you want iPod audio to continue playing along with your audio, and so on.
Six audio session categories, along with a set of override and modifier switches, let you customize audio behavior according to your application’s personality or role. Various categories support playback, recording, playback along with recording, and offline audio processing. When the system knows your app’s audio role, it affords you appropriate access to hardware resources. The system also ensures that other audio on the device behaves in a way that works for your application; for example, if you need iPod audio to be silenced, it is.
Delegates Support Interruption Handling
An audio interruption is the deactivation of your application’s audio session—which immediately stops your audio. Interruptions happen when a competing audio session from a built-in application activates and that session is not categorized by the system to mix with yours. After your session goes inactive, the system sends a “you were interrupted” message which you can respond to by saving state, updating the user interface, and so on.
To handle interruptions, implement Objective-C interruption delegate methods provided by the AV Foundation framework. Write your
endInterruption methods to ensure the minimum possible disruption, and the most graceful possible recovery, from the perspective of the user.
Callbacks Support Audio Route Change Handling
Users have particular expectations when they initiate an audio route change by docking or undocking a device, or by plugging in or unplugging a headset. “Using Sound” in iOS Human Interface Guidelines describes these expectations and provides guidelines on how to meet them. Handle route changes by writing a C callback function and registering it with your audio session.
Properties Support Advanced Features
You can fine-tune an audio session category in a variety of ways. Depending on the category, you can:
Allow other audio (such as from the iPod) to mix with yours when a category normally disallows it
Change the audio output route from the receiver to the speaker
Allow Bluetooth audio input
Specify that other audio should reduce in volume (“duck”) when your audio plays
You also use properties to optimize your application for device hardware at runtime. This lets your code adapt to the characteristics of the device it’s running on, as well as to changes in hardware capabilities initiated by the user (such as by plugging in a headset) as your application runs.
To use properties, employ the C-based Audio Session Services API from the Audio Toolbox framework.
How to Use This Document
All iOS developers who use the AV Foundation framework, Audio Queue Services, OpenAL, or the I/O audio unit should read this document in its entirety. Other iOS developers should read at least this and the next chapter, “Audio Session Basics.” If you are already up-to-speed on audio session concepts, go straight to the “Audio Session Cookbook” chapter.
An appendix, “Audio Session Categories,” provides details on the behavior of each iOS audio session category.
Before reading this document, you should be familiar with Cocoa Touch development as introduced in iOS App Programming Guide and with the basics of Core Audio as described in that document and in Core Audio Overview. Because audio sessions bear on practical end-user scenarios involving the various switches, buttons, and connectors on a device, you should also be familiar with using iOS devices.
You may find the following resources helpful as you learn about using audio sessions:
Audio Session Services Reference, the C-language, companion API reference to this document.
AVAudioSession Class Reference, which describes the Objective-C interface for configuring and using this technology.
Core Audio Overview, which describes the architecture and design principles of Core Audio in iOS and Mac OS X.
iOS App Programming Guide, an essential introduction to programming Cocoa Touch applications.
AddMusic, a sample code project that demonstrates use of an audio session object in the context of a playback application. This sample also demonstrates coordination between application audio and iPod audio.