Musickit

作者 dpearson26998d90fd121a26无许可证1.1K 个星标收录于 2026年10月8日更新于 2026年10月8日仓库2个月前更新

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.

仅含说明Software Development

AI 生成的概览

指导 iOS 开发者使用 MusicKit 集成 Apple Music 搜索、订阅检查、播放和正在播放元数据。

功能: 该技能提供参考说明和 Swift 代码示例，用于通过 MusicKit 和 MediaPlayer 为 iOS 应用添加 Apple Music 功能。内容涵盖项目配置、授权、目录搜索、订阅检查、使用 ApplicationMusicPlayer 播放、队列管理、正在播放信息和远程命令处理。还包含常见错误表和审查清单。
适用场景: 在为 iOS 应用添加音乐搜索、Apple Music 订阅流程、队列管理、播放控制、远程命令处理或正在播放信息时使用。也适用于审查或调试现有的 MusicKit 集成。
运行要求: 需要一个 iOS 应用项目，并为该 bundle ID 启用 MusicKit App Service，在 Info.plist 中添加 NSAppleMusicUsageDescription，后台播放还需启用 audio 后台模式。使用 MusicKit 和 MediaPlayer 框架。不包含脚本，仅为说明文档。

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

来源与署名

来源：dpearson2699/swift-ios-skills位于skills/musickit提交8d90fd1

许可证：无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

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

来源与署名

更多来自 dpearson2699/swift-ios-skills 的技能

Widgetkit

Weatherkit

Vision Framework

Tipkit

Tabletopkit

Swiftui Webkit

更多Software Development技能

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices