Musickit

MusicKit

Search the Apple Music catalog, manage playback with ApplicationMusicPlayer, check subscriptions, and publish Now Playing metadata via MPNowPlayingInfoCenter and MPRemoteCommandCenter. Targets Swift 6.3 / iOS 26+.

Contents

• Setup
• Authorization
• Catalog Search
• Subscription Checks
• Playback with ApplicationMusicPlayer
• Queue Management
• Now Playing Info
• Remote Command Center
• Common Mistakes
• Review Checklist
• References

Setup

Project Configuration

1. Enable the MusicKit App Service for the app's explicit bundle ID in the Apple Developer portal so MusicKit can generate developer tokens automatically. 2. Add NSAppleMusicUsageDescription to Info.plist explaining why the app accesses the user's media library. 3. For background playback, add the audio background mode to UIBackgroundModes.

Imports

import MusicKit       // Catalog, auth, playback
import MediaPlayer    // MPRemoteCommandCenter, MPNowPlayingInfoCenter

Authorization

Request permission before accessing the user's music data or playing Apple Music content. request() presents Apple's consent dialog when necessary; use currentStatus to read the current setting without prompting.

func requestMusicAccess() async -> MusicAuthorization.Status {
    let status = await MusicAuthorization.request()
    switch status {
    case .authorized:
        // Full access to MusicKit APIs
        break
    case .denied, .restricted:
        // Show guidance to enable in Settings
        break
    case .notDetermined:
        break
    @unknown default:
        break
    }
    return status
}

// Check current status without prompting
let current = MusicAuthorization.currentStatus

Catalog Search

Use MusicCatalogSearchRequest to search the Apple Music catalog. Catalog lookup can fetch Apple Music resources, but playback of subscription catalog content must still be gated on MusicSubscription.current.canPlayCatalogContent.

func searchCatalog(term: String) async throws -> MusicItemCollection<Song> {
    var request = MusicCatalogSearchRequest(term: term, types: [Song.self])
    request.limit = 25

    let response = try await request.response()
    return response.songs
}

Displaying Results

for song in songs {
    print("\(song.title) by \(song.artistName)")
    if let artwork = song.artwork {
        let url = artwork.url(width: 300, height: 300)
        // Load artwork from url
    }
}

Subscription Checks

Check whether the user has an active Apple Music subscription before offering playback features.

func checkSubscription() async throws -> Bool {
    let subscription = try await MusicSubscription.current
    return subscription.canPlayCatalogContent
}

// Observe subscription changes
func observeSubscription() async {
    for await subscription in MusicSubscription.subscriptionUpdates {
        if subscription.canPlayCatalogContent {
            // Enable full playback UI
        } else {
            // Show subscription offer
        }
    }
}

Offering Apple Music

Present the Apple Music subscription offer sheet when the user is not subscribed. Check canBecomeSubscriber first, and pass MusicSubscriptionOffer.Options or onLoadCompletion when the sheet needs contextual metadata or load-error handling.

import MusicKit
import SwiftUI

struct MusicOfferView: View {
    @State private var showOffer = false

    var body: some View {
        Button("Subscribe to Apple Music") {
            Task {
                let subscription = try? await MusicSubscription.current
                showOffer = subscription?.canBecomeSubscriber == true
            }
        }
        .musicSubscriptionOffer(
            isPresented: $showOffer,
            options: .default,
            onLoadCompletion: { error in
                if let error {
                    // Surface loading errors in app UI or diagnostics.
                    print(error)
                }
            }
        )
    }
}

Playback with ApplicationMusicPlayer

ApplicationMusicPlayer plays Apple Music content independently from the Music app. It does not affect the system player's state.

let player = ApplicationMusicPlayer.shared

func playSong(_ song: Song) async throws {
    player.queue = [song]
    try await player.play()
}

func pause() {
    player.pause()
}

func skipToNext() async throws {
    try await player.skipToNextEntry()
}

Observing Playback State

