/musickit

name: musickit
description: "Integrate Apple Music playback, catalog search, and Now Playing metadata using MusicKit and MediaPlayer. Use when adding music search, Apple Music subscription flows, queue management, playback controls, remote command handling, or Now Playing info to iOS apps."

MusicKit

Search the Apple Music catalog, manage playback with `ApplicationMusicPlayer`, check subscriptions, and publish Now Playing metadata via `MPNowPlayingInfoCenter` and `MPRemoteCommandCenter`.

Contents

• [Setup](#setup)
• [Workflow](#workflow)
• [Authorization](#authorization)
• [Catalog Search](#catalog-search)
• [Subscription Checks](#subscription-checks)
• [Playback with ApplicationMusicPlayer](#playback-with-applicationmusicplayer)
• [Queue Management](#queue-management)
• [Now Playing Info](#now-playing-info)
• [Remote Command Center](#remote-command-center)
• [Common Mistakes](#common-mistakes)
• [Review Checklist](#review-checklist)
• [References](#references)

Workflow

1. Verify the MusicKit App Service, bundle identifier, purpose string, and background-audio mode before debugging code. 2. Request authorization, then model every non-authorized state explicitly. 3. Search or load catalog content and check `MusicSubscription.current` before queueing playback. 4. Choose `ApplicationMusicPlayer` for app-scoped playback; wire Now Playing and remote commands only when the app owns those surfaces. 5. Test authorized, denied, unsubscribed, offline, queue failure, interruption, and track-change states. Fix the smallest failing layer, restore the fixture, and rerun the same state matrix.

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