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