MusicKit

Access the Apple Music catalog, play tracks, query personal cloud libraries, and present subscription upsells using MusicKit. Targets Swift 6.4 / iOS 26+.

Contents

• Setup & Permissions
• Subscription Verification
• Catalog Search & Browse
• Audio Playback
• Subscription Upsell
• Common Mistakes
• Review Checklist
• References

Setup & Permissions

Add NSAppleMusicUsageDescription to Info.plist. Request user authorization:

import MusicKit

func requestMusicAccess() async -> MusicAuthorization.Status {
    let status = await MusicAuthorization.request()
    return status
}

Subscription Verification

Check capabilities on MusicSubscription.current before offering catalog playback:

func verifySubscription() async -> Bool {
    let sub = try? await MusicSubscription.current
    return sub?.canPlayCatalogContent ?? false
}

Catalog Search & Browse

Search Apple Music songs, albums, and artists:

func searchMusic(term: String) async throws -> MusicItemCollection<Song> {
    var request = MusicCatalogSearchRequest(term: term, types: [Song.self])
    request.limit = 20
    let response = try await request.response()
    return response.songs
}

func fetchCharts() async throws -> MusicItemCollection<Song> {
    let request = MusicCatalogChartsRequest(types: [Song.self])
    let response = try await request.response()
    return response.songs.first?.items ?? []
}

Audio Playback

Use ApplicationMusicPlayer for app-scoped playback or SystemMusicPlayer for system-wide Music app playback:

let player = ApplicationMusicPlayer.shared

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

Subscription Upsell

Present the native subscription sheet when canBecomeSubscriber is true:

import SwiftUI
import MusicKit

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

    var body: some View {
        Button("Subscribe to Apple Music") {
            showOffer = true
        }
        .musicSubscriptionOffer(isPresented: $showOffer)
    }
}

Common Mistakes

• Playing catalog songs without checking subscription: Fails or plays previews unless subscription.canPlayCatalogContent is true.
• Missing NSAppleMusicUsageDescription: Instant crash on calling MusicAuthorization.request().
• Using SystemMusicPlayer when app-scoped audio is needed: SystemMusicPlayer replaces the user's active Music app queue. Use ApplicationMusicPlayer.shared for in-app music.
• Forgetting playback error handling: Playback can fail due to parental restrictions, offline status, or DRM. Catch errors from player.play().
• Hardcoding storefront IDs: MusicKit automatically infers the current storefront from user account settings; avoid hardcoding country codes.

Review Checklist

• NSAppleMusicUsageDescription added to Info.plist
• MusicAuthorization.request() handled before library/playback calls
• subscription.canPlayCatalogContent verified prior to full track streaming
• musicSubscriptionOffer provided for non-subscribers
• Appropriate player selected (ApplicationMusicPlayer vs SystemMusicPlayer)

References

• Extended patterns (custom playlists, Now Playing metadata, audio engine integration): references/musickit-patterns.md
• MusicKit framework
• MusicAuthorization
• ApplicationMusicPlayer
• MusicCatalogSearchRequest
• MusicSubscription
• canPlayCatalogContent
• canBecomeSubscriber
• hasCloudLibraryEnabled
• MusicCatalogChartsRequest initializer
• musicSubscriptionOffer(isPresented:options:onLoadCompletion:)
• MPRemoteCommandCenter
• MPNowPlayingInfoCenter
• NSAppleMusicUsageDescription