Choose the Apple engine approach #8

Activity

1. ranokay

   added

   wayfinder:grillingWayfinder grilling ticketWayfinder grilling ticket

   on Sep 1, 2026
2. ranokay

   added a parent issue on Sep 1, 2026

   • Wayfinder map: Apple Music as a second provider in Waves #1
3. ranokay

   marked this as blocked by 5 issues on Sep 1, 2026

   • Evaluate glomatico/gamdl as the Apple engine #2
   • Evaluate zhaarey/apple-music-downloader as the Apple engine #3
   • Evaluate WorldObservationLog wrapper & AppleMusicDecrypt as the Apple engine #4
   • Apple catalog surface: search, quality tiers, lyrics formats, cover art #6
   • ALAC corruption: what Waves must do to verify Apple downloads #5
4. ranokay

   marked this as blocking 4 issues on Sep 1, 2026

   • Design the Provider abstraction seam #9
   • Config-first settings architecture for two providers #11
   • Apple Music account + one-time decryption setup (human) #14
   • Write the decision-complete spec #15
5. ranokay

   self-assigned this

   on Sep 1, 2026
6. ranokay commented on Sep 1, 2026

   

   ranokay

   on Sep 1, 2026

   OwnerAuthor

   More actions

   Resolution

   Decision: Waves adopts glomatico/gamdl as the Apple Music engine — embedded as a Python library, with glomatico/wrapper-v2 backing the ALAC path.

   Grounded in the three engine evaluations (docs/research/gamdl-eval.md, worldobs-eval.md, zhaarey-eval.md) plus a 2026-09-01 platform fact-check of gamdl 3.8.5 source, wrapper-v2 README/build workflows/releases API, and N_m3u8DL-RE releases.

   The choice

   1. Engine: gamdl (MIT, v3.8.x), used via its published embedding API (AppleMusicApi + downloaders) — not vendored, not CLI-driven. Catalog search is built in (get_search_results) and needs only the auto-scraped dev token (no cookies, no user input): the Apple section of search works before any setup exists.
   2. ALAC path: wrapper-v2 (Unlicense). Docker-based Android-guest whose guest libs are arm64 — on Apple silicon the linux/arm64 image runs natively in a VM (no emulation). This is the deciding platform fact: the whole family's FairPlay bridges are Android guests, and the x86-64 guests (WorldObs wrapper-lite, zhaarey's wrapper) are where the M-series crash reports live (wrapper#61), against a settled "macOS Apple silicon first" order. Atmos needs no wrapper at all (web path since gamdl 3.8.0). wrapper-v2 publishes zero binaries (releases 0.0.1/0.0.2, source only) — Waves builds and pins its own artifacts.
   3. Download robustness: default to the N_m3u8DL-RE download mode (MIT; prebuilt binaries for macOS arm64/x64, Windows x64/arm64, Linux x64/arm64). gamdl's yt-dlp-mode corruption class (refactor(package): feature-based layout, descriptive test names, multi-provider fixes #344/refactor(ui): extract BackToTop, DotMatrix and SnakeField from Main.qml (#315) #328/refactor(ui): extract the SearchProviderGroup closure from Main.qml (#315 slice 6) #337) and Apple's own malformed-ALAC encoder bug (ticket ALAC corruption: what Waves must do to verify Apple downloads #5) both land in the engine-agnostic verify + retry + quarantine gate ticket ALAC corruption: what Waves must do to verify Apple downloads #5 already committed Waves to.
   4. Throttling: Waves adds license-exchange backoff/pacing of its own (gamdl has none, fix(ui): settings switches ignore AX press and the welcome's Not now has no accessible name #306).
   5. Fallback engine: WorldObservationLog wrapper@lite + AppleMusicDecrypt@v3 (MIT + AGPL-3.0). Kept viable by the Provider seam (ticket Design the Provider abstraction seam #9). Swap triggers: dev-token scraper breakage outpacing upstream releases, the wrapper/APK setup proving unacceptable in practice, or word-timed lyrics becoming a hard requirement (v3 has syllable TTML today).
   6. Ruled out: zhaarey/apple-music-downloader — no license (external CLI only, never vendored), wrapper Linux-x86_64-first against a macOS-first platform order, no releases; in-house thin client for v1 — FairPlay is only reachable through the Android-lib bridge every candidate wraps, and hi-res/TTML/original-art ride undocumented extensions; a hybrid two-engine v1 — double integration surface, no v1 gain.

   One-time setup (the ticket's second question): managed, degrading to two tiers

   • Design target: Waves provisions what it can, FFmpeg-manager style — wrapper runtime/image, N_m3u8DL-RE, checksum-verified, one click. The user does only what only they can: Apple ID login, 2FA, and supplying the Apple Music APK (whether the APK can be fetched automatically is left to the packaging ticket).
   • Graceful tier below it: a cookies-file export alone unlocks AAC 256 + Atmos with no runtime; ALAC unlocks when the managed wrapper step completes.
   • Session supervision detail (sidecar restart/cooldown UX, scraper-breakage messaging) is spun out as its own decision ticket, not decided here.

   Lyrics ruling

   Syllable-level (word-timed) lyrics is not a hard v1 requirement: line-level LRC/SRT/TTML satisfies the map's "all provided formats" note for v1; upstream PR glomatico/gamdl#345 is tracked. The final lyrics/art matrix belongs to ticket #10, which inherits the sourcing question (wait for #345 vs call the syllable-lyrics relationship directly through the embedded library).

   Tickets spun out of this decision

   • "ALAC verification & quarantine: user-facing UX and policy" (from the fog's verification-UX line)
   • "Apple session supervision: wrapper lifecycle & Apple-side failure recovery" (from the fog's supervision line, now engine-specific)

   Map fog updated accordingly.
7. ranokay

   closed this as completedon Sep 1, 2026