danvics/soulsync
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
soulsync/revamp_plan.md
BoulderBadgeDad c3aea58b03 Player revamp Phase 2: smart radio ranking (play-count + popularity) 
Replaces radio's pure ORDER BY RANDOM() with weighted ranking. Each tier now
fetches a generous random POOL (4x the needed count, floored) and
core/radio/selection ranks it before the collector keeps the best:

  score_candidate = play_count(log-damped, w=1.0)
                  + lastfm_playcount(log-damped, w=0.5)
                  - recently_played penalty(w=2.0)
                  + stable per-id jitter(w=1.0, hash-derived so runs vary but
                    tests stay reproducible)

Modest weights so popularity guides without burying lesser-played tracks, and
jitter keeps radio from being identical every run. All intelligence is in pure
functions (rank_candidates / score_candidate) so it's tunable + unit-testable
without SQL.

Defensive: the DB method probes PRAGMA table_info(tracks) and omits
play_count/lastfm_playcount from the SELECT when absent (older DBs predating
the listening-history migration) — the scorer treats missing signals as 0, so
radio degrades to jitter-only instead of crashing on 'no such column'.

Tests (tests/radio/, 43 total):
  - score_candidate / rank_candidates: deterministic unit coverage (popularity
    ordering, lastfm contribution, recency penalty, garbage→0, stable jitter).
    These CANNOT pass against pre-Phase-2 code.
  - DB end-to-end: ranking surfaces the heavily-played track first out of a
    decoy pool (wiring proof — probabilistic vs old random, documented honestly);
    plus a no-rank-columns DB proving the defensive degrade path.
  - All Phase-0a behavioral/refactor-equivalence tests still green.
60 radio + adjacent-DB tests pass; ruff clean.
2026-05-30 08:47:18 -07:00

2.9 KiB
Raw Blame History

Stream / Player / Radio Revamp — Plan

Goal: bring the audio stream + media-player + radio system to Spotify/Apple-level polish and feature set. Target stack: plain JS (webui/static/media-player.js), not the React migration. Intended architecture direction: multi-listener (final call deferred to Phase 3; Phases 0–2 stay compatible either way).

Rule for every phase: kettui standard — importable/testable logic, seam-level + differential tests, break nothing, ship one reviewable phase at a time.

Phase 0 — Make it provable (foundation, no user-visible change)

  • 0a. Extract radio selection logic into testable core/radio/. DONE (commit cbc001e2). core/radio/selection.py owns parse_tags/merge_tags/same_artist_cap/build_like_conditions/RadioCollector; DB method delegates. 29 tests, refactor-equivalence proven (behavioral tests pass against old AND new).
  • 0b. Centralize frontend player state. ~10 scattered np* globals in media-player.js → one PlayerState object. Seam for every later frontend phase. No behavior change.

Phase 1 — Polish / feel (frontend)

  • Persistent queue across refresh (localStorage first; server-side in P3)
  • Drag-to-reorder queue; duration + art per queue item
  • Seek tooltip (hover timestamp); smoother progress
  • Crossfade via dual-<audio> swap (honest approximation of gapless — true gapless impossible w/ single element)
  • Full Media Session API (lockscreen / hardware transport keys)
  • Keyboard shortcut overlay + fuller bindings

Phase 2 — Smart radio (backend algorithm)

  • Weighted ranking DONE. Each tier now fetches a random POOL (4x, floored) and core/radio/selection.rank_candidates orders it by score_candidate: play_count + lastfm_playcount (log-damped), recently-played penalty, stable per-id jitter for run variety. Defensive column-probe → still works on a DB predating the play_count/lastfm migration. 43 radio tests; ranking math is deterministic-unit-proven; DB wiring shown via decoy-pool test (probabilistic by nature — documented).
  • Future (optional deepening): wire _recently_played from listening_history (column + scorer support already exist; not yet populated in the query), genre-adjacency graph (currently exact-genre LIKE only).

Phase 3 — Architecture (deepest, riskiest — listener decision lands here)

  • Per-session (or multi-tenant) stream state — replaces the single global stream_state + 1-worker executor + single Stream/ staging file (web_server.py:747).
  • Server-side persistent queue (resume across devices/refresh).
  • Final multi-listener vs single-listener scope decided here, with real usage in hand.

Order of execution

0a (radio extraction) → 2 (smart radio) first: highest visible upgrade, backend-only, cleanest to prove, zero playback risk. Then 0b → 1 (polish). Then 3 (architecture) last.