# Enabling the Full Apple Music Catalog ("Search Apple Music")

The "Search Apple Music" path in the menu uses Apple's **MusicKit** framework
to search the entire Apple Music catalog by song or artist. It's currently
disabled at runtime — searching produces a `.developerTokenRequestFailed`
error — because the app's bundle ID is not yet registered with MusicKit on
the Apple Developer side.

The in-app **"Pick from Library"** path works without any of this setup and
is the recommended path until the steps below are completed.

## Why it doesn't work yet

MusicKit's catalog API requires a developer token. On iOS 15+, the system
issues that token automatically — but only if:

1. The app target has the **MusicKit** entitlement enabled in Xcode.
2. The app's bundle identifier is registered with the **MusicKit** capability
   in the Apple Developer portal.
3. The provisioning profile in use was generated after MusicKit was enabled
   on that bundle ID.

If any of those is missing, MusicKit raises `.developerTokenRequestFailed`
and search returns nothing.

## Steps to enable

1. **Xcode → target → Signing & Capabilities**
   - Make sure your team is a **paid** Apple Developer Program team (free
     "Personal Team" accounts cannot enable MusicKit).
   - Click **+ Capability** → search for **MusicKit** → add it.

2. **Apple Developer portal**
   - Visit <https://developer.apple.com/account/resources/identifiers/list>.
   - Find the bundle identifier in use by the DashSmash target (e.g.
     `com.yourname.DashSmash`).
   - Click **Edit**.
   - Scroll to the **Capabilities** section, find **MusicKit**, and enable
     it. Save.

3. **Regenerate the provisioning profile**
   - Easiest path: in Xcode's Signing & Capabilities tab, toggle **Automatically
     manage signing** off and back on. Xcode will request a fresh
     provisioning profile that includes the MusicKit entitlement.
   - Or manually regenerate the profile under **Profiles** in the developer
     portal and re-download.

4. **Clean build and redeploy**
   - Delete the existing copy of DashSmash from the device (to clear any
     cached entitlements).
   - Product → Clean Build Folder.
   - Build & run.

## How to verify it worked

Open the **"Search Apple Music"** flow:
- The first time, iOS should show a system prompt asking for permission to
  access Apple Music. Tap Allow.
- The Xcode console should print:
  ```
  [DashSmash] MusicAuthorization result: authorized
  ```
- Typing a search query should print:
  ```
  [DashSmash] Apple Music search: <query>
  [DashSmash] Apple Music search returned N songs
  ```
- If you still see `developerTokenRequestFailed`, the entitlement is still
  not present on the provisioning profile in use. Double-check that the
  exact bundle ID Xcode is signing with matches the one you enabled MusicKit
  on, and that the profile was regenerated after enabling it.

## If you don't want to enable MusicKit

The **"Pick from Library"** menu option uses `MPMediaPickerController` /
`MPMusicPlayerController`, which work without MusicKit, without a developer
token, and on free Apple Developer accounts. It can only see songs that are
in the device's Apple Music library (anything you've added or downloaded
via the Apple Music app), not the full catalog, but the gameplay and
tap-tempo flow are otherwise identical.