axiom-now-playing

Now Playing Integration Guide

Purpose: Prevent the 4 most common Now Playing issues on iOS 18+: info not appearing, commands not working, artwork problems, and state sync issues

Swift Version: Swift 6.0+ iOS Version: iOS 18+ Xcode: Xcode 16+

Core Philosophy

"Now Playing eligibility requires THREE things working together: AVAudioSession activation, remote command handlers, and metadata publishing. Missing ANY of these silently breaks the entire system. 90% of Now Playing issues stem from incorrect activation order or missing command handlers, not API bugs."

Key Insight from WWDC 2022/110338: Apps must meet two system heuristics:

1. Register handlers for at least one remote command
2. Configure AVAudioSession with a non-mixable category

When to Use This Skill

✅ Use this skill when:

• Now Playing info doesn't appear on Lock Screen or Control Center
• Play/pause/skip buttons are grayed out or don't respond
• Album artwork is missing, wrong, or flickers between images
• Control Center shows "Playing" when app is paused, or vice versa
• Apple Music or other apps "steal" Now Playing status
• Implementing Now Playing for the first time
• Debugging Now Playing issues in existing implementation
• Integrating CarPlay Now Playing (covered in Pattern 6)
• Working with MusicKit/Apple Music content (covered in Pattern 7)

iOS 26 Note

iOS 26 introduces Liquid Glass visual design for Lock Screen and Control Center Now Playing widgets. This is automatic system behavior — no code changes required. The patterns in this skill remain valid for iOS 26.

❌ Do NOT use this skill for:

• Background audio configuration details (see AVFoundation skill)

Related Skills

• swift-concurrency - For @MainActor patterns, weak self in closures, async artwork loading
• memory-debugging - For retain cycles in command handlers
• avfoundation-ref - For AVAudioSession configuration details

---

Red Flags / Anti-Patterns

If you see ANY of these, suspect Now Playing misconfiguration:

• Info appears briefly then disappears (AVAudioSession deactivated)
• Commands work in simulator but not on device (simulator has different audio stack)
• Artwork shows placeholder then updates (race condition, not necessarily wrong)
• Artwork never appears (format/size issue or MPMediaItemArtwork block returning nil)
• Play/pause state incorrect after backgrounding (not updating on playback rate changes)
• Another app "steals" Now Playing (didn't meet eligibility requirements)
• playbackState property doesn't update (iOS doesn't have playbackState, macOS only!)

FORBIDDEN Assumptions:

• "Just set nowPlayingInfo and it works" - Must have AVAudioSession + command handlers
• "playbackState controls Control Center" - iOS ignores playbackState, uses playbackRate
• "Artwork just needs an image" - Needs proper MPMediaItemArtwork with size handler
• "Commands enable themselves" - Must add target AND set isEnabled = true
• "Update elapsed time every second" - System infers from rate, causes jitter

Mandatory First Steps (Pre-Diagnosis)

Run this code to understand current state before debugging:

// 1. Verify AVAudioSession configuration
let session = AVAudioSession.sharedInstance()
print("Category: \(session.category.rawValue)")
print("Mode: \(session.mode.rawValue)")
print("Options: \(session.categoryOptions)")
print("Is active: \(try? session.setActive(true))")
// Must be: .playback category, NOT .mixWithOthers option

// 2. Verify background mode
// Info.plist must have: UIBackgroundModes = ["audio"]

// 3. Check command handlers are registered
let commandCenter = MPRemoteCommandCenter.shared()
print("Play enabled: \(commandCenter.playCommand.isEnabled)")
print("Pause enabled: \(commandCenter.pauseCommand.isEnabled)")
// Must have at least one command with target AND isEnabled = true

// 4. Check nowPlayingInfo dictionary
if let info = MPNowPlayingInfoCenter.default().nowPlayingInfo {
    print("Title: \(info[MPMediaItemPropertyTitle] ?? "nil")")
    print("Artwork: \(info[MPMediaItemPropertyArtwork] != nil)")
    print("Duration: \(info[MPMediaItemPropertyPlaybackDuration] ?? "nil")")
    print("Elapsed: \(info[MPNowPlayingInfoPropertyElapsedPlaybackTime] ?? "nil")")
    print("Rate: \(info[MPNowPlayingInfoPropertyPlaybackRate] ?? "nil")")
} else {
    print("No nowPlayingInfo set!")
}

What this tells you:

Observation	Diagnosis	Pattern
Category is .ambient or has .mixWithOthers	Won't become Now Playing app	Pattern 1
No commands have targets	System ignores app	Pattern 2
Commands have targets but isEnabled = false	UI grayed out	Pattern 2
Artwork is nil	MPMediaItemArtwork block returning nil	Pattern 3
playbackRate is 0.0 when playing	Control Center shows paused	Pattern 4
Background mode "audio" not in Info.plist	Info disappears on lock	Pattern 1

Decision Tree

