feat: add auto-skip unavailable tracks option for queue playback

zarzet · zarzet · commit 54ae9836850c · 2026-02-21T19:27:09.000+07:00
- Add autoSkipUnavailableTracks setting (default: on) to skip to next queue item when stream resolution fails instead of stopping playback
- Extract _handleQueueItemPlaybackFailure to centralize resolve error handling and auto-skip logic
- Wrap prefetched stream re-resolve in try/catch to handle secondary failures gracefully
- Add settings toggle UI with localized strings for EN, ID, and all supported languages
diff --git a/lib/l10n/app_localizations.dart b/lib/l10n/app_localizations.dart
@@ -544,6 +544,24 @@ abstract class AppLocalizations {
   /// **'Try other services if download fails'**
   String get optionsAutoFallbackSubtitle;
 
+  /// Toggle to skip to the next queue track when current track stream resolution fails
+  ///
+  /// In en, this message translates to:
+  /// **'Auto Skip Unavailable Tracks'**
+  String get optionsAutoSkipUnavailableTracks;
+
+  /// Subtitle when auto skip on resolve failure is enabled
+  ///
+  /// In en, this message translates to:
+  /// **'Automatically skip to the next queue track when a stream cannot be resolved.'**
+  String get optionsAutoSkipUnavailableTracksSubtitleOn;
+
+  /// Subtitle when auto skip on resolve failure is disabled
+  ///
+  /// In en, this message translates to:
+  /// **'Stop on failed track resolution and show an error.'**
+  String get optionsAutoSkipUnavailableTracksSubtitleOff;
+
   /// Tap behavior mode for track lists
   ///
   /// In en, this message translates to:
diff --git a/lib/l10n/app_localizations_de.dart b/lib/l10n/app_localizations_de.dart
@@ -251,6 +251,17 @@ class AppLocalizationsDe extends AppLocalizations {
   String get optionsAutoFallbackSubtitle =>
       'Andere Dienste versuchen, wenn Download fehlschlägt';
 
+  @override
+  String get optionsAutoSkipUnavailableTracks => 'Auto Skip Unavailable Tracks';
+
+  @override
+  String get optionsAutoSkipUnavailableTracksSubtitleOn =>
+      'Automatically skip to the next queue track when a stream cannot be resolved.';
+
+  @override
+  String get optionsAutoSkipUnavailableTracksSubtitleOff =>
+      'Stop on failed track resolution and show an error.';
+
   @override
   String get optionsInteractionMode => 'Interaction Mode';
 
diff --git a/lib/l10n/app_localizations_en.dart b/lib/l10n/app_localizations_en.dart
@@ -248,6 +248,17 @@ class AppLocalizationsEn extends AppLocalizations {
   String get optionsAutoFallbackSubtitle =>
       'Try other services if download fails';
 
+  @override
+  String get optionsAutoSkipUnavailableTracks => 'Auto Skip Unavailable Tracks';
+
+  @override
+  String get optionsAutoSkipUnavailableTracksSubtitleOn =>
+      'Automatically skip to the next queue track when a stream cannot be resolved.';
+
+  @override
+  String get optionsAutoSkipUnavailableTracksSubtitleOff =>
+      'Stop on failed track resolution and show an error.';
+
   @override
   String get optionsInteractionMode => 'Interaction Mode';
 
diff --git a/lib/l10n/app_localizations_es.dart b/lib/l10n/app_localizations_es.dart
@@ -248,6 +248,17 @@ class AppLocalizationsEs extends AppLocalizations {
   String get optionsAutoFallbackSubtitle =>
       'Try other services if download fails';
 
+  @override
+  String get optionsAutoSkipUnavailableTracks => 'Auto Skip Unavailable Tracks';
+
+  @override
+  String get optionsAutoSkipUnavailableTracksSubtitleOn =>
+      'Automatically skip to the next queue track when a stream cannot be resolved.';
+
+  @override
+  String get optionsAutoSkipUnavailableTracksSubtitleOff =>
+      'Stop on failed track resolution and show an error.';
+
   @override
   String get optionsInteractionMode => 'Interaction Mode';
 
diff --git a/lib/l10n/app_localizations_fr.dart b/lib/l10n/app_localizations_fr.dart
@@ -253,6 +253,17 @@ class AppLocalizationsFr extends AppLocalizations {
   String get optionsAutoFallbackSubtitle =>
       'Essayez d\'autres services si le téléchargement échoue';
 
+  @override
+  String get optionsAutoSkipUnavailableTracks => 'Auto Skip Unavailable Tracks';
+
+  @override
+  String get optionsAutoSkipUnavailableTracksSubtitleOn =>
+      'Automatically skip to the next queue track when a stream cannot be resolved.';
+
+  @override
+  String get optionsAutoSkipUnavailableTracksSubtitleOff =>
+      'Stop on failed track resolution and show an error.';
+
   @override
   String get optionsInteractionMode => 'Interaction Mode';
 
diff --git a/lib/l10n/app_localizations_hi.dart b/lib/l10n/app_localizations_hi.dart
@@ -248,6 +248,17 @@ class AppLocalizationsHi extends AppLocalizations {
   String get optionsAutoFallbackSubtitle =>
       'Try other services if download fails';
 
+  @override
+  String get optionsAutoSkipUnavailableTracks => 'Auto Skip Unavailable Tracks';
+
+  @override
+  String get optionsAutoSkipUnavailableTracksSubtitleOn =>
+      'Automatically skip to the next queue track when a stream cannot be resolved.';
+
+  @override
+  String get optionsAutoSkipUnavailableTracksSubtitleOff =>
+      'Stop on failed track resolution and show an error.';
+
   @override
   String get optionsInteractionMode => 'Interaction Mode';
 
diff --git a/lib/l10n/app_localizations_id.dart b/lib/l10n/app_localizations_id.dart
@@ -251,6 +251,18 @@ class AppLocalizationsId extends AppLocalizations {
   String get optionsAutoFallbackSubtitle =>
       'Coba layanan lain jika unduhan gagal';
 
+  @override
+  String get optionsAutoSkipUnavailableTracks =>
+      'Lewati Otomatis Lagu yang Tidak Tersedia';
+
+  @override
+  String get optionsAutoSkipUnavailableTracksSubtitleOn =>
+      'Otomatis lanjut ke lagu berikutnya di antrean jika stream lagu tidak bisa ditemukan.';
+
+  @override
+  String get optionsAutoSkipUnavailableTracksSubtitleOff =>
+      'Berhenti di lagu yang gagal dan tampilkan pesan error.';
+
   @override
   String get optionsInteractionMode => 'Mode Interaksi';
 
diff --git a/lib/l10n/app_localizations_ja.dart b/lib/l10n/app_localizations_ja.dart
@@ -248,6 +248,17 @@ class AppLocalizationsJa extends AppLocalizations {
   String get optionsAutoFallbackSubtitle =>
       'Try other services if download fails';
 
+  @override
+  String get optionsAutoSkipUnavailableTracks => 'Auto Skip Unavailable Tracks';
+
+  @override
+  String get optionsAutoSkipUnavailableTracksSubtitleOn =>
+      'Automatically skip to the next queue track when a stream cannot be resolved.';
+
+  @override
+  String get optionsAutoSkipUnavailableTracksSubtitleOff =>
+      'Stop on failed track resolution and show an error.';
+
   @override
   String get optionsInteractionMode => 'Interaction Mode';
 
diff --git a/lib/l10n/app_localizations_ko.dart b/lib/l10n/app_localizations_ko.dart
@@ -247,6 +247,17 @@ class AppLocalizationsKo extends AppLocalizations {
   @override
   String get optionsAutoFallbackSubtitle => '다운로드가 실패한 경우, 다른 서비스로 재시도';
 
+  @override
+  String get optionsAutoSkipUnavailableTracks => 'Auto Skip Unavailable Tracks';
+
+  @override
+  String get optionsAutoSkipUnavailableTracksSubtitleOn =>
+      'Automatically skip to the next queue track when a stream cannot be resolved.';
+
+  @override
+  String get optionsAutoSkipUnavailableTracksSubtitleOff =>
+      'Stop on failed track resolution and show an error.';
+
   @override
   String get optionsInteractionMode => 'Interaction Mode';
 
diff --git a/lib/l10n/app_localizations_nl.dart b/lib/l10n/app_localizations_nl.dart
@@ -248,6 +248,17 @@ class AppLocalizationsNl extends AppLocalizations {
   String get optionsAutoFallbackSubtitle =>
       'Try other services if download fails';
 
+  @override
+  String get optionsAutoSkipUnavailableTracks => 'Auto Skip Unavailable Tracks';
+
+  @override
+  String get optionsAutoSkipUnavailableTracksSubtitleOn =>
+      'Automatically skip to the next queue track when a stream cannot be resolved.';
+
+  @override
+  String get optionsAutoSkipUnavailableTracksSubtitleOff =>
+      'Stop on failed track resolution and show an error.';
+
   @override
   String get optionsInteractionMode => 'Interaction Mode';
 
diff --git a/lib/l10n/app_localizations_pt.dart b/lib/l10n/app_localizations_pt.dart
@@ -248,6 +248,17 @@ class AppLocalizationsPt extends AppLocalizations {
   String get optionsAutoFallbackSubtitle =>
       'Try other services if download fails';
 
+  @override
+  String get optionsAutoSkipUnavailableTracks => 'Auto Skip Unavailable Tracks';
+
+  @override
+  String get optionsAutoSkipUnavailableTracksSubtitleOn =>
+      'Automatically skip to the next queue track when a stream cannot be resolved.';
+
+  @override
+  String get optionsAutoSkipUnavailableTracksSubtitleOff =>
+      'Stop on failed track resolution and show an error.';
+
   @override
   String get optionsInteractionMode => 'Interaction Mode';
 
diff --git a/lib/l10n/app_localizations_ru.dart b/lib/l10n/app_localizations_ru.dart
@@ -255,6 +255,17 @@ class AppLocalizationsRu extends AppLocalizations {
   String get optionsAutoFallbackSubtitle =>
       'Попробовать другие сервисы при сбое загрузки';
 
+  @override
+  String get optionsAutoSkipUnavailableTracks => 'Auto Skip Unavailable Tracks';
+
+  @override
+  String get optionsAutoSkipUnavailableTracksSubtitleOn =>
+      'Automatically skip to the next queue track when a stream cannot be resolved.';
+
+  @override
+  String get optionsAutoSkipUnavailableTracksSubtitleOff =>
+      'Stop on failed track resolution and show an error.';
+
   @override
   String get optionsInteractionMode => 'Interaction Mode';
 
diff --git a/lib/l10n/app_localizations_tr.dart b/lib/l10n/app_localizations_tr.dart
@@ -252,6 +252,17 @@ class AppLocalizationsTr extends AppLocalizations {
   String get optionsAutoFallbackSubtitle =>
       'İndirme başarısız olursa diğer hizmetleri dene';
 
+  @override
+  String get optionsAutoSkipUnavailableTracks => 'Auto Skip Unavailable Tracks';
+
+  @override
+  String get optionsAutoSkipUnavailableTracksSubtitleOn =>
+      'Automatically skip to the next queue track when a stream cannot be resolved.';
+
+  @override
+  String get optionsAutoSkipUnavailableTracksSubtitleOff =>
+      'Stop on failed track resolution and show an error.';
+
   @override
   String get optionsInteractionMode => 'Interaction Mode';
 
diff --git a/lib/l10n/app_localizations_zh.dart b/lib/l10n/app_localizations_zh.dart
@@ -248,6 +248,17 @@ class AppLocalizationsZh extends AppLocalizations {
   String get optionsAutoFallbackSubtitle =>
       'Try other services if download fails';
 
+  @override
+  String get optionsAutoSkipUnavailableTracks => 'Auto Skip Unavailable Tracks';
+
+  @override
+  String get optionsAutoSkipUnavailableTracksSubtitleOn =>
+      'Automatically skip to the next queue track when a stream cannot be resolved.';
+
+  @override
+  String get optionsAutoSkipUnavailableTracksSubtitleOff =>
+      'Stop on failed track resolution and show an error.';
+
   @override
   String get optionsInteractionMode => 'Interaction Mode';
 
diff --git a/lib/l10n/arb/app_en.arb b/lib/l10n/arb/app_en.arb
@@ -175,6 +175,12 @@
   "@optionsAutoFallback": {"description": "Auto-retry with other services"},
   "optionsAutoFallbackSubtitle": "Try other services if download fails",
   "@optionsAutoFallbackSubtitle": {"description": "Subtitle for auto fallback"},
+  "optionsAutoSkipUnavailableTracks": "Auto Skip Unavailable Tracks",
+  "@optionsAutoSkipUnavailableTracks": {"description": "Toggle to skip to the next queue track when current track stream resolution fails"},
+  "optionsAutoSkipUnavailableTracksSubtitleOn": "Automatically skip to the next queue track when a stream cannot be resolved.",
+  "@optionsAutoSkipUnavailableTracksSubtitleOn": {"description": "Subtitle when auto skip on resolve failure is enabled"},
+  "optionsAutoSkipUnavailableTracksSubtitleOff": "Stop on failed track resolution and show an error.",
+  "@optionsAutoSkipUnavailableTracksSubtitleOff": {"description": "Subtitle when auto skip on resolve failure is disabled"},
   "optionsInteractionMode": "Interaction Mode",
   "@optionsInteractionMode": {"description": "Tap behavior mode for track lists"},
   "modeDownloader": "Downloader Mode",
diff --git a/lib/l10n/arb/app_id.arb b/lib/l10n/arb/app_id.arb
@@ -308,6 +308,18 @@
   "@optionsAutoFallbackSubtitle": {
     "description": "Subtitle for auto fallback"
   },
+  "optionsAutoSkipUnavailableTracks": "Lewati Otomatis Lagu yang Tidak Tersedia",
+  "@optionsAutoSkipUnavailableTracks": {
+    "description": "Toggle to skip to the next queue track when current track stream resolution fails"
+  },
+  "optionsAutoSkipUnavailableTracksSubtitleOn": "Otomatis lanjut ke lagu berikutnya di antrean jika stream lagu tidak bisa ditemukan.",
+  "@optionsAutoSkipUnavailableTracksSubtitleOn": {
+    "description": "Subtitle when auto skip on resolve failure is enabled"
+  },
+  "optionsAutoSkipUnavailableTracksSubtitleOff": "Berhenti di lagu yang gagal dan tampilkan pesan error.",
+  "@optionsAutoSkipUnavailableTracksSubtitleOff": {
+    "description": "Subtitle when auto skip on resolve failure is disabled"
+  },
   "optionsInteractionMode": "Mode Interaksi",
   "@optionsInteractionMode": {
     "description": "Tap behavior mode for track lists"
diff --git a/lib/models/settings.dart b/lib/models/settings.dart
@@ -12,6 +12,7 @@ class AppSettings {
   final String storageMode; // 'app' or 'saf'
   final String downloadTreeUri; // SAF persistable tree URI
   final bool autoFallback;
+  final bool autoSkipUnavailableTracks;
   final bool smartQueueEnabled; // Enable smart curated autoplay queue
   final bool embedLyrics;
   final bool maxQualityCover;
@@ -87,6 +88,7 @@ class AppSettings {
     this.storageMode = 'app',
     this.downloadTreeUri = '',
     this.autoFallback = true,
+    this.autoSkipUnavailableTracks = true,
     this.smartQueueEnabled = true,
     this.embedLyrics = true,
     this.maxQualityCover = true,
@@ -151,6 +153,7 @@ class AppSettings {
     String? storageMode,
     String? downloadTreeUri,
     bool? autoFallback,
+    bool? autoSkipUnavailableTracks,
     bool? smartQueueEnabled,
     bool? embedLyrics,
     bool? maxQualityCover,
@@ -209,6 +212,8 @@ class AppSettings {
       storageMode: storageMode ?? this.storageMode,
       downloadTreeUri: downloadTreeUri ?? this.downloadTreeUri,
       autoFallback: autoFallback ?? this.autoFallback,
+      autoSkipUnavailableTracks:
+          autoSkipUnavailableTracks ?? this.autoSkipUnavailableTracks,
       smartQueueEnabled: smartQueueEnabled ?? this.smartQueueEnabled,
       embedLyrics: embedLyrics ?? this.embedLyrics,
       maxQualityCover: maxQualityCover ?? this.maxQualityCover,
diff --git a/lib/models/settings.g.dart b/lib/models/settings.g.dart
diff --git a/lib/providers/playback_provider.dart b/lib/providers/playback_provider.dart
diff --git a/lib/providers/settings_provider.dart b/lib/providers/settings_provider.dart
diff --git a/lib/screens/settings/options_settings_page.dart b/lib/screens/settings/options_settings_page.dart
