Skip to content

Provider seam: where TIDAL assumptions live in the Waves codebase #7

Closed
Closed
Provider seam: where TIDAL assumptions live in the Waves codebase#7
Assignees
ranokay
Labels
wayfinder:researchWayfinder research ticket

Description

@ranokay
ranokay
opened on Sep 1, 2026

Question

Internal codebase research (no code changes). Map every place Waves assumes a single TIDAL provider, so a Provider abstraction can be designed on facts. Go through:

  • waves/download.py, waves/matching.py, waves/metadata.py, waves/lyrics.py, waves/config.py, waves/ownership.py, waves/library_index.py, waves/worker.py, waves/model/
  • waves/waves_ui/backend.py (search, album/artist/playlist loading, queue rows, settings), waves/waves_ui/bridge_library.py
  • QML: Main.qml (search results, queue, download buttons), SettingsPage.qml

Deliverable: a seam inventory (file:line per touchpoint) grouped by: session/auth, catalog metadata shapes, search, quality tiers, download pipeline, lyrics, artwork, ownership/library detection, queue presentation, settings. Conclude with the minimum interface a second provider must implement and which parts of the current engine are reusable as-is vs TIDAL-specific.

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 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

    Provider seam analysis complete — full inventory in docs/research/provider-seam-analysis.md on branch research/provider-seam-analysis.

    Summary of findings:

    1. Minimum Provider interface: ~15 methods across auth (login_begin/complete/logout/apply_quality), catalog (search/open_url/get_object/collection_items/user_collections returning the app's existing plain dicts), quality (advertised_tier/ceiling), and per-track delivery (resolve_stream/fetch_lyrics/cover_url/track_facts).
    2. Reusable as-is: matching.py, library_index.py, mb_arbiter.py, lyrics.py (LRCLIB), ownership.py, metadata.py, the segment/file pipeline, ffmpeg post-processing, m3u writer, progress/gauge/worker infra — matching.py:8-18 and library_index.py:20 were deliberately built provider-agnostic.
    3. TIDAL-specific: config.py Tidal session singleton + Atmos swap, helper/tidal.py adapter layer, tidalapi.page browse, _get_stream_info/StreamManifest, refusal taxonomy, tier vocabulary.
    4. Biggest surprises: (a) metadata_write (download.py:3772) is the implicit provider fact schema — reads ~15 tidalapi attrs inline with no helper seam; (b) the dict boundary to QML is already provider-neutral, so UI work is nearly free; (c) three cross-cutting vocabularies (item ids incl. WAVES_TIDAL_ID on-disk tags, the QUALITY_RANK tier scale, MediaType) must be namespaced/shared or ownership breaks silently.
    5. Inventory tables cite file:line for every touchpoint across 11 groups: session/auth, catalog shapes, search, quality tiers, download pipeline, lyrics, artwork, ownership, queue, settings, browse.

    Ticket #7 can be closed; no other issues touched.

  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