Skip to content

Apple catalog surface: search, quality tiers, lyrics formats, cover art #6

Closed
Closed
Apple catalog surface: search, quality tiers, lyrics formats, cover art#6
Assignees
ranokay
Labels
wayfinder:researchWayfinder research ticket

Description

@ranokay
ranokay
opened on Sep 1, 2026

Question

What does the Apple Music catalog actually expose, independent of engine choice? Verify against primary sources (Apple's API docs, the candidate engines' source code — how they call Apple endpoints). Report:

  • Search: can the Apple Music API be searched programmatically (terms, kinds: song/album/artist/playlist)? What auth does search need vs what fetching needs?
  • Per-track quality metadata: how a client knows a track has ALAC 24/192, AAC 256, or Dolby Atmos — the exact flags/fields.
  • Lyrics: what formats Apple serves (plain, timed line, word/syllable TTML), and per-track availability.
  • Cover art: maximum resolution obtainable and how the URL/template works.
  • ISRC / identifiers: what cross-provider matching (future ISRC dedupe) could key on.
  • Which candidate engine (gamdl / zhaarey / AppleMusicDecrypt) exposes or could expose each of these.

This ticket feeds the chooser UX, lyrics/art policy, and engine choice.

Activity

  1. ranokay
    added
    wayfinder:researchWayfinder research ticket
    on Sep 1, 2026
  2. ranokay
    added a parent issue on Sep 1, 2026
  3. ranokay
    marked this as blocking 3 issues on Sep 1, 2026
  4. ranokay
    self-assigned this
    on Sep 1, 2026

  5. ranokay commented on Sep 1, 2026

    @ranokay
    ranokay
    on Sep 1, 2026
    OwnerAuthor

    Research complete — findings in docs/research/apple-catalog-surface.md on branch research/apple-catalog-surface (commit 078dad0).

    Summary (verified against Apple docs + all three engines' source):

    1. Search: yes, documented — GET /v1/catalog/{sf}/search?term=&types= (songs/albums/artists/playlists/music-videos). Dev token only; Music-User-Token just for /v1/me/.... All engines scrape the web player's dev token; gamdl + zhaarey expose search, AppleMusicDecrypt doesn't.
    2. Quality: two layers. Catalog audioVariants gives tier presence (lossy-stereo/lossless/hi-res-lossless/dolby-atmos/dolby-audio). Exact 24/192 vs 24/96 and Atmos/AAC bitrates are ONLY in the enhanced-HLS master playlist (extendedAssetUrls.enhancedHls, undocumented): audio-alac-stereo-192000-24, audio-atmos-2768, audio-stereo-256. Chooser needs one extra m3u8 GET for exact tier.
    3. Lyrics: TTML only on the wire, three timing modes (itunes:timing None/Line/Word), translations+transliterations embedded; availability via documented hasLyrics + undocumented hasTimeSyncedLyrics; word-level via syllable-lyrics sub-resource; wants media-user-token.
    4. Cover art: documented {w}x{h}bb.jpg template with native max in width/height; original master via undocumented URL rewrite (gamdl + zhaarey implement); animated artwork via editorialVideo.
    5. ISRC: documented Song attribute plus a documented batch lookup endpoint (filter[isrc], 25 max) — the natural TIDAL↔Apple dedupe key; albums expose upc.
    6. Exposure: gamdl = broadest library surface (incl. search); zhaarey = richest lyrics (word-level enhanced LRC) + original art; AppleMusicDecrypt = richest per-variant quality probe but no search/art-original. Details table in the file.

    Closes the research question feeding #8/#10/#13.

  6. ranokay
    closed this as completedon Sep 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

wayfinder:researchWayfinder research ticket

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions