In a dance-class app, a phone call interrupts the AVPlayer lesson and playback never resumes afterwards; how do you diagnose and fix it with AVAudioSession?
answer
- the player pauses itself; resuming is yours
- began and ended, plus an option
- only on the ended event
- reactivate before you play
- iOS 27 recommends resumption separately
basics
~20 sAVPlayer pauses itself when the call interrupts the audio session, but resuming is the app's job: observe the interruption notification, and on .ended with .shouldResume reactivate the session and call play(). On iOS 27, observe resumptionRecommendationNotification instead.
solid answer
~40 sApple documents that `AVPlayer` watches the audio session and pauses on an interruption; nothing restarts it unless the app does. So I check that an observer for `AVAudioSession.interruptionNotification` exists and stays alive, that it reads `AVAudioSessionInterruptionTypeKey`, and that on `.ended` it reads `AVAudioSessionInterruptionOptionKey`, which is present only on the end event. If the options contain `.shouldResume`, it calls `setActive(true)` and `play()`; if not, it leaves the lesson paused. The legacy flow has a gap: the end event can fail to arrive. iOS 27 deprecates that notification for `didBecomeInactiveNotification` and `resumptionRecommendationNotification`, whose `ResumptionContext.recommendation` does not depend on the interrupting app ending cleanly. I would also pause on a route change with reason `.oldDeviceUnavailable`.
code
swift · 27 linesimport AVFoundation
@MainActor
final class LessonInterruptions {
private let player: AVPlayer
private var token: NSObjectProtocol?
init(player: AVPlayer) {
self.player = player
token = NotificationCenter.default.addObserver(
forName: AVAudioSession.interruptionNotification,
object: AVAudioSession.sharedInstance(), queue: .main
) { [weak self] note in
let typeRaw = note.userInfo?[AVAudioSessionInterruptionTypeKey] as? UInt
let optionsRaw = note.userInfo?[AVAudioSessionInterruptionOptionKey] as? UInt
MainActor.assumeIsolated { self?.handle(typeRaw: typeRaw, optionsRaw: optionsRaw) }
}
}
private func handle(typeRaw: UInt?, optionsRaw: UInt?) {
guard let typeRaw, AVAudioSession.InterruptionType(rawValue: typeRaw) == .ended else { return }
let options = AVAudioSession.InterruptionOptions(rawValue: optionsRaw ?? 0)
guard options.contains(.shouldResume) else { return } // leave it paused
try? AVAudioSession.sharedInstance().setActive(true)
player.play()
}
}go deeper
Recall that the system pauses AVPlayer during a call and that the app must listen to AVAudioSession to resume.
Explain the began and ended types, why the options key appears only on ended, and what shouldResume asks of the app.
Walk the five causes of a lesson that never resumes, including a lost observer and a missing end event, and add the route-change pause.
Plan the move to iOS 27's lifecycle notifications while still deploying to iOS 17, and make interruption tests part of release checks.
## What happens during a call An **interruption** is the system taking the audio hardware from your app's audio session: an incoming call, a FaceTime call, an alarm, Siri. Apple's interruption article describes the system side: your session is deactivated, and **`AVPlayer` monitors the session and pauses playback automatically**. You can watch that through key-value observing of the player's `timeControlStatus`. The automatic part stops there. The pause is the system's; the resume is the app's. "Playback never resumes" is therefore almost always a missing or broken handler, not a framework bug. ## The legacy notification (iOS 6 to iOS 26) Until iOS 27, the session reports interruptions through **`AVAudioSession.interruptionNotification`**, posted with the session as its object and a `userInfo` dictionary: - `AVAudioSessionInterruptionTypeKey` holds an `AVAudioSession.InterruptionType`, either `.began` or `.ended`. - `AVAudioSessionInterruptionOptionKey` is **present only on the ended event** and holds `AVAudioSession.InterruptionOptions`. - `.shouldResume` in those options means the system suggests resuming; its absence means stay paused, for example because another app's media took over. - `AVAudioSessionInterruptionReasonKey` (iOS 14.5) on the began event explains why, such as `.builtInMicMuted` or `.routeDisconnected` (iOS 17). The correct ended handler reactivates the session with `setActive(true)` and then calls `play()`. ## Diagnosing "never resumes" Work through the causes in order: 1. **No observer.** The app relies on AVPlayer and never subscribed. Fix: observe the notification for the lifetime of the player screen. 2. **A dead observer.** The observer was removed when the lesson screen disappeared, or the weakly captured object that handles it was deallocated during the call. Fix: let something that outlives the interruption own the observer token. 3. **Ignoring the options.** The handler resumes on every `.ended` (annoying when the user started music) or never reads `.shouldResume` at all. 4. **No reactivation.** Apple's guidance re-activates the session and then resumes playback; a handler that skips the reactivation is the next suspect. 5. **No end event.** Apple's iOS 27 article says the legacy model can get out of sync when the system cannot deliver an end event, leaving the app stuck in its interrupted state. The fifth cause is why iOS 27 changed the model. ## The iOS 27 lifecycle notifications In **iOS 27** the SDK deprecates `interruptionNotification`, its keys and its `InterruptionType` and `InterruptionOptions` enums, in favour of three lifecycle notifications, which Apple says are posted on the main queue: | Legacy (iOS 6 to 26) | iOS 27 and later | |---|---| | `.began` in the type key | `didBecomeInactiveNotification` with an `AVAudioSession.DeactivationContext` under `deactivationContextKey` | | reason key on `.began` | the context's `source` (`.app` or `.system`) and `interruptionContext?.reason` | | `.ended` plus `.shouldResume` | `resumptionRecommendationNotification` with an `AVAudioSession.ResumptionContext` whose `recommendation` is `.shouldResume` or `.shouldNotResume` | | none | `didBecomeActiveNotification` | Apple notes that the resumption recommendation is **not tied to the interrupting app's end-of-interruption signal**, so the app is not left stranded if that signal never comes. On `.shouldResume`, reactivate with the new asynchronous `activate()` (or `setActive(true)`) and play. An app deploying to iOS 17 keeps the legacy observer for older systems and adopts the new notifications behind `if #available(iOS 27, *)`. ## Route changes are the other half Unplugging headphones is not an interruption; it is a **route change**, posted as `AVAudioSession.routeChangeNotification` with `AVAudioSessionRouteChangeReasonKey`. The header states that media playback apps are expected to **pause when the reason is `.oldDeviceUnavailable`**, so a lesson never bursts out of the speaker in a quiet studio. Since iOS 17, Now Playing sessions are interrupted by default when a route disconnects, and `setPrefersInterruptionOnRouteDisconnect(_:)` opts in or out. One more notification to know: `mediaServicesWereResetNotification` means the media server restarted, and the header says to re-initialise the audio objects the app uses. ## What to check in review - An interruption observer exists for as long as a lesson can play, not only while one screen is visible. - The ended branch reads the options and resumes only on `.shouldResume`. - The handler re-activates the session before calling `play()`. - The play button is driven by the player's `timeControlStatus`, so the UI shows the system's pause instead of a stale "playing" state. - A route-change observer pauses on `.oldDeviceUnavailable`. - Code that deploys to iOS 17 keeps the legacy path and adds the iOS 27 notifications behind an availability check, rather than dropping one for the other.
- What should the lesson player do when wired headphones are unplugged?Observe `routeChangeNotification` and pause when `AVAudioSessionRouteChangeReasonKey` is `.oldDeviceUnavailable`; the header says media playback apps are expected to. Since iOS 17, a Now Playing session is also interrupted by default on a route disconnect, which `setPrefersInterruptionOnRouteDisconnect(_:)` controls.
- Why can a correct legacy handler still leave the lesson paused?It depends on an ended event the system cannot always deliver. Apple's iOS 27 article says the lifecycle model avoids that drift: `resumptionRecommendationNotification` is not tied to the interrupting app's end signal. On older systems, a visible play button lets the user recover.
- Should the handler resume on every ended interruption?No. Resume only when `.shouldResume` is present (or the iOS 27 recommendation is `.shouldResume`). Without it, the user may have started other audio, and restarting the lesson over it would be wrong.
- AVPlayer resumes by itself once the phone call ends
- The interruption option key is present on both began and ended events
- Every ended interruption should restart playback
- The legacy ended event is guaranteed to arrive after every call
- Unplugging headphones posts an interruption notification
Assumes the iOS 27.1 SDK: iOS 27 deprecates interruptionNotification and its keys for lifecycle notifications; apps deploying to iOS 17 to 26 still observe the legacy one.