func observePlayback() {
    // player.state is an @Observable property
    let state = player.state
    switch state.playbackStatus {
    case .playing:
        break
    case .paused:
        break
    case .stopped, .interrupted, .seekingForward, .seekingBackward:
        break
    @unknown default:
        break
    }
}

Queue Management

Build and manipulate the playback queue using ApplicationMusicPlayer.Queue.

// Initialize with multiple items
func playAlbum(_ album: Album) async throws {
    player.queue = [album]
    try await player.play()
}

// Append songs to the existing queue
func appendToQueue(_ songs: [Song]) async throws {
    try await player.queue.insert(songs, position: .tail)
}

// Insert song to play next
func playNext(_ song: Song) async throws {
    try await player.queue.insert(song, position: .afterCurrentEntry)
}

Now Playing Info

Update MPNowPlayingInfoCenter so the Lock Screen, Control Center, and CarPlay display current track metadata. This is essential when playing custom audio (non-MusicKit sources). ApplicationMusicPlayer handles this automatically for Apple Music content.

import MediaPlayer

func updateNowPlaying(title: String, artist: String, duration: TimeInterval, elapsed: TimeInterval) {
    var info = [String: Any]()
    info[MPMediaItemPropertyTitle] = title
    info[MPMediaItemPropertyArtist] = artist
    info[MPMediaItemPropertyPlaybackDuration] = duration
    info[MPNowPlayingInfoPropertyElapsedPlaybackTime] = elapsed
    info[MPNowPlayingInfoPropertyPlaybackRate] = 1.0
    info[MPNowPlayingInfoPropertyMediaType] = MPNowPlayingInfoMediaType.audio.rawValue

    MPNowPlayingInfoCenter.default().nowPlayingInfo = info
}

func clearNowPlaying() {
    MPNowPlayingInfoCenter.default().nowPlayingInfo = nil
}

Adding Artwork

func setArtwork(_ image: UIImage) {
    let artwork = MPMediaItemArtwork(boundsSize: image.size) { _ in image }
    var info = MPNowPlayingInfoCenter.default().nowPlayingInfo ?? [:]
    info[MPMediaItemPropertyArtwork] = artwork
    MPNowPlayingInfoCenter.default().nowPlayingInfo = info
}

Remote Command Center

Register handlers for MPRemoteCommandCenter to respond to Lock Screen controls, AirPods tap gestures, and CarPlay buttons.

func setupRemoteCommands() {
    let center = MPRemoteCommandCenter.shared()

    center.playCommand.addTarget { _ in
        resumePlayback()
        return .success
    }

    center.pauseCommand.addTarget { _ in
        pausePlayback()
        return .success
    }

    center.nextTrackCommand.addTarget { _ in
        skipToNext()
        return .success
    }

    center.previousTrackCommand.addTarget { _ in
        skipToPrevious()
        return .success
    }

    // Disable commands you do not support
    center.seekForwardCommand.isEnabled = false
    center.seekBackwardCommand.isEnabled = false
}

Scrubbing Support

func enableScrubbing() {
    let center = MPRemoteCommandCenter.shared()
    center.changePlaybackPositionCommand.addTarget { event in
        guard let positionEvent = event as? MPChangePlaybackPositionCommandEvent else {
            return .commandFailed
        }
        seek(to: positionEvent.positionTime)
        return .success
    }
}

Common Mistakes

DON'T: Skip MusicKit App Service setup or usage description

Without the MusicKit App Service on the app's explicit bundle ID, automatic developer token generation for Apple Music API requests is not configured. Without NSAppleMusicUsageDescription, the app cannot access the user's media library on Apple platforms that require the purpose string.

// WRONG: MusicKit App Service not enabled for this bundle ID

// CORRECT: Enable MusicKit App Service in the developer portal,
// set the matching bundle ID, then add NSAppleMusicUsageDescription.
let status = await MusicAuthorization.request()

DON'T: Forget to check subscription before playback

Attempting to play catalog content without a subscription silently fails or throws.

