feat(flutter): #415 stage 3 — play-events reporter + rotation wiring

The Flutter client previously reported NO plays — mobile listening
never reached play_events, so history, recommendation scoring,
ListenBrainz scrobbles, and #415 rotation all missed mobile entirely.
Operator chose to close that gap properly as part of Stage 3.

New:
- EventsApi (api/endpoints/events.dart): play_started/ended/skipped.
- PlayEventsReporter (player/play_events_reporter.dart): state
  machine over (track id, playing) mirroring the web dispatcher.
  Persists an opaque client_id in secure storage. Deliberate
  divergence from web: a track change inside a queue is classified
  ended-vs-skipped by whether the prior track reached ~its duration
  (3s tolerance), instead of web's blanket "track change = skip"
  which would mark every naturally-finished in-queue track a skip
  and dilute recommendation skip-ratios — the exact failure mode
  that motivated doing this properly. Fail-safe: no-ops when there's
  no audio handler (tests / no-audio env). App-lifecycle paused/
  detached closes an open row as a best-effort skip (web pagehide
  parity). Wired in app.dart postFrame.
- PlaylistsApi.systemShuffle(variant): GET the rotation-aware order.

Wiring:
- audio_handler: _queueSource carried through setQueueFromTracks
  (source param); preserved across internal skipToQueueItem rebuild.
- player_provider.playTracks: source param → setQueueFromTracks.
- PlaylistCard: system playlists fetch systemShuffle and play as-is
  tagged with source (no client shuffle — server already ordered).
- playlist_detail_screen: header Play + per-track tap tag source for
  system playlists so rotation advances from any entry point.

Known/flagged separately: the web dispatcher likely has the same
false-skip-on-advance issue; not fixed here to keep #415 scoped and
clients' wire behavior comparable.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-05-15 08:15:32 -04:00
parent 179519689b
commit 3054e8702b
8 changed files with 325 additions and 11 deletions
@@ -71,10 +71,13 @@ class PlayerActions {
List<TrackRef> tracks, {
int initialIndex = 0,
bool shuffle = false,
String? source,
}) async {
// shuffle=true means "play this pool randomly, starting at a
// random track." Used for system playlists so the first track of
// a re-play within the day is different from the prior one.
// random track" (client-side; used for non-system surfaces that
// want shuffle). System playlists instead fetch a server-ordered
// list and pass source — no client shuffle, the order is already
// rotation-aware (#415).
var startAt = initialIndex;
if (shuffle && tracks.length > 1) {
startAt = Random().nextInt(tracks.length);
@@ -91,7 +94,7 @@ class PlayerActions {
audioCacheManager: audioCache,
likeBridge: _buildLikeBridge(),
);
await h.setQueueFromTracks(tracks, initialIndex: startAt);
await h.setQueueFromTracks(tracks, initialIndex: startAt, source: source);
if (shuffle) {
await h.setShuffleMode(AudioServiceShuffleMode.all);
}