Skip to content

feat(Apple Music): Add catalog API provider for streaming-only releases - #252

Open
dwei30 wants to merge 6 commits into
kellnerd:mainfrom
dwei30:feat/apple-music-provider
Open

feat(Apple Music): Add catalog API provider for streaming-only releases#252
dwei30 wants to merge 6 commits into
kellnerd:mainfrom
dwei30:feat/apple-music-provider

Conversation

@dwei30

@dwei30 dwei30 commented Aug 16, 2026

Copy link
Copy Markdown

Summary

  • Adds a separate Apple Music provider that looks up music.apple.com albums via the catalog API (/v1/catalog/{storefront}/albums/{id}), including streaming-only releases that the iTunes Search API returns with no tracks (and often no GTIN from artwork URLs).
  • Prefers the official Apple Music API (api.music.apple.com) when HARMONY_APPLE_MUSIC_TOKEN is set. For self-hosted instances, unofficial AMP (amp-api.music.apple.com) is available via HARMONY_APPLE_MUSIC_AMP_TOKEN or HARMONY_APPLE_MUSIC_SCRAPE=true.
  • iTunes is unchanged (Search API only). Apple Music is registered only when one of those env vars is set, and only then does it claim music.apple.com URLs. itunes.apple.com stays on iTunes. Without credentials, Harmony behaves as today.

Auth (pick one; first match wins):

  1. HARMONY_APPLE_MUSIC_TOKEN — official developer JWT
  2. HARMONY_APPLE_MUSIC_AMP_TOKEN — unofficial AMP JWT
  3. HARMONY_APPLE_MUSIC_SCRAPE — scrape a MusicKit JWT from music.apple.com (self-hosted)

Needs testing with an official Apple Music API token as I don't have access to one.

.env

Copy from .env.example. You only need one of these; leave the others blank.

# 1. Official Apple Music API (preferred). MusicKit developer JWT.
HARMONY_APPLE_MUSIC_TOKEN=
# 2. Unofficial AMP JWT, used only if HARMONY_APPLE_MUSIC_TOKEN is unset.
HARMONY_APPLE_MUSIC_AMP_TOKEN=
# 3. Scrape a MusicKit JWT from music.apple.com when no token is set (self-hosted only).
# Set true or false.
HARMONY_APPLE_MUSIC_SCRAPE=

Local / self-hosted without an Apple Developer key:

HARMONY_APPLE_MUSIC_SCRAPE=true

Sources

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant