Musickit

by dpearson26998d90fd121a26No license1.1K starsListed Oct 8, 2026Updated Oct 8, 2026Repository updated 2 months ago

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.

Instructions onlySoftware Development

AI-generated overview

Guides iOS developers through integrating Apple Music search, subscription checks, playback, and Now Playing metadata with MusicKit.

What it does: This skill provides reference instructions and Swift code examples for adding Apple Music features to iOS apps using MusicKit and MediaPlayer. It covers project configuration, authorization, catalog search, subscription checks, playback with ApplicationMusicPlayer, queue management, Now Playing info, and remote command handling. It also includes a common-mistakes table and a review checklist.
When to use it: Use it when adding music search, Apple Music subscription flows, queue management, playback controls, remote command handling, or Now Playing info to an iOS app. It is also useful for reviewing or debugging existing MusicKit integration.
Requirements: Requires an iOS app project with the MusicKit App Service enabled for the bundle ID, NSAppleMusicUsageDescription in Info.plist, and the audio background mode for background playback. Uses the MusicKit and MediaPlayer frameworks. No scripts are included; it is instructions only.

MusicKit

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

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

Workflow

Verify the MusicKit App Service, bundle identifier, purpose string, and background-audio mode before debugging code.
Request authorization, then model every non-authorized state explicitly.
Search or load catalog content and check MusicSubscription.current before queueing playback.
Choose ApplicationMusicPlayer for app-scoped playback; wire Now Playing and remote commands only when the app owns those surfaces.
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

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

Imports

swift

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

import MusicKit       // Catalog, auth, playbackimport 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.

swift

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 promptinglet current = MusicAuthorization.currentStatus

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 promptinglet 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.

swift

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}

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

swift

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    }}

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.

swift

func checkSubscription() async throws -> Bool {    let subscription = try await MusicSubscription.current    return subscription.canPlayCatalogContent}
// Observe subscription changesfunc observeSubscription() async {    for await subscription in MusicSubscription.subscriptionUpdates {        if subscription.canPlayCatalogContent {            // Enable full playback UI        } else {            // Show subscription offer        }    }}

func checkSubscription() async throws -> Bool {    let subscription = try await MusicSubscription.current    return subscription.canPlayCatalogContent}
// Observe subscription changesfunc 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.

swift

import MusicKitimport 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)                }            }        )    }}

import MusicKitimport 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.

swift

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()}

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

swift

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    }}

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.

swift

// Initialize with multiple itemsfunc playAlbum(_ album: Album) async throws {    player.queue = [album]    try await player.play()}
// Append songs to the existing queuefunc appendToQueue(_ songs: [Song]) async throws {    try await player.queue.insert(songs, position: .tail)}
// Insert song to play nextfunc playNext(_ song: Song) async throws {    try await player.queue.insert(song, position: .afterCurrentEntry)}

// Initialize with multiple itemsfunc playAlbum(_ album: Album) async throws {    player.queue = [album]    try await player.play()}
// Append songs to the existing queuefunc appendToQueue(_ songs: [Song]) async throws {    try await player.queue.insert(songs, position: .tail)}
// Insert song to play nextfunc 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.

swift

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}

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

swift

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

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.

swift

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}

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

swift

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    }}

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

Mistake	Fix
Debugging authorization before configuring the App Service and purpose string	Verify service, bundle ID, and `NSAppleMusicUsageDescription` first.
Queueing catalog content without a subscription gate	Check `canPlayCatalogContent`; offer subscription only when `canBecomeSubscriber`.
Using `SystemMusicPlayer` for app-owned playback	Use `ApplicationMusicPlayer`; the system player changes the Music app's global queue.
Publishing Now Playing metadata once	Refresh it on track, duration, rate, and elapsed-time changes.
Registering unsupported remote commands	Disable them; supported handlers must perform the action and return `.success`.

Review Checklist

References

Extended patterns (SwiftUI integration, genre browsing, playlist management): references/musickit-patterns.md [blocked]
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

Source and attribution

Source:dpearson2699/swift-ios-skillsinskills/musickitat commit8d90fd1

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

More from dpearson2699/swift-ios-skills

Widgetkit

dpearson2699

Guides implementing, reviewing, and improving WidgetKit widgets and controls for iOS, iPadOS, watchOS, and CarPlay.

Software Development1.1Kupdated 2 months ago

Weatherkit

dpearson2699

Guides iOS developers in fetching WeatherKit forecasts, alerts, and attribution using WeatherService.

Software Development1.1Kupdated 2 months ago

Vision Framework

dpearson2699

Implement computer vision features including text recognition (OCR), face detection, barcode scanning, image segmentation, object tracking, and document scanning in iOS apps. Covers both the modern Swift-native Vision API (iOS 18+) and legacy VNRequest patterns, VisionKit DataScannerViewController for live camera scanning, and CoreMLRequest/VNCoreMLRequest for custom model inference. Use when adding OCR, barcode scanning, face detection, or custom Core ML model inference with Vision.

Awaiting classification1.1Kupdated 2 months ago

Tipkit

dpearson2699

Implement and review Apple TipKit feature-discovery UI for iOS 17+ apps. Use when adding or auditing in-app tips, contextual help, coach marks, Tip, TipView, popoverTip, rules, events, actions, display frequency, testing overrides, reusable tip identifiers, or iOS 18+ TipGroup and CloudKit tip sync; avoid for generic SwiftUI navigation or layout outside tip presentation.

Awaiting classification1.1Kupdated 2 months ago

Tabletopkit

dpearson2699

Guides building multiplayer spatial board games on visionOS with Apple's TabletopKit and RealityKit.

Software Development1.1Kupdated 2 months ago

Swiftui Webkit

dpearson2699

Guides embedding and controlling web content in SwiftUI apps with WebKit for SwiftUI on iOS 26 and later.

Software Development1.1Kupdated 2 months ago

Musickit

MusicKit

Contents

Workflow

Setup

Project Configuration

Imports

Authorization

Catalog Search

Displaying Results

Subscription Checks

Offering Apple Music

Playback with ApplicationMusicPlayer

Observing Playback State

Queue Management

Now Playing Info

Adding Artwork

Remote Command Center

Scrubbing Support

Common Mistakes

Review Checklist

References

Source and attribution

More from dpearson2699/swift-ios-skills

Widgetkit

Weatherkit

Vision Framework

Tipkit

Tabletopkit

Swiftui Webkit

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices