WWDC26：MusicKit app 整合工作流

// 一句話結論

MusicKit 的實作重點不是「能不能播放音樂」，而是把授權、訂閱可用性、選歌 UI、播放狀態與地區差異整理成一條可測的產品流程。

Apple Developer · WWDC26 · Video ID: 2rwWEy2USw8Apple Developer 官方頁

Content map

這支影片其實在拆四個 MusicKit 整合問題

授權入口

先處理 developer token 與使用者同意

MusicKit request 需要 developer token；app 也要用 MusicAuthorization.request() 取得音樂內容存取權，並在 Media Library capability 中寫清楚使用理由。

訂閱狀態

Apple Music 訂閱會決定 catalog 能力

未訂閱使用者仍可使用 MusicKit，但可存取內容主要限於已購買或同步的音樂。若要播放 Apple Music catalog，需要檢查 subscription status，並視情況呈現 subscription offer。

選歌體驗

Music Picker 把 catalog 與 library 合成一個 UI

新的選歌流程不必自己重做搜尋與 library picker。.musicPicker 可支援單選、多選，並讓使用者從 Apple Music catalog 或個人 library 挑 song、album、playlist。

播放控制

SystemMusicPlayer 與 ApplicationMusicPlayer 是產品決策

前者控制系統 Music app，背景行為自然延續；後者在 app 內播放，queue 可完整讀寫，但要自行處理背景音訊 capability、狀態觀察與 UI。

Implementation flow

導入 MusicKit 的實作順序

啟用 MusicKit 與 Media Library capability

在 Apple Developer portal 的 App Services 勾選 MusicKit，確認 Xcode 登入同一 developer account；再加入 Media Library capability，提供權限提示文案。

請求授權並觀察訂閱狀態

用 asynchronous authorization request 取得權限。授權後讀取 current subscription status，並監聽更新，避免 UI 只反映啟動當下的狀態。

用 Music Picker 取得使用者想聽的內容

把選取狀態設成單一 song 或 array，就能切換單選與多選。未訂閱者的 picker 會偏向個人 library；訂閱者可同時瀏覽 catalog。

選擇播放器並建 queue

SystemMusicPlayer 適合延續系統 Music app；ApplicationMusicPlayer 適合 app 內深度控制。若已知要播放什麼，先呼叫 prepareToPlay() 降低 play 後等待。

用 catalog requests 做 curated shelf

用 MusicCatalogResourceRequest 取歌單、歌曲或推薦內容，並處理 pagination、region/storefront、explicit/clean 版本與 unavailable resource。

重點 1：授權、訂閱與權限文案是同一個 onboarding 問題

影片先從 project setup 開始，而不是直接呼叫播放 API。原因是 MusicKit 的可用性同時受到 developer token、使用者授權、Media Library capability 文案與 Apple Music subscription status 影響。這些狀態如果分散處理，使用者會遇到「按了選歌但看不到 catalog」、「能選但不能播」或「不知道為什麼要授權」的斷裂體驗。

Apple 明確提到 Apple Music subscription 不是使用 MusicKit 的必要條件；但沒有訂閱時，app 通常只能存取使用者已購買或同步的音樂。產品文案要把「library access」與「catalog playback」分開說清楚。

Developer token 自動生成在 App ID 的 App Services 裡啟用 MusicKit，並確認 Xcode 使用同一 developer account，才讓 MusicKit requests 能順利工作。

權限提示要具體Media Library capability 的描述會出現在 permission alert，應說明 app 為什麼需要讀取音樂內容，而不是只寫泛用句。

Subscription offer 是條件 UI.musicSubscriptionOffer 可在 app 內提供訂閱入口；是否顯示要根據 subscription status 與使用者是否可能訂閱判斷。

狀態要持續觀察授權或訂閱可能在 app 外改變，應用 async task 或更新 stream 同步 UI，不要只在首次啟動檢查一次。

重點 2：Music item 模型讓選歌與 catalog request 有共同語言

MusicKit 的 Song、Album、Playlist、Station、Genre 都是 music item。每種 item 有 attributes、relationships 與 associations。這讓 Music Picker 選出的內容、播放器 queue、以及 catalog request 回傳的內容可以共用同一套型別語言。

Attributes 是本體資訊

例如 album title、content rating、song title，可直接用來呈現 UI。

Relationships 是強關聯

例如 album tracks，適合在 request 中明確要求一起 fulfill。

Associations 是較弱關聯

例如 otherVersions，適合做探索、替代版本或跨 storefront fallback。

重點 3：播放器選擇會影響背景行為、queue 控制與聆聽紀錄

SystemMusicPlayer 控制系統 Music app，只能設定 queue，無法完整讀取 queue 內容；但因為是系統 Music app，app background 或 quit 後仍可繼續播放。ApplicationMusicPlayer 則在你的 app 內播放，queue 可完整讀寫，也能直接觀察 playback state 與 queue，但若要背景播放，需要啟用 Audio Background Mode。

影片也提醒 affectsListeningHistory 預設為 true，但仍尊重使用者在 Music app 的 Use Listening History 設定。若你的 app 是冥想、睡眠、兒童或工作場景，是否寫入 Recently Played 是產品與隱私體驗的一部分。

風險與遷移注意事項

不要把 catalog ID 當全球穩定 ID同一首歌在不同 storefront 可能有不同 ID，explicit content 也可能被 clean version 取代。catalog request 要開啟 equivalency 並處理缺項。

Picker 不等於播放授權使用者能選到內容，不代表每個狀態都能立即播放。仍要檢查訂閱、library 可用性與 region 限制。

先 prepare 再 playqueue 載入與 audio assets 載入需要時間。若 workout 或遊戲場景需要立即播放，應先 prepareToPlay()。

背景播放能力要明確測ApplicationMusicPlayer 的背景行為取決於 Audio Background Mode；不要用 SystemMusicPlayer 的行為推測 app 內播放器。

章節索引

Chapters