// WRONG
func play(_ song: Song) async throws {
    player.queue = [song]
    try await player.play() // Fails if no subscription
}

// CORRECT
func play(_ song: Song) async throws {
    let sub = try await MusicSubscription.current
    guard sub.canPlayCatalogContent else {
        showSubscriptionOffer()
        return
    }
    player.queue = [song]
    try await player.play()
}

DON'T: Use SystemMusicPlayer when you mean ApplicationMusicPlayer

SystemMusicPlayer controls the global Music app queue. Changes affect the user's Music app state. Use ApplicationMusicPlayer for app-scoped playback.

// WRONG: Modifies the user's Music app queue
let player = SystemMusicPlayer.shared

// CORRECT: App-scoped playback
let player = ApplicationMusicPlayer.shared

DON'T: Forget to update Now Playing info when track changes

Stale metadata on the Lock Screen confuses users. Update Now Playing info every time the current track changes.

// WRONG: Set once and forget
updateNowPlaying(title: firstSong.title, ...)

// CORRECT: Update on every track change
func onTrackChanged(_ song: Song) {
    updateNowPlaying(
        title: song.title,
        artist: song.artistName,
        duration: song.duration ?? 0,
        elapsed: 0
    )
}

DON'T: Register remote commands without handling them

Registering a command but returning .commandFailed breaks Lock Screen controls. Disable commands you do not support instead.

// WRONG
center.skipForwardCommand.addTarget { _ in .commandFailed }

// CORRECT
center.skipForwardCommand.isEnabled = false

Review Checklist

• [ ] MusicKit App Service enabled for the app's explicit bundle ID
• [ ] NSAppleMusicUsageDescription added to Info.plist
• [ ] MusicAuthorization.request() called before any MusicKit access
• [ ] Subscription checked before attempting catalog playback
• [ ] canBecomeSubscriber checked before presenting a subscription offer
• [ ] hasCloudLibraryEnabled checked before library writes
• [ ] ApplicationMusicPlayer used (not SystemMusicPlayer) for app-scoped playback
• [ ] Background audio mode enabled if music plays in background
• [ ] Now Playing info updated on every track change (for custom audio)
• [ ] Remote command handlers return .success for supported commands
• [ ] Unsupported remote commands disabled with isEnabled = false
• [ ] Artwork provided in Now Playing info for Lock Screen display
• [ ] Elapsed playback time updated periodically for scrubber accuracy
• [ ] Subscription offer presented when user lacks Apple Music subscription

References

• Extended patterns (SwiftUI integration, genre browsing, playlist management): references/musickit-patterns.md
• MusicKit framework
• Using automatic developer token generation for Apple Music API
• MusicAuthorization
• ApplicationMusicPlayer
• MusicCatalogSearchRequest
• MusicSubscription
• canPlayCatalogContent
• canBecomeSubscriber
• hasCloudLibraryEnabled
• MusicCatalogChartsRequest initializer)
• musicSubscriptionOffer(isPresented:options:onLoadCompletion:))
• MPRemoteCommandCenter
• MPNowPlayingInfoCenter
• NSAppleMusicUsageDescription

MusicKit + MediaPlayer Extended Patterns

Overflow reference for the musickit skill. Contains advanced patterns that exceed the main skill file's scope.

Contents

• MusicKit SwiftUI Integration
• Genre and Chart Browsing
• Library Management
• Playlist Access
• Now Playing Session
• Background Audio Configuration

MusicKit SwiftUI Integration

Music Player Manager with @Observable

import MusicKit
import MediaPlayer

@Observable
@MainActor
final class MusicPlayerManager {
    let player = ApplicationMusicPlayer.shared

    var currentSong: Song?
    var isPlaying = false
    var playbackTime: TimeInterval = 0
    var queue: [Song] = []
    var hasSubscription = false

    func setup() async {
        // Check authorization
        let status = await MusicAuthorization.request()
        guard status == .authorized else { return }

        // Check subscription
        if let subscription = try? await MusicSubscription.current {
            hasSubscription = subscription.canPlayCatalogContent
        }

        // Observe subscription changes
        Task {
            for await subscription in MusicSubscription.subscriptionUpdates {
                hasSubscription = subscription.canPlayCatalogContent
            }
        }
    }

