Config-first settings architecture for two providers #11

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 on Sep 1, 2026

   • Choose the Apple engine approach #8
4. ranokay

   marked this as blocking on Sep 1, 2026

   • 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

   Settings architecture: two-axis layout — per-provider sections for what differs, shared sections for what doesn't — with a one-migration carry-over that no existing user feels. Config-first throughout, per the map's standing preference.

   1. Grouping: a Providers area + unchanged shared sections

   • A new Providers area with a TIDAL section and an Apple section, each holding: enable/session state, the provider's quality default, and provider-specific runtime/pacing.
   • Cross-provider behavior stays in the existing sections, now explicitly governing both providers (help-text updates only): the lyrics/art toggles (per ticket Lyrics & album-art policy matrix #10), the path templates including the Dolby Atmos files template (per ticket Stereo + Atmos dual-download behavior #12 — tokens, live per-field example, and validation all inherited from the existing path-template UX), library, queue, diagnostics.
   • Per-provider duplication of shared toggles is rejected: Lyrics & album-art policy matrix #10 made the lyrics/art toggles shared on purpose, and doubled config surface would misstate that.

   2. Per-provider quality fields, one migration

   • quality_audio (a serialized tidalapi enum today) splits into tidal_quality_audio and apple_quality_audio, serialized as Waves tier strings (the Provider-seam's Waves-owned 4-rung enum) — completing the seam's quality decision at the storage layer.
   • One settings migration converts the existing quality_audio value into tidal_quality_audio; nobody's settings reset and no meaning changes.
   • quality_video keeps its name and section (video is a TIDAL-only capability; rename only if a second video provider ever appears). download_dolby_atmos keeps its name and its shared both-provider meaning (ticket Stereo + Atmos dual-download behavior #12).

   3. The Apple opt-in gate and setup wizard

   • An Apple Music section, always visible, behind an enable switch (default off) — the map's optional-component decision made concrete.
   • Turning it on starts the in-place setup wizard: managed runtime provisioning (wrapper-v2 image + N_m3u8DL-RE; download, checksum-verify, one click — the FFmpeg-manager pattern), Apple ID login + 2FA, and APK supply; the cookies-only tier lives in the same wizard as the graceful fallback for anyone who won't run the runtime (per the engine decision's two-tier setup).
   • A color-coded status light — not set up / runtime ready / signed in / needs attention — mirrors the existing FFmpeg status light.
   • The section also hosts Apple's pacing fields and runtime manage actions (update, remove).

   4. Pacing fields

   • TIDAL's api_rate_limit_* keep their names, meaning, and section verbatim.
   • Apple gains its own pacing fields in the Apple section (same shape: pause after N songs for N seconds; defaults tuned to the license-exchange 429 behavior). Their exact supervision semantics belong to Apple session supervision — it inherits a named place to live.

   Chooser defaults (fallout, not new decisions)

   The Chooser's defaults come from Settings exactly as CONTEXT.md says: per-provider quality (tidal_quality_audio / apple_quality_audio), the shared audio-type toggle (download_dolby_atmos, stereo/Atmos/both per ticket #12), and the shared lyrics/art toggles. Per-download chooser & provider-sectioned search UI inherits this whole answer.
7. ranokay

   closed this as completedon Sep 1, 2026