Now Playing not working?
├─ Info never appears at all?
│  ├─ AVAudioSession category .ambient or .mixWithOthers?
│  │  └─ Pattern 1a (Wrong Category)
│  ├─ No remote command handlers registered?
│  │  └─ Pattern 2a (Missing Handlers)
│  ├─ Background mode "audio" not in Info.plist?
│  │  └─ Pattern 1b (Background Mode)
│  └─ AVAudioSession.setActive(true) never called?
│     └─ Pattern 1c (Not Activated)
│
├─ Info appears briefly, then disappears?
│  ├─ On lock screen specifically?
│  │  ├─ AVAudioSession deactivated too early?
│  │  │  └─ Pattern 1d (Early Deactivation)
│  │  └─ App suspended (no background mode)?
│  │     └─ Pattern 1b (Background Mode)
│  └─ When switching apps?
│     └─ Another app claiming Now Playing → Pattern 5
│
├─ Commands not responding?
│  ├─ Buttons grayed out (disabled)?
│  │  └─ command.isEnabled = false → Pattern 2b
│  ├─ Buttons visible but no response?
│  │  ├─ Handler not returning .success?
│  │  │  └─ Pattern 2c (Handler Return)
│  │  └─ Using wrong command center (session vs shared)?
│  │     └─ Pattern 2d (Command Center)
│  └─ Skip forward/backward not showing?
│     └─ preferredIntervals not set → Pattern 2e
│
├─ Artwork problems?
│  ├─ Never appears?
│  │  ├─ MPMediaItemArtwork block returning nil?
│  │  │  └─ Pattern 3a (Artwork Block)
│  │  └─ Image format/size invalid?
│  │     └─ Pattern 3b (Image Format)
│  ├─ Wrong artwork showing?
│  │  └─ Race condition between sources → Pattern 3c
│  └─ Artwork flickering?
│     └─ Multiple updates in rapid succession → Pattern 3d
│
├─ State sync issues?
│  ├─ Shows "Playing" when paused?
│  │  └─ playbackRate not updated → Pattern 4a
│  ├─ Progress bar stuck or jumping?
│  │  └─ elapsedTime not updated at right moments → Pattern 4b
│  └─ Duration wrong?
│     └─ Not setting playbackDuration → Pattern 4c
│
├─ CarPlay specific issues?
│  ├─ App doesn't appear in CarPlay at all?
│  │  └─ Missing entitlement → Pattern 6 (Add com.apple.developer.carplay-audio)
│  ├─ Now Playing blank in CarPlay but works on iOS?
│  │  └─ Same root cause as iOS → Check Patterns 1-4
│  ├─ Custom buttons don't appear in CarPlay?
│  │  └─ Wrong configuration timing → Pattern 6 (Configure at templateApplicationScene)
│  └─ Works on device but not CarPlay simulator?
│     └─ Debugger interference → Pattern 6 (Run without debugger)
│
└─ Using MusicKit (ApplicationMusicPlayer)?
   ├─ Now Playing shows wrong info?
   │  └─ Overwriting automatic data → Pattern 7 (Don't set nowPlayingInfo manually)
   └─ Mixing MusicKit + own content?
      └─ Hybrid approach needed → Pattern 7 (Switch between players)

---

Pattern 1: AVAudioSession Configuration (Info Not Appearing)

Time cost: 10-15 minutes

Symptom

• Now Playing info never appears on Lock Screen
• Info appears briefly then disappears on lock
• Works in foreground, disappears in background

BAD Code

// ❌ WRONG — Category allows mixing, won't become Now Playing app
class PlayerService {
    func setupAudioSession() throws {
        try AVAudioSession.sharedInstance().setCategory(
            .playback,
            options: .mixWithOthers  // ❌ Mixable = not eligible for Now Playing
        )
        // Never called setActive()  // ❌ Session not activated
    }

    func play() {
        player.play()
        updateNowPlaying()  // ❌ Won't appear - session not active
    }
}

GOOD Code

// ✅ CORRECT — Non-mixable category, activated before playback
class PlayerService {
    func setupAudioSession() throws {
        try AVAudioSession.sharedInstance().setCategory(
            .playback,
            mode: .default,
            options: []  // ✅ No .mixWithOthers = eligible for Now Playing
        )
    }

    func play() async throws {
        // ✅ Activate BEFORE starting playback
        try AVAudioSession.sharedInstance().setActive(true)

        player.play()
        updateNowPlaying()  // ✅ Now appears correctly
    }

    func stop() async throws {
        player.pause()

        // ✅ Deactivate AFTER stopping, with notify option
        try AVAudioSession.sharedInstance().setActive(
            false,
            options: .notifyOthersOnDeactivation
        )
    }
}

Info.plist Requirement

<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
</array>

Verification

• Lock screen shows Now Playing controls
• Info persists when app backgrounded
• Survives app switch (unless another app plays)

---

Pattern 2: Remote Command Registration (Commands Not Working)

Time cost: 15-20 minutes

Symptom

• Play/pause buttons grayed out
• Buttons visible but tapping does nothing
• Skip buttons don't appear
• Commands work once then stop

BAD Code

// ❌ WRONG — Missing targets and isEnabled
class PlayerService {
    func setupCommands() {
        let commandCenter = MPRemoteCommandCenter.shared()

        // ❌ Added target but forgot isEnabled
        commandCenter.playCommand.addTarget { _ in
            self.play

---

*Content truncated.*