Skill v1.0.1
currentLLM-judged scan95/100+3 new
version: "1.0.1" 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. 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
- 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
NSAppleMusicUsageDescriptionto Info.plist explaining why the app accesses the user's media library. - For background playback, add the
audiobackground mode toUIBackgroundModes.
Imports
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.
func requestMusicAccess() async -> MusicAuthorization.Status {let status = await MusicAuthorization.request()switch status {case .authorized:// Full access to MusicKit APIsbreakcase .denied, .restricted:// Show guidance to enable in Settingsbreakcase .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.
func searchCatalog(term: String) async throws -> MusicItemCollection<Song> {var request = MusicCatalogSearchRequest(term: term, types: [Song.self])request.limit = 25let 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.currentreturn 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.
import MusicKitimport SwiftUIstruct MusicOfferView: View {@State private var showOffer = falsevar body: some View {Button("Subscribe to Apple Music") {Task {let subscription = try? await MusicSubscription.currentshowOffer = subscription?.canBecomeSubscriber == true}}.musicSubscriptionOffer(isPresented: $showOffer,options: .default,onLoadCompletion: { error inif 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.sharedfunc 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 propertylet state = player.stateswitch state.playbackStatus {case .playing:breakcase .paused:breakcase .stopped, .interrupted, .seekingForward, .seekingBackward:break@unknown default:break}}
Queue Management
Build and manipulate the playback queue using ApplicationMusicPlayer.Queue.
// 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.
import MediaPlayerfunc updateNowPlaying(title: String, artist: String, duration: TimeInterval, elapsed: TimeInterval) {var info = [String: Any]()info[MPMediaItemPropertyTitle] = titleinfo[MPMediaItemPropertyArtist] = artistinfo[MPMediaItemPropertyPlaybackDuration] = durationinfo[MPNowPlayingInfoPropertyElapsedPlaybackTime] = elapsedinfo[MPNowPlayingInfoPropertyPlaybackRate] = 1.0info[MPNowPlayingInfoPropertyMediaType] = MPNowPlayingInfoMediaType.audio.rawValueMPNowPlayingInfoCenter.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] = artworkMPNowPlayingInfoCenter.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 { _ inresumePlayback()return .success}center.pauseCommand.addTarget { _ inpausePlayback()return .success}center.nextTrackCommand.addTarget { _ inskipToNext()return .success}center.previousTrackCommand.addTarget { _ inskipToPrevious()return .success}// Disable commands you do not supportcenter.seekForwardCommand.isEnabled = falsecenter.seekBackwardCommand.isEnabled = false}
Scrubbing Support
func enableScrubbing() {let center = MPRemoteCommandCenter.shared()center.changePlaybackPositionCommand.addTarget { event inguard 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.
// WRONGfunc play(_ song: Song) async throws {player.queue = [song]try await player.play() // Fails if no subscription}// CORRECTfunc play(_ song: Song) async throws {let sub = try await MusicSubscription.currentguard 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 queuelet player = SystemMusicPlayer.shared// CORRECT: App-scoped playbacklet 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 forgetupdateNowPlaying(title: firstSong.title, ...)// CORRECT: Update on every track changefunc 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.
// WRONGcenter.skipForwardCommand.addTarget { _ in .commandFailed }// CORRECTcenter.skipForwardCommand.isEnabled = false
Review Checklist
- [ ] MusicKit App Service enabled for the app's explicit bundle ID
- [ ]
NSAppleMusicUsageDescriptionadded to Info.plist - [ ]
MusicAuthorization.request()called before any MusicKit access - [ ] Subscription checked before attempting catalog playback
- [ ]
canBecomeSubscriberchecked before presenting a subscription offer - [ ]
hasCloudLibraryEnabledchecked before library writes - [ ]
ApplicationMusicPlayerused (notSystemMusicPlayer) 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
.successfor 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