perf: lazy-load lyrics only when lyrics view is visible

- Remove eager lyrics prefetch on every track change to avoid unnecessary network calls
- Add ensureLyricsLoaded() method with lifecycle-aware guard (skip when app is paused/hidden)
- Trigger lyrics fetch from full-screen player only when visible and app is resumed
- Deduplicate prefetch calls using track key to prevent redundant requests

Author: zarzet

lib/providers/playback_provider.dart

@@ -1209,8 +1209,6 @@ class PlaybackController extends Notifier<PlaybackState> {
 
     if (!preserveQueue) {
       _clearLyricsForTrackChange(upcomingItem: resolvingItem);
-      // Start lyrics lookup immediately while stream URL is still resolving.
-      unawaited(_fetchLyricsForItem(resolvingItem));
     }
     state = state.copyWith(
       currentItem: resolvingItem,
@@ -1462,8 +1460,6 @@ class PlaybackController extends Notifier<PlaybackState> {
     );
 
     _clearLyricsForTrackChange(upcomingItem: item);
-    // Start lyrics lookup immediately while local source is preparing.
-    unawaited(_fetchLyricsForItem(item));
 
     // Replacing stream playback with local playback should also replace queue,
     // otherwise the old streaming queue remains visible in queue UI.
@@ -1761,8 +1757,6 @@ class PlaybackController extends Notifier<PlaybackState> {
       clearError: true,
     );
     await _savePlaybackSnapshot();
-    // Start lyrics lookup at track-change time, not after playback starts.
-    unawaited(_fetchLyricsForItem(item));
 
     // If the item has a Track but no resolved sourceUri, resolve stream
     if (item.sourceUri.isEmpty && item.track != null) {
@@ -1990,8 +1984,23 @@ class PlaybackController extends Notifier<PlaybackState> {
 
   /// Public method to manually refetch lyrics (e.g. retry button).
   Future<void> refetchLyrics() async {
+    await ensureLyricsLoaded(force: true);
+  }
+
+  /// Load lyrics only when needed (e.g. when lyrics page is visible).
+  Future<void> ensureLyricsLoaded({bool force = false}) async {
     final item = state.currentItem;
     if (item == null) return;
+    final lifecycleState = WidgetsBinding.instance.lifecycleState;
+    if (!force &&
+        lifecycleState != null &&
+        lifecycleState != AppLifecycleState.resumed) {
+      return;
+    }
+    if (!force) {
+      if (state.lyricsLoading) return;
+      if (state.lyrics != null) return;
+    }
     await _fetchLyricsForItem(item);
   }
 

lib/widgets/mini_player_bar.dart

@@ -201,19 +201,58 @@ class _FullScreenPlayerState extends ConsumerState<_FullScreenPlayer> {
   late final PageController _pageController;
   bool _isScrubbing = false;
   double _scrubSeconds = 0;
+  String? _lastLyricsPrefetchKey;
+  AppLifecycleListener? _appLifecycleListener;
+  bool _isAppResumed = true;
 
   @override
   void initState() {
     super.initState();
     _pageController = PageController();
+    final initialState = WidgetsBinding.instance.lifecycleState;
+    _isAppResumed =
+        initialState == null || initialState == AppLifecycleState.resumed;
+    _appLifecycleListener = AppLifecycleListener(
+      onResume: () {
+        _isAppResumed = true;
+        if (!mounted) return;
+        final state = ref.read(playbackProvider);
+        _prefetchLyricsForCurrentTrack(state);
+      },
+      onPause: () => _isAppResumed = false,
+      onHide: () => _isAppResumed = false,
+      onDetach: () => _isAppResumed = false,
+      onInactive: () => _isAppResumed = false,
+    );
   }
 
   @override
   void dispose() {
+    _appLifecycleListener?.dispose();
+    _appLifecycleListener = null;
     _pageController.dispose();
     super.dispose();
   }
 
+  String _lyricsPrefetchKey(PlaybackItem item) {
+    return '${item.id}|${item.title}|${item.artist}';
+  }
+
+  void _prefetchLyricsForCurrentTrack(PlaybackState state) {
+    if (!_isAppResumed) return;
+    final item = state.currentItem;
+    if (item == null) return;
+
+    final key = _lyricsPrefetchKey(item);
+    if (_lastLyricsPrefetchKey == key) return;
+    _lastLyricsPrefetchKey = key;
+
+    WidgetsBinding.instance.addPostFrameCallback((_) {
+      if (!mounted) return;
+      unawaited(ref.read(playbackProvider.notifier).ensureLyricsLoaded());
+    });
+  }
+
   void _switchToLyrics() {
     setState(() => _currentPage = 1);
     _pageController.animateToPage(
@@ -246,12 +285,14 @@ class _FullScreenPlayerState extends ConsumerState<_FullScreenPlayer> {
     final playbackError = _localizedPlaybackError(context, state);
     final item = state.currentItem;
     if (item == null) {
+      _lastLyricsPrefetchKey = null;
       // Track stopped, close the player
       WidgetsBinding.instance.addPostFrameCallback((_) {
         if (mounted) Navigator.of(context).pop();
       });
       return const SizedBox.shrink();
     }
+    _prefetchLyricsForCurrentTrack(state);
 
     final colorScheme = Theme.of(context).colorScheme;
     final textTheme = Theme.of(context).textTheme;