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