Audio Session Programming Guide
Contents Introduction 6 At a Glance 7 An Audio Session Encapsulates a Set of Behaviors 7 Categories Express Audio Roles 7 Modes Customize Categories 7 Notifications Support Interruption Handling 8 Notifications Support Audio Route Change Handling 8 Categories Support Advanced Features 8 Prerequisites 9 See Also 9 Defining an Audio Session 10 Audio Session Default Behavior 10 Why a Default Audio Session Usually Isn’t What You Want 11 How the System Resolves Competing Audio Demands 12 Incorporating an AVCap
Contents Handling Interruptions From Siri 27 The Interruption Life Cycle 28 OpenAL and Audio Interruptions 29 Using the AVAudioPlayer Class to Handle Audio Interruptions 29 Responding to a Media Server Reset 30 Providing Guidelines to the User 30 Optimizing Your App for Device Hardware 32 Choosing Preferred Audio Hardware Values 32 Setting Preferred Hardware Values 33 Querying Hardware Characteristics 34 Specifying Preferred Hardware I/O Buffer Duration 35 Obtaining and Using the Hardware Sample Rate 35 R
Figures, Tables, and Listings Defining an Audio Session 10 Figure 1-1 Listing 1-1 The system manages competing audio demands 13 Activating an audio session using the AV Foundation framework 15 Working with Categories 18 Figure 2-1 Listing 2-1 Sending different files to different audio routes 21 Setting the audio session category using the AV Foundation framework 22 Responding to Interruptions 26 Figure 3-1 Table 3-1 Table 3-2 Listing 3-1 Listing 3-2 An audio session gets interrupted 28 What should hap
SwiftObjective-C 2014-09-17 | Copyright © 2014 Apple Inc. All Rights Reserved.
Introduction iOS handles audio behavior at the app, inter-app, and device levels through audio sessions and the AVAudioSession APIs. Using the AVAudioSession API, you resolve questions such as: ● Should your app’s audio be silenced by the Ring/Silent switch? Yes, if audio is not essential to your app. An example is an app that lets users take notes in a meeting without its sound disturbing others.
Introduction At a Glance At a Glance AVAudioSession gives you control your app’s audio behavior. You can: ● Select the appropriate input and output routes for your app ● Determine how your app integrates audio from other apps ● Handle interruptions from other apps ● Automatically configure audio for the type of app your are creating An Audio Session Encapsulates a Set of Behaviors An audio session is the intermediary between your app and iOS used to configure your app’s audio behavior.
Introduction At a Glance Relevant Chapters: Working with Categories (page 18). Notifications Support Interruption Handling An audio interruption is the deactivation of your app’s audio session—which immediately stops your audio. Interruptions occur when a competing audio session from an app activates and that session is not categorized by the system to mix with yours.
Introduction Prerequisites Relevant Chapters: Working with Categories (page 18), Optimizing Your App for Device Hardware (page 32), and Fine-Tuning an Audio Session for Players (page 40) Prerequisites Be familiar with Cocoa Touch development as introduced in App Programming Guide for iOS and with the basics of Core Audio as described in that document and in Core Audio Overview .
Defining an Audio Session Objective-CSwift An audio session is the intermediary between your app and iOS for configuring audio behavior. Upon launch, your app automatically gets a singleton audio session. You configure it to express your app’s audio intentions.
Defining an Audio Session Why a Default Audio Session Usually Isn’t What You Want All of the above behavior is provided by the default audio session category, AVAudioSessionCategorySoloAmbient. Working with Categories (page 18) provides information on how to incorporate a category into your app. Your audio session begins automatically when you start to play or record audio; however, relying on the default activation is a risky state for your app.
Defining an Audio Session How the System Resolves Competing Audio Demands ● Scenario 2. You write a first-person shooter game that uses OpenAL-based sound effects. You also provide a background soundtrack but include an option for the user to turn it off and play a song from the user’s music library instead. After starting up a motivating song, the user fires a photon torpedo at an enemy ship, and the music stops. To ensure that music is not interrupted, configure your audio session to allow mixing.
Defining an Audio Session How the System Resolves Competing Audio Demands If you think of an iOS device as an airport, with apps represented as taxiing planes, the system serves as a sort of control tower. Your app can make audio requests and state its desired priority, but final authority over what happens “on the tarmac” comes from the system. You communicate with the “control tower” using the audio session.
Defining an Audio Session Incorporating an AVCaptureSession The system has final authority to activate or deactivate any audio session present on a device. The system follows the inviolable rule that “the phone always wins.” No app, no matter how vehemently it demands priority, can trump the phone. When a call arrives, the user gets notified and your app is interrupted—no matter what audio operation you have in progress and no matter what category you have set.
Defining an Audio Session Adding Volume and Route Control Adding Volume and Route Control Use the MPVolumeView class to present volume and routing control for your app. The volume view provides a slider to control the volume from inside your app and a button for choosing the output audio route. Apple recommends using the MPVolumeView route picker over AVAudioSessionPortOverride when routing audio to the built-in speaker. See MPVolumeView Class Reference .
Defining an Audio Session Checking Whether Other Audio Is Playing During App Launch if (!success) { /* handle the error in activationError */ } To deactivate your audio session, pass NO to the setActive parameter. In the specific case of playing or recording audio with an AVAudioPlayer or AVAudioRecorder object, the system takes care of audio session reactivation upon interruption end. Nonetheless, Apple recommends that you register for notification messages and explicitly reactivate your audio session.
Defining an Audio Session Working with Inter-App Audio Working with Inter-App Audio In its most basic form, inter-app audio allows one app, called the node app, to send its audio output to another app, called the host app. However, it is also possible for the host app to send its output to the node app, have the node app process the audio, and send the result back to the host app.
Working with Categories Objective-CSwift An audio session category is a key that identifies a set of audio behaviors for your app. By setting a category, you indicate your audio intentions to the system—such as whether your audio should continue when the Ringer/Silent switch is flipped. The seven audio session categories in iOS, along with a set of override and modifier switches, let you customize your app’s audio behavior.
Working with Categories Choosing the Best Category ● Is audio that you play essential or peripheral to using your app? If essential, the best category is one that supports continued playback when the Ring/Silent switch is set to silent. If peripheral, pick a category that goes silent with the Ring/Silent switch set to silent. ● Is other audio (such as the Music app) playing when the user launches your app? Checking during launch enables you to branch.
Working with Categories Expanding Options Using the Multiroute Category ● AVAudioSessionCategoryMultiRoute—Playback and record. Allow simultaneous input and output for different audio streams, for example, USB and headphone output. A DJ app would benefit from using the multiroute category. A DJ often needs to listen to one track of music while another track is playing. Using the multiroute category, a DJ app can play future tracks through the headphones while the current track is played for the dancers.
Working with Categories Setting Your Audio Session Category Your app can send different audio streams to different output routes. For example, your app could send one audio stream to the left headphone, another audio stream to the right headphone, and a third audio stream to the HDMI routes. Figure 2-1 shows an example of sending multiple files to different audio routes.
Working with Categories Using Modes to Specialize the Category To set the audio session category, call the setCategory:error: method as shown in Listing 2-1. For descriptions of all the categories, refer to Choosing the Best Category (page 18).
Working with Categories Choosing Categories and Modes for AirPlay Note: Apple recommends that apps using voice or video chat also use the Voice-Processing I/O audio unit. The Voice-Processing I/O unit provides several features for VOIP apps, including automatic gain correction, adjustment of voice-processing, and muting. See Voice-Processing I/O Unit for more information. ● AVAudioSessionModeGameChat—For game apps.
Working with Categories Fine-Tuning a Category ● AVAudioSessionModeVideoChat ● AVAudioSessionModeGameChat Fine-Tuning a Category You can fine-tune an audio session category in a variety of ways.
Working with Categories Recording Permission Recording Permission Starting in iOS 7, your app must ask and receive permission from the user before you can record audio. If the user does not give your app permission to record audio, then only silence is recorded. The system automatically prompts the user for permission when you use a category that supports recording and the app attempts to use an input route.
Responding to Interruptions Adding audio session code to handle interruptions ensures that your app’s audio continues behaving gracefully when a phone call arrives, a Clock or Calendar alarm sounds, or another app activates its audio session. An audio interruption is the deactivation of your app’s audio session—which immediately stops or pauses your audio, depending on which technology you are using.
Responding to Interruptions Audio Interruption Handling Techniques Table 3-2 summarizes how to handle audio interruptions according to technology. The rest of this chapter provides details. Table 3-2 Audio interruption handling techniques according to audio technology Audio technology How interruptions work AV Foundation framework The AVAudioPlayer and AVAudioRecorder classes provide delegate methods for interruption start and end.
Responding to Interruptions The Interruption Life Cycle The Interruption Life Cycle Figure 3-1 illustrates the sequence of events before, during, and after an audio session interruption for a playback app. Figure 3-1 An audio session gets interrupted An interruption event—in this example, the arrival of a phone call—proceeds as follows. The numbered steps correspond to the numbers in the figure. 1. Your app is active, playing back audio. 2. A phone call arrives.
Responding to Interruptions OpenAL and Audio Interruptions There is no guarantee that a begin interruption will have an end interruption. Your app needs to be aware of switching to a foreground running state or the user pressing a play button. In either case, determine whether your app should reactivate its audio session. OpenAL and Audio Interruptions When using OpenAL for audio playback, implement an interruption listener callback function, as you do when using Audio Queue Services.
Responding to Interruptions Responding to a Media Server Reset Listing 3-2 An interruption-ended delegate method for an audio player - (void) audioPlayerEndInterruption: (AVAudioPlayer *) player { if (interruptedOnPlayback) { [player prepareToPlay]; [player play]; playing = YES; interruptedOnPlayback = NO; } } Responding to a Media Server Reset The media server provides audio and other multimedia functionality through a shared server process.
Responding to Interruptions Providing Guidelines to the User There is no programmatic way to ensure that an audio session is never interrupted. The reason is that iOS always gives priority to the phone. iOS also gives high priority to certain alarms and alerts—you wouldn’t want to miss your flight now, would you? The solution to guaranteeing an uninterrupted recording is for a user to deliberately silence their iOS device by taking the following steps: 1.
Optimizing Your App for Device Hardware Using audio session properties, you can optimize your app’s audio behavior 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 made by the user (such as plugging in a headset or docking the device) as your app runs.
Optimizing Your App for Device Hardware Setting Preferred Hardware Values For example, as shown in the top-middle cell of the table, you might specify a preference for a high sample rate if audio quality is very important in your app, and if large file size is not a significant issue. The default audio I/O buffer duration (about 0.02 seconds for 44.1 kHz audio) provides sufficient responsiveness for most apps.
Optimizing Your App for Device Hardware Querying Hardware Characteristics [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(handleRouteChange:) name:AVAudioSessionRouteChangeNotification object:session]; [session setActive:YES error:&audioSessionError]; if (audioSessionError) { NSLog(@"Error %ld, %@, (long)audioSessionError.code, audioSessionError.localizedDescription); } sampeRate = session.sampleRate; bufferDuration = session.IOBuffferDuration; NSLog(@"Sampe Rate:%0.
Optimizing Your App for Device Hardware Querying Hardware Characteristics Important: To obtain meaningful values for hardware characteristics, ensure that the audio session is initialized and active before you issue queries. Two of the most useful audio session hardware properties are sampleRate and outputLatency. The sampleRate property contains the hardware sample rate of the device. The outputLatency property contains the playback latency of the device.
Optimizing Your App for Device Hardware Running Your App in the Simulator Running Your App in the Simulator When you add audio session support to your app, you can run your app in the Simulator or on a device. However, the Simulator does not simulate audio session behavior and does not have access to the hardware features of a device.
Responding to Route Changes As your app runs, a user might plug in or unplug a headset, or use a docking station with audio connections. iOS Human Interface Guidelines describes how iOS apps should respond to such events. To implement the recommendations, write audio session code to handle audio hardware route changes. Certain types of apps, like games, don’t always have to respond to route changes. However other types of apps, such as media players, must respond to all route changes.
Responding to Route Changes Responding to Audio Hardware Route Changes In the figure, the system initially determines the audio route after your app launches. It continues to monitor the active route as your app runs. Consider first the case of a user tapping a Record button in your app, represented by the “Recording starts” box on the left side of the figure. During recording, the user may plug in or unplug a headset—see the diamond-shaped decision element toward the lower-left of the figure.
Responding to Route Changes Responding to Audio Hardware Route Changes ● What the previous route was The keys for the dictionary are AVAudioSessionRouteChangeReasonKey and AVAudioSessionRouteChangePreviousRouteKey. The various reasons why a hardware audio route might have changed—accessed by the AVAudioSessionRouteChangeReasonKey key—are listed and described in AVAudioSessionRouteChangeReason.
Fine-Tuning an Audio Session for Players Objective-CSwift Movie players let you play movies from a file or a network stream. Music players let you play audio content from a user’s music library. To use these objects in coordination with your app audio, consider their audio session characteristics. ● Music players (instances of the MPMusicPlayerController class) always use a system-supplied audio session.
Fine-Tuning an Audio Session for Players Working with Movie Players Working with Movie Players By default, a movie player shares your app’s audio session. In effect, a movie player transcends the notion of mixing with your app’s audio; the movie player’s audio behaves as though it belongs to your app. No matter which playback category you choose, and no matter how you configure that category, your audio and the movie player’s audio never interrupt each other.
Fine-Tuning an Audio Session for Players Using the Media Player Framework Exclusively If you have configured a movie player to use its own audio session, there’s some cleanup to perform. To restore the movie player’s ability to play audio after a movie finishes, or the user dismisses it: 1. Dispose of the movie player—even if you intend to play the same movie again later. 2. Reactivate your audio session. For a description of the movie player class, see MPMoviePlayerController Class Reference .
Audio Guidelines By App Type The latest driving game does not have the same audio requirements as a real-time video chat app. The following sections provide design guidelines for different types of audio apps. Audio Guidelines for Game Apps Most games require user interaction for anything to happen in the game. Use the AVAudioSessionCategoryAmbient or AVAudioSessionCategorySoloAmbient categories when designing games.
Audio Guidelines By App Type Audio Guidelines for VoIP and Chat Apps ● Update the UI to indicate that audio has paused when it is interrupted. Do not deactivate the audio session or pause/stop player objects. ● Check for the presence of the AVAudioSessionInterruptionOptionKey constant and honor its value after an end interruption. Don’t start playing audio again unless the app was playing prior to the interruption.
Audio Guidelines By App Type Audio Guidelines for Metering Apps ● Ask the user for permission to record input using the requestRecordPermission: method. Don’t rely on the iOS to prompt the user. Audio Guidelines for Metering Apps Metering apps want the minimal amount of system-supplied signal processing applied to the input and output routes. Set the AVAudioSessionCategoryPlayAndRecord category and the measurement mode to minimize signal processing. Also, apps of this type will not mix with other apps.
Audio Guidelines By App Type Audio Guidelines for Navigation and Workout Apps Audio Guidelines for Navigation and Workout Apps Navigations and workout apps use the AVAudioSessionCategoryPlayback or AVAudioSessionCategoryPlayAndRecord categories. The audio from these apps are typically short prompts and will mix with other apps. As it is assumed that the user wants to hear the audio from these apps even when other apps are playing, these apps will duck audio from other apps.
Audio Session Categories and Modes You tell iOS your app’s audio intentions by designating a category for your audio session. Table B-1 provides details on each of the categories. The default category, AVAudioSessionCategorySoloAmbient, is shaded. For an explanation of how categories work, see Working with Categories (page 18). For an explanation of the mixing override switch, see Choosing the Best Category (page 18).
Audio Session Categories and Modes Category identifiers Silenced by Interrupts Allows audio the non-mixable input Ring/Silent apps audio (recording) and switch and output by screen (playback) locking see note AVAudioSessionCategoryRecord No (recording continues with the screen locked) Yes Input only AVAudioSessionCategorySoloAmbient Yes Yes Output only Note: For your app to continue playing audio when the Ring/Silent switch is set to silent and the screen is locked, make sure the UIB
Audio Session Categories and Modes Mode identifiers Compatible categories AVAudioSessionModeVideoChat AVAudioSessionCategoryPlayAndRecord 2014-09-17 | Copyright © 2014 Apple Inc. All Rights Reserved.
Document Revision History This table describes the changes to Audio Session Programming Guide . Date Notes 2014-09-17 Added information on AVAudioSessionCategoryMultiRoute able to be modified by AVAudioSessionCategoryOptionMixWithOthers. 2014-03-10 Updated document for iOS 7. Removed all C references. 2012-12-13 Added information on how to handle interruptions when using an audio processing graph. 2010-11-15 Added audio session considerations for the playInputClick method.
Apple Inc. Copyright © 2014 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc.
