Apple Music and MusicKit

Apple Music and MusicKit

Streaming Apple Music inside Foldman needs Apple's MusicKit for Android SDK and a developer token, both from an Apple Developer Program membership. Without them, Foldman still builds; Apple Music then works by driving the Apple Music app.

Release APKs on the releases page are already built with both, so users don't need any of this.

1. Media ID

developer.apple.com → Certificates, Identifiers & Profiles → Identifiers → + → Media IDs.

• Description: anything, e.g. Foldman.
• Identifier: reverse-domain, e.g. media.dev.foldman.
• Tick MusicKit, then register.

2. Private key

Keys → +:

1. Name it (e.g. Foldman MusicKit) and tick Media Services (MusicKit, ShazamKit, Apple Music Feed).
2. Configure → choose the Media ID from step 1 → Save → Continue → Register.
3. Download the AuthKey_XXXXXXXXXX.p8. Apple offers it once; keep it safe and outside the repository.
4. Note the Key ID (shown on that page) and your Team ID (top right of the portal).

3. Developer token

cp apple-music.properties.example apple-music.properties

Fill in apple.teamId, apple.keyId, apple.mediaId and apple.keyPath (the path to the .p8). Then:

python3 tools/make_apple_token.py

This signs an ES256 JWT that lasts 180 days and writes it to apple-music.properties as apple.developerToken. The build bakes it into BuildConfig. The script needs only Python 3 and openssl, which ship with macOS. Run it again to renew the token; Apple's maximum lifetime is six months.

To test a token:

TOKEN=$(grep '^apple.developerToken=' apple-music.properties | cut -d= -f2-)
curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer $TOKEN" \
  "https://api.music.apple.com/v1/catalog/us/search?term=walkman&types=songs&limit=1"

200 means Apple accepts it.

4. The SDK

developer.apple.com → Downloads → More → Android MusicKit (Android-MusicKit-SDK-1.1.2.zip). From the zip, copy these into app/libs/:

• musickitauth-release-1.1.2.aar: sign-in, which unlocks playlist browsing.
• mediaplayback-release-1.1.1.aar: in-app streaming.

Rebuild. Foldman finds the SDK at runtime (by reflection), so no code changes are needed.

Files that must never be committed

*.p8, apple-music.properties, signing.properties, *.jks and app/libs/*.aar are all in .gitignore. The developer token is meant to ship inside the app; that's how Apple designed MusicKit tokens.

How Foldman uses the SDK

• Sign-in: AuthenticationManager opens Apple's screen through the Apple Music app and returns a Music User Token, which Foldman stores in its private settings.
• Browsing: the Apple Music API endpoints /v1/me/library/playlists and /v1/me/library/playlists/{id}/tracks, called with both tokens.
• Playback: MediaPlayerController in ApplePlayerService, which runs in its own :apple process and talks to the app over a Messenger. Songs are queued by catalog ID with CatalogPlaybackQueueItemProvider, with shuffle off.

Quirks of Apple's 2021 SDK, and Foldman's workarounds

Quirk	Workaround
Native code crashes under Android's tagged heap pointers	android:allowNativeHeapPointerTagging="false" in the manifest
Native code can still crash	The player lives in a separate process; Foldman restores the queue, song and position when it restarts
Sign-in callback activity lacks android:exported (it predates Android 12)	Declared exported="true" in Foldman's manifest
Native libraries aren't loaded automatically	System.loadLibrary("c++_shared") and ("appleMusicSDK") before creating the player
The sign-in theme extends AppCompat	androidx.appcompat dependency
Ships Android Studio's template ic_launcher_foreground	Foldman's icon layers are named foldman_icon_*
getQueueItems() lists only songs after the current one	Labels come from getCurrentItem(); the position from getPlaybackQueueIndex()
Sign-in can return USER_CANCELLED after Apple Music updates	User workaround: sign out of the Apple Music app and back in