    func play(_ song: Song) async throws {
        guard hasSubscription else { return }
        player.queue = [song]
        try await player.play()
        currentSong = song
        isPlaying = true
    }

    func togglePlayPause() {
        if player.state.playbackStatus == .playing {
            player.pause()
            isPlaying = false
        } else {
            Task {
                try? await player.play()
                isPlaying = true
            }
        }
    }

    func skip() async {
        try? await player.skipToNextEntry()
    }
}

SwiftUI Player View

import SwiftUI
import MusicKit

struct MiniPlayerView: View {
    @Environment(MusicPlayerManager.self) private var manager

    var body: some View {
        HStack {
            if let song = manager.currentSong {
                if let artwork = song.artwork {
                    ArtworkImage(artwork, width: 44, height: 44)
                        .clipShape(.rect(cornerRadius: 6))
                }

                VStack(alignment: .leading) {
                    Text(song.title)
                        .font(.subheadline)
                        .lineLimit(1)
                    Text(song.artistName)
                        .font(.caption)
                        .foregroundStyle(.secondary)
                }

                Spacer()

                Button {
                    manager.togglePlayPause()
                } label: {
                    Image(systemName: manager.isPlaying ? "pause.fill" : "play.fill")
                        .font(.title2)
                }

                Button {
                    Task { await manager.skip() }
                } label: {
                    Image(systemName: "forward.fill")
                }
            }
        }
        .padding(.horizontal)
        .frame(height: 60)
    }
}

Search View

struct MusicSearchView: View {
    @State private var searchText = ""
    @State private var results: MusicItemCollection<Song> = []
    @Environment(MusicPlayerManager.self) private var manager

    var body: some View {
        NavigationStack {
            List(results) { song in
                Button {
                    Task { try? await manager.play(song) }
                } label: {
                    HStack {
                        if let artwork = song.artwork {
                            ArtworkImage(artwork, width: 50, height: 50)
                                .clipShape(.rect(cornerRadius: 4))
                        }
                        VStack(alignment: .leading) {
                            Text(song.title)
                            Text(song.artistName)
                                .font(.caption)
                                .foregroundStyle(.secondary)
                        }
                    }
                }
            }
            .searchable(text: $searchText, prompt: "Search Apple Music")
            .onChange(of: searchText) {
                Task { await search() }
            }
            .navigationTitle("Search")
        }
    }

    private func search() async {
        guard !searchText.isEmpty else {
            results = []
            return
        }
        var request = MusicCatalogSearchRequest(term: searchText, types: [Song.self])
        request.limit = 25
        if let response = try? await request.response() {
            results = response.songs
        }
    }
}

Genre and Chart Browsing

Fetching Top Charts

func fetchTopSongs() async throws -> MusicItemCollection<Song> {
    var request = MusicCatalogChartsRequest(
        genre: nil,
        kinds: [.mostPlayed],
        types: [Song.self]
    )
    request.limit = 50
    let response = try await request.response()
    return response.songCharts.first?.items ?? []
}

Fetching by Genre

func fetchSongsByGenre(_ genre: Genre) async throws -> MusicItemCollection<Song> {
    var request = MusicCatalogSearchRequest(term: genre.name, types: [Song.self])
    request.limit = 25
    let response = try await request.response()
    return response.songs
}

Library Management

Library writes require MusicKit authorization and an enabled iCloud Music Library. Check MusicSubscription.current.hasCloudLibraryEnabled before adding items or modifying playlists.

Adding to Library

func addToLibrary(_ song: Song) async throws {
    guard MusicAuthorization.currentStatus == .authorized else { return }
    let subscription = try await MusicSubscription.current
    guard subscription.hasCloudLibraryEnabled else { return }

    try await MusicLibrary.shared.add(song)
}

