soulsync/PLAN-download-quality-flags.md

Plan: Download Quality Flags Refactor

Background

The current force_download_all flag is misleadingly named. It does NOT lower quality requirements or "force download any quality". It only skips the library ownership check so every track is treated as missing and re-downloaded regardless of whether the user already owns it.

This causes two distinct problems:

1. The name implies quality-related behavior that doesn't exist.
2. The discover sync tab currently sends force_download_all: true, which means every discover playlist sync re-downloads tracks the user already owns.

Additionally, users have expressed a real need for a per-batch quality override: their main library should stay strict (FLAC preferred, high bitrate) while rotating/ephemeral playlists (discover) should grab whatever is available for quantity over quality.

Per-client fallback settings already exist (Soulseek quality profile fallback_enabled, Deezer/Tidal/Qobuz allow_fallback chains) but they are global all-or-nothing flags. There is no way today to say "relax quality just for this one batch".

Goals

1. Rename force_download_all to reflect what it actually does (skip ownership check / re-download owned).
2. Stop discover sync from blindly re-downloading owned tracks.
3. Add a new per-batch "Any Quality" flag that bypasses quality filtering for that specific batch only, without touching the user's global quality settings.

Non-Goals

• No changes to the global per-client quality/fallback settings.
• No changes to the matching engine scoring.
• No changes to album consistency / MusicBrainz preflight logic.

Phase 0 (this PR): UI framework only

Scope is tiny and safe to ship immediately.

• Replace the "Force DL" toggle in the Sync page Discover tab with an "Any Quality" toggle.
• Leave the new toggle permanently disabled / greyed out for now.
• Tooltip on the toggle reads something like "Coming soon: download any available quality for this batch".
• Remove the force_download_all: true body payload from the discover sync path. Discover playlists will now always run ownership analysis.
• No backend changes in this phase.

Files touched:

• webui/static/discover.js - replace toggle HTML, remove forceDownload plumbing from syncDiscoverPlaylistFromTab / _doSyncDiscoverPlaylist.

Phase 1: Rename force_download_all

Rename to skip_ownership_check (backend) and surface in the UI as "Re-download Owned" (or equivalent).

• Backend: add new key skip_ownership_check everywhere the flag is used. Accept both keys on inbound API payloads for one release (back-compat).
• Frontend: rename the Wishlist / Downloads modal toggles, keep the same default behavior (wishlists still skip the library check by default).
• Update helper.js tooltip description to match the new name and behavior.

Files touched:

• web_server.py (lines ~15663, 24858, 25858, 26065, 29051, 29057, 29062, 29104, 29135, 33556, 33596)
• webui/static/downloads.js (lines ~195, 598, 2152, 2155, 2195, 2436)
• webui/static/wishlist-tools.js (line ~6347)
• webui/static/helper.js (lines ~663)

Phase 2: Implement "Any Quality" per-batch override

Introduce a new batch flag any_quality that, when set, bypasses quality filtering for that batch only.

Backend behavior:

• Add any_quality to the batch dict alongside skip_ownership_check.
• For Soulseek: when any_quality is true, skip the call to soulseek_client.filter_results_by_quality_preference() and pass ranked candidates through unchanged.
• For Deezer / Tidal / Qobuz: when any_quality is true, temporarily force the candidate selection path to treat allow_fallback=True AND start from the lowest quality tier so downloads succeed fastest.
• The flag is per-batch only. Global quality profile / allow_fallback settings remain untouched.

Frontend behavior:

• Enable the "Any Quality" toggle added in Phase 0.
• Remove the "Coming soon" tooltip, replace with a real description.
• Wire the toggle into the discover sync POST body as any_quality: true.
• Consider exposing the same toggle on the Wishlist / Downloads modal.

Files touched:

• web_server.py - batch creation + candidate selection path
• core/soulseek_client.py - accept override in filter call
• core/deezer_download_client.py, core/tidal_download_client.py, core/qobuz_client.py - accept per-request quality override
• webui/static/discover.js - enable toggle, send flag
• webui/static/downloads.js - add matching toggle on manual download modals

Risks / Open Questions

• Soulseek quality profile bypass: is it safe to pass all density-filtered candidates through without the priority filter? Likely yes, since the matching engine already ranks by confidence and peer quality.
• Streaming clients with strict API quality params (Tidal HiRes vs Lossless entitlement, Qobuz subscription tiers): forcing lowest tier should be safe for all users regardless of subscription.
• Back-compat on the renamed flag: keep the old force_download_all key accepted for at least one release cycle to avoid breaking any third-party callers or stale browser sessions.

Rollout

• Phase 0 ships with this PR (UI framework + discover fix).
• Phase 1 and Phase 2 can ship as separate PRs on dev.
• No migrations required; all flags are request-scoped and batch-scoped.