bvandeusen/minstrel
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases 38 Wiki Activity

fix(player): align audio + UI on track change, prewarm covers + palette

Browse Source 
Four related fixes to the player flow that together remove the
audio↔UI lag on track change:

1. **Prefetcher pre-warms covers + palette for the next N tracks.**
   The existing prefetcher pinned audio files only. When auto-advance
   landed on the next track, the cover bytes were cold → mediaItem
   broadcast with artUri=null → now-playing screen stalled in
   _scheduleSwap awaiting precacheImage of a file that didn't exist
   yet. Each upcoming queue item now also fires
   AlbumCoverCache.getOrFetch (writes bytes to disk so _toMediaItem's
   peekCached returns the path) and AlbumColorCache.getOrExtract
   (memoizes the dominant color). Both fire-and-forget; idempotent
   if already cached.

2. **AlbumColorCache.peekColor sync getter** so the now-playing
   fast-path can read the memoized color without awaiting a Future.

3. **_scheduleSwap fast path** when cover bytes + palette are
   already cached (the common in-queue auto-advance case): commit
   _displayedMedia / _displayedDominant synchronously in setState
   without awaiting. The async preload remains as the slow-path
   fallback for genuine cold cache. This is what closes the gap
   the user reported: "art is loading and metadata hasn't updated
   but the new song is playing."

4. **setQueueFromTracks: build source before broadcasting queue /
   mediaItem.** Previously we broadcast immediately for snappy UI;
   if _buildAudioSource threw, the UI showed the new track while
   the player held the old source. Now: build first, broadcast
   only on success. Source build is sub-100ms on warm cache so the
   tap response cost is imperceptible. _suppressIndexUpdates is set
   around setAudioSources + broadcast so a transient currentIndex
   emission can't cross-broadcast the OLD queue's entry at the NEW
   index.

5. **playbackEventStream error handler skips past failing tracks.**
   Previously errors only logged. The player would go silent on a
   404 / decoder failure but mediaItem stayed on the failed track —
   user saw "now playing X" with no audio. Now seekToNext on error;
   if at queue tail, pause cleanly so PlaybackState reflects idle.
This commit is contained in:
Bryan Van Deusen
2026-05-14 16:42:19 -04:00
parent 67bacac84b
commit fb95a462fb
4 changed files with 156 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files
flutter_client/lib/player/audio_handler.dart
+75 -18
View File
@@ -15,11 +15,16 @@ class MinstrelAudioHandler extends BaseAudioHandler with QueueHandler, SeekHandl
_player.playbackEventStream.listen(
_broadcastState,
// ExoPlayer surfaces stream errors (404, premature EOS, decoder
// failure, network drop) here. Without an error sink, the
// player just goes quiet — exactly the "starts then stops"
// symptom we hit.
// failure, network drop) here. Logging alone leaves the UI
// claiming "now playing X" while audio is silent — the user-
// observable mismatch between visual and audio state. Skip
// forward so the queue advances past the failed track and
// mediaItem updates to whatever's actually playing. If the
// failure is at the queue tail, just_audio will go idle on its
// own and _broadcastState reflects that.
onError: (Object e, StackTrace st) {
debugPrint('audio_handler: playbackEventStream error: $e\n$st');
unawaited(_handlePlaybackError());
},
);
_player.currentIndexStream.listen(_onCurrentIndexChanged);
@@ -113,9 +118,6 @@ class MinstrelAudioHandler extends BaseAudioHandler with QueueHandler, SeekHandl
// check and stop calling player mutations — important so a stale
// fill doesn't append old-playlist tracks into the new queue.
final myGen = ++_queueGeneration;
// Reset suppress flag in case a prior backward-fill bailed on
// gen check before reaching its `finally`.
_suppressIndexUpdates = false;
_lastTracks = tracks;
// Pause the old source immediately so the previous track stops
@@ -127,25 +129,49 @@ class MinstrelAudioHandler extends BaseAudioHandler with QueueHandler, SeekHandl
await _player.pause();
}
// Populate the visible queue + current mediaItem immediately so
// the player UI reflects the user's tap before any source has
// been built. Source list at the just_audio layer fills in
// asynchronously below.
// Build MediaItems up front (pure — no side effects); we'll
// broadcast queue/mediaItem only AFTER setAudioSources resolves
// so the audio engine and the UI flip together. If the build
// throws, the UI stays on the previous track (correct: audio
// also stays on the previous track since setAudioSources never
// ran).
final items = tracks.map(_toMediaItem).toList();
queue.add(items);
mediaItem.add(items[clampedInitial]);
// Fast path: build only the initial source so the player can
// start. Remaining sources stream in via _fillRemainingSources()
// in the background — addAudioSource for next/auto-advance
// tracks, insertAudioSource for skipPrev tracks.
final initial = await _buildAudioSource(tracks[clampedInitial]);
// Build only the initial source for fast start. Remaining
// sources stream in via _fillRemainingSources() — addAudioSource
// for next/auto-advance tracks, insertAudioSource for skipPrev.
final AudioSource initial;
try {
initial = await _buildAudioSource(tracks[clampedInitial]);
} catch (e, st) {
// Source build failed (bad URL, missing baseUrl, etc.). Don't
// broadcast the new state — leaving queue/mediaItem on the
// previous track keeps UI in sync with what the player is
// actually doing (which is "still on the previous track,
// paused").
debugPrint('audio_handler: _buildAudioSource failed: $e\n$st');
return;
}
if (myGen != _queueGeneration) {
debugPrint('audio_handler: superseded before setAudioSources (gen=$myGen)');
return;
}
await _player.setAudioSources([initial], initialIndex: 0);
// Suppress _onCurrentIndexChanged side effects while the source
// list is being swapped — without this, a transient currentIndex
// emission during setAudioSources could broadcast the OLD queue's
// entry at the NEW index. Re-enabled after the broadcasts land.
_suppressIndexUpdates = true;
try {
await _player.setAudioSources([initial], initialIndex: 0);
// Broadcast in this order: queue first (so any consumer that
// reacts to mediaItem and reads queue.value sees the consistent
// pair), then mediaItem.
queue.add(items);
mediaItem.add(items[clampedInitial]);
} finally {
_suppressIndexUpdates = false;
}
unawaited(_loadArtForCurrentItem());
unawaited(_fillRemainingSources(tracks, clampedInitial, myGen));
@@ -365,6 +391,37 @@ class MinstrelAudioHandler extends BaseAudioHandler with QueueHandler, SeekHandl
await mgr.registerStreamCache(trackId, path, size);
}
/// Called when playbackEventStream emits an error. Skips past the
/// failing track so the UI and audio re-converge — without this,
/// _player goes silent on a 404 / decoder failure / EOS but
/// mediaItem stays on the failed track and the user sees a "now
/// playing" header for something that isn't.
///
/// If we're at the last track, seekToNext is a no-op; the state
/// drops to idle and _broadcastState reflects that.
Future<void> _handlePlaybackError() async {
final currentIdx = _player.currentIndex;
final queueLen = queue.value.length;
if (currentIdx == null || currentIdx + 1 >= queueLen) {
// Last track or no queue context — just pause; _broadcastState
// already reflects the idle/error processingState.
try {
await _player.pause();
} catch (_) {}
return;
}
try {
await _player.seekToNext();
} catch (_) {
// If seekToNext fails too (next source not built yet, etc.),
// there's nothing safe to do — pause and let the user recover
// manually.
try {
await _player.pause();
} catch (_) {}
}
}
void _onCurrentIndexChanged(int? idx) {
if (idx == null) return;
if (_suppressIndexUpdates) return;