A cross platform Audiobookshelf client for Android and iOS
Dart
part of 'library_provider.dart';
mixin _CoreMixin on ChangeNotifier, _StateMixin {
// ── Rolling download opt-in ──
bool isRollingDownloadEnabled(String seriesOrShowId) =>
_rollingDownloadSeries.contains(seriesOrShowId);
Future<void> enableRollingDownload(String seriesOrShowId,
{String? name, String? kind}) async {
_rollingDownloadSeries.add(seriesOrShowId);
_rememberRollingDownloadSource(seriesOrShowId, name: name, kind: kind);
await _saveRollingDownloadSeries();
notifyListeners();
final player = AudioPlayerService();
final itemId = player.currentItemId;
if (itemId != null) {
final episodeId = player.currentEpisodeId;
final playingKey = episodeId == null ? itemId : '$itemId-$episodeId';
_checkRollingDownloads(playingKey);
unawaited(_checkQueueAutoDownloads(playingKey));
}
unawaited(_catchUpListRollingDownloads(onlyListId: seriesOrShowId));
}
Future<void> disableRollingDownload(String seriesOrShowId) async {
_rollingDownloadSeries.remove(seriesOrShowId);
_rollingDownloadSourceNames.remove(seriesOrShowId);
unawaited(_saveRollingDownloadSourceNames());
await _saveRollingDownloadSeries();
notifyListeners();
}
Future<void> toggleRollingDownload(String seriesOrShowId,
{String? name, String? kind}) async {
if (_rollingDownloadSeries.contains(seriesOrShowId)) {
await disableRollingDownload(seriesOrShowId);
} else {
await enableRollingDownload(seriesOrShowId, name: name, kind: kind);
}
}
void _rememberRollingDownloadSource(String id, {String? name, String? kind}) {
final existing = _rollingDownloadSourceNames[id];
final mergedName =
(name != null && name.isNotEmpty) ? name : existing?['name'];
_rollingDownloadSourceNames[id] = {
if (mergedName != null) 'name': mergedName,
'kind': kind ?? existing?['kind'] ?? 'unknown',
};
unawaited(_saveRollingDownloadSourceNames());
}
Future<void> _saveRollingDownloadSourceNames() => ScopedPrefs.setString(
'rolling_download_source_names',
jsonEncode(_rollingDownloadSourceNames));
/// Everything auto-download is currently turned on for, resolved to a name
/// where we can. The stored set is bare ids with no type, so entries we
/// can't match against the cached series/playlist/collection/show data are
/// still returned unnamed rather than hidden - a toggle you can't see is a
/// toggle you can't turn off.
List<Map<String, String>> enabledAutoDownloadSources() {
final sources = <Map<String, String>>[];
for (final id in _rollingDownloadSeries) {
String? name;
var kind = 'unknown';
// Names stored at enable time (or by an earlier resolve) win; the
// live caches below only cover the currently selected library.
final stored = _rollingDownloadSourceNames[id];
if (stored != null) {
name = stored['name'];
kind = stored['kind'] ?? 'unknown';
}
if (name == null) {
for (final raw in _playlists) {
if (raw is Map<String, dynamic> && raw['id'] == id) {
name = raw['name'] as String?;
kind = 'playlist';
break;
}
}
}
if (name == null) {
for (final raw in _collections) {
if (raw is Map<String, dynamic> && raw['id'] == id) {
name = raw['name'] as String?;
kind = 'collection';
break;
}
}
}
if (name == null) {
for (final raw in _series) {
if (raw is Map<String, dynamic> && raw['id'] == id) {
name = raw['name'] as String?;
kind = 'series';
break;
}
}
}
if (name == null) {
for (final cached in _absorbingItemCache.values) {
if (cached['id'] != id) continue;
final media = cached['media'] as Map<String, dynamic>? ?? const {};
final metadata =
media['metadata'] as Map<String, dynamic>? ?? const {};
name = metadata['title'] as String?;
if (name != null) kind = 'podcast';
break;
}
}
if (name != null && name.isNotEmpty && stored?['name'] == null) {
_rememberRollingDownloadSource(id, name: name, kind: kind);
}
sources.add({
'id': id,
'kind': kind,
if (name != null && name.isNotEmpty) 'name': name,
});
}
sources.sort((a, b) {
final an = a['name'];
final bn = b['name'];
if (an == null && bn == null) return a['id']!.compareTo(b['id']!);
if (an == null) return 1;
if (bn == null) return -1;
return an.toLowerCase().compareTo(bn.toLowerCase());
});
return sources;
}
Future<void> _loadRollingDownloadSeries() async {
_rollingDownloadSeries =
(await ScopedPrefs.getStringList('rolling_download_series')).toSet();
_rollingDownloadSourceNames = {};
final namesJson =
await ScopedPrefs.getString('rolling_download_source_names');
if (namesJson != null && namesJson.isNotEmpty) {
try {
final decoded = jsonDecode(namesJson);
if (decoded is Map<String, dynamic>) {
for (final entry in decoded.entries) {
final value = entry.value;
if (value is Map) {
_rollingDownloadSourceNames[entry.key] = {
for (final e in value.entries)
if (e.value is String) e.key.toString(): e.value as String,
};
}
}
}
} catch (_) {}
}
final prefs = await SharedPreferences.getInstance();
if (prefs.containsKey('rollingDownload')) {
await prefs.remove('rollingDownload');
}
}
bool _resolvingAutoDownloadNames = false;
/// Fetch names for auto-download ids enabled before names were stored.
/// The set holds bare UUIDs with no type, so try each endpoint until one
/// answers: playlist, collection, series, then podcast item.
Future<void> resolveAutoDownloadSourceNames() async {
final api = _api;
if (api == null || isOffline || _resolvingAutoDownloadNames) return;
final unknown = _rollingDownloadSeries
.where((id) => _rollingDownloadSourceNames[id]?['name'] == null)
.toList();
if (unknown.isEmpty) return;
_resolvingAutoDownloadNames = true;
try {
final bookLibraryIds = <String>[];
for (final l in _libraries) {
if (l is Map && (l['mediaType'] as String? ?? 'book') != 'podcast') {
final libraryId = l['id'];
if (libraryId is String) bookLibraryIds.add(libraryId);
}
}
var resolvedAny = false;
for (final id in unknown) {
String? name;
String? kind;
final playlist = await api.getPlaylist(id);
if (playlist != null) {
name = playlist['name'] as String?;
kind = 'playlist';
}
if (name == null) {
final collection = await api.getCollection(id);
if (collection != null) {
name = collection['name'] as String?;
kind = 'collection';
}
}
if (name == null) {
final series =
await api.getSeriesInfo(id, libraryIds: bookLibraryIds);
if (series != null) {
name = series['name'] as String?;
kind = 'series';
}
}
if (name == null) {
final item = await api.getLibraryItem(id);
if (item != null) {
final media = item['media'] as Map<String, dynamic>? ?? const {};
final metadata =
media['metadata'] as Map<String, dynamic>? ?? const {};
name = metadata['title'] as String?;
kind = item['mediaType'] == 'podcast' ? 'podcast' : 'unknown';
}
}
if (name != null && name.isNotEmpty) {
debugPrint('[AutoDL] Resolved $id -> $kind "$name"');
_rememberRollingDownloadSource(id, name: name, kind: kind);
resolvedAny = true;
} else {
debugPrint(
'[AutoDL] Unresolved $id (stored kind: ${_rollingDownloadSourceNames[id]?['kind'] ?? 'none'}) - no playlist/collection/series/item answered');
}
}
if (resolvedAny) notifyListeners();
} finally {
_resolvingAutoDownloadNames = false;
}
}
Future<void> _saveRollingDownloadSeries() async {
await ScopedPrefs.setStringList(
'rolling_download_series', _rollingDownloadSeries.toList());
}
// ── Podcast subscription opt-in ──
bool isPodcastSubscribed(String podcastId) =>
_subscribedPodcasts.contains(podcastId);
Future<void> subscribePodcast(String podcastId) async {
_subscribedPodcasts.add(podcastId);
await _saveSubscribedPodcasts();
final item = await _api?.getLibraryItem(podcastId);
if (item != null) {
final media = item['media'] as Map<String, dynamic>? ?? {};
final episodes = media['episodes'] as List<dynamic>? ?? [];
final ids = episodes
.map((e) => (e as Map<String, dynamic>)['id'] as String?)
.whereType<String>()
.toSet();
_knownEpisodeIds[podcastId] = ids;
_saveKnownEpisodeIds(podcastId);
}
notifyListeners();
}
Future<void> unsubscribePodcast(String podcastId) async {
_subscribedPodcasts.remove(podcastId);
_knownEpisodeIds.remove(podcastId);
await _saveSubscribedPodcasts();
await ScopedPrefs.remove('known_episodes_$podcastId');
notifyListeners();
}
Future<void> togglePodcastSubscription(String podcastId) async {
if (_subscribedPodcasts.contains(podcastId)) {
await unsubscribePodcast(podcastId);
} else {
await subscribePodcast(podcastId);
}
}
Future<void> _loadSubscribedPodcasts() async {
_subscribedPodcasts =
(await ScopedPrefs.getStringList('subscribed_podcasts')).toSet();
}
Future<void> _saveSubscribedPodcasts() async {
await ScopedPrefs.setStringList(
'subscribed_podcasts', _subscribedPodcasts.toList());
}
// ── "Finished this year" local hide list ──
Future<void> _loadYearHidden() async {
_yearHiddenIds =
(await ScopedPrefs.getStringList('year_hidden_ids')).toSet();
}
/// Hide a finished book from Absorb's local "finished this year" count and
/// list. The server's finished date is untouched; this only affects Absorb.
Future<void> hideFromThisYear(String itemId) async {
if (itemId.isEmpty || !_yearHiddenIds.add(itemId)) return;
await ScopedPrefs.setStringList('year_hidden_ids', _yearHiddenIds.toList());
notifyListeners();
HomeWidgetService().refreshStats(force: true);
}
/// Undo a local hide so the book counts toward this year again.
Future<void> unhideFromThisYear(String itemId) async {
if (!_yearHiddenIds.remove(itemId)) return;
await ScopedPrefs.setStringList('year_hidden_ids', _yearHiddenIds.toList());
notifyListeners();
HomeWidgetService().refreshStats(force: true);
}
// ── Offline mode ──
Future<void> setManualOffline(bool value) async {
if (AppPlatform.lacksPhonePlugins) {
_manualOffline = false;
_networkOffline = false;
return;
}
debugPrint('[Library] setManualOffline($value)');
_manualOffline = value;
final prefs = await SharedPreferences.getInstance();
await prefs.setBool('manual_offline_mode', value);
if (!value) {
_stopServerPingTimer();
final reachable =
await _pingActiveServerWithFallback(const Duration(seconds: 5)) != null;
if (!reachable) {
debugPrint('[Library] Manual offline off but server unreachable — staying offline');
_networkOffline = true;
_buildOfflineSections();
notifyListeners();
if (_deviceHasConnectivity) _startServerPingTimer();
return;
}
_networkOffline = false;
if (_api != null) {
debugPrint('[Library] Manual offline off — flushing pending syncs');
ProgressSyncService().flushPendingSync(api: _api!);
ProgressSyncService().flushOfflineListeningTime(api: _api!);
LocalSessionService().flushPending(api: _api!);
}
if (_selectedLibraryId == null || _librariesFromCache) {
(this as LibraryProvider).loadLibraries();
} else {
(this as LibraryProvider).refresh();
}
} else {
_buildOfflineSections();
}
notifyListeners();
}
Future<void> restoreOfflineMode() async {
if (AppPlatform.lacksPhonePlugins) {
_manualOffline = false;
_networkOffline = false;
return;
}
final prefs = await SharedPreferences.getInstance();
_manualOffline = prefs.getBool('manual_offline_mode') ?? false;
}
/// User-triggered reconnect attempt for the offline cloud icon. If currently
/// offline (manual or network), pings the server (local first when enabled)
/// and flips back online on success. Returns true if online when the call
/// completes. Sets [isReconnecting] for the duration so the UI can spin.
Future<bool> tryReconnect() async {
if (!isOffline) return true;
if (_isReconnecting) return !isOffline;
debugPrint('[Library] tryReconnect: manual=$_manualOffline network=$_networkOffline');
_isReconnecting = true;
notifyListeners();
try {
if (_manualOffline) {
await setManualOffline(false);
return !isOffline;
}
final auth = _auth;
if (auth == null) return false;
if (auth.localServerEnabled && auth.localServerUrl.isNotEmpty) {
final localReachable = await ApiService.pingServer(
auth.localServerUrl,
customHeaders: auth.customHeaders,
).timeout(const Duration(seconds: 5), onTimeout: () => false);
if (localReachable) {
debugPrint('[Library] tryReconnect: local server reachable');
await auth.checkLocalServer();
_stopServerPingTimer();
setNetworkOffline(false);
return true;
}
if (auth.useLocalServer) {
debugPrint('[Library] tryReconnect: local unreachable, clearing override');
auth.clearLocalOverride();
}
}
final serverUrl = auth.serverUrl;
if (serverUrl == null || serverUrl.isEmpty) return false;
final reachable = await ApiService.pingServer(
serverUrl,
customHeaders: auth.customHeaders,
).timeout(const Duration(seconds: 5), onTimeout: () => false);
if (reachable) {
debugPrint('[Library] tryReconnect: remote server reachable');
_stopServerPingTimer();
setNetworkOffline(false);
return true;
}
debugPrint('[Library] tryReconnect: still unreachable');
return false;
} finally {
_isReconnecting = false;
notifyListeners();
}
}
void setNetworkOffline(bool offline) {
if (AppPlatform.lacksPhonePlugins) {
_networkOffline = false;
AudioPlayerService().setKnownOffline(false);
return;
}
final wasOffline = _networkOffline;
_networkOffline = offline;
// Mirror into AudioPlayerService so playback start can skip server session
// creation immediately - otherwise a downloaded book waits ~5s for the
// capped startPlaybackSession() timeout before audio kicks in.
AudioPlayerService().setKnownOffline(offline);
if (offline && !wasOffline) {
_stopHealthCheckTimer();
_buildOfflineSections();
notifyListeners();
AndroidAutoService().refresh(force: true);
CarPlayService().refreshTemplates();
if (_deviceHasConnectivity && !_manualOffline) {
_startServerPingTimer();
}
} else if (!offline && wasOffline && !_manualOffline) {
_stopServerPingTimer();
_startHealthCheckTimer();
PaintingBinding.instance.imageCache.clear();
// If we launched offline (e.g. right after an app update), the user info
// (type/permissions) never loaded and admin-only UI stayed hidden. Now
// that we're back online, pull it so the admin settings appear without a
// force-close. No-op if it's already loaded.
unawaited(_auth?.ensureUserInfoLoaded() ?? Future.value());
if (_api != null) {
debugPrint('[Library] Back online — flushing pending syncs');
AudioPlayerService().resetServerSyncBackoff();
ProgressSyncService().flushPendingSync(api: _api!);
ProgressSyncService().flushOfflineListeningTime(api: _api!);
LocalSessionService().flushPending(api: _api!);
}
if (_selectedLibraryId == null || _librariesFromCache) {
(this as LibraryProvider).loadLibraries();
} else {
(this as LibraryProvider).refresh();
}
AndroidAutoService().refresh(force: true);
CarPlayService().refreshTemplates();
}
}
void _buildOfflineSections() {
if (AppPlatform.lacksPhonePlugins) {
_personalizedSections = [];
_errorMessage = null;
_isLoading = false;
return;
}
final isPodcast = isPodcastLibrary;
final allDownloads = DownloadService().downloadedItems;
final downloads = allDownloads.where((dl) {
final libraryId = dl.libraryId;
if (libraryId != null &&
libraryId.isNotEmpty &&
_selectedLibraryId != null) {
return libraryId == _selectedLibraryId;
}
return (dl.itemId.length > 36) == isPodcast;
}).toList();
final downloadedIds = downloads.map((d) => d.itemId).toSet();
final keptEbooks = isPodcast
? const <DownloadInfo>[]
: DownloadService().keptEbooks.where((k) {
if (downloadedIds.contains(k.itemId)) return false;
final libraryId = k.libraryId;
if (libraryId != null &&
libraryId.isNotEmpty &&
_selectedLibraryId != null) {
return libraryId == _selectedLibraryId;
}
return true;
}).toList();
debugPrint(
'[Library] Building offline sections: ${downloads.length}/${allDownloads.length} downloads (${isPodcast ? "podcast" : "book"}) '
'+${keptEbooks.length} kept ebooks library=$_selectedLibraryId of ${_libraries.length}');
if (downloads.isEmpty && keptEbooks.isEmpty) {
_personalizedSections = [];
_errorMessage = null;
_isLoading = false;
notifyListeners();
return;
}
final continueEntities = <Map<String, dynamic>>[];
final downloadedEntities = <Map<String, dynamic>>[];
for (final dl in downloads) {
double duration = 0;
List<dynamic> chapters = [];
String? episodeTitle;
Map<String, dynamic>? ebookFile;
if (dl.sessionData != null) {
try {
final session = jsonDecode(dl.sessionData!) as Map<String, dynamic>;
duration = (session['duration'] as num?)?.toDouble() ?? 0;
chapters = session['chapters'] as List<dynamic>? ?? [];
episodeTitle = session['episodeTitle'] as String? ??
session['displayTitle'] as String?;
ebookFile = resolveEbookFile(
session['libraryItem'] as Map<String, dynamic>?);
} catch (_) {}
}
final isCompound = dl.itemId.length > 36;
late final Map<String, dynamic> entity;
if (isCompound) {
final showId = dl.itemId.substring(0, 36);
final episodeId = dl.itemId.substring(37);
entity = {
'id': showId,
'_absorbingKey': dl.itemId,
'recentEpisode': {
'id': episodeId,
'title': episodeTitle ?? dl.title ?? 'Episode',
'duration': duration,
'chapters': chapters,
},
'media': {
'metadata': {
'title': dl.title ?? 'Unknown Title',
'authorName': dl.author ?? '',
},
'duration': duration,
'chapters': chapters,
},
};
} else {
entity = {
'id': dl.itemId,
'media': {
'metadata': {
'title': dl.title ?? 'Unknown Title',
'authorName': dl.author ?? '',
},
'duration': duration,
'chapters': chapters,
if (ebookFile != null) 'ebookFile': ebookFile,
},
};
}
final progress = _resetItems.contains(dl.itemId)
? 0.0
: _localProgressOverrides[dl.itemId] ??
(_progressMap[dl.itemId]?['progress'] as num?)?.toDouble() ??
0.0;
final isFinished =
_progressMap[dl.itemId]?['isFinished'] == true || progress >= 0.999;
if (progress > 0 && !isFinished) continueEntities.add(entity);
downloadedEntities.add(entity);
}
for (final kept in keptEbooks) {
Map<String, dynamic>? item;
try {
item = (jsonDecode(kept.sessionData ?? '{}')
as Map<String, dynamic>)['libraryItem'] as Map<String, dynamic>?;
} catch (_) {}
final ebookFile = resolveEbookFile(item);
downloadedEntities.add({
'id': kept.itemId,
if (kept.libraryId != null) 'libraryId': kept.libraryId,
'media': {
'metadata': {
'title': kept.title ?? 'Unknown Title',
'authorName': kept.author ?? '',
},
'duration': 0,
'chapters': const <dynamic>[],
if (ebookFile != null) 'ebookFile': ebookFile,
},
});
}
_personalizedSections = [
if (continueEntities.isNotEmpty)
{
'id': 'continue-listening',
'label': 'Continue Listening',
'type': isPodcast ? 'podcast' : 'book',
'entities': continueEntities,
},
if (downloadedEntities.isNotEmpty)
{
'id': 'downloaded-books',
'label': isPodcast ? 'Downloaded Episodes' : 'Downloaded Books',
'type': isPodcast ? 'podcast' : 'book',
'entities': downloadedEntities,
},
];
_errorMessage = null;
_isLoading = false;
}
void _onDownloadsChanged() {
if (isOffline || _personalizedSections.isEmpty) return;
_personalizedSections = _personalizedSections
.where((s) => (s as Map)['id'] != 'downloaded-books')
.toList();
_injectDownloadedSection();
notifyListeners();
}
void _injectDownloadedSection() {
if (AppPlatform.lacksPhonePlugins) return;
final isPodcast = isPodcastLibrary;
final allDownloads = DownloadService().downloadedItems;
final downloads = allDownloads.where((dl) {
final libraryId = dl.libraryId;
if (libraryId != null &&
libraryId.isNotEmpty &&
_selectedLibraryId != null) {
return libraryId == _selectedLibraryId;
}
return (dl.itemId.length > 36) == isPodcast;
}).toList();
if (downloads.isEmpty) return;
final entities = <Map<String, dynamic>>[];
for (final dl in downloads) {
double duration = 0;
List<dynamic> chapters = [];
String? episodeTitle;
Map<String, dynamic>? ebookFile;
if (dl.sessionData != null) {
try {
final session = jsonDecode(dl.sessionData!) as Map<String, dynamic>;
duration = (session['duration'] as num?)?.toDouble() ?? 0;
chapters = session['chapters'] as List<dynamic>? ?? [];
episodeTitle = session['episodeTitle'] as String? ??
session['displayTitle'] as String?;
ebookFile = resolveEbookFile(
session['libraryItem'] as Map<String, dynamic>?);
} catch (_) {}
}
final isCompound = dl.itemId.length > 36;
if (isCompound) {
final showId = dl.itemId.substring(0, 36);
final episodeId = dl.itemId.substring(37);
entities.add({
'id': showId,
'_absorbingKey': dl.itemId,
'recentEpisode': {
'id': episodeId,
'title': episodeTitle ?? dl.title ?? 'Episode',
'duration': duration,
'chapters': chapters,
},
'media': {
'metadata': {
'title': dl.title ?? 'Unknown Title',
'authorName': dl.author ?? '',
},
'duration': duration,
'chapters': chapters,
},
});
} else {
entities.add({
'id': dl.itemId,
'media': {
'metadata': {
'title': dl.title ?? 'Unknown Title',
'authorName': dl.author ?? '',
},
'duration': duration,
'chapters': chapters,
if (ebookFile != null) 'ebookFile': ebookFile,
},
});
}
}
_personalizedSections.add({
'id': 'downloaded-books',
'label': isPodcast ? 'Downloaded Episodes' : 'Downloaded Books',
'type': isPodcast ? 'podcast' : 'book',
'entities': entities,
});
}
// ── Progress ──
double getProgress(String? itemId) {
if (itemId == null) return 0;
if (_resetItems.contains(itemId)) return 0;
final local = _localProgressOverrides[itemId];
if (local != null) return local;
final mp = _progressMap[itemId];
if (mp == null) return 0;
final audio = (mp['progress'] as num?)?.toDouble() ?? 0;
if (audio > 0) return audio;
// Ebook-only books (comics, PDFs, mobi) have no audio progress; surface
// their reading progress so the cover bar and detail sheet still fill in.
return (mp['ebookProgress'] as num?)?.toDouble() ?? 0;
}
/// The ebook's own reading progress, apart from any audio progress.
double getEbookProgress(String? itemId) {
if (itemId == null) return 0;
return (_progressMap[itemId]?['ebookProgress'] as num?)?.toDouble() ?? 0;
}
/// Reflect ebook reading progress in the in-memory map right away, so covers
/// and the detail sheet update on return from the reader instead of waiting
/// for the server round-trip / socket echo.
void applyLocalEbookProgress(String itemId,
{required String location, required double progress, bool finished = false}) {
final mp = Map<String, dynamic>.from(_progressMap[itemId] ?? {});
mp['ebookLocation'] = location;
mp['ebookProgress'] = progress.clamp(0.0, 1.0);
if (finished) mp['isFinished'] = true;
_progressMap[itemId] = mp;
// Reading again after a reset or "not finished" is new progress; while
// the item stayed marked reset, the reader couldn't see its own saved
// page and started over on every open.
_resetItems.remove(itemId);
notifyListeners();
}
double getEpisodeProgress(String itemId, String episodeId) {
final key = '$itemId-$episodeId';
if (_resetItems.contains(key)) return 0;
final local = _localProgressOverrides[key];
if (local != null) return local;
final mp = _progressMap[key];
if (mp == null) return 0;
return (mp['progress'] as num?)?.toDouble() ?? 0;
}
Map<String, dynamic>? getProgressData(String? itemId) {
if (itemId == null) return null;
if (_resetItems.contains(itemId)) return null;
final data = _progressMap[itemId];
if (_locallyFinishedItems.contains(itemId)) {
debugPrint('[Progress] getProgressData($itemId) — forcing isFinished from local override (server isFinished=${data?['isFinished']})');
return {...?data, 'isFinished': true};
}
return data;
}
void applyLocalProgressDates(
String itemId, {
int? startedAt,
int? finishedAt,
}) {
final progress = Map<String, dynamic>.from(_progressMap[itemId] ?? {});
if (startedAt != null) progress['startedAt'] = startedAt;
if (finishedAt != null) progress['finishedAt'] = finishedAt;
_progressMap[itemId] = progress;
notifyListeners();
}
/// True if [itemId] currently appears in the personalized "Continue Listening"
/// shelf. Gates the "Remove from Continue Listening" book action.
bool isInContinueListeningShelf(String itemId) => continueShelfOf(itemId) == 'continue-listening';
/// Which Continue shelf shows [itemId], 'continue-listening' or
/// 'continue-reading', or null. Gates the remove-from-Continue action.
String? continueShelfOf(String itemId) {
for (final id in const ['continue-listening', 'continue-reading']) {
for (final section in _personalizedSections) {
if (section is! Map<String, dynamic> || section['id'] != id) continue;
for (final e in (section['entities'] as List<dynamic>? ?? const [])) {
if (e is Map<String, dynamic> && e['id'] == itemId) return id;
}
}
}
return null;
}
/// Takes a book or a series off the Continue shelves straight away. A
/// refresh already on its way could otherwise put it back from before the
/// server heard.
void hideFromContinueShelves({String? itemId, String? seriesId}) {
final now = DateTime.now();
if (itemId != null) _hiddenShelfItems[itemId] = now;
if (seriesId != null) _hiddenShelfSeries[seriesId] = now;
_personalizedSections = _withoutJustHidden(_personalizedSections);
notifyListeners();
}
List<dynamic> _withoutJustHidden(List<dynamic> sections) {
final now = DateTime.now();
bool stale(String _, DateTime at) => now.difference(at) > const Duration(minutes: 2);
_hiddenShelfItems.removeWhere(stale);
_hiddenShelfSeries.removeWhere(stale);
if (_hiddenShelfItems.isEmpty && _hiddenShelfSeries.isEmpty) return sections;
bool hidden(String shelf, Object? e) {
if (e is! Map) return false;
if (shelf != 'continue-series') return _hiddenShelfItems.containsKey(e['id']);
final series = [
((e['media'] as Map?)?['metadata'] as Map?)?['series'],
e['series'],
].expand((s) => s is List ? s : [s]);
return series.any((s) => s is Map && _hiddenShelfSeries.containsKey(s['id']));
}
return [
for (final section in sections)
if (section is Map<String, dynamic> &&
const {'continue-listening', 'continue-reading', 'continue-series'}.contains(section['id']))
{
...section,
'entities': [
for (final e in (section['entities'] as List<dynamic>? ?? const []))
if (!hidden(section['id'] as String, e)) e,
],
}
else
section,
];
}
/// If one of [seriesIds] (the opened book's series) is currently shown in the
/// "Continue Series" shelf, returns that series id (needed for the remove
/// call); otherwise null. Gates the "Remove Series from Continue Series".
///
/// The shelf entities are the *next book* in each continued series. The server
/// clears the book's own series list and re-attaches the continued series as a
/// single {id, name, sequence} object at `media.metadata.series` (see
/// libraryFilters.getLibraryItemsContinueSeries) - so we read the id from
/// there, not from the entity (book) id.
String? continueSeriesShelfMatch(Iterable<String> seriesIds) {
final wanted = {for (final s in seriesIds) if (s.isNotEmpty) s};
if (wanted.isEmpty) return null;
String? idFrom(dynamic raw) {
if (raw is Map<String, dynamic>) {
final id = raw['id'] as String?;
if (id != null && wanted.contains(id)) return id;
} else if (raw is List) {
for (final s in raw) {
final id = s is Map<String, dynamic> ? s['id'] as String? : null;
if (id != null && wanted.contains(id)) return id;
}
}
return null;
}
for (final section in _personalizedSections) {
if (section is! Map<String, dynamic>) continue;
if (section['id'] != 'continue-series') continue;
for (final e in (section['entities'] as List<dynamic>? ?? const [])) {
if (e is! Map<String, dynamic>) continue;
final metadata =
(e['media'] as Map<String, dynamic>?)?['metadata'] as Map<String, dynamic>?;
final match = idFrom(metadata?['series']) ?? idFrom(e['series']);
if (match != null) return match;
}
}
return null;
}
Map<String, dynamic>? getEpisodeProgressData(
String itemId, String episodeId) {
final key = '$itemId-$episodeId';
if (_resetItems.contains(key)) return null;
final data = _progressMap[key];
if (_locallyFinishedItems.contains(key)) {
return {...?data, 'isFinished': true};
}
return data;
}
/// Shows the user has started or finished at least one episode of. The
/// progress map is the only place that knows this without walking every
/// show's episode list.
Set<String> podcastShowIdsWithProgress() {
final out = <String>{};
for (final p in _progressMap.values) {
final ep = p['episodeId'];
if (ep is! String || ep.isEmpty) continue;
final id = p['libraryItemId'];
if (id is String && id.isNotEmpty) out.add(id);
}
return out;
}
/// Count of episodes in [show] that the user hasn't finished (includes
/// partially-played and never-started episodes). Used by tile badges and
/// the show sheet header.
///
/// Prefers the server-provided `numEpisodesIncomplete` field (requested via
/// `include=numEpisodesIncomplete` on the library/personalized endpoints) so
/// scrolling grids don't have to load every episode payload. Falls back to
/// iterating `media.episodes` when the full payload is available (e.g.
/// inside the show sheet).
int getUnfinishedEpisodeCount(Map<String, dynamic>? show) {
if (show == null) return 0;
final media = show['media'] as Map<String, dynamic>? ?? const {};
final itemId = show['id'] as String? ?? '';
// Try the server-provided count first.
final serverCount = show['numEpisodesIncomplete'] as int? ??
media['numEpisodesIncomplete'] as int?;
if (serverCount != null) {
return _adjustedUnfinishedCount(itemId, serverCount);
}
// Fallback: count from the loaded episodes array. Match server semantics
// — count any episode the user hasn't marked finished.
if (itemId.isEmpty) return 0;
final episodes = media['episodes'] as List<dynamic>? ?? const [];
if (episodes.isEmpty) return 0;
var count = 0;
for (final e in episodes) {
if (e is! Map<String, dynamic>) continue;
final epId = e['id'] as String? ?? '';
if (epId.isEmpty) continue;
final pd = getEpisodeProgressData(itemId, epId);
final isFinished = pd?['isFinished'] == true;
if (!isFinished) count++;
}
return count;
}
/// Apply (and fold pending) local badge nudges onto the server's count.
/// The cached items showing badges aren't all owned by the provider, so the
/// correction lives here instead of in the item maps. Self-discards when
/// the server count moves off the base it was recorded against.
int _adjustedUnfinishedCount(String showId, int serverCount) {
if (showId.isEmpty) return serverCount;
final pending = _pendingUnfinishedDeltas.remove(showId);
if (pending != null) {
final prior = _unfinishedCountAdjustments[showId];
final from = (prior != null && prior.$1 == serverCount) ? prior.$2 : serverCount;
_unfinishedCountAdjustments[showId] =
(serverCount, (from + pending).clamp(0, 1 << 30));
}
final adj = _unfinishedCountAdjustments[showId];
if (adj == null) return serverCount;
if (adj.$1 == serverCount) return adj.$2;
_unfinishedCountAdjustments.remove(showId);
return serverCount;
}
/// Record a local +/- nudge for a show's unfinished-episode badge.
void nudgeUnfinishedEpisodeCount(String showId, int delta) {
if (showId.isEmpty) return;
_pendingUnfinishedDeltas[showId] =
(_pendingUnfinishedDeltas[showId] ?? 0) + delta;
}
Future<void> refreshLocalProgress() async {
final sync = ProgressSyncService();
final itemIds = <String>{..._progressMap.keys};
for (final dl in DownloadService().downloadedItems) {
itemIds.add(dl.itemId);
}
for (final itemId in itemIds) {
if (_locallyFinishedItems.contains(itemId)) continue;
if (_resetItems.contains(itemId)) continue;
final serverFinished = _progressMap[itemId]?['isFinished'] == true;
final data = await sync.getLocal(itemId);
if (data != null) {
final currentTime = (data['currentTime'] as num?)?.toDouble() ?? 0;
final duration = (data['duration'] as num?)?.toDouble() ?? 0;
if (duration > 0) {
final progress = (currentTime / duration).clamp(0.0, 1.0);
if (progress >= 0.99 && !serverFinished) continue;
if (serverFinished) continue;
_localProgressOverrides[itemId] = progress;
if (currentTime > 0) _resetItems.remove(itemId);
}
}
}
notifyListeners();
}
void clearProgressFor(String itemId) {
_progressMap.remove(itemId);
_localProgressOverrides.remove(itemId);
notifyListeners();
}
/// After "mark as not finished" lands on the server, which clears the
/// position there, drop the local copy too so the card and the next play
/// don't carry on from the old spot.
Future<void> markNotFinishedLocally(String itemId) async {
// A loaded player still holds the old position in memory and would sync
// it straight back on the next play, so let it go the way reset does.
final player = AudioPlayerService();
final loadedKey = player.currentEpisodeId != null
? '${player.currentItemId}-${player.currentEpisodeId}'
: player.currentItemId;
if (loadedKey == itemId) await player.stopWithoutSaving();
await ProgressSyncService().deleteLocal(itemId);
resetProgressFor(itemId);
}
void resetProgressFor(String itemId) {
if (itemId.length > 36 && _progressMap[itemId]?['isFinished'] == true) {
nudgeUnfinishedEpisodeCount(itemId.substring(0, 36), 1);
}
// The widget stash is a third copy of the position, outside the scoped
// prefs. Left alone it wins the resume race and the first sync writes the
// old spot back to the server.
unawaited(HomeWidgetService().clearStashedNowPlayingPosition(
itemId.length > 36 ? itemId.substring(0, 36) : itemId,
itemId.length > 36 ? itemId.substring(37) : null,
));
_progressMap.remove(itemId);
_localProgressOverrides.remove(itemId);
_locallyFinishedItems.remove(itemId);
_resetItems.add(itemId);
notifyListeners();
}
void _buildProgressMap(AuthProvider auth) {
_progressMap = {};
final progressList = auth.userJson?['mediaProgress'] as List<dynamic>?;
if (progressList != null) {
for (final mp in progressList) {
if (mp is Map<String, dynamic>) {
final itemId = mp['libraryItemId'] as String?;
final episodeId = mp['episodeId'] as String?;
if (itemId != null) {
final key = episodeId != null ? '$itemId-$episodeId' : itemId;
_progressMap[key] = mp;
}
}
}
}
// Overlay queued-offline ebook positions (their PATCH never landed), so a
// cold start can't resume the reader behind the last page read offline.
_overlayPendingEbookProgress();
}
// Once overlaid here, the position lives in _progressMap like any local
// write, so _refreshProgress's furthest-wins snapshot carries it forward.
Future<void> _overlayPendingEbookProgress() async {
final pending = await ProgressSyncService().getPendingEbookProgress();
if (pending.isEmpty) return;
var changed = false;
for (final entry in pending.entries) {
final loc = entry.value['loc'] as String?;
final prog = (entry.value['prog'] as num?)?.toDouble() ?? 0;
if (loc == null) continue;
// Furthest wins, same rule as _refreshProgress: a fresher server
// position (read on another device) stays.
final serverProg =
(_progressMap[entry.key]?['ebookProgress'] as num?)?.toDouble() ?? -1;
if (prog >= serverProg) {
_progressMap[entry.key] = {
...?_progressMap[entry.key],
'ebookLocation': loc,
'ebookProgress': prog.clamp(0.0, 1.0),
};
changed = true;
}
}
if (changed) notifyListeners();
}
Future<void> _refreshProgress() async {
if (_api == null) return;
try {
final pendingSyncs =
(await ScopedPrefs.getStringList('pending_syncs')).toSet();
final progressList = await _api!.getAllProgress();
if (progressList != null) {
final localFinished = <String, Map<String, dynamic>>{};
if (_lastFinishedItemId != null &&
_progressMap.containsKey(_lastFinishedItemId!)) {
localFinished[_lastFinishedItemId!] =
_progressMap[_lastFinishedItemId!]!;
}
// Snapshot local ebook positions: the just-read page is saved locally
// (applyLocalEbookProgress) but its server PATCH may not have landed,
// and this rebuild would otherwise replace it with the server's older
// location - resuming the reader a page behind. Re-applied below when
// still at/ahead of the server.
final localEbook = <String, Map<String, dynamic>>{};
for (final e in _progressMap.entries) {
if (e.value['ebookLocation'] != null) {
localEbook[e.key] = {
'ebookLocation': e.value['ebookLocation'],
'ebookProgress': e.value['ebookProgress'],
};
}
}
_progressMap = {};
for (final mp in progressList) {
final itemId = mp['libraryItemId'] as String?;
final episodeId = mp['episodeId'] as String?;
if (itemId != null) {
final key = episodeId != null ? '$itemId-$episodeId' : itemId;
_progressMap[key] = mp;
}
}
for (final entry in localFinished.entries) {
final serverEntry = _progressMap[entry.key];
final serverHasFinished = serverEntry?['isFinished'] == true;
if (serverEntry == null || !serverHasFinished) {
_progressMap[entry.key] = {...?serverEntry, ...entry.value};
}
}
// Keep the furthest-read ebook position (local vs server), so a stale
// server pull can't rewind the reader's saved page.
for (final entry in localEbook.entries) {
final serverProg =
(_progressMap[entry.key]?['ebookProgress'] as num?)?.toDouble() ?? -1;
final localProg = (entry.value['ebookProgress'] as num?)?.toDouble() ?? 0;
if (localProg >= serverProg) {
_progressMap[entry.key] = {
...?_progressMap[entry.key],
'ebookLocation': entry.value['ebookLocation'],
'ebookProgress': entry.value['ebookProgress'],
};
}
}
if (_locallyFinishedItems.isNotEmpty) {
debugPrint('[Progress] locallyFinished before cleanup: $_locallyFinishedItems');
}
if (_localProgressOverrides.isNotEmpty) {
debugPrint('[Progress] localOverrides before cleanup: ${_localProgressOverrides.keys.toList()}');
}
_locallyFinishedItems.removeWhere((key) {
final serverData = _progressMap[key];
if (serverData?['isFinished'] == true) {
debugPrint('[Progress] Clearing local finished (server confirmed): $key');
return true;
}
if (serverData != null && serverData['isFinished'] == false) {
if (pendingSyncs.contains(key)) {
debugPrint('[Progress] Keeping local finished (sync pending): $key');
return false;
}
debugPrint('[Progress] Clearing local finished (server says not finished): $key');
return true;
}
debugPrint('[Progress] Keeping local finished (no server data): $key');
return false;
});
final overridesBefore = _localProgressOverrides.length;
_localProgressOverrides.removeWhere((key, localProgress) {
if (pendingSyncs.contains(key)) return false;
if (_locallyFinishedItems.contains(key)) return false;
// Keep the override if local progress is ahead of server
final serverProgress = ((_progressMap[key]?['progress'] as num?)?.toDouble()) ?? 0;
if (localProgress > serverProgress + 0.001) return false;
return true;
});
final cleared = overridesBefore - _localProgressOverrides.length;
if (cleared > 0) {
debugPrint('[Progress] Cleared $cleared overrides');
}
(this as _AbsorbingMixin)
._pruneRemotelyFinishedBooks(_progressMap.keys);
}
} catch (_) {}
}
// ── Connectivity ──
void _startConnectivityMonitoring() {
_connectivitySub?.cancel();
_connectivityDebounce?.cancel();
Connectivity().checkConnectivity().then((result) {
_deviceHasConnectivity = !result.contains(ConnectivityResult.none);
if (!_deviceHasConnectivity) {
_stopServerPingTimer();
_stopLocalProbeTimer();
setNetworkOffline(true);
} else if (_networkOffline && !_manualOffline) {
_auth?.checkLocalServer().then((_) {
if (_auth?.serverReachable == true || _auth?.useLocalServer == true) {
setNetworkOffline(false);
} else {
_startServerPingTimer();
}
_startLocalProbeTimer();
});
} else if (_deviceHasConnectivity) {
_startLocalProbeTimer();
}
});
_connectivitySub = Connectivity().onConnectivityChanged.listen((result) async {
final hasConnectivity = !result.contains(ConnectivityResult.none);
_deviceHasConnectivity = hasConnectivity;
if (!hasConnectivity) {
_connectivityDebounce?.cancel();
_stopServerPingTimer();
_stopLocalProbeTimer();
setNetworkOffline(true);
// Don't flip the local/remote choice here. The local server may still
// be reachable on a lower-priority interface (e.g. wifi briefly drops
// out of the connectivity list during scans). The probe timer decides.
return;
}
if (_manualOffline) return;
// Coalesce bursts of "connected" events (wifi<->mobile handoff, interface
// scans) so we don't re-ping the server and re-run catch-up downloads on
// every blip - that was burning packets and battery on flaky networks.
_connectivityDebounce?.cancel();
_connectivityDebounce = Timer(const Duration(seconds: 2), () async {
// Got connectivity back - re-probe and potentially come online.
// We pick the active server based on actual reachability, not on
// whether the connectivity list happens to contain wifi this tick.
final reachable =
await _pingActiveServerWithFallback(const Duration(seconds: 5)) != null;
if (reachable) {
setNetworkOffline(false);
if (_rollingDownloadSeries.isNotEmpty) _catchUpRollingDownloads();
unawaited(_catchUpQueueAutoDownloads());
(this as LibraryProvider).catchUpSubscribedPodcasts();
final ebookApi = _api;
if (ebookApi != null) {
unawaited(DownloadService().catchUpEbookCaches(ebookApi));
}
} else {
debugPrint('[Library] Connectivity changed but server unreachable — starting ping timer');
if (_networkOffline) {
_startServerPingTimer();
} else {
_goOffline();
}
}
_startLocalProbeTimer();
});
});
}
/// Ping the active server and return the URL that answered, or null if
/// nothing did. When the local override is active but its ip:port has gone
/// stale, fall back to the remote URL before giving up - otherwise a dead
/// local address flags the app offline while the domain still answers
/// (same local-then-remote order tryReconnect uses).
Future<String?> _pingActiveServerWithFallback(Duration timeout) async {
final auth = _auth;
if (auth == null) return null;
final activeUrl = auth.activeServerUrl ?? auth.serverUrl ?? '';
if (activeUrl.isEmpty) return null;
final reachable = await ApiService.pingServer(activeUrl, customHeaders: auth.customHeaders)
.timeout(timeout, onTimeout: () => false);
if (reachable) return activeUrl;
final remoteUrl = auth.serverUrl ?? '';
if (remoteUrl.isEmpty || remoteUrl == activeUrl) return null;
final remoteReachable = await ApiService.pingServer(remoteUrl, customHeaders: auth.customHeaders)
.timeout(timeout, onTimeout: () => false);
if (!remoteReachable) return null;
debugPrint('[Library] Local server unreachable but remote responds - switching to remote');
auth.clearLocalOverride();
return remoteUrl;
}
void _startServerPingTimer() {
_serverPingTimer?.cancel();
if (_isBackgrounded || _readerQuiet || PlayerSettings.einkMode) return;
final serverUrl = _auth?.serverUrl;
if (serverUrl == null) return;
debugPrint('[Library] Starting server ping timer');
_serverPingTimer = Timer.periodic(const Duration(seconds: 20), (_) async {
if (!_networkOffline || _manualOffline) {
_stopServerPingTimer();
return;
}
final auth = _auth;
if (auth != null && auth.localServerEnabled && auth.localServerUrl.isNotEmpty) {
final localReachable = await ApiService.pingServer(
auth.localServerUrl,
customHeaders: auth.customHeaders,
).timeout(const Duration(seconds: 6), onTimeout: () => false);
if (localReachable) {
debugPrint('[Library] Local server ping succeeded — going online');
await auth.checkLocalServer();
_stopServerPingTimer();
setNetworkOffline(false);
return;
}
}
final reachable = await ApiService.pingServer(
serverUrl,
customHeaders: _auth?.customHeaders ?? {},
);
if (reachable) {
debugPrint('[Library] Server ping succeeded — going online');
_stopServerPingTimer();
setNetworkOffline(false);
}
});
}
void _stopServerPingTimer() {
_serverPingTimer?.cancel();
_serverPingTimer = null;
}
// ── Local server reachability probe ──
//
// Replaces the old "react to every onConnectivityChanged event" switching,
// which would flap between local and remote whenever the connectivity list
// briefly dropped wifi (signal blips, mobile interface coming up, etc).
// Polls every 30s with hysteresis: 2 consecutive failures to switch off
// local, 1 success to switch back on. Skips the ping if some other code
// path (progress sync, health check) already proved local is reachable
// within the past 25s.
static const _localProbeInterval = Duration(seconds: 30);
static const _localProbeFailuresToFlip = 2;
static const _localProbePiggybackWindow = Duration(seconds: 25);
// Away from home the local server never answers, and a ping every 30s all
// day on mobile data (or with no signal at all) is pure waste. After two
// minutes of misses the checks spread out to at most every 5 minutes. A
// network change starts the fast checks again, so joining home WiFi still
// switches over straight away.
int _remoteProbeMisses = 0;
DateTime? _nextRemoteProbeAt;
static const _remoteProbeFastMisses = 4;
static const _remoteProbeMaxGap = Duration(minutes: 5);
void _startLocalProbeTimer() {
final auth = _auth;
if (auth == null) return;
if (!auth.localServerEnabled || auth.localServerUrl.isEmpty) {
_stopLocalProbeTimer();
return;
}
// Don't run when truly idle in the background, or while reading (battery).
// Playback still needs it either way.
if ((_isBackgrounded || _readerQuiet) && !AudioPlayerService().isPlaying) {
_stopLocalProbeTimer();
return;
}
_remoteProbeMisses = 0;
_nextRemoteProbeAt = null;
if (_localProbeTimer != null) return;
_localProbeFailures = 0;
_localProbeTimer = Timer.periodic(_localProbeInterval, (_) => _probeLocalServer());
}
void _stopLocalProbeTimer() {
_localProbeTimer?.cancel();
_localProbeTimer = null;
_localProbeFailures = 0;
}
/// Mark local-server reachability based on a successful API call, so the
/// next probe tick can skip its own ping. Call sites: progress sync ok,
/// health check ok - anything that confirms the active server responded.
void notifyServerReachable(String url) {
final auth = _auth;
if (auth == null) return;
if (auth.localServerUrl.isEmpty) return;
if (url == auth.localServerUrl) {
_localLastReachableAt = DateTime.now();
_localProbeFailures = 0;
}
}
Future<void> _probeLocalServer() async {
final auth = _auth;
if (auth == null || _manualOffline) return;
if (!auth.localServerEnabled || auth.localServerUrl.isEmpty) {
_stopLocalProbeTimer();
return;
}
// Piggy-back: skip if another path proved reachability recently.
final last = _localLastReachableAt;
if (auth.useLocalServer && last != null &&
DateTime.now().difference(last) < _localProbePiggybackWindow) {
return;
}
final nextRemote = _nextRemoteProbeAt;
if (!auth.useLocalServer &&
nextRemote != null &&
DateTime.now().isBefore(nextRemote)) {
return;
}
final probe = await ApiService.pingServerDetailed(
auth.localServerUrl,
customHeaders: auth.customHeaders,
).timeout(
const Duration(seconds: 6),
onTimeout: () => (ok: false, detail: 'no answer within 6s'),
);
final reachable = probe.ok;
if (auth.useLocalServer) {
if (reachable) {
_localLastReachableAt = DateTime.now();
_localProbeFailures = 0;
} else {
_localProbeFailures++;
if (_localProbeFailures >= _localProbeFailuresToFlip) {
debugPrint('[Library] Local probe failed ${_localProbeFailures}x — switching to remote (${probe.detail})');
auth.clearLocalOverride();
_localProbeFailures = 0;
} else {
debugPrint('[Library] Local probe miss $_localProbeFailures/$_localProbeFailuresToFlip (${probe.detail})');
}
}
} else if (reachable) {
debugPrint('[Library] Local probe succeeded — switching to local');
await auth.checkLocalServer();
_localLastReachableAt = DateTime.now();
_localProbeFailures = 0;
_remoteProbeMisses = 0;
_nextRemoteProbeAt = null;
} else {
_remoteProbeMisses++;
if (_remoteProbeMisses > _remoteProbeFastMisses) {
final steps = _remoteProbeMisses - _remoteProbeFastMisses;
final gap = _localProbeInterval * (1 << steps.clamp(0, 4));
final wait = gap < _remoteProbeMaxGap ? gap : _remoteProbeMaxGap;
_nextRemoteProbeAt = DateTime.now().add(wait);
debugPrint(
'[Library] Local probe miss while on remote (${probe.detail}), next in ${wait.inSeconds}s');
} else {
debugPrint('[Library] Local probe miss while on remote (${probe.detail})');
}
}
}
// ── Health check (proactive reachability verification while online) ──
//
// The offline state only flips via explicit triggers (connectivity change,
// ping timer success, manual toggle). HTTP 5xx bursts and socket connect
// failures don't feed back, so during a server outage the cloud icon stays
// green until the next explicit event. This periodic ping closes that gap.
void _startHealthCheckTimer() {
_healthCheckTimer?.cancel();
if (_isBackgrounded || _readerQuiet || PlayerSettings.einkMode) return;
debugPrint('[Library] Health check timer started (60s ping while online)');
_healthCheckTimer = Timer.periodic(const Duration(seconds: 60), (_) async {
if (_networkOffline || _manualOffline || !_deviceHasConnectivity) return;
if ((_auth?.activeServerUrl ?? _auth?.serverUrl ?? '').isEmpty) return;
var reachableUrl =
await _pingActiveServerWithFallback(const Duration(seconds: 10));
if (reachableUrl == null) {
// One lost answer is often a short drop on the phone's side, so ask
// once more before tearing the online state down.
debugPrint('[Library] Health check missed - confirming before going offline');
await Future.delayed(const Duration(seconds: 3));
if (_networkOffline || _manualOffline || !_deviceHasConnectivity) return;
reachableUrl =
await _pingActiveServerWithFallback(const Duration(seconds: 10));
}
if (reachableUrl == null) {
debugPrint('[Library] Health check failed twice — server unreachable, going offline');
setNetworkOffline(true);
} else {
notifyServerReachable(reachableUrl);
// Safety net: if user info never loaded (e.g. /me failed at launch
// while the server was technically reachable), admin-only UI stays
// hidden. Idempotent once loaded.
unawaited(_auth?.ensureUserInfoLoaded() ?? Future.value());
}
});
}
void _stopHealthCheckTimer() {
_healthCheckTimer?.cancel();
_healthCheckTimer = null;
}
/// BookOrbit pushes no progress events, so while the app is open the book
/// sitting paused in the player is checked against the server instead, and
/// a newer position from another device goes through the same handler the
/// Audiobookshelf socket feeds. Its notification feed runs alongside.
void _startBookOrbitPoll() {
_bookOrbitPollTimer?.cancel();
_bookOrbitPollTimer = null;
final api = _api;
if (_auth?.isBookOrbit != true || api == null ||
_isBackgrounded || _readerQuiet || PlayerSettings.einkMode) {
BookOrbitNotificationSocket.instance.stop();
return;
}
_bookOrbitPollTimer = Timer.periodic(
const Duration(seconds: 30), (_) => _pollPausedBookProgress());
unawaited(BookOrbitNotificationSocket.instance.start(api));
}
void _stopBookOrbitPoll() {
_bookOrbitPollTimer?.cancel();
_bookOrbitPollTimer = null;
BookOrbitNotificationSocket.instance.stop();
}
Future<void> _pollPausedBookProgress() async {
final api = _api;
if (api == null || !api.isBookOrbit || isOffline) return;
final player = AudioPlayerService();
final itemId = player.currentItemId;
if (!player.hasBook || player.isPlaying || itemId == null) return;
if (player.currentEpisodeId != null) return;
try {
final mp = await api.getItemProgress(itemId);
if (mp == null || player.isPlaying || player.currentItemId != itemId) return;
final serverUpd = (mp['lastUpdate'] as num?)?.toInt() ?? 0;
if (serverUpd <= await ProgressSyncService().getSavedTimestamp(itemId)) return;
// A chapter picked or a start still loading moved the player after the
// server's save, without saving yet.
if (serverUpd <= (player.lastSeekAt?.millisecondsSinceEpoch ?? 0)) return;
debugPrint('[Sync] BookOrbit has a newer position for the paused book');
_onRemoteProgressUpdated(mp);
} catch (e) {
debugPrint('[Sync] BookOrbit progress poll failed: $e');
}
}
// ── Battery-saving lifecycle ──
void onAppBackgrounded() {
_isBackgrounded = true;
_backgroundedAt = DateTime.now();
_stopServerPingTimer();
_stopHealthCheckTimer();
_stopBookOrbitPoll();
if (!AudioPlayerService().isPlaying) {
_stopLocalProbeTimer();
}
_softDisconnectSocket(); // Always disconnect, even during playback
}
// The socket stays connected the whole time the app is foregrounded: the
// screen dominates battery while the app is visible, an idle websocket is
// just ping frames, and live updates (progress sync, scan results) are worth
// it. The old 5-minute foreground idle disconnect is gone; backgrounding
// still tears the socket down.
void onAppForegrounded() {
_isBackgrounded = false;
// Coming back to a book that's still open: stay quiet, the reader will say
// when it closes.
if (_readerQuiet) {
debugPrint('[Library] Foregrounded into the reader - staying quiet');
return;
}
_resumeLiveWork(quietSince: _backgroundedAt);
}
/// The ebook reader keeps the app foregrounded with nothing on screen that
/// needs live data, so while it's open the app drops to its background
/// behavior: no socket, no polling. Page turns still push progress over
/// HTTP, and playback keeps its own work running.
bool get readerQuiet => _readerQuiet;
void setReaderQuiet(bool quiet) {
if (_readerQuiet == quiet) return;
_readerQuiet = quiet;
PlayerScreenWake.covered.value = quiet;
if (quiet) {
_readerQuietAt = DateTime.now();
debugPrint('[Library] Reader open - quieting live work');
_stopServerPingTimer();
_stopHealthCheckTimer();
_stopBookOrbitPoll();
if (!AudioPlayerService().isPlaying) _stopLocalProbeTimer();
_softDisconnectSocket();
return;
}
final since = _readerQuietAt;
_readerQuietAt = null;
debugPrint('[Library] Reader closed - waking live work');
// Backgrounded while reading: the background handler owns the wake-up.
if (_isBackgrounded) return;
_resumeLiveWork(quietSince: since);
}
/// E-ink mode holds the app in its quiet state permanently: no socket, no
/// foreground polling, battery first. Progress still syncs over plain HTTP.
/// Called when the settings toggle flips; startup needs no call because the
/// socket and timer entry points all check PlayerSettings.einkMode.
void applyEinkMode(bool on) {
if (on) {
debugPrint('[Library] E-ink mode on - quieting live work');
_stopServerPingTimer();
_stopHealthCheckTimer();
_stopBookOrbitPoll();
if (!AudioPlayerService().isPlaying) _stopLocalProbeTimer();
_softDisconnectSocket();
return;
}
if (_isBackgrounded || _readerQuiet) return;
debugPrint('[Library] E-ink mode off - waking live work');
_resumeLiveWork();
}
/// Bring back the socket and the polling this app does while it's visible
/// and awake. [quietSince] is when live work stopped, so a long gap can
/// replay what the socket would have delivered.
void _resumeLiveWork({DateTime? quietSince}) {
if (_auth?.isBookOrbit == true) unawaited(_api?.ensureMediaReady());
_softReconnectSocket();
_startBookOrbitPoll();
if (_networkOffline && _deviceHasConnectivity && !_manualOffline) {
_startServerPingTimer();
} else if (!_networkOffline && !_manualOffline) {
_startHealthCheckTimer();
}
_startLocalProbeTimer();
if (!isOffline && !_manualOffline) {
(this as LibraryProvider).checkSubscribedPodcasts();
// Item events emitted while the socket was down are never replayed, so
// anything edited from another device would stay stale forever. Skip
// quick gaps - a fresh socket has nothing to have missed.
final away = quietSince == null
? null
: DateTime.now().difference(quietSince);
if (away != null && away > const Duration(seconds: 30)) {
_catchUpAfterBackground();
if (_auth?.isBookOrbit == true) {
unawaited(_pollPausedBookProgress());
unawaited(_catchUpRemoteProgress());
}
}
}
}
/// Re-sync what the missed socket events would have delivered: reload the
/// home shelves, and sweep the most recently updated items in the current
/// library to bump cover cache-busters and patch the search index.
Future<void> _catchUpAfterBackground() async {
loadPersonalizedView(force: true);
final api = _api;
final libId = _selectedLibraryId;
if (api == null || libId == null) return;
try {
final data = await api.getLibraryItems(libId,
sort: 'updatedAt', desc: 1, limit: 50);
final results = data?['results'] as List? ?? const [];
var changed = false;
for (final r in results) {
final item = (r is Map<String, dynamic>)
? (r['libraryItem'] as Map<String, dynamic>? ?? r)
: null;
if (item == null) continue;
final id = item['id'] as String?;
final ts = item['updatedAt'] as num?;
if (id == null || ts == null) continue;
final cur = _itemUpdatedAt[id];
if (cur == null || ts.toInt() > cur) {
registerUpdatedAt(id, ts.toInt());
changed = true;
}
BookSearchIndex().patchItem(item);
}
if (changed) notifyListeners();
} catch (_) {}
}
void onPlaybackStarted() {
if (!_isBackgrounded && !_readerQuiet) {
_softReconnectSocket();
}
_startLocalProbeTimer();
}
void onPlaybackStopped() {
if (_isBackgrounded || _readerQuiet) {
_softDisconnectSocket();
_stopLocalProbeTimer();
}
}
void _softDisconnectSocket() {
if (_socketSoftDisconnected || _manualOffline) return;
_socketSoftDisconnected = true;
SocketService().softDisconnect();
}
void _softReconnectSocket() {
if (_manualOffline || PlayerSettings.einkMode) return;
if (!_socketSoftDisconnected && !SocketService().hasSocket) {
_socketSoftDisconnected = true;
}
if (!_socketSoftDisconnected) return;
_socketSoftDisconnected = false;
SocketService().softReconnect();
}
void _onSocketReconnectFailed() {
debugPrint('[Library] Socket reconnection failed — going offline');
_goOffline();
}
void _onEncodeFinished(Map<String, dynamic> data) {
final navigator = rootNavigatorKey.currentState;
if (navigator == null) return;
final l = AppLocalizations.of(navigator.context);
showNavigatorOverlayToast(
navigator,
l?.encodeFinished ?? 'M4B encode finished',
icon: Icons.check_circle_outline_rounded,
);
}
void _goOffline() {
if (_networkOffline) return;
debugPrint('[Library] Network error — going offline');
_networkOffline = true;
_buildOfflineSections();
notifyListeners();
if (_deviceHasConnectivity && !_manualOffline) _startServerPingTimer();
}
// ── Socket event handlers ──
DateTime? _lastProgressCatchUp;
/// The socket only delivers progress events while connected - anything
/// that happens during a backgrounded gap is lost for good, which left
/// finished-elsewhere books sitting in Absorbing until a tap un-finished
/// them. On every socket auth, pull the server's progress list and replay
/// entries newer than what we hold through the same handler the live
/// event uses, so pruning and shelf refreshes behave identically.
Future<void> _catchUpRemoteProgress() async {
final api = _api;
if (api == null) return;
final now = DateTime.now();
if (_lastProgressCatchUp != null &&
now.difference(_lastProgressCatchUp!) < const Duration(seconds: 45)) {
return;
}
_lastProgressCatchUp = now;
try {
final list = await api.getAllProgress();
if (list == null) return;
var applied = 0;
for (final mp in list) {
final itemId = mp['libraryItemId'] as String?;
if (itemId == null) continue;
final episodeId = mp['episodeId'] as String?;
final key = episodeId != null ? '$itemId-$episodeId' : itemId;
final serverUpd = (mp['lastUpdate'] as num?)?.toInt() ?? 0;
final localUpd =
((_progressMap[key]?['lastUpdate']) as num?)?.toInt() ?? 0;
if (serverUpd <= localUpd) continue;
// What this device saved itself counts too, not just the last
// server value it happened to see - otherwise a reconnect after an
// offline stretch replays the server's pre-outage position over it.
final savedAt = await ProgressSyncService().getSavedTimestamp(key);
if (serverUpd <= savedAt) continue;
_onRemoteProgressUpdated(mp);
applied++;
}
if (applied > 0) {
debugPrint('[Sync] Progress catch-up applied $applied newer entries');
}
} catch (e) {
debugPrint('[Sync] Progress catch-up failed: $e');
}
}
/// A start reads the position this phone saved, and only asks the server
/// for a couple of seconds before playing. On a slow server that loses,
/// and the book resumes from a spot another device has long moved past
/// even though its newer position already arrived here. Store it where
/// the start looks, but only when it's newer than this phone's own save.
Future<void> _storeNewerServerPosition(
String key, Map<String, dynamic> mp) async {
if (mp['isFinished'] == true) return;
// BookOrbit's list carries only a percent for some books, with a
// currentTime of 0 that is no place at all: storing it sent the next
// start back to the beginning.
if (mp['positionUnknown'] == true) return;
final serverTime = (mp['currentTime'] as num?)?.toDouble();
final serverUpd = (mp['lastUpdate'] as num?)?.toInt() ?? 0;
if (serverTime == null || serverUpd <= 0) return;
final sync = ProgressSyncService();
if (serverUpd <= await sync.getSavedTimestamp(key)) return;
final local = await sync.getLocal(key);
final localTime = (local?['currentTime'] as num?)?.toDouble();
if (localTime != null && (localTime - serverTime).abs() < 1.0) return;
final duration = (mp['duration'] as num?)?.toDouble() ??
(local?['duration'] as num?)?.toDouble() ??
0;
await sync.cacheServerProgress(
itemId: key,
currentTime: serverTime,
duration: duration,
overridePending: true,
);
debugPrint('[Sync] Stored newer server position for $key: '
'${localTime?.toStringAsFixed(1) ?? '-'}s -> ${serverTime.toStringAsFixed(1)}s');
}
void _onRemoteProgressUpdated(Map<String, dynamic> mp) {
final itemId = mp['libraryItemId'] as String?;
final episodeId = mp['episodeId'] as String?;
if (itemId == null) return;
final key = episodeId != null ? '$itemId-$episodeId' : itemId;
if (_locallyFinishedItems.contains(key) && mp['isFinished'] != true) return;
final player = AudioPlayerService();
final playingKey = player.currentEpisodeId != null
? '${player.currentItemId}-${player.currentEpisodeId}'
: player.currentItemId;
if (!(key == playingKey && player.isPlaying)) {
unawaited(_storeNewerServerPosition(key, mp));
}
if (key == playingKey && player.hasBook) {
if (mp['isFinished'] == true && !_resetItems.contains(key)) {
// Re-reading a finished book: the server keeps isFinished=true and
// echoes it back after every sync. Pinning the override to 100%
// while this device is actively mid-listen drags every inactive
// view to the end of the book (GH #345) - only honor the echo when
// we aren't the ones listening far from the end.
final posS = player.position.inMilliseconds / 1000.0;
final durS = player.totalDuration;
final nearEnd = durS <= 0 || posS >= durS - 60;
if (!player.isPlaying || nearEnd) {
(this as _AbsorbingMixin)
.markFinishedLocally(key, skipAutoAdvance: true, fromRemote: true);
}
} else if (mp['isFinished'] != true) {
final prevUpd = ((_progressMap[key]?['lastUpdate']) as num?)?.toInt() ?? 0;
final newUpd = (mp['lastUpdate'] as num?)?.toInt() ?? 0;
_progressMap[key] = mp;
_localProgressOverrides.remove(key);
_resetItems.remove(key);
// Cross-device continuity: a newer position from another device
// moves the paused player too, so the card shows it and resume
// carries on from there instead of the stale pause point.
final serverTime = (mp['currentTime'] as num?)?.toDouble();
if (serverTime != null &&
newUpd > prevUpd &&
!player.isPlaying &&
!ChromecastService().isCasting) {
// "Newer than the last server value we saw" is not "newer than
// where this phone got to": after an hour offline the server still
// holds the position from before the outage, and adopting it drags
// the paused player back and then syncs that old spot up over the
// real one. The position saved here carries its own timestamp.
unawaited(() async {
// This phone's own sync coming back can only be behind where it
// is now (GH #440), whatever the clocks say.
final from = mp['fromSession'];
if (from != null && from == player.playbackSessionId) {
debugPrint('[Sync] Ignoring remote position for paused player: '
"it is this phone's own sync ($from)");
return;
}
final savedAt =
await ProgressSyncService().getSavedTimestamp(key);
if (newUpd <= savedAt) {
debugPrint('[Sync] Ignoring remote position for paused player: '
'server ${serverTime.toStringAsFixed(1)}s ($newUpd) is older '
'than what this phone saved ($savedAt)');
return;
}
final movedAt = player.lastSeekAt?.millisecondsSinceEpoch ?? 0;
if (newUpd <= movedAt) {
debugPrint('[Sync] Ignoring remote position for paused player: '
'server ${serverTime.toStringAsFixed(1)}s ($newUpd) is older '
'than the last move here ($movedAt)');
return;
}
if (player.isPlaying) return;
final posS = player.position.inMilliseconds / 1000.0;
if ((serverTime - posS).abs() > 5.0) {
debugPrint('[Sync] Adopting newer remote position for paused player: '
'${posS.toStringAsFixed(1)}s -> ${serverTime.toStringAsFixed(1)}s');
await player.seekTo(
Duration(milliseconds: (serverTime * 1000).round()));
}
}());
}
notifyListeners();
}
return;
}
_progressMap[key] = mp;
_localProgressOverrides.remove(key);
_resetItems.remove(key);
(this as _AbsorbingMixin)._pruneRemotelyFinishedBooks([key]);
notifyListeners();
_progressRefreshDebounce?.cancel();
_progressRefreshDebounce = Timer(const Duration(seconds: 2), () {
refreshProgressShelves(reason: 'remote-progress');
});
}
void _onRemoteItemUpdated(Map<String, dynamic> data) {
// Update cover cache buster timestamp
final id = data['id'] as String?;
final ts = data['updatedAt'] as num?;
if (id != null && ts != null) {
registerUpdatedAt(id, ts.toInt());
// Mirror into AA/CarPlay so the next browse-tree refresh hands out a
// ts-suffixed cover URI and the native cover cache can invalidate.
if (!AppPlatform.lacksPhonePlugins) {
AndroidAutoService.notifyItemUpdated(id, ts.toInt());
}
}
if (id != null) {
final coverPath = (data['media'] as Map<String, dynamic>?)?['coverPath'] as String?;
registerHasCover(id, coverPath != null && coverPath.isNotEmpty);
}
// Invalidate cached session metadata - track URLs may have changed
if (id != null) SessionCache.clear(itemId: id);
loadPersonalizedView(force: true);
_checkSubscribedPodcastUpdate(data);
}
void _onRemoteItemRemoved(Map<String, dynamic> data) {
final id = data['id'] as String?;
if (id != null) SessionCache.clear(itemId: id);
loadPersonalizedView(force: true);
}
void _onRemoteSeriesUpdated() {
loadPersonalizedView(force: true);
(this as LibraryProvider).loadSeries();
}
void _onRemoteCollectionUpdated() {
loadPersonalizedView(force: true);
loadCollections();
}
void _onRemotePlaylistUpdated() {
loadPlaylists();
}
void _onRemoteUserUpdated(Map<String, dynamic> data) {
// Sync bookmarks from user_updated event
final bookmarks = data['bookmarks'] as List<dynamic>?;
if (bookmarks != null && _api != null) {
// Group server bookmarks by libraryItemId
final byItem = <String, List<Map<String, dynamic>>>{};
for (final b in bookmarks) {
if (b is Map<String, dynamic>) {
final id = b['libraryItemId'] as String? ?? '';
if (id.isNotEmpty) byItem.putIfAbsent(id, () => []).add(b);
}
}
// Sync each item that has bookmarks, plus the currently playing item
final player = AudioPlayerService();
final currentId = player.currentItemId;
final idsToSync = <String>{...byItem.keys};
if (currentId != null) idsToSync.add(currentId);
for (final itemId in idsToSync) {
BookmarkService().syncBookmarks(itemId, _api!,
preloadedServerBookmarks: byItem[itemId] ?? []);
}
}
final progressList = data['mediaProgress'] as List<dynamic>?;
if (progressList != null) {
final player = AudioPlayerService();
final updatedKeys = <String>[];
final playingKey = player.currentEpisodeId != null
? '${player.currentItemId}-${player.currentEpisodeId}'
: player.currentItemId;
for (final mp in progressList) {
if (mp is Map<String, dynamic>) {
final itemId = mp['libraryItemId'] as String?;
final episodeId = mp['episodeId'] as String?;
if (itemId != null) {
final key = episodeId != null ? '$itemId-$episodeId' : itemId;
if (_locallyFinishedItems.contains(key) && mp['isFinished'] != true) continue;
if (key == playingKey && player.hasBook) continue;
_progressMap[key] = mp;
_localProgressOverrides.remove(key);
updatedKeys.add(key);
}
}
}
(this as _AbsorbingMixin)._pruneRemotelyFinishedBooks(updatedKeys);
notifyListeners();
} else {
_progressRefreshDebounce?.cancel();
_progressRefreshDebounce = Timer(const Duration(milliseconds: 800), () {
refreshProgressShelves(force: true, reason: 'user-updated');
});
}
}
// ── Personalized home view ──
Future<void> loadPersonalizedView({bool force = false}) async {
final existing = _personalizedInFlight;
if (existing != null) {
await existing;
return;
}
// Per-library cooldown, so a book <-> podcast tab flip that returns
// within the window reuses the cached sections instead of refetching.
if (!force) {
final fetchedAt = _sectionsFetchedAt[_selectedLibraryId];
if (fetchedAt != null &&
DateTime.now().difference(fetchedAt) <
_StateMixin._personalizedFetchCooldown) {
return;
}
}
final inFlight = _doLoadPersonalizedView();
_personalizedInFlight = inFlight;
try {
await inFlight;
} finally {
if (identical(_personalizedInFlight, inFlight)) {
_personalizedInFlight = null;
}
}
}
Future<void> _doLoadPersonalizedView() async {
if (_api == null || _selectedLibraryId == null) return;
if (isOffline) {
_buildOfflineSections();
return;
}
final hadData = _personalizedSections.isNotEmpty;
if (!hadData) {
_isLoading = true;
notifyListeners();
}
try {
await _refreshProgress();
_personalizedSections = _withoutJustHidden(await _api!.getPersonalizedView(
_selectedLibraryId!,
include: const ['numEpisodesIncomplete'],
) ??
[]);
for (final section in _personalizedSections) {
for (final e in (section['entities'] as List<dynamic>? ?? [])) {
if (e is Map<String, dynamic>) {
final id = e['id'] as String?;
final ts = e['updatedAt'] as num?;
if (id != null && ts != null) registerUpdatedAt(id, ts.toInt());
if (id != null) {
final coverPath = (e['media'] as Map<String, dynamic>?)?['coverPath'] as String?;
registerHasCover(id, coverPath != null && coverPath.isNotEmpty);
}
}
}
}
// Playlists and collections load straight away: they came last, and a
// podcast-only step below that threw skipped them (GH #413).
loadPlaylists();
loadCollections();
_narratedToContinueListening();
await (this as _AbsorbingMixin)._updateAbsorbingCache();
_injectDownloadedSection();
// Snapshot after injection so a tab flip restores the full shelf set.
_sectionsByLibrary[_selectedLibraryId!] = _personalizedSections;
_sectionsFetchedAt[_selectedLibraryId!] = DateTime.now();
SiriService().scheduleCatalogUpdate();
if (isPodcastLibrary) {
_hydrateRssFeedFieldsDeferred();
}
} catch (e) {
if (_isLikelyNetworkError(e)) {
_goOffline();
} else {
debugPrint('[Library] Non-network error (staying online): $e');
}
}
_isLoading = false;
notifyListeners();
}
Future<void> refreshProgressShelves({
bool force = false,
String reason = 'unknown',
}) async {
if (_api == null || _selectedLibraryId == null || isOffline) return;
if (_personalizedSections.isEmpty) {
await loadPersonalizedView(force: force);
return;
}
final existing = _progressShelvesInFlight;
if (existing != null) {
await existing;
// A forced refresh wants an answer from after it was asked for.
if (!force) return;
if (_progressShelvesInFlight != null) {
await _progressShelvesInFlight;
return;
}
}
if (!force &&
_lastProgressShelvesFetchAt != null &&
_lastProgressShelvesLibraryId == _selectedLibraryId &&
DateTime.now().difference(_lastProgressShelvesFetchAt!) <
_StateMixin._progressShelvesFetchCooldown) {
return;
}
final inFlight = _loadProgressShelves(reason: reason);
_progressShelvesInFlight = inFlight;
try {
await inFlight;
} finally {
if (identical(_progressShelvesInFlight, inFlight)) {
_progressShelvesInFlight = null;
}
}
}
Future<void> _loadProgressShelves({required String reason}) async {
final api = _api;
final libraryId = _selectedLibraryId;
if (api == null || libraryId == null) return;
try {
final sections = await api.getPersonalizedView(
libraryId,
include: const ['numEpisodesIncomplete'],
shelves: _StateMixin._progressDrivenShelfIds,
limit: 10,
) ??
[];
_lastProgressShelvesFetchAt = DateTime.now();
_lastProgressShelvesLibraryId = libraryId;
if (_selectedLibraryId != libraryId || isOffline) return;
_mergeProgressShelves(sections);
await (this as _AbsorbingMixin)._updateAbsorbingCache();
notifyListeners();
debugPrint(
'[Library] refreshProgressShelves reason=$reason sections=${sections.length}');
} catch (e) {
debugPrint('[Library] refreshProgressShelves error ($reason): $e');
}
}
void _mergeProgressShelves(List<dynamic> sections) {
final updatedById = <String, dynamic>{};
for (final section in sections) {
if (section is Map<String, dynamic>) {
final id = section['id'] as String?;
if (id != null && _StateMixin._progressDrivenShelfIds.contains(id)) {
updatedById[id] = section;
}
}
}
final merged = <dynamic>[];
final seen = <String>{};
for (final section in _personalizedSections) {
if (section is! Map<String, dynamic>) {
merged.add(section);
continue;
}
final id = section['id'] as String?;
if (id == null) {
merged.add(section);
continue;
}
if (_StateMixin._progressDrivenShelfIds.contains(id)) {
final replacement = updatedById[id];
if (replacement != null) {
merged.add(replacement);
seen.add(id);
}
} else {
merged.add(section);
}
}
for (final id in _StateMixin._progressDrivenShelfIds) {
final replacement = updatedById[id];
if (replacement != null && !seen.contains(id)) {
merged.add(replacement);
}
}
_personalizedSections = _withoutJustHidden(merged);
_narratedToContinueListening();
}
/// Audiobookshelf sees only an ebook in an EPUB that reads itself aloud, so
/// one being listened to comes back under Continue Reading. Absorb plays it
/// as an audiobook, so while it has listening progress it moves to Continue
/// Listening. One only being read stays where it is.
void _narratedToContinueListening() {
final api = _api;
if (api == null || api.isBookOrbit || isPodcastLibrary) return;
final sections = _personalizedSections;
final ri = sections.indexWhere((s) => s is Map<String, dynamic> && s['id'] == 'continue-reading');
if (ri < 0) return;
final reading = sections[ri] as Map<String, dynamic>;
final keep = <dynamic>[];
final moved = <Map<String, dynamic>>[];
for (final e in (reading['entities'] as List<dynamic>? ?? const [])) {
final id = e is Map<String, dynamic> ? e['id'] as String? : null;
final listened = id != null &&
NarratedBooks.contains(id) &&
_progressMap[id]?['isFinished'] != true &&
(((_progressMap[id]?['currentTime'] as num?) ?? 0) > 0 ||
(_localProgressOverrides[id] ?? 0) > 0);
if (listened) {
moved.add(e as Map<String, dynamic>);
} else {
keep.add(e);
}
}
if (moved.isEmpty) return;
final li = sections.indexWhere((s) => s is Map<String, dynamic> && s['id'] == 'continue-listening');
final listening = li < 0 ? null : sections[li] as Map<String, dynamic>;
final entities = List<dynamic>.from(listening?['entities'] as List<dynamic>? ?? const []);
int at(dynamic e) {
if (e is! Map<String, dynamic>) return 0;
final v = e['progressLastUpdate'] ?? _progressMap[e['id']]?['lastUpdate'];
return v is num ? v.toInt() : 0;
}
for (final m in moved) {
if (entities.any((e) => e is Map<String, dynamic> && e['id'] == m['id'])) continue;
final when = at(m);
final i = entities.indexWhere((e) => at(e) < when);
entities.insert(i < 0 ? entities.length : i, m);
}
final next = List<dynamic>.from(sections);
next[ri] = {...reading, 'entities': keep};
final shelf = <String, dynamic>{
...?listening,
'id': 'continue-listening',
'label': listening?['label'] ?? 'Continue Listening',
'type': listening?['type'] ?? 'book',
'entities': entities,
};
if (li < 0) {
next.insert(0, shelf);
} else {
next[li] = shelf;
}
_personalizedSections = next;
debugPrint('[Narration] ${moved.length} narrated book(s) moved from Continue Reading to Continue Listening');
}
void _hydrateRssFeedFieldsDeferred() {
final api = _api;
final libraryId = _selectedLibraryId;
if (api == null || libraryId == null || isOffline) return;
if (_rssHydrationInFlight) return;
final now = DateTime.now();
if (_lastRssHydrationLibraryId == libraryId &&
_lastRssHydrationAt != null &&
now.difference(_lastRssHydrationAt!) < _StateMixin._rssHydrationCooldown) {
return;
}
_rssHydrationInFlight = true;
unawaited(() async {
try {
final sections = await api.getPersonalizedView(
libraryId,
include: const ['numEpisodesIncomplete', 'rssfeed'],
) ??
[];
_lastRssHydrationAt = DateTime.now();
_lastRssHydrationLibraryId = libraryId;
if (_selectedLibraryId == libraryId && sections.isNotEmpty) {
_personalizedSections = _withoutJustHidden(sections);
await (this as _AbsorbingMixin)._updateAbsorbingCache();
notifyListeners();
}
} catch (_) {
} finally {
_rssHydrationInFlight = false;
}
}());
}
// ── Playlists ──
Future<void> loadPlaylists({bool force = false}) async {
if (_api == null || _selectedLibraryId == null || isOffline) return;
final libId = _selectedLibraryId!;
// A load already running for another library (a switch mid-load) would
// hand this one that library's playlists.
final existing = _playlistsInFlight;
if (existing != null && _playlistsInFlightFor == libId) {
await existing;
return;
}
final inFlight = _doLoadPlaylists(libId);
_playlistsInFlight = inFlight;
_playlistsInFlightFor = libId;
try {
await inFlight;
} finally {
if (identical(_playlistsInFlight, inFlight)) {
_playlistsInFlight = null;
_playlistsInFlightFor = null;
}
}
}
Future<void> _doLoadPlaylists([String? forLibrary]) async {
final libId = forLibrary ?? _selectedLibraryId;
if (_api == null || libId == null) return;
_isLoadingPlaylists = true;
try {
// Keep whatever we already had when the request fails, rather than
// blanking the shelves over one bad response.
final loaded = await _api!.getLibraryPlaylists(libId);
if (loaded != null && _selectedLibraryId == libId) _playlists = loaded;
debugPrint('[Library] playlists for $libId: ${loaded?.length ?? 'failed'}');
} catch (e) {
debugPrint('[Library] playlists for $libId failed: $e');
}
_isLoadingPlaylists = false;
notifyListeners();
unawaited(_catchUpQueueAutoDownloads());
}
Future<Map<String, dynamic>?> createPlaylist(String name) async {
if (_api == null || _selectedLibraryId == null) return null;
if (_api!.isBookOrbit) return createCollection(name);
final result = await _api!.createPlaylist(_selectedLibraryId!, name);
if (result != null) {
_playlists = [..._playlists, result];
notifyListeners();
}
return result;
}
Future<bool> addToPlaylist(
String playlistId,
String libraryItemId, {
String? episodeId,
}) async {
if (_api == null) return false;
if (_api!.isBookOrbit) return addToCollection(playlistId, libraryItemId);
final updated = await _api!.addItemToPlaylist(
playlistId, libraryItemId, episodeId: episodeId,
);
if (updated != null) {
await _doLoadPlaylists();
return true;
}
return false;
}
Future<bool> removeFromPlaylist(
String playlistId,
String libraryItemId, {
String? episodeId,
}) async {
if (_api == null) return false;
if (_api!.isBookOrbit) return removeFromCollection(playlistId, libraryItemId);
final updated = await _api!.removeItemFromPlaylist(
playlistId, libraryItemId, episodeId: episodeId,
);
if (updated != null) {
await _doLoadPlaylists();
return true;
}
return false;
}
Future<bool> reorderPlaylistItems(
String playlistId,
List<Map<String, dynamic>> reorderedItems,
) async {
if (_api == null) return false;
final itemRefs = reorderedItems.map((item) {
final ref = <String, dynamic>{'libraryItemId': item['libraryItemId']};
final eid = item['episodeId'] as String?;
if (eid != null) ref['episodeId'] = eid;
return ref;
}).toList();
final updated = await _api!.updatePlaylist(playlistId, items: itemRefs);
if (updated != null) {
await _doLoadPlaylists();
return true;
}
return false;
}
Future<bool> deletePlaylist(String playlistId) async {
if (_api == null) return false;
if (_api!.isBookOrbit) return await deleteCollection(playlistId) == 200;
final ok = await _api!.deletePlaylist(playlistId);
if (ok) {
_playlists = _playlists.where((p) => (p as Map)['id'] != playlistId).toList();
_hiddenSectionIds.remove('playlist:$playlistId');
_sectionOrder.remove('playlist:$playlistId');
await _saveSectionPrefs();
notifyListeners();
}
return ok;
}
// ── Collections ──
Future<void> loadCollections({bool force = false}) async {
if (_api == null || _selectedLibraryId == null || isOffline) return;
final libId = _selectedLibraryId!;
final existing = _collectionsInFlight;
if (existing != null && _collectionsInFlightFor == libId) {
await existing;
return;
}
final inFlight = _doLoadCollections(libId);
_collectionsInFlight = inFlight;
_collectionsInFlightFor = libId;
try {
await inFlight;
} finally {
if (identical(_collectionsInFlight, inFlight)) {
_collectionsInFlight = null;
_collectionsInFlightFor = null;
}
}
}
Future<void> _doLoadCollections([String? forLibrary]) async {
final libId = forLibrary ?? _selectedLibraryId;
if (_api == null || libId == null) return;
_isLoadingCollections = true;
try {
final loaded = await _api!.getLibraryCollections(libId);
if (loaded != null && _selectedLibraryId == libId) _collections = loaded;
} catch (_) {}
_isLoadingCollections = false;
notifyListeners();
unawaited(_catchUpQueueAutoDownloads());
}
/// A BookOrbit collection or Smart Scope that holds more books than the
/// Lists tab loaded.
bool collectionHasMore(String collectionId) {
final c = _collections
.whereType<Map<String, dynamic>>()
.where((c) => c['id'] == collectionId)
.firstOrNull;
if (c == null) return false;
final total = ((c['bookOrbit'] as Map?)?['total'] as num?)?.toInt();
return total != null && ((c['books'] as List<dynamic>?)?.length ?? 0) < total;
}
/// Loads the next page of such a collection's books. False when the page
/// could not be fetched.
Future<bool> loadMoreCollectionBooks(String collectionId) async {
final api = _api;
if (api == null || !collectionHasMore(collectionId)) return true;
final before = _collections
.whereType<Map<String, dynamic>>()
.firstWhere((c) => c['id'] == collectionId);
final have = (before['books'] as List<dynamic>?)?.length ?? 0;
final page = await api.collectionBooksPage(collectionId, page: have ~/ 100);
if (page == null) return false;
final at = _collections.indexWhere((c) => c is Map && c['id'] == collectionId);
if (at < 0) return true;
final current = _collections[at] as Map<String, dynamic>;
final books = [...(current['books'] as List<dynamic>? ?? const [])];
final seen = books.map((b) => (b as Map)['id']).toSet();
for (final b in page) {
if (seen.add(b['id'])) books.add(b);
}
final bo = Map<String, dynamic>.from(current['bookOrbit'] as Map? ?? const {});
// Rules can match fewer books than when the list loaded; stop at the end.
if (books.length == (current['books'] as List<dynamic>? ?? const []).length) {
bo['total'] = books.length;
}
_collections = [..._collections]..[at] = {...current, 'books': books, 'bookOrbit': bo};
notifyListeners();
return true;
}
Future<Map<String, dynamic>?> createCollection(String name, {List<String> books = const []}) async {
if (_api == null || _selectedLibraryId == null) return null;
final result = await _api!.createCollection(_selectedLibraryId!, name, books: books);
if (result != null) {
await _doLoadCollections();
}
return result;
}
Future<bool> addToCollection(String collectionId, String libraryItemId) async {
if (_api == null) return false;
final updated = await _api!.addBookToCollection(collectionId, libraryItemId);
if (updated != null) {
await _doLoadCollections();
return true;
}
return false;
}
Future<bool> removeFromCollection(String collectionId, String libraryItemId) async {
if (_api == null) return false;
final updated = await _api!.removeBookFromCollection(collectionId, libraryItemId);
if (updated != null) {
await _doLoadCollections();
return true;
}
return false;
}
Future<bool> setCollectionPublic(String collectionId, bool isPublic) async {
if (_api == null) return false;
final ok = await _api!.setCollectionPublic(collectionId, isPublic);
if (ok) await _doLoadCollections();
return ok;
}
Future<bool> reorderCollectionBooks(
String collectionId,
List<String> bookIds,
) async {
if (_api == null) return false;
final updated = await _api!.updateCollection(collectionId, books: bookIds);
if (updated != null) {
await _doLoadCollections();
return true;
}
return false;
}
/// Returns HTTP status code from the server (0 on exception, 200 on
/// success, 403 when caller lacks the `delete` permission flag).
Future<int> deleteCollection(String collectionId) async {
if (_api == null) return 0;
final status = await _api!.deleteCollection(collectionId);
if (status == 200) {
_collections = _collections.where((c) => (c as Map)['id'] != collectionId).toList();
_hiddenSectionIds.remove('collection:$collectionId');
_sectionOrder.remove('collection:$collectionId');
await _saveSectionPrefs();
notifyListeners();
}
return status;
}
// ── Section customization ──
Future<void> _loadSectionPrefs() async {
final libId = _selectedLibraryId ?? '';
final orderJson = await ScopedPrefs.getStringList('home_section_order_$libId');
final hiddenJson = await ScopedPrefs.getStringList('home_hidden_sections_$libId');
_sectionOrder = orderJson.toList();
if (hiddenJson.isEmpty && orderJson.isEmpty) {
_hiddenSectionIds = Set<String>.from(_defaultHiddenSections);
} else {
_hiddenSectionIds = hiddenJson.toSet();
}
_applyDefaultPlaylistCollectionHiding = false;
// Load persisted genre sections
final genreJson = await ScopedPrefs.getStringList('home_genre_sections_$libId');
_addedGenres = genreJson.toSet();
_genreSections = {};
// Fetch items for each added genre in background
for (final genre in _addedGenres) {
_fetchGenreSectionItems(genre);
}
}
Future<void> _saveSectionPrefs() async {
final libId = _selectedLibraryId ?? '';
await ScopedPrefs.setStringList('home_section_order_$libId', _sectionOrder);
await ScopedPrefs.setStringList('home_hidden_sections_$libId', _hiddenSectionIds.toList());
}
Future<void> saveSectionOrder(List<String> order) async {
_sectionOrder = List<String>.from(order);
_applyDefaultPlaylistCollectionHiding = false;
await _saveSectionPrefs();
notifyListeners();
}
Future<void> toggleSectionVisibility(String sectionId) async {
final updated = Set<String>.from(_hiddenSectionIds);
if (updated.contains(sectionId)) {
updated.remove(sectionId);
} else {
updated.add(sectionId);
}
_hiddenSectionIds = updated;
await _saveSectionPrefs();
notifyListeners();
}
static const _defaultHiddenSections = {'newest-authors', 'recent-series'};
// ── Genre home sections ──
Set<String> get addedGenres => _addedGenres;
Future<void> _fetchGenreSectionItems(String genre) async {
if (_api == null || _selectedLibraryId == null) return;
final filterValue = base64Encode(utf8.encode(genre));
final data = await _api!.getLibraryItems(
_selectedLibraryId!,
filter: 'genres.$filterValue',
limit: 20,
sort: 'addedAt',
desc: 1,
);
if (data == null) return;
final results = data['results'] as List<dynamic>? ?? [];
_genreSections[genre] = results;
notifyListeners();
}
Future<void> addGenreSection(String genre) async {
if (_addedGenres.contains(genre)) return;
_addedGenres.add(genre);
final libId = _selectedLibraryId ?? '';
await ScopedPrefs.setStringList('home_genre_sections_$libId', _addedGenres.toList());
await _fetchGenreSectionItems(genre);
notifyListeners();
}
Future<void> removeGenreSection(String genre) async {
_addedGenres.remove(genre);
_genreSections.remove(genre);
final sectionId = 'genre:$genre';
_sectionOrder.remove(sectionId);
_hiddenSectionIds.remove(sectionId);
final libId = _selectedLibraryId ?? '';
await ScopedPrefs.setStringList('home_genre_sections_$libId', _addedGenres.toList());
await _saveSectionPrefs();
notifyListeners();
}
List<Map<String, dynamic>> getOrderedHomeSections() {
final allSections = <String, Map<String, dynamic>>{};
for (final s in _personalizedSections) {
final id = (s as Map)['id'] as String? ?? '';
if (id.isEmpty) continue;
allSections[id] = Map<String, dynamic>.from(s);
}
for (final p in _playlists) {
final pm = p as Map<String, dynamic>;
final id = 'playlist:${pm['id']}';
allSections[id] = {
'id': id,
'label': pm['name'] ?? 'Playlist',
'type': 'playlist',
'entities': (pm['items'] as List<dynamic>?) ?? [],
'_playlistId': pm['id'],
};
}
for (final c in _collections) {
final cm = c as Map<String, dynamic>;
final id = 'collection:${cm['id']}';
allSections[id] = {
'id': id,
'label': _collectionSectionLabel(cm),
'type': 'collection',
'entities': (cm['books'] as List<dynamic>?) ?? [],
'_collectionId': cm['id'],
if (_isSmartScope(cm)) '_smartScope': true,
};
}
for (final genre in _addedGenres) {
final id = 'genre:$genre';
final items = _genreSections[genre] ?? [];
allSections[id] = {
'id': id,
'label': genre,
'type': 'book',
'entities': items,
};
}
allSections.removeWhere((id, _) => _hiddenSectionIds.contains(id));
if (_applyDefaultPlaylistCollectionHiding) {
allSections.removeWhere((id, _) =>
id.startsWith('playlist:') || id.startsWith('collection:'));
}
if (_sectionOrder.isEmpty) {
final result = <Map<String, dynamic>>[];
for (final s in _personalizedSections) {
final id = (s as Map)['id'] as String? ?? '';
if (allSections.containsKey(id)) result.add(allSections[id]!);
}
for (final p in _playlists) {
final id = 'playlist:${(p as Map)['id']}';
if (allSections.containsKey(id)) result.add(allSections[id]!);
}
for (final c in _collections) {
final id = 'collection:${(c as Map)['id']}';
if (allSections.containsKey(id)) result.add(allSections[id]!);
}
for (final genre in _addedGenres) {
final id = 'genre:$genre';
if (allSections.containsKey(id)) result.add(allSections[id]!);
}
return result;
}
final result = <Map<String, dynamic>>[];
for (final id in _sectionOrder) {
if (allSections.containsKey(id)) {
result.add(allSections.remove(id)!);
}
}
// An order saved before Continue Reading existed (BookOrbit had none)
// gets it next to Continue Listening rather than at the bottom.
final reading = allSections.remove('continue-reading');
result.addAll(allSections.values);
if (reading != null) {
final listening = result.indexWhere((s) => s['id'] == 'continue-listening');
result.insert(listening + 1, reading);
}
return result;
}
List<Map<String, String>> getAllSectionMeta() {
final result = <Map<String, String>>[];
for (final s in _personalizedSections) {
final id = (s as Map)['id'] as String? ?? '';
final label = s['label'] as String? ?? id;
if (id.isNotEmpty) result.add({'id': id, 'label': label});
}
for (final p in _playlists) {
final pm = p as Map<String, dynamic>;
result.add({
'id': 'playlist:${pm['id']}',
'label': pm['name'] as String? ?? 'Playlist',
});
}
for (final c in _collections) {
final cm = c as Map<String, dynamic>;
result.add({
'id': 'collection:${cm['id']}',
'label': _collectionSectionLabel(cm),
if (_isSmartScope(cm)) 'smartScope': 'true',
});
}
for (final genre in _addedGenres) {
result.add({
'id': 'genre:$genre',
'label': genre,
});
}
return result;
}
bool _isSmartScope(Map<String, dynamic> cm) =>
(cm['bookOrbit'] as Map?)?['smartScope'] == true;
// Audiobookshelf collections are shared by everyone on the server, so their
// rows say so. BookOrbit lists the user's own collections and Smart Scopes.
String _collectionSectionLabel(Map<String, dynamic> cm) {
final name = cm['name'] as String? ?? 'Collection';
final kind = cm['bookOrbit'] is! Map
? 'Server Collection'
: _isSmartScope(cm) ? 'Smart Scope' : 'Collection';
return '$kind - $name';
}
// ── Podcast subscriptions ──
Future<void> _loadKnownEpisodeIds() async {
for (final podcastId in _subscribedPodcasts) {
final ids = await ScopedPrefs.getStringList('known_episodes_$podcastId');
if (ids.isNotEmpty) {
_knownEpisodeIds[podcastId] = ids.toSet();
}
}
}
Future<void> _saveKnownEpisodeIds(String podcastId) async {
final ids = _knownEpisodeIds[podcastId];
if (ids != null) {
await ScopedPrefs.setStringList('known_episodes_$podcastId', ids.toList());
} else {
await ScopedPrefs.remove('known_episodes_$podcastId');
}
}
void _checkSubscribedPodcastUpdate(Map<String, dynamic> data) {
if (_subscribedPodcasts.isEmpty || _api == null || isOffline) return;
final itemId = data['id'] as String?;
if (itemId == null || !_subscribedPodcasts.contains(itemId)) return;
final mediaType = data['mediaType'] as String?;
if (mediaType != 'podcast') return;
_fetchAndCheckSubscribedPodcast(itemId);
}
Future<void> _fetchAndCheckSubscribedPodcast(String itemId) async {
if (_api == null || isOffline) return;
final item = await _api!.getLibraryItem(itemId);
if (item == null) return;
final media = item['media'] as Map<String, dynamic>? ?? {};
final episodes = media['episodes'] as List<dynamic>? ?? [];
final knownIds = _knownEpisodeIds[itemId];
if (knownIds == null) {
final ids = episodes
.map((e) => (e as Map<String, dynamic>)['id'] as String?)
.whereType<String>()
.toSet();
_knownEpisodeIds[itemId] = ids;
_saveKnownEpisodeIds(itemId);
debugPrint('[Subscription] Seeded $itemId with ${ids.length} episodes');
return;
}
// "Already seen" is tracked per device (known_episodes_ is not synced or
// backed up), so a phone that was off, or a second phone, meets episodes
// another device already announced. Progress DOES sync, so use it as the
// tiebreaker: an episode already listened to is not news, and re-downloading
// it is worse than not mentioning it. Record it as known and move on.
final newEpisodes = <Map<String, dynamic>>[];
var alreadyHeard = 0;
for (final ep in episodes) {
final epMap = ep as Map<String, dynamic>;
final epId = epMap['id'] as String?;
if (epId == null || knownIds.contains(epId)) continue;
final progress = getEpisodeProgressData(itemId, epId);
final finished = progress?['isFinished'] == true;
final started = ((progress?['currentTime'] as num?)?.toDouble() ?? 0) > 0;
if (finished || started) {
knownIds.add(epId);
alreadyHeard++;
continue;
}
newEpisodes.add(epMap);
}
if (alreadyHeard > 0) {
debugPrint(
'[Subscription] $alreadyHeard episode(s) for $itemId were already '
'listened to elsewhere - marking known, not announcing',
);
await _saveKnownEpisodeIds(itemId);
await EpisodeNotificationService.markAlreadySurfaced(
itemId,
knownIds,
);
}
if (newEpisodes.isNotEmpty) {
debugPrint('[Subscription] ${newEpisodes.length} new episode(s) for $itemId');
int queued = 0;
// Per-show choice of where the new episode lands in the absorbing queue.
final position = await PlayerSettings.getPodcastNewEpisodePosition(itemId);
// 'second' means the 2nd item the user actually sees. With merge on the
// queue is global, so that's index 1. With merge off the home view is
// filtered to this podcast's library, so insert after the first entry from
// the same library instead (otherwise an item from another library at
// index 0 would push this to visible-first). 'start'/'end' are the list
// extremes and read correctly in both modes, so they need no adjustment.
// 'none' subscribes without queueing: the episode is still detected,
// notified and downloaded, it just never lands on the absorbing list.
final queueless = position == 'none';
final merged = await PlayerSettings.getMergeAbsorbingLibraries();
final libId = item['libraryId'] as String?;
// The download step normally rediscovers episodes by scanning the
// absorbing queue, which finds nothing for a queue-less show, so the
// keys and their metadata have to be carried over explicitly.
final freshKeys = <String>[];
final freshMeta = <String, Map<String, dynamic>>{};
final freshEpIds = <String>[];
// For 'start', remember the front-most new episode so the absorbing
// screen's keep-on-top pins yield to it (otherwise a paused/last-finished
// item gets pulled above it and it shows 2nd).
String? startFrontKey;
for (final epMap in newEpisodes) {
final epId = epMap['id'] as String;
final key = '$itemId-$epId';
final entry = {
'id': itemId,
'libraryId': item['libraryId'] as String?,
'mediaType': 'podcast',
'_absorbingKey': key,
'recentEpisode': epMap,
'media': media,
};
freshKeys.add(key);
freshMeta[key] = entry;
if (!queueless) {
switch (position) {
case 'end':
_absorbingIdsAdd(key, atFront: false);
break;
case 'second':
if (merged) {
_absorbingIdsAdd(key, atIndex: 1);
} else {
final firstSameLib = _absorbingBookIds.indexWhere(
(k) => _absorbingItemCache[k]?['libraryId'] == libId);
_absorbingIdsAdd(key, atIndex: firstSameLib >= 0 ? firstSameLib + 1 : 0);
}
break;
default:
// The slot under the needle stays put: when the front card is
// the item that is loaded in the player, a new episode lands
// right behind it instead of on top - otherwise the card you
// are listening to "drops" to #2 the moment you pause.
final p = AudioPlayerService();
final activeKey = p.currentEpisodeId != null
? '${p.currentItemId}-${p.currentEpisodeId}'
: p.currentItemId;
final frontIsActive = p.hasBook &&
activeKey != null &&
_absorbingBookIds.isNotEmpty &&
_absorbingBookIds.first == activeKey;
if (frontIsActive) {
_absorbingIdsAdd(key, atIndex: 1);
} else {
_absorbingIdsAdd(key, atFront: true);
startFrontKey = key;
}
}
// Only cache what the queue will render. A queue-less show would
// otherwise grow this cache with entries nothing ever reads.
_absorbingItemCache[key] = entry;
_manualAbsorbAdds.add(key);
_manualAbsorbRemoves.remove(key);
}
freshEpIds.add(epId);
queued++;
}
if (queued > 0) {
if (startFrontKey != null) {
(this as _AbsorbingMixin).setFreshQueuedFront(startFrontKey);
}
if (!queueless) {
knownIds.addAll(freshEpIds);
_saveKnownEpisodeIds(itemId);
// The user is looking at these right now, queued and downloading, so
// the background job must not announce them hours later as news.
unawaited(EpisodeNotificationService.markAlreadySurfaced(
itemId,
freshEpIds,
));
(this as _AbsorbingMixin)._saveManualAbsorbing();
notifyListeners();
_downloadSubscribedEpisodes(itemId, keys: freshKeys, meta: freshMeta);
} else {
// Nothing queue-less lands on the absorbing list, so the catch-up
// pass has no way to rediscover these. Only mark them seen once the
// download is actually enqueued - if it was deferred for WiFi,
// leaving them unseen makes the next check retry instead of losing
// the episode entirely.
final started = await _downloadSubscribedEpisodes(itemId,
keys: freshKeys, meta: freshMeta);
if (started) {
knownIds.addAll(freshEpIds);
_saveKnownEpisodeIds(itemId);
unawaited(EpisodeNotificationService.markAlreadySurfaced(
itemId,
freshEpIds,
));
} else {
debugPrint('[Subscription] $itemId download deferred - leaving '
'${freshEpIds.length} episode(s) unseen so the next check retries');
}
}
}
}
}
Future<void> checkSubscribedPodcasts() async {
if (_subscribedPodcasts.isEmpty || _api == null) return;
for (final podcastId in _subscribedPodcasts) {
try {
await _fetchAndCheckSubscribedPodcast(podcastId);
} catch (e) {
debugPrint('[Subscription] Failed to check $podcastId: $e');
}
}
}
/// Downloads a subscribed show's episodes. [keys] names the exact episodes
/// (with [meta] carrying their details); without it the absorbing queue is
/// scanned instead, which is what the catch-up pass does. A queue-less show
/// must pass [keys] - its episodes never enter the queue, so a scan would
/// come back empty and silently download nothing.
///
/// Returns false when it bailed before enqueueing anything (offline, or
/// holding out for WiFi), so a caller that can't rely on the catch-up pass
/// knows the episodes still need retrying.
Future<bool> _downloadSubscribedEpisodes(
String podcastId, {
List<String>? keys,
Map<String, Map<String, dynamic>>? meta,
}) async {
if (AppPlatform.lacksPhonePlugins || _api == null || isOffline) return false;
final wifiOnly = await PlayerSettings.getWifiOnlyDownloads();
if (wifiOnly) {
final connectivity = await Connectivity().checkConnectivity();
if (!connectivity.contains(ConnectivityResult.wifi)) {
debugPrint('[Subscription] Skipping download (not on WiFi) - will retry on WiFi');
return false;
}
}
final dl = DownloadService();
int downloaded = 0;
final targets = keys ??
[for (final k in _absorbingBookIds) if (k.startsWith(podcastId)) k];
for (final key in targets) {
if (dl.isDownloaded(key) || dl.isDownloading(key)) continue;
final cached = meta?[key] ?? _absorbingItemCache[key];
// key is '<podcastId>-<episodeId>', so the offset follows the show id
// rather than assuming every id is a 36-char UUID.
final epId = key.substring(podcastId.length + 1);
final ep = cached?['recentEpisode'] as Map<String, dynamic>?;
final media = cached?['media'] as Map<String, dynamic>? ?? {};
final metadata = media['metadata'] as Map<String, dynamic>? ?? {};
dl.downloadItem(
api: _api!,
itemId: key,
automatic: true,
title: ep?['title'] as String? ?? 'Episode',
author: metadata['title'] as String? ?? '',
coverUrl: getCoverUrl(podcastId),
episodeId: epId,
libraryId: cached?['libraryId'] as String? ?? _selectedLibraryId,
);
downloaded++;
}
if (downloaded > 0) {
// A queue-less show has nothing in the absorbing cache, so fall back to
// the metadata that came in with this batch.
final cached = meta?.values.firstOrNull ??
_absorbingItemCache.values.firstWhere(
(c) => (c['id'] as String?) == podcastId,
orElse: () => {},
);
final media = cached['media'] as Map<String, dynamic>? ?? {};
final metadata = media['metadata'] as Map<String, dynamic>? ?? {};
final showTitle = metadata['title'] as String? ?? 'Podcast';
final position = await PlayerSettings.getPodcastNewEpisodePosition(podcastId);
final l = _l();
final String message;
switch (position) {
case 'none':
message = l?.lpSubscribedEpisodeDownloaded(showTitle)
?? 'New $showTitle episode downloaded';
break;
case 'end':
message = l?.lpSubscribedEpisodeAddedEnd(showTitle)
?? '$showTitle added to the end of your queue';
break;
case 'second':
message = l?.lpSubscribedEpisodeAddedSecond(showTitle)
?? '$showTitle added 2nd in your queue';
break;
default:
message = l?.lpSubscribedEpisodeAddedStart(showTitle)
?? '$showTitle added to the top of your queue';
}
final ctx = rootNavigatorKey.currentContext;
if (ctx != null) {
showOverlayToast(ctx,
message,
icon: position == 'none'
? Icons.download_done_rounded
: Icons.playlist_add_rounded);
}
}
return true;
}
Future<void> catchUpSubscribedPodcasts() async {
if (AppPlatform.lacksPhonePlugins ||
_subscribedPodcasts.isEmpty ||
_api == null ||
isOffline) {
return;
}
for (final podcastId in _subscribedPodcasts) {
await _downloadSubscribedEpisodes(podcastId);
}
}
// ── Rolling auto-download ──
/// Whether a progress entry shows real listening. A reset keeps the row:
/// Absorb's own reset writes it back with progress 0, position 0, hidden
/// from Continue Listening and the newest lastUpdate, so picking anchors
/// by lastUpdate alone let an accidentally played then reset episode drag
/// a whole show's rolling window to the newest episodes.
static bool _hasListened(Map<String, dynamic>? progress) {
if (progress == null) return false;
if (progress['hideFromContinueListening'] == true) return false;
final fraction = (progress['progress'] as num?)?.toDouble() ?? 0;
final currentTime = (progress['currentTime'] as num?)?.toDouble() ?? 0;
return fraction > 0 || currentTime > 0;
}
void _catchUpRollingDownloads() async {
if (AppPlatform.lacksPhonePlugins ||
_api == null ||
isOffline ||
_rollingDownloadSeries.isEmpty) {
return;
}
final wifiOnly = await PlayerSettings.getWifiOnlyDownloads();
if (wifiOnly) {
final connectivity = await Connectivity().checkConnectivity();
if (!connectivity.contains(ConnectivityResult.wifi)) return;
}
for (final seriesOrShowId in _rollingDownloadSeries.toList()) {
String? latestPodcastKey;
num latestPodcastUpdate = 0;
String? latestBookKey;
num latestBookUpdate = 0;
for (final entry in _progressMap.entries) {
final key = entry.key;
final data = entry.value;
if (data['isFinished'] == true) continue;
if (!_hasListened(data)) continue;
final lastUpdate = data['lastUpdate'] as num? ?? 0;
if (key.length > 36 && key.substring(0, 36) == seriesOrShowId) {
if (lastUpdate > latestPodcastUpdate) {
latestPodcastUpdate = lastUpdate;
latestPodcastKey = key;
}
} else if (key.length <= 36) {
final itemData = _itemDataWithSeries(key);
if (itemData != null) {
final (sid, _) = _StateMixin._extractSeries(itemData);
if (sid == seriesOrShowId && lastUpdate > latestBookUpdate) {
latestBookUpdate = lastUpdate;
latestBookKey = key;
}
}
}
}
if (latestPodcastKey != null) {
_checkRollingDownloads(latestPodcastKey);
} else if (latestBookKey != null) {
_checkRollingDownloads(latestBookKey);
}
}
await _catchUpListRollingDownloads();
}
void _checkRollingDownloads(String playingKey) async {
if (AppPlatform.lacksPhonePlugins) return;
final api = _api;
if (api == null || isOffline) return;
// With the "auto series download" default on, a book in a series enables
// rolling download for that series on first play (books only).
final autoSeriesDefault =
await PlayerSettings.getAutoSeriesDownloadDefault();
final player = AudioPlayerService();
final activeKey = player.currentEpisodeId == null
? player.currentItemId
: '${player.currentItemId}-${player.currentEpisodeId}';
final activeQueueMode = activeKey == null
? 'off'
: activeKey.length > 36
? await PlayerSettings.getPodcastQueueMode()
: await PlayerSettings.getBookQueueMode();
final globalQueueAutoDownload =
await PlayerSettings.getQueueAutoDownload();
if (_rollingDownloadSeries.isEmpty && !autoSeriesDefault) return;
final count = await PlayerSettings.getRollingDownloadCount();
_checkListRollingDownloads(playingKey, count);
if (playingKey.length > 36) {
final showId = playingKey.substring(0, 36);
final activeShowId = activeKey != null && activeKey.length > 36
? activeKey.substring(0, 36)
: null;
// Only an auto_next queue follows this same show; playlist and
// collection queues plan their own list's window instead, so they
// must not suppress the show's rolling download.
final activeQueueOwnsWindow = activeQueueMode == 'auto_next' &&
resolveQueueAutoDownloadEnabled(
queueMode: activeQueueMode,
globalEnabled: globalQueueAutoDownload,
activeSourceId: activeShowId,
activeSourceEnabled: activeShowId != null &&
_rollingDownloadSeries.contains(activeShowId),
);
if (activeQueueOwnsWindow && activeShowId == showId) return;
if (_rollingDownloadSeries.contains(showId)) {
_rollingDownloadPodcast(playingKey, count);
}
} else {
var data = _itemDataWithSeries(playingKey);
var (seriesId, _) = data != null ? _StateMixin._extractSeries(data) : (null, null);
if (seriesId == null) {
final fullItem = await api.getLibraryItem(playingKey);
if (fullItem != null) {
data = fullItem;
(seriesId, _) = _StateMixin._extractSeries(fullItem);
}
}
if (seriesId == null) return;
if (autoSeriesDefault && !_rollingDownloadSeries.contains(seriesId)) {
_rollingDownloadSeries.add(seriesId);
await _saveRollingDownloadSeries();
notifyListeners();
}
String? activeSeriesId;
if (activeKey != null && activeKey.length <= 36) {
if (activeKey == playingKey) {
activeSeriesId = seriesId;
} else {
var activeData = _itemDataWithSeries(activeKey);
(activeSeriesId, _) = activeData != null
? _StateMixin._extractSeries(activeData)
: (null, null);
if (activeSeriesId == null) {
activeData = await api.getLibraryItem(activeKey);
if (activeData != null) {
(activeSeriesId, _) = _StateMixin._extractSeries(activeData);
}
}
}
}
final activeQueueOwnsWindow = activeQueueMode == 'auto_next' &&
resolveQueueAutoDownloadEnabled(
queueMode: activeQueueMode,
globalEnabled: globalQueueAutoDownload,
activeSourceId: activeSeriesId,
activeSourceEnabled: activeSeriesId != null &&
_rollingDownloadSeries.contains(activeSeriesId),
);
if (activeQueueOwnsWindow && activeSeriesId == seriesId) return;
if (_rollingDownloadSeries.contains(seriesId)) {
_rollingDownloadBook(playingKey, count);
}
}
}
/// Per-playlist and per-collection auto-download. Mirrors how series behave:
/// it runs off whatever is playing and needs only the list's own toggle, so
/// the auto-play queue does not have to be in playlist or collection mode.
/// A list whose window the active queue already covers is skipped so the two
/// paths don't plan the same downloads twice.
Future<void> _checkListRollingDownloads(String playingKey, int count) async {
final api = _api;
if (api == null || isOffline || count <= 0) return;
if (_rollingDownloadSeries.isEmpty) return;
final self = this as LibraryProvider;
final sources =
<({String id, String kind, List<Map<String, dynamic>> items})>[];
for (final raw in _playlists) {
if (raw is! Map<String, dynamic>) continue;
final id = raw['id'] as String?;
if (id == null || !_rollingDownloadSeries.contains(id)) continue;
final items = (raw['items'] as List<dynamic>? ?? const [])
.whereType<Map<String, dynamic>>()
.toList();
if (items.isNotEmpty) {
sources.add((id: id, kind: 'playlist', items: items));
}
}
for (final raw in _collections) {
if (raw is! Map<String, dynamic>) continue;
final id = raw['id'] as String?;
if (id == null || !_rollingDownloadSeries.contains(id)) continue;
final items = self._collectionItems(raw);
if (items.isNotEmpty) {
sources.add((id: id, kind: 'collection', items: items));
}
}
if (sources.isEmpty) return;
final activeQueueMode = playingKey.length > 36
? await PlayerSettings.getPodcastQueueMode()
: await PlayerSettings.getBookQueueMode();
final globalAutoDownload = await PlayerSettings.getQueueAutoDownload();
final activePlaylistId = await PlayerSettings.getQueuePlaylistId();
final activeCollectionId = await PlayerSettings.getQueueCollectionId();
String? playingNow() {
final player = AudioPlayerService();
final itemId = player.currentItemId;
if (itemId == null) return null;
final episodeId = player.currentEpisodeId;
return episodeId == null ? itemId : '$itemId-$episodeId';
}
// Plans anchored to live playback abort when the user moves on; plans
// from catch-up or an idle toggle have no playback to go stale against.
final anchoredToPlayback = playingNow() == playingKey;
bool isStale() =>
_api == null ||
isOffline ||
(anchoredToPlayback && playingNow() != playingKey);
Future<bool> settingsStillMatch() async =>
!isStale() && await PlayerSettings.getRollingDownloadCount() == count;
for (final source in sources) {
if (isStale()) return;
final activeId =
source.kind == 'playlist' ? activePlaylistId : activeCollectionId;
final queueOwnsWindow = activeQueueMode == source.kind &&
activeId == source.id &&
resolveQueueAutoDownloadEnabled(
queueMode: activeQueueMode,
globalEnabled: globalAutoDownload,
activeSourceId: activeId,
activeSourceEnabled: _rollingDownloadSeries.contains(activeId),
);
if (queueOwnsWindow) {
debugPrint(
'[QueueDL] ${source.kind} ${source.id}: active queue already covers this window');
continue;
}
final window = queueTailFrom(
items: source.items,
currentKey: playingKey,
keyOf: self._playlistItemKey,
);
if (window.isEmpty) continue;
debugPrint(
'[QueueDL] ${source.kind} ${source.id}: ${source.items.length} items, window=${window.length} from $playingKey');
await _downloadQueueWindow(
items: window,
count: count,
api: api,
isStale: isStale,
settingsStillMatch: () async =>
await settingsStillMatch() &&
_rollingDownloadSeries.contains(source.id),
logLabel: '${source.kind}=${source.id}',
);
}
}
/// Plan list windows without a playback anchor: on launch/reconnect and
/// when a list's toggle is turned on while idle. Anchors at the member
/// with the most recent unfinished progress, or the first unfinished
/// member of a list that was never started. A list whose member is
/// currently playing is skipped - the playback-anchored check owns it.
Future<void> _catchUpListRollingDownloads({String? onlyListId}) async {
if (_api == null || isOffline || _rollingDownloadSeries.isEmpty) return;
final count = await PlayerSettings.getRollingDownloadCount();
if (count <= 0) return;
final self = this as LibraryProvider;
final player = AudioPlayerService();
final playingItemId = player.currentItemId;
final playingKey = playingItemId == null
? null
: player.currentEpisodeId == null
? playingItemId
: '$playingItemId-${player.currentEpisodeId}';
final anchors = <String>{};
void collectAnchor(String? id, List<Map<String, dynamic>> items) {
if (id == null || !_rollingDownloadSeries.contains(id)) return;
if (onlyListId != null && id != onlyListId) return;
String? latestKey;
num latestUpdate = -1;
String? firstUnfinishedKey;
for (final item in items) {
final key = self._playlistItemKey(item);
if (key.isEmpty) continue;
if (key == playingKey) return;
final progress = _progressMap[key];
if (progress?['isFinished'] == true) continue;
firstUnfinishedKey ??= key;
final lastUpdate = progress?['lastUpdate'] as num? ?? 0;
if (_hasListened(progress) && lastUpdate > latestUpdate) {
latestUpdate = lastUpdate;
latestKey = key;
}
}
final anchor = latestKey ?? firstUnfinishedKey;
if (anchor != null) anchors.add(anchor);
}
for (final raw in _playlists) {
if (raw is! Map<String, dynamic>) continue;
collectAnchor(
raw['id'] as String?,
(raw['items'] as List<dynamic>? ?? const [])
.whereType<Map<String, dynamic>>()
.toList());
}
for (final raw in _collections) {
if (raw is! Map<String, dynamic>) continue;
collectAnchor(raw['id'] as String?, self._collectionItems(raw));
}
for (final anchor in anchors) {
await _checkListRollingDownloads(anchor, count);
}
}
Future<String?> _queueAutoDownloadSourceId(
String playingKey,
String queueMode,
ApiService api,
) async {
if (queueMode == 'playlist') {
return PlayerSettings.getQueuePlaylistId();
}
if (queueMode == 'collection') {
return PlayerSettings.getQueueCollectionId();
}
if (queueMode != 'auto_next') return null;
if (playingKey.length > 36) return playingKey.substring(0, 36);
var data = _itemDataWithSeries(playingKey);
var (seriesId, _) = data != null
? _StateMixin._extractSeries(data)
: (null, null);
if (seriesId == null) {
data = await api.getLibraryItem(playingKey);
if (data != null) {
(seriesId, _) = _StateMixin._extractSeries(data);
}
}
return seriesId;
}
// Alpha [QueueDL]: every exit from this function used to be silent, so a
// queue auto-download that never fired looked identical to one that never
// ran. Each return now names the gate that stopped it. Strip before beta.
Future<void> _checkQueueAutoDownloads(String playingKey) async {
if (AppPlatform.lacksPhonePlugins) return;
try {
final self = this as LibraryProvider;
final planGeneration = ++_queueDownloadPlanGeneration;
final api = _api;
if (api == null) {
debugPrint('[QueueDL] stop at entry: no api (key=$playingKey)');
return;
}
if (isOffline) {
debugPrint('[QueueDL] stop at entry: offline (key=$playingKey)');
return;
}
final accountGeneration = self._accountLoadGeneration;
// `_api` builds a fresh ApiService on every read, so the session has to
// be identified by the server it points at - comparing instances is
// always unequal.
final sessionUrl = _auth?.activeServerUrl;
String? activePlayerKey() {
final player = AudioPlayerService();
final itemId = player.currentItemId;
if (itemId == null) return null;
final episodeId = player.currentEpisodeId;
return episodeId == null ? itemId : '$itemId-$episodeId';
}
String? staleReason() {
if (planGeneration != _queueDownloadPlanGeneration) {
return 'a newer check superseded this one';
}
if (accountGeneration != self._accountLoadGeneration) {
return 'account reloaded';
}
if (_api == null) return 'signed out';
if (_auth?.activeServerUrl != sessionUrl) return 'server changed';
if (isOffline) return 'went offline';
final active = activePlayerKey();
if (active != playingKey) return 'now playing $active';
return null;
}
bool isStale() => staleReason() != null;
bool stop(String stage) {
final reason = staleReason();
if (reason == null) return false;
debugPrint('[QueueDL] stop at $stage: $reason (key=$playingKey)');
return true;
}
debugPrint('[QueueDL] check start key=$playingKey');
if (stop('start')) return;
final isPodcastKey = playingKey.length > 36;
final bookMode = await PlayerSettings.getBookQueueMode();
if (stop('read book mode')) return;
final podcastMode = await PlayerSettings.getPodcastQueueMode();
if (stop('read podcast mode')) return;
final merged = await PlayerSettings.getMergeAbsorbingLibraries();
if (stop('read merge setting')) return;
final queueMode = isPodcastKey ? podcastMode : bookMode;
if (queueMode == 'off') {
debugPrint(
'[QueueDL] stop: queue mode is off (isPodcastKey=$isPodcastKey book=$bookMode podcast=$podcastMode)');
return;
}
final queueSourceId = queueMode == 'playlist'
? await PlayerSettings.getQueuePlaylistId()
: queueMode == 'collection'
? await PlayerSettings.getQueueCollectionId()
: null;
if (stop('read queue source')) return;
debugPrint(
'[QueueDL] mode=$queueMode sourceId=$queueSourceId merged=$merged');
final autoDownloadSourceId =
await _queueAutoDownloadSourceId(playingKey, queueMode, api);
if (stop('resolve auto-download source')) return;
final globalAutoDownload =
await PlayerSettings.getQueueAutoDownload();
final enabled = resolveQueueAutoDownloadEnabled(
queueMode: queueMode,
globalEnabled: globalAutoDownload,
activeSourceId: autoDownloadSourceId,
activeSourceEnabled: autoDownloadSourceId != null &&
_rollingDownloadSeries.contains(autoDownloadSourceId),
);
if (!enabled) {
debugPrint(
'[QueueDL] stop: auto-download disabled (mode=$queueMode global=$globalAutoDownload autoSourceId=$autoDownloadSourceId perSource=${autoDownloadSourceId != null && _rollingDownloadSeries.contains(autoDownloadSourceId)})');
return;
}
if (stop('resolve enabled')) return;
final count = await PlayerSettings.getRollingDownloadCount();
if (count <= 0) {
debugPrint('[QueueDL] stop: keep-next count is $count');
return;
}
if (stop('read keep-next count')) return;
final podcastAdvanceDir = isPodcastKey && queueMode == 'auto_next'
? await PlayerSettings.getPodcastAdvanceDir(
playingKey.substring(0, 36))
: null;
if (stop('read podcast advance dir')) return;
final wifiOnly = await PlayerSettings.getWifiOnlyDownloads();
if (stop('read wifi-only setting')) return;
if (wifiOnly) {
final connectivity = await Connectivity().checkConnectivity();
if (stop('check connectivity')) return;
if (!connectivity.contains(ConnectivityResult.wifi)) {
debugPrint(
'[QueueDL] stop: wifi-only downloads on, not on wifi ($connectivity)');
return;
}
}
Future<bool> settingsStillMatch() async {
if (isStale()) return false;
if (await PlayerSettings.getBookQueueMode() != bookMode || isStale()) {
return false;
}
if (await PlayerSettings.getPodcastQueueMode() != podcastMode ||
isStale()) {
return false;
}
if (await PlayerSettings.getMergeAbsorbingLibraries() != merged ||
isStale()) {
return false;
}
final currentGlobalAutoDownload =
await PlayerSettings.getQueueAutoDownload();
if (isStale() ||
!resolveQueueAutoDownloadEnabled(
queueMode: queueMode,
globalEnabled: currentGlobalAutoDownload,
activeSourceId: autoDownloadSourceId,
activeSourceEnabled: autoDownloadSourceId != null &&
_rollingDownloadSeries.contains(autoDownloadSourceId),
)) {
return false;
}
if (await PlayerSettings.getRollingDownloadCount() != count ||
isStale()) {
return false;
}
if (queueMode == 'playlist' &&
await PlayerSettings.getQueuePlaylistId() != queueSourceId) {
return false;
}
if (queueMode == 'collection' &&
await PlayerSettings.getQueueCollectionId() != queueSourceId) {
return false;
}
if (podcastAdvanceDir != null &&
await PlayerSettings.getPodcastAdvanceDir(
playingKey.substring(0, 36)) !=
podcastAdvanceDir) {
return false;
}
return !isStale();
}
final items = await self._queueItemsForDownload(
playingKey,
queueMode,
api,
limit: count,
bookMode: bookMode,
podcastMode: podcastMode,
merged: merged,
queueSourceId: queueSourceId,
podcastAdvanceDir: podcastAdvanceDir,
isStale: isStale,
);
if (items.isEmpty) {
debugPrint(
'[QueueDL] stop: queue tail is empty (mode=$queueMode sourceId=$queueSourceId key=$playingKey) - the window starts at the playing item, so this means it was not found in the queue');
return;
}
if (!await settingsStillMatch()) {
debugPrint(
'[QueueDL] stop: settings changed while planning (${items.length} items found)');
return;
}
await _downloadQueueWindow(
items: items,
count: count,
api: api,
isStale: isStale,
settingsStillMatch: settingsStillMatch,
logLabel: 'mode=$queueMode',
);
} catch (error, stackTrace) {
debugPrint('[QueueDownload] Check failed: $error\n$stackTrace');
}
}
/// Download the first [count] not-yet-available entries of an already-ordered
/// queue window. Shared by the active-queue check and the per-playlist /
/// per-collection check so both keep the same "keep next N" behaviour.
Future<void> _downloadQueueWindow({
required List<Map<String, dynamic>> items,
required int count,
required ApiService api,
required bool Function() isStale,
required Future<bool> Function() settingsStillMatch,
required String logLabel,
}) async {
final self = this as LibraryProvider;
final downloads = DownloadService();
var newDownloads = 0;
String keyOf(Map<String, dynamic> item) {
final libraryItemId = item['libraryItemId'] as String? ?? '';
final episodeId = item['episodeId'] as String?;
return queueItemKey(
libraryItemId: libraryItemId,
episodeId: episodeId,
);
}
final pendingItems = queueItemsNeedingDownload(
items: items.where((item) => keyOf(item).isNotEmpty),
count: count,
keyOf: keyOf,
isFinished: (item) => self.isItemFinishedByKey(keyOf(item)),
isAvailable: (item) {
final key = keyOf(item);
return downloads.isDownloaded(key) || downloads.isDownloading(key);
},
);
debugPrint(
'[QueueDL] plan ($logLabel): ${items.length} in window, keep-next=$count, ${pendingItems.length} need downloading -> ${pendingItems.map(keyOf).join(', ')}');
if (pendingItems.isEmpty) {
debugPrint(
'[QueueDL] nothing to do ($logLabel) - the next $count are already downloaded or finished');
}
for (final item in pendingItems) {
if (isStale()) {
debugPrint('[QueueDL] stop during download loop ($logLabel)');
return;
}
final libraryItemId = item['libraryItemId'] as String? ?? '';
if (libraryItemId.isEmpty) continue;
final episodeId = item['episodeId'] as String?;
final key = keyOf(item);
if (downloads.isDownloaded(key) || downloads.isDownloading(key)) {
continue;
}
var libraryItem =
item['libraryItem'] as Map<String, dynamic>? ?? const {};
if (libraryItem['media'] == null) {
final fetched = await api.getLibraryItem(libraryItemId);
if (fetched != null) libraryItem = fetched;
}
if (!await settingsStillMatch()) return;
final media = libraryItem['media'] as Map<String, dynamic>? ?? const {};
final metadata =
media['metadata'] as Map<String, dynamic>? ?? const {};
var episode = item['episode'] as Map<String, dynamic>?;
if (episode == null && episodeId != null) {
for (final candidate
in (media['episodes'] as List<dynamic>? ?? const [])) {
if (candidate is Map<String, dynamic> &&
candidate['id'] == episodeId) {
episode = candidate;
break;
}
}
}
final title = episodeId == null
? metadata['title'] as String? ?? ''
: episode?['title'] as String? ?? 'Episode';
final author = episodeId == null
? metadata['authorName'] as String? ?? ''
: metadata['title'] as String? ?? '';
if (downloads.isDownloaded(key) || downloads.isDownloading(key)) {
continue;
}
await downloads.liftAutoDownloadBlock(key);
final error = await downloads.downloadItem(
api: api,
itemId: key,
automatic: true,
title: title,
author: author,
coverUrl: getCoverUrl(libraryItemId),
episodeId: episodeId,
libraryId: libraryItem['libraryId'] as String? ?? _selectedLibraryId,
shouldStart: () => !isStale(),
);
if (isStale()) return;
if (error == null &&
(downloads.isDownloaded(key) || downloads.isDownloading(key))) {
newDownloads++;
}
}
if (newDownloads > 0) {
final l = _l();
_showRollingToast(
l?.lpQueueDownloadingItems(newDownloads) ??
'Queue: downloading $newDownloads item${newDownloads == 1 ? '' : 's'}',
icon: Icons.download_rounded);
}
}
Future<void> _catchUpQueueAutoDownloads() async {
if (AppPlatform.lacksPhonePlugins) return;
final itemId = AudioPlayerService().currentItemId;
if (itemId == null) {
debugPrint(
'[QueueDL] stop: nothing is playing, so there is no queue position to download from');
_queueDownloadPlanGeneration++;
return;
}
final epId = AudioPlayerService().currentEpisodeId;
final key = epId != null ? '$itemId-$epId' : itemId;
await _checkQueueAutoDownloads(key);
}
Future<void> syncQueueAutoDownloads() => _catchUpQueueAutoDownloads();
void _checkAutoDownloadOnStream(String playingKey) async {
if (AppPlatform.lacksPhonePlugins || _api == null || isOffline) {
return;
}
final enabled = await PlayerSettings.getAutoDownloadOnStream();
if (!enabled) {
return;
}
// Network policy (Wi-Fi only vs Wi-Fi & mobile) is enforced centrally by
// downloadItem(), so this honors the user's Download network setting rather
// than forcing Wi-Fi.
final dl = DownloadService();
if (dl.isDownloaded(playingKey) || dl.isDownloading(playingKey)) return;
final player = AudioPlayerService();
if (player.currentItemId == null) return;
// playingKey is the composite 'itemId-episodeId' for podcast episodes (plain
// itemId for books), which is exactly what downloadItem expects - it slices
// the episode part back off to reach the library item. Passing the plain
// podcast id here would corrupt that id and silently fail the download.
dl.downloadItem(
api: _api!,
itemId: playingKey,
title: player.currentTitle ?? '',
author: player.currentAuthor ?? '',
coverUrl: player.currentCoverUrl,
episodeId: player.currentEpisodeId,
libraryId: _selectedLibraryId,
);
}
Future<void> _rollingDownloadBook(String bookId, int count) async {
if (AppPlatform.lacksPhonePlugins) return;
var data = _itemDataWithSeries(bookId);
var (seriesId, currentSeq) =
data != null ? _StateMixin._extractSeries(data) : (null, null);
if (seriesId == null || currentSeq == null) {
final fullItem = await _api!.getLibraryItem(bookId);
if (fullItem == null) return;
data = fullItem;
(seriesId, currentSeq) = _StateMixin._extractSeries(fullItem);
}
if (seriesId == null || currentSeq == null) return;
final libraryId = data?['libraryId'] as String? ?? _selectedLibraryId;
final books = await _api!.getAllBooksBySeries(libraryId ?? '', seriesId);
if (books.isEmpty) return;
final dl = DownloadService();
int queued = 0;
int newDownloads = 0;
final anchorFinished = _progressMap[bookId]?['isFinished'] == true;
if (!anchorFinished &&
!dl.isDownloaded(bookId) &&
!dl.isDownloading(bookId)) {
final media = data!['media'] as Map<String, dynamic>? ?? {};
final md = media['metadata'] as Map<String, dynamic>? ?? {};
dl.downloadItem(
api: _api!,
itemId: bookId,
automatic: true,
title: md['title'] as String? ?? '',
author: md['authorName'] as String? ?? '',
coverUrl: getCoverUrl(bookId),
libraryId: libraryId,
);
newDownloads++;
}
if (!anchorFinished) queued++;
for (final book in books) {
if (queued >= count) break;
final bookMap = book as Map<String, dynamic>;
final id = bookMap['id'] as String?;
if (id == null || id == bookId) continue;
final media = bookMap['media'] as Map<String, dynamic>? ?? {};
final metadata = media['metadata'] as Map<String, dynamic>? ?? {};
final seriesRaw = metadata['series'];
double? seq;
if (seriesRaw is Map<String, dynamic> && seriesRaw['id'] == seriesId) {
seq = _StateMixin._parseSequence((seriesRaw['sequence'] ?? '').toString());
} else if (seriesRaw is List) {
for (final s in seriesRaw) {
if (s is Map<String, dynamic> && s['id'] == seriesId) {
seq = _StateMixin._parseSequence((s['sequence'] ?? '').toString());
break;
}
}
}
if (seq == null || seq <= currentSeq) continue;
if (dl.isDownloaded(id) || dl.isDownloading(id)) {
queued++;
continue;
}
if (_progressMap[id]?['isFinished'] == true) continue;
dl.downloadItem(
api: _api!,
itemId: id,
automatic: true,
title: metadata['title'] as String? ?? '',
author: metadata['authorName'] as String? ?? '',
coverUrl: getCoverUrl(id),
libraryId: bookMap['libraryId'] as String? ?? libraryId,
);
queued++;
newDownloads++;
}
if (newDownloads > 0) {
final l = _l();
_showRollingToast(
l?.lpDownloadingBooks(newDownloads)
?? 'Downloading $newDownloads book${newDownloads == 1 ? '' : 's'}',
icon: Icons.download_rounded);
}
}
Future<void> _rollingDownloadPodcast(String compoundKey, int count) async {
if (AppPlatform.lacksPhonePlugins) return;
final showId = compoundKey.substring(0, 36);
final episodeId = compoundKey.substring(37);
final fullItem = await _api!.getLibraryItem(showId);
if (fullItem == null) return;
final media = fullItem['media'] as Map<String, dynamic>? ?? {};
final libraryId = fullItem['libraryId'] as String? ?? _selectedLibraryId;
final episodes =
List<dynamic>.from(media['episodes'] as List<dynamic>? ?? []);
if (episodes.isEmpty) return;
final newestFirst =
await PlayerSettings.getPodcastAdvanceDir(showId) == 'newest_first';
episodes.sort((a, b) {
final aTime = (a['publishedAt'] as num?)?.toInt() ?? 0;
final bTime = (b['publishedAt'] as num?)?.toInt() ?? 0;
return newestFirst ? bTime.compareTo(aTime) : aTime.compareTo(bTime);
});
final currentIdx = episodes.indexWhere(
(e) => e is Map<String, dynamic> && (e['id'] as String?) == episodeId,
);
if (currentIdx < 0) return;
final dl = DownloadService();
final metadata = media['metadata'] as Map<String, dynamic>? ?? {};
int queued = 0;
int newDownloads = 0;
final anchorFinished = _progressMap[compoundKey]?['isFinished'] == true;
if (!anchorFinished &&
!dl.isDownloaded(compoundKey) &&
!dl.isDownloading(compoundKey) &&
!dl.isAutoDownloadBlocked(compoundKey)) {
final curEp = episodes[currentIdx] as Map<String, dynamic>;
dl.downloadItem(
api: _api!,
itemId: compoundKey,
automatic: true,
title: curEp['title'] as String? ?? 'Episode',
author: metadata['title'] as String? ?? '',
coverUrl: getCoverUrl(showId),
episodeId: episodeId,
libraryId: libraryId,
);
newDownloads++;
}
if (!anchorFinished) queued++;
for (int i = currentIdx + 1; i < episodes.length && queued < count; i++) {
final ep = episodes[i] as Map<String, dynamic>;
final epId = ep['id'] as String?;
if (epId == null) continue;
final key = '$showId-$epId';
if (dl.isDownloaded(key) || dl.isDownloading(key)) {
queued++;
continue;
}
if (_progressMap[key]?['isFinished'] == true) continue;
// Deleted by hand: downloadItem would skip it anyway, and counting it
// here is what announced "Downloading 2 episodes" on every launch while
// nothing downloaded.
if (dl.isAutoDownloadBlocked(key)) continue;
dl.downloadItem(
api: _api!,
itemId: key,
automatic: true,
title: ep['title'] as String? ?? 'Episode',
author: metadata['title'] as String? ?? '',
coverUrl: getCoverUrl(showId),
episodeId: epId,
libraryId: libraryId,
);
queued++;
newDownloads++;
}
if (newDownloads > 0) {
final l = _l();
_showRollingToast(
l?.lpDownloadingEpisodes(newDownloads)
?? 'Downloading $newDownloads episode${newDownloads == 1 ? '' : 's'}',
icon: Icons.download_rounded);
}
}
// ── Absorbing helpers used by _CoreMixin ──
void _absorbingIdsAdd(String key, {String? afterKey, bool atFront = true, int? atIndex}) {
if (_absorbingBookIds.contains(key) && afterKey == null) return;
if (afterKey != null) {
_absorbingBookIds.remove(key);
final afterIdx = _absorbingBookIds.indexOf(afterKey);
if (afterIdx >= 0) {
_absorbingBookIds.insert(afterIdx + 1, key);
return;
}
}
if (_absorbingBookIds.contains(key)) return;
if (atIndex != null) {
_absorbingBookIds.insert(atIndex.clamp(0, _absorbingBookIds.length), key);
} else if (atFront) {
_absorbingBookIds.insert(0, key);
} else {
_absorbingBookIds.add(key);
}
}
}