func addAlbumToLibrary(_ album: Album) async throws {
    guard MusicAuthorization.currentStatus == .authorized else { return }
    let subscription = try await MusicSubscription.current
    guard subscription.hasCloudLibraryEnabled else { return }

    try await MusicLibrary.shared.add(album)
}

Fetching Library Content

func fetchLibrarySongs() async throws -> MusicItemCollection<Song> {
    var request = MusicLibraryRequest<Song>()
    request.sort(by: \.lastPlayedDate, ascending: false)
    request.limit = 50
    let response = try await request.response()
    return response.items
}

Playlist Access

Fetching User Playlists

func fetchPlaylists() async throws -> MusicItemCollection<Playlist> {
    var request = MusicLibraryRequest<Playlist>()
    request.sort(by: \.lastModifiedDate, ascending: false)
    let response = try await request.response()
    return response.items
}

Adding Tracks to a Playlist

func addToPlaylist(_ playlist: Playlist, songs: [Song]) async throws {
    guard MusicAuthorization.currentStatus == .authorized else { return }
    let subscription = try await MusicSubscription.current
    guard subscription.hasCloudLibraryEnabled else { return }

    try await MusicLibrary.shared.add(songs, to: playlist)
}

Now Playing Session

Use MPNowPlayingSession when your app manages multiple simultaneous audio sessions (e.g., picture-in-picture video plus background music).

import MediaPlayer
import AVFoundation

func createNowPlayingSession(for player: AVPlayer) -> MPNowPlayingSession {
    let session = MPNowPlayingSession(players: [player])

    // Session-scoped remote command center
    session.remoteCommandCenter.playCommand.addTarget { _ in
        player.play()
        return .success
    }

    session.remoteCommandCenter.pauseCommand.addTarget { _ in
        player.pause()
        return .success
    }

    // Session-scoped now playing info
    session.nowPlayingInfoCenter.nowPlayingInfo = [
        MPMediaItemPropertyTitle: "Track Title",
        MPMediaItemPropertyArtist: "Artist Name"
    ]

    // Activate this session to become the "now playing" app
    session.becomeActiveIfPossible { success in
        print("Now playing session active: \(success)")
    }

    return session
}

Background Audio Configuration

Audio Session Setup

Configure the audio session before starting playback to enable background audio.

import AVFoundation

func configureAudioSession() throws {
    let session = AVAudioSession.sharedInstance()
    try session.setCategory(.playback, mode: .default)
    try session.setActive(true)
}

Info.plist Background Mode

Add audio to UIBackgroundModes in Info.plist:

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

Handling Interruptions

func observeInterruptions() {
    NotificationCenter.default.addObserver(
        forName: AVAudioSession.interruptionNotification,
        object: AVAudioSession.sharedInstance(),
        queue: .main
    ) { notification in
        guard let typeValue = notification.userInfo?[AVAudioSessionInterruptionTypeKey] as? UInt,
              let type = AVAudioSession.InterruptionType(rawValue: typeValue) else {
            return
        }

        switch type {
        case .began:
            // Pause UI, save state
            break
        case .ended:
            let options = notification.userInfo?[AVAudioSessionInterruptionOptionKey] as? UInt
            if let options, AVAudioSession.InterruptionOptions(rawValue: options).contains(.shouldResume) {
                // Resume playback
            }
        @unknown default:
            break
        }
    }
}

Route Change Handling

Pause playback when headphones are unplugged to avoid unexpected speaker output.

func observeRouteChanges() {
    NotificationCenter.default.addObserver(
        forName: AVAudioSession.routeChangeNotification,
        object: AVAudioSession.sharedInstance(),
        queue: .main
    ) { notification in
        guard let reasonValue = notification.userInfo?[AVAudioSessionRouteChangeReasonKey] as? UInt,
              let reason = AVAudioSession.RouteChangeReason(rawValue: reasonValue) else {
            return
        }

        if reason == .oldDeviceUnavailable {
            // Headphones were unplugged -- pause playback
            pausePlayback()
        }
    }
}