A cross platform Audiobookshelf client for Android and iOS
Dart
import 'dart:async';
import 'dart:convert';
import 'dart:io';
import 'dart:ui' as ui;
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:path_provider/path_provider.dart';
import 'package:shared_preferences/shared_preferences.dart';
import 'package:connectivity_plus/connectivity_plus.dart';
import 'package:http/http.dart' as http;
import 'package:background_downloader/background_downloader.dart';
import 'package:flutter_local_notifications/flutter_local_notifications.dart';
import '../l10n/app_localizations.dart';
import '../main.dart' show rootNavigatorKey;
import '../widgets/overlay_toast.dart';
import 'api_service.dart';
import 'audio_player_service.dart';
import 'ebook_cache.dart';
import 'narrated_books.dart';
import 'narration_service.dart';
import 'offline_source.dart';
import 'server_backend.dart';
import '../utils/app_platform.dart';
import '../utils/percent_escapes.dart';
import 'user_account_service.dart';
enum DownloadStatus { none, downloading, downloaded, error }
class DownloadInfo {
final String itemId;
final DownloadStatus status;
final double progress;
final List<String> localPaths;
final String? sessionData;
// Metadata for offline display
final String? title;
final String? author;
final String? coverUrl;
final String? localCoverPath;
final String? localDirPath;
final String? libraryId;
DownloadInfo({
required this.itemId,
this.status = DownloadStatus.none,
this.progress = 0,
this.localPaths = const [],
this.sessionData,
this.title,
this.author,
this.coverUrl,
this.localCoverPath,
this.localDirPath,
this.libraryId,
});
Map<String, dynamic> toJson() => {
'itemId': itemId,
'status': status.index,
'localPaths': localPaths,
'sessionData': sessionData,
'title': title,
'author': author,
'coverUrl': coverUrl,
'localCoverPath': localCoverPath,
if (localDirPath != null) 'localDirPath': localDirPath,
if (libraryId != null) 'libraryId': libraryId,
};
factory DownloadInfo.fromJson(Map<String, dynamic> json) {
String? title = json['title'] as String?;
String? author = json['author'] as String?;
String? coverUrl = json['coverUrl'] as String?;
// Fallback: extract metadata from cached sessionData for old downloads
if ((title == null || title.isEmpty) && json['sessionData'] != null) {
try {
final session = jsonDecode(json['sessionData'] as String) as Map<String, dynamic>;
// Try session-level metadata first
final sessionMeta = session['mediaMetadata'] as Map<String, dynamic>?;
if (sessionMeta != null) {
title ??= sessionMeta['title'] as String?;
author ??= sessionMeta['authorName'] as String?;
}
// Try libraryItem path
if (title == null || title.isEmpty) {
final libItem = session['libraryItem'] as Map<String, dynamic>? ?? {};
final media = libItem['media'] as Map<String, dynamic>? ?? {};
final metadata = media['metadata'] as Map<String, dynamic>? ?? {};
title ??= metadata['title'] as String?;
author ??= metadata['authorName'] as String?;
}
// Try direct displayTitle/displayAuthor
title ??= session['displayTitle'] as String?;
author ??= session['displayAuthor'] as String?;
} catch (_) {}
}
return DownloadInfo(
itemId: json['itemId'] as String,
status: DownloadStatus.values[json['status'] as int? ?? 0],
localPaths: (json['localPaths'] as List<dynamic>?)
?.map((e) => e as String)
.toList() ??
[],
sessionData: _stripLibraryItem(json['sessionData'] as String?),
title: title,
author: author,
coverUrl: coverUrl,
localCoverPath: json['localCoverPath'] as String?,
localDirPath: json['localDirPath'] as String?,
libraryId: json['libraryId'] as String?,
);
}
}
class _QueuedDownload {
final ApiService api;
final String itemId;
final String title;
final String? author;
final String? coverUrl;
final String? episodeId;
final String? libraryId;
_QueuedDownload({
required this.api,
required this.itemId,
required this.title,
this.author,
this.coverUrl,
this.episodeId,
this.libraryId,
});
}
/// An in-flight multi-file download. The static fields (persisted to
/// SharedPreferences) carry everything needed to finalize the book even if the
/// app is killed and relaunched while the OS finishes the transfer. The runtime
/// maps are rebuilt from the background_downloader task database on relaunch.
class _PendingBook {
final String itemId; // composite key used in _downloads
final String apiItemId; // real library item id for API calls
final String? episodeId;
final String title;
final String? author;
final String? coverUrl;
final String? localCoverPath;
final String? libraryId;
final String bookDir;
final int trackCount;
final List<String> expectedPaths; // index-aligned final file paths
final String? slimSessionJson;
/// When set, this book downloads to internal storage first, then its files
/// are moved into the user's SAF folder ([safTreeUri]) under [safSubfolder]
/// (e.g. "Author/Title") on completion. Null for internal / iOS downloads.
final String? safTreeUri;
final String? safSubfolder;
/// An EPUB that reads itself aloud: the one task downloads the whole EPUB,
/// and its audio is taken out when it lands.
final bool narration;
/// The narration keeps the server's own timings (BookOrbit's), saved on
/// this phone when the download started, rather than the file's.
final bool serverTimings;
/// True once the user cancels, so terminal handling cleans up instead of
/// surfacing an error.
bool cancelled = false;
/// Set synchronously the moment a terminal handler (success/fail/cancel) is
/// chosen, so a burst of terminal updates can't finalize the book twice.
bool finalizing = false;
/// Times a narrated EPUB went on with a fresh sign-in after the server
/// turned it away.
int signInRenewals = 0;
/// A hard track failure aborts the whole book; remember why for the message.
bool failing = false;
TaskException? failException;
int? failCode;
final Map<int, double> trackProgress = {};
final Map<int, TaskStatus> trackStatus = {};
DateTime lastUi = DateTime.fromMillisecondsSinceEpoch(0);
/// Throttle state for the byte-accurate notification overlay.
int notifPct = -1;
int notifDone = -1;
DateTime notifPost = DateTime.fromMillisecondsSinceEpoch(0);
/// Last time any track update arrived, so the slot-leak reconciler can spot a
/// book whose terminal updates were missed.
DateTime lastUpdate = DateTime.fromMillisecondsSinceEpoch(0);
/// True when this book's files get moved into a SAF folder on completion.
bool get isSaf => safTreeUri != null;
_PendingBook({
required this.itemId,
required this.apiItemId,
required this.title,
required this.bookDir,
required this.trackCount,
required this.expectedPaths,
this.episodeId,
this.author,
this.coverUrl,
this.localCoverPath,
this.libraryId,
this.slimSessionJson,
this.safTreeUri,
this.safSubfolder,
this.narration = false,
this.serverTimings = false,
}) {
// Start the no-progress watchdog clock at creation (fresh or restored).
lastUpdate = DateTime.now();
}
double get overallProgress {
if (trackCount == 0) return 0;
var sum = 0.0;
for (int i = 0; i < trackCount; i++) {
sum += trackProgress[i] ?? 0.0;
}
return (sum / trackCount).clamp(0.0, 1.0);
}
Map<String, dynamic> toJson() => {
'itemId': itemId,
'apiItemId': apiItemId,
'episodeId': episodeId,
'title': title,
'author': author,
'coverUrl': coverUrl,
'localCoverPath': localCoverPath,
'libraryId': libraryId,
'bookDir': bookDir,
'trackCount': trackCount,
'expectedPaths': expectedPaths,
'slimSessionJson': slimSessionJson,
if (safTreeUri != null) 'safTreeUri': safTreeUri,
if (safSubfolder != null) 'safSubfolder': safSubfolder,
if (narration) 'narration': true,
if (serverTimings) 'serverTimings': true,
};
factory _PendingBook.fromJson(Map<String, dynamic> j) => _PendingBook(
itemId: j['itemId'] as String,
apiItemId: j['apiItemId'] as String,
episodeId: j['episodeId'] as String?,
title: j['title'] as String? ?? '',
author: j['author'] as String?,
coverUrl: j['coverUrl'] as String?,
localCoverPath: j['localCoverPath'] as String?,
libraryId: j['libraryId'] as String?,
bookDir: j['bookDir'] as String,
trackCount: j['trackCount'] as int? ?? 0,
expectedPaths: (j['expectedPaths'] as List<dynamic>?)
?.map((e) => e as String)
.toList() ??
const [],
slimSessionJson: j['slimSessionJson'] as String?,
safTreeUri: j['safTreeUri'] as String?,
safSubfolder: j['safSubfolder'] as String?,
narration: j['narration'] == true,
serverTimings: j['serverTimings'] == true,
);
}
/// Trim the bulky parts of the persisted `libraryItem` while keeping the bits
/// offline features need. Drops `media.episodes` (a podcast's full episode list
/// is hundreds of KB) and `media.audioFiles` (the server file list, unused for
/// local playback), but KEEPS `media.metadata` (so offline series auto-advance
/// still knows the book's series + sequence), `duration`, and `chapters` (so the
/// now-playing UI is correct).
String? _stripLibraryItem(String? sessionJson) {
if (sessionJson == null) return null;
try {
final session = jsonDecode(sessionJson) as Map<String, dynamic>;
final libItem = session['libraryItem'] as Map<String, dynamic>?;
if (libItem == null) return sessionJson;
final media = libItem['media'] as Map<String, dynamic>?;
if (media != null) {
final own = ownEpisodeRecord(media, session['episodeId'] as String?);
media.remove('episodes');
media.remove('audioFiles');
if (own != null) media['episodes'] = [own];
}
return jsonEncode(session);
} catch (_) {}
return sessionJson;
}
/// The small part of a podcast episode's record worth keeping with its
/// download: enough to order the show's downloads by publish date offline,
/// where the server's episode list is out of reach.
Map<String, dynamic>? ownEpisodeRecord(Map<String, dynamic> media, String? episodeId) {
if (episodeId == null) return null;
for (final e in media['episodes'] as List<dynamic>? ?? const []) {
if (e is! Map<String, dynamic> || e['id'] != episodeId) continue;
return {
for (final k in const ['id', 'title', 'publishedAt', 'pubDate', 'duration', 'season', 'episode', 'index'])
if (e[k] != null) k: e[k],
};
}
return null;
}
/// Sanitize a string for use as a filesystem directory/file name.
String _sanitizePath(String name) {
// Replace filesystem-illegal characters with underscore
var s = name.replaceAll(RegExp(r'[<>:"/\\|?*]'), '_');
// Collapse multiple underscores/spaces
s = s.replaceAll(RegExp(r'[_\s]+'), ' ').trim();
// Fallback for empty result
if (s.isEmpty) s = 'Unknown';
// Limit length to avoid filesystem issues
if (s.length > 100) s = s.substring(0, 100).trim();
return s;
}
class DownloadService extends ChangeNotifier {
static final DownloadService _instance = DownloadService._();
factory DownloadService() => _instance;
DownloadService._()
: _initializeOverride = null,
_cancelTasksOverride = null,
_deleteTaskRecordOverride = null {
UserAccountService.onScopeMoved = _moveOrigins;
}
@visibleForTesting
DownloadService.forTesting({
required Future<void> Function() initialize,
Future<void> Function(List<String>)? cancelTasks,
Future<void> Function(String)? deleteTaskRecord,
}) : _initializeOverride = initialize,
_cancelTasksOverride = cancelTasks,
_deleteTaskRecordOverride = deleteTaskRecord;
final Future<void> Function()? _initializeOverride;
final Future<void> Function(List<String>)? _cancelTasksOverride;
final Future<void> Function(String)? _deleteTaskRecordOverride;
Future<void>? _initFuture;
Future<void>? _iosAudioMigrationFuture;
bool _initialized = false;
/// Set to true (before init) by short-lived background isolates like the
/// episode-notification job. Downloads then run as plain background tasks
/// instead of in the foreground service: Android 15+ kills a dataSync
/// foreground service started while the app is in the background almost
/// immediately ("FGS (dataSync) timed out"), leaving the task stuck at 0%.
static bool backgroundIsolateMode = false;
final Map<String, DownloadInfo> _downloads = {};
// Downloads are shared on the device across accounts. Which account each
// one came from, so a book from another server is read here without its
// position going to the server you are signed in to, where the same id can
// be a different book.
final Map<String, String> _origins = {};
void _noteOrigin(String itemId) {
final scope = UserAccountService().activeScopeKey;
if (scope.isNotEmpty) _origins[itemId] = scope;
}
/// Whether [itemId] is a download made on a different account than the one
/// signed in now. Downloads from before origins were kept give themselves
/// away by their id: a BookOrbit book's is a number and an Audiobookshelf
/// one's never is.
bool isFromOtherAccount(String itemId) {
final accounts = UserAccountService();
final current = accounts.activeScopeKey;
if (current.isEmpty) return false;
final origin = _origins[itemId];
if (origin == current) return false;
final bookOrbitId = int.tryParse(itemId) != null;
if (origin == null) return bookOrbitId != ServerBackend.active.isBookOrbit;
final me = accounts.accounts.where((a) => a.scopeKey == current).firstOrNull;
if (me == null) return true;
// Another user on the same server has the same books under the same
// ids, so their download is this account's to read and sync too.
if (origin.startsWith('${_serverOf(me)}_')) return false;
final from = accounts.accounts.where((a) => a.scopeKey == origin).firstOrNull ??
_movedAccount(origin, accounts.accounts, bookOrbit: bookOrbitId);
return from == null || _serverOf(from) != _serverOf(me);
}
static String _serverOf(SavedAccount a) =>
a.scopeKey.substring(0, a.scopeKey.length - a.username.length - 1);
/// The saved account an origin no account has any more stands for: its
/// address was changed before origins followed it, so it is the one
/// account with that user on the same kind of server.
static SavedAccount? _movedAccount(String origin, List<SavedAccount> accounts, {required bool bookOrbit}) {
final candidates = accounts
.where((a) => origin.endsWith('_${a.username}') && a.backend.isBookOrbit == bookOrbit)
.toList();
return candidates.length == 1 ? candidates.single : null;
}
@visibleForTesting
void debugSetOrigin(String itemId, String scope) => _origins[itemId] = scope;
/// An account's address changed: its downloads are still its own, and so
/// are the places kept for another account's books.
Future<void> _moveOrigins(String from, String to) async {
var moved = 0;
_origins.updateAll((_, scope) {
if (scope != from) return scope;
moved++;
return to;
});
try {
final prefs = await SharedPreferences.getInstance();
final spots = jsonDecode(prefs.getString(_otherAccountSpotsKey) ?? '{}') as Map<String, dynamic>;
final renamed = {
for (final e in spots.entries)
e.key.startsWith('$from|') ? '$to|${e.key.substring(from.length + 1)}' : e.key: e.value,
};
await prefs.setString(_otherAccountSpotsKey, jsonEncode(renamed));
} catch (_) {}
if (moved > 0) await _save();
debugPrint('[Download] $moved download(s) moved with their account: $from -> $to');
}
static const _otherAccountSpotsKey = 'other_account_reading';
/// Where reading stopped in another account's download, kept on the device.
Future<({String location, double progress})?> otherAccountReadingSpot(String itemId) async {
final origin = _origins[itemId];
if (origin == null) return null;
try {
final prefs = await SharedPreferences.getInstance();
final map = jsonDecode(prefs.getString(_otherAccountSpotsKey) ?? '{}') as Map<String, dynamic>;
final spot = map['$origin|$itemId'];
if (spot is! Map) return null;
final loc = spot['loc'];
if (loc is! String || loc.isEmpty) return null;
return (location: loc, progress: (spot['prog'] as num?)?.toDouble() ?? 0);
} catch (_) {
return null;
}
}
Future<void> saveOtherAccountReadingSpot(String itemId, String location, double progress) async {
final origin = _origins[itemId];
if (origin == null) return;
try {
final prefs = await SharedPreferences.getInstance();
final map = jsonDecode(prefs.getString(_otherAccountSpotsKey) ?? '{}') as Map<String, dynamic>;
map['$origin|$itemId'] = {'loc': location, 'prog': progress};
await prefs.setString(_otherAccountSpotsKey, jsonEncode(map));
} catch (e) {
debugPrint('[Download] saving the reading spot for $itemId failed: $e');
}
}
// Items whose stored cover was already checked (and upgraded if it was an
// old 400px thumbnail) this session - see enrichMetadata.
final Set<String> _coverUpgradeChecked = {};
final Set<String> _activeDownloadIds = {};
final Set<String> _cancelledIds = {};
/// SAF tree URI (content://) for the Android custom download folder, or null
/// to use internal storage. This is the only custom-location mechanism now;
/// the old raw-path approach (MANAGE_EXTERNAL_STORAGE) is gone.
String? _customDownloadUri;
/// Downloaded items still pointing at raw external paths from before the SAF
/// switch. Unreadable without the dropped storage permission, so they're kept
/// listed for the user to re-download rather than silently deleted.
final Set<String> _legacyExternalIds = {};
/// All `background_downloader` tasks share this group for update routing.
/// Notifications are configured per task at enqueue time (one notification
/// per book); the group-level config is only a fallback.
static const String _dlGroup = 'absorb_downloads';
/// In-flight books keyed by itemId. Holds everything needed to aggregate
/// per-track progress and finalize the book, including after an app relaunch.
final Map<String, _PendingBook> _pending = {};
/// Play sessions kept open for downloads that use their temporary links.
final Map<String, ({ApiService api, String sessionId})> _linkSessions = {};
/// The API each narrated EPUB download started with, so one the server
/// turns away for a lapsed sign-in can go on with a fresh one. Empty after
/// a restart, when such a download fails the way it always did.
final Map<String, ApiService> _narrationApis = {};
StreamSubscription<TaskUpdate>? _updatesSub;
bool _downloaderConfigured = false;
/// Periodically reconverges in-flight books with the package task DB so a
/// missed terminal update can't leave a slot leaked and wedge the queue.
Timer? _reconcileTimer;
/// Queue of pending download requests.
final List<_QueuedDownload> _queue = [];
// Items the user deleted by hand. Every auto-download planner (rolling
// series and show, queue window, playlist and collection, new subscribed
// episodes) funnels through [downloadItem] with automatic: true and skips
// these, so a half-finished book that was deleted stops coming back on the
// next launch. Global like the downloads themselves, not per account.
final Set<String> _autoDownloadBlocked = {};
/// True when the user deleted this download, so an automatic download of it
/// would be skipped. Callers that count or announce downloads need to know
/// before they call, or they announce work that never happens.
bool isAutoDownloadBlocked(String itemId) =>
_autoDownloadBlocked.contains(itemId);
/// The queue's next-up books are wanted whatever happened to an earlier
/// download of them, so the planner lifts the block before it downloads.
Future<void> liftAutoDownloadBlock(String itemId) async {
if (!_autoDownloadBlocked.remove(itemId)) return;
debugPrint('[Download] $itemId is next in the queue - auto-download may fetch it again');
await _saveAutoDownloadBlocks();
}
static const _autoDownloadBlockedKey = 'auto_download_blocked';
/// The current Android SAF folder URI (content://), or null if using default.
String? get customDownloadUri => _customDownloadUri;
/// Items left pointing at unreadable raw external paths from before SAF.
List<DownloadInfo> get legacyExternalDownloads =>
_legacyExternalIds.map((id) => _downloads[id]).whereType<DownloadInfo>().toList();
/// Get the effective default (non-custom) download base directory.
///
/// Android custom folders no longer use a filesystem base path - they go
/// through SAF ([_customDownloadUri]) in the task builder. This getter now
/// only resolves the built-in location: the iOS app group container (so the
/// widget extension and native player core can read it; falls back to
/// Documents/ if the app group lookup fails) or Android internal storage.
Future<String> get downloadBasePath async {
if (Platform.isIOS) {
final groupPath = await _iosAppGroupAudioBase();
if (groupPath != null) return groupPath;
}
final appDir = await getApplicationDocumentsDirectory();
return '${appDir.path}/downloads';
}
/// Always returns the internal app directory for cover caching.
/// Covers are stored here even when audio uses a custom external path,
/// because external storage may have permission restrictions.
Future<String> get _internalBasePath async {
final appDir = await getApplicationDocumentsDirectory();
return '${appDir.path}/downloads';
}
/// Set the Android SAF custom download folder. Pass null to revert to default.
Future<void> setCustomDownloadUri(Uri? uri) async {
_customDownloadUri = uri?.toString();
final prefs = await SharedPreferences.getInstance();
if (_customDownloadUri != null && _customDownloadUri!.isNotEmpty) {
await prefs.setString('custom_download_uri', _customDownloadUri!);
} else {
await prefs.remove('custom_download_uri');
}
notifyListeners();
}
/// Get a human-readable label for the current download location.
Future<String> get downloadLocationLabel async {
final uri = _customDownloadUri;
if (uri != null && uri.isNotEmpty) return _friendlySafLabel(uri);
return 'App Internal Storage (Default)';
}
/// Turn a SAF tree URI into a friendly folder name. Tree URIs encode the
/// location in their last path segment, e.g.
/// `.../tree/primary%3ADownload%2FAudiobooks` -> `Download/Audiobooks`.
String _friendlySafLabel(String uriString) {
try {
final uri = Uri.parse(uriString);
var docId =
uri.pathSegments.isNotEmpty ? uri.pathSegments.last : uriString;
docId = undoPercentEscapes(docId);
final colon = docId.indexOf(':');
final rel = colon >= 0 ? docId.substring(colon + 1) : docId;
return rel.isEmpty ? docId : rel;
} catch (_) {
return uriString;
}
}
/// Calculate total size of all downloaded files.
Future<int> get totalDownloadSize async {
// No downloads in a browser, and no app directory to look in: asking for
// one threw, which failed the Settings load and left every control there
// disabled on the web.
if (AppPlatform.isWeb) return 0;
await hydrateEbookCacheDir();
int total = 0;
for (final info in _downloads.values) {
if (info.status == DownloadStatus.downloaded) {
for (final path in info.localPaths) {
if (isContentUri(path)) continue; // SAF audio not counted in the tally
try {
final file = File(path);
if (file.existsSync()) {
total += file.lengthSync();
}
} catch (_) {}
}
total += cachedEbookBytesSync(info.itemId);
}
}
return total;
}
/// Calculate total file size for a single download item.
int getItemFileSize(String itemId) {
final info = _downloads[itemId];
if (info == null || info.status != DownloadStatus.downloaded) return 0;
int total = 0;
for (final path in info.localPaths) {
if (isContentUri(path)) continue; // SAF audio not counted in the tally
try {
final file = File(path);
if (file.existsSync()) {
total += file.lengthSync();
}
} catch (_) {}
}
return total + cachedEbookBytesSync(itemId);
}
static const _storageChannel = MethodChannel('com.absorb.storage');
static const _widgetChannel = MethodChannel('com.absorb.widget');
/// Cached iOS app group container path. Populated lazily by
/// [_iosAppGroupAudioBase] and cleared if the lookup fails so we retry
/// (the app group entitlement may roll in mid-session).
String? _iosAppGroupContainerPath;
/// Stops iCloud from backing up an audio file. Audiobooks are large and
/// re-downloadable from the user's ABS server, so eating their iCloud
/// quota would only cause problems (system backup breaks once quota is
/// hit). iOS-only no-op elsewhere.
Future<void> _excludeFromBackup(String path) async {
if (!Platform.isIOS) return;
try {
await _widgetChannel.invokeMethod<bool>(
'excludeFromBackup',
{'path': path},
);
} catch (e) {
debugPrint('[Download] excludeFromBackup failed for $path: $e');
}
}
/// Returns the iOS app group's audio directory (`<group>/audio/downloads`),
/// or null on Android / when the app group entitlement isn't available.
/// Audio downloads live here so the native player core can read them
/// from the widget extension (the widget can't reach Documents/).
Future<String?> _iosAppGroupAudioBase() async {
if (!Platform.isIOS) return null;
var groupPath = _iosAppGroupContainerPath;
if (groupPath == null) {
try {
groupPath = await _widgetChannel.invokeMethod<String>('getGroupContainerPath');
} catch (e) {
debugPrint('[Download] getGroupContainerPath failed: $e');
return null;
}
if (groupPath == null || groupPath.isEmpty) return null;
_iosAppGroupContainerPath = groupPath;
}
final dir = Directory('$groupPath/audio/downloads');
if (!dir.existsSync()) {
try {
dir.createSync(recursive: true);
} catch (e) {
debugPrint('[Download] create app group audio dir failed: $e');
return null;
}
}
return dir.path;
}
/// Get device storage info: {totalBytes, availableBytes}. Returns null on failure.
static Future<Map<String, int>?> getDeviceStorage() async {
try {
final result = await _storageChannel.invokeMethod('getDeviceStorage');
if (result is Map) {
return {
'totalBytes': (result['totalBytes'] as num).toInt(),
'availableBytes': (result['availableBytes'] as num).toInt(),
};
}
} catch (e) {
debugPrint('[Download] getDeviceStorage error: $e');
}
return null;
}
DownloadInfo getInfo(String itemId) =>
_downloads[itemId] ?? DownloadInfo(itemId: itemId);
// Books whose ebook was opened in the reader. The cached copy stays listed
// and kept when there is no audio download to carry it. Never a download
// record: the player must not think the audio is on the phone.
final Map<String, DownloadInfo> _keptEbooks = {};
List<DownloadInfo> get keptEbooks => _keptEbooks.values.toList();
DownloadInfo? keptEbook(String itemId) => _keptEbooks[itemId];
Future<void> keepEbook({
required ApiService api,
required String itemId,
Map<String, dynamic>? item,
}) async {
if (_keptEbooks.containsKey(itemId)) return;
Map<String, dynamic>? full;
try {
full = await api.getLibraryItem(itemId);
} catch (_) {}
final stored = full ?? item;
if (stored == null) return;
final media = stored['media'] as Map<String, dynamic>?;
final metadata = media?['metadata'] as Map<String, dynamic>?;
String? coverPath;
try {
final resp = await http
.get(Uri.parse(_hiResCoverUrl(api.getCoverUrl(itemId, width: 800))),
headers: api.mediaHeaders)
.timeout(const Duration(seconds: 10));
if (resp.statusCode == 200 && resp.bodyBytes.isNotEmpty) {
final f = await ebookCoverCacheFile(itemId);
await f.writeAsBytes(resp.bodyBytes);
coverPath = f.path;
}
} catch (_) {}
_noteOrigin(itemId);
_keptEbooks[itemId] = DownloadInfo(
itemId: itemId,
status: DownloadStatus.downloaded,
sessionData: jsonEncode({
'libraryItem': stored,
'mediaMetadata': metadata,
'duration': 0,
'chapters': const <dynamic>[],
}),
title: metadata?['title'] as String?,
author: metadata?['authorName'] as String?,
localCoverPath: coverPath,
libraryId: stored['libraryId'] as String?,
);
await _save();
notifyListeners();
debugPrint('[Download] ebook kept for offline: $itemId');
}
/// What a downloaded book has on the phone, for choosing what to remove:
/// whether its audio is here and how big it is (null when that can't be
/// told, as in a custom folder), the ebook copy's size, or null when there
/// is no copy, and whether the audio was taken out of that ebook (a
/// narrated EPUB, one file on the server and one book to remove).
Future<({bool audio, int? audioBytes, int? ebookBytes, bool fromEbook})> onPhone(String itemId) async {
final info = _downloads[itemId];
final audio = info != null && info.localPaths.isNotEmpty;
var fromEbook = false;
if (audio) {
try {
final media = ((jsonDecode(info.sessionData ?? '') as Map)['libraryItem'] as Map?)?['media'] as Map?;
final audioFiles = (media?['audioFiles'] as List?) ?? const [];
fromEbook = audioFiles.isEmpty && (media?['narration'] != null || NarratedBooks.contains(itemId));
} catch (_) {}
}
int? audioBytes;
if (audio) {
var total = 0;
var known = true;
for (final path in info.localPaths) {
if (isContentUri(path)) {
known = false;
continue;
}
try {
final f = File(path);
if (f.existsSync()) total += f.lengthSync();
} catch (_) {}
}
// Files in a custom folder can't be measured here; the server's sizes
// for the book's audio stand in.
audioBytes = known ? total : _serverAudioBytes(info.sessionData);
}
int? ebookBytes;
try {
final entry = await cachedEbookFileFor(itemId);
if (entry != null) {
final f = await ebookCacheFileFor(itemId, entry);
if (f.existsSync()) ebookBytes = f.lengthSync();
}
} catch (_) {}
return (audio: audio, audioBytes: audioBytes, ebookBytes: ebookBytes, fromEbook: fromEbook);
}
static int? _serverAudioBytes(String? sessionData) {
try {
final session = jsonDecode(sessionData ?? '') as Map<String, dynamic>;
final media = (session['libraryItem'] as Map?)?['media'] as Map?;
final files = (media?['audioFiles'] as List?) ?? (session['audioTracks'] as List?) ?? const [];
var total = 0;
for (final f in files.whereType<Map>()) {
total += ((f['metadata'] as Map?)?['size'] as num?)?.toInt() ?? 0;
}
return total > 0 ? total : null;
} catch (_) {
return null;
}
}
/// Takes a downloaded book's ebook copy off the phone and leaves its audio.
Future<void> deleteEbookCopy(String itemId) async {
_keptEbooks.remove(itemId);
await deleteCachedEbook(itemId);
if (!_downloads.containsKey(itemId)) _origins.remove(itemId);
await _save();
notifyListeners();
}
/// Takes a downloaded book's audio off the phone and keeps its ebook copy,
/// listed on its own the way one the reader kept is.
Future<void> deleteAudioKeepEbook(String itemId) async {
final info = _downloads[itemId];
if (info != null && !_keptEbooks.containsKey(itemId)) {
Map<String, dynamic>? stored;
try {
stored = (jsonDecode(info.sessionData ?? '') as Map<String, dynamic>)['libraryItem'] as Map<String, dynamic>?;
} catch (_) {}
String? cover;
try {
final from = info.localCoverPath == null ? null : File(info.localCoverPath!);
if (from != null && from.existsSync()) {
final to = await ebookCoverCacheFile(itemId);
await from.copy(to.path);
cover = to.path;
}
} catch (_) {}
_keptEbooks[itemId] = DownloadInfo(
itemId: itemId,
status: DownloadStatus.downloaded,
sessionData: stored == null
? null
: jsonEncode({
'libraryItem': stored,
'mediaMetadata': (stored['media'] as Map?)?['metadata'],
'duration': 0,
'chapters': const <dynamic>[],
}),
title: info.title,
author: info.author,
coverUrl: info.coverUrl,
localCoverPath: cover,
libraryId: info.libraryId,
);
}
await deleteDownload(itemId, byUser: true);
}
Future<void> deleteKeptEbook(String itemId) async {
if (_keptEbooks.remove(itemId) == null) return;
if (!_downloads.containsKey(itemId)) _origins.remove(itemId);
// A downloaded audiobook still reads from the same cached file.
if (_downloads.containsKey(itemId)) {
await deleteCachedEbookCover(itemId);
} else {
await deleteCachedEbook(itemId);
}
await _save();
notifyListeners();
}
/// A narrated EPUB on Audiobookshelf counts as downloaded only once its
/// audio is: its ebook alone (kept by the reader in earlier builds) would
/// otherwise block the narration's download and play from nothing.
bool isDownloaded(String itemId) {
final d = _downloads[itemId];
if (d?.status != DownloadStatus.downloaded) return false;
return d!.localPaths.isNotEmpty || !NarratedBooks.contains(itemId);
}
/// Registers an ebook-only book as a completed download so it shows in the
/// offline library and its detail sheet loads offline. There's no audio, so
/// localPaths is empty - the book opens in the reader, never the player. The
/// ebook bytes live in the reader's persistent cache (fetchEbookToCache).
/// Fetches a full copy of the item so the offline sheet has the cover,
/// description, and ebookFile - not just the title.
/// With [onlyIfNoAudio], a book that has audio is left alone: opening the
/// companion ebook of an audiobook must not mark the audiobook downloaded.
/// Returns whether a record was written.
Future<bool> registerEbookDownload({
required ApiService api,
required String itemId,
Map<String, dynamic>? item,
String? libraryId,
bool onlyIfNoAudio = false,
}) async {
// A narrated EPUB's download is its audio; the reader keeps the ebook
// apart (keepEbook) so the two don't get mixed up.
if (onlyIfNoAudio && NarratedBooks.contains(itemId)) return false;
Map<String, dynamic>? fullItem;
try {
fullItem = await api.getLibraryItem(itemId);
} catch (_) {}
final stored = fullItem ?? item ?? {'id': itemId};
final media = stored['media'] as Map<String, dynamic>?;
if (onlyIfNoAudio) {
final tracks = media?['numTracks'];
final audioFiles = media?['audioFiles'];
final duration = media?['duration'];
final hasAudio = (tracks is num && tracks > 0) ||
(audioFiles is List && audioFiles.isNotEmpty) ||
(duration is num && duration > 0);
if (fullItem == null || hasAudio) return false;
}
final metadata = media?['metadata'] as Map<String, dynamic>?;
final title = metadata?['title'] as String?;
final author = metadata?['authorName'] as String?;
final localCoverPath = await _cacheCover(api, itemId, api.getCoverUrl(itemId, width: 800));
_noteOrigin(itemId);
final sessionJson = jsonEncode({
'libraryItem': stored,
'mediaMetadata': metadata,
'duration': 0,
'chapters': const <dynamic>[],
});
_downloads[itemId] = DownloadInfo(
itemId: itemId,
status: DownloadStatus.downloaded,
localPaths: const [],
sessionData: sessionJson,
title: title,
author: author,
localCoverPath: localCoverPath,
libraryId: libraryId ?? stored['libraryId'] as String?,
);
await _save();
notifyListeners();
debugPrint('[Download] ebook-only book kept for offline: $itemId');
return true;
}
/// A narrated EPUB's audio, taken out of the book file, kept as the book's
/// download so it plays like any downloaded audiobook. Replaces an
/// ebook-only record for the same book.
Future<void> registerNarration({
ApiService? api,
String? localCoverPath,
required String itemId,
required Map<String, dynamic> item,
required String dirPath,
required List<String> paths,
required double duration,
required List<Map<String, dynamic>> chapters,
required List<Map<String, dynamic>> audioTracks,
}) async {
final media = Map<String, dynamic>.from(item['media'] as Map? ?? const {});
final metadata = media['metadata'] as Map<String, dynamic>?;
media['duration'] = duration;
media['chapters'] = chapters;
media['tracks'] = audioTracks;
media['narration'] = {...?(media['narration'] as Map?), 'duration': duration, 'local': true};
final stored = {...item, 'media': media};
final cover = localCoverPath ??
(api == null ? null : await _cacheCover(api, itemId, api.getCoverUrl(itemId, width: 800)));
var finalPaths = paths;
var finalDir = dirPath;
// A custom download folder gets the narration too, moved in under
// "Author/Title" the way a finished download is. If the move fails the
// book stays usable from its internal copy.
final tree = Platform.isAndroid ? _customDownloadUri : null;
if (tree != null && tree.isNotEmpty) {
final author = metadata?['authorName'] as String?;
final title = metadata?['title'] as String? ?? itemId;
var nested = (author != null && author.isNotEmpty)
? '${_sanitizePath(author)}/${_sanitizePath(title)}'
: _sanitizePath(title);
if (_folderTakenByOther(nested, itemId)) {
nested = '$nested (${itemId.substring(itemId.length - 8)})';
}
final moved = await _moveBookToSaf(tree, nested, [for (final p in paths) p.split('/').last], paths);
if (moved != null) {
finalPaths = moved.fileUris;
finalDir = moved.dirUri;
await _cleanupBookDir(dirPath, itemId);
debugPrint('[Download] narration for $itemId moved into the custom folder under "$nested"');
} else {
debugPrint('[Download] narration for $itemId kept in app storage: the move into the custom folder failed');
}
} else {
for (final p in paths) {
await _excludeFromBackup(p);
}
}
_noteOrigin(itemId);
_downloads[itemId] = DownloadInfo(
itemId: itemId,
status: DownloadStatus.downloaded,
localPaths: finalPaths,
sessionData: jsonEncode({
'libraryItem': stored,
'mediaMetadata': metadata,
'displayTitle': metadata?['title'],
'displayAuthor': metadata?['authorName'],
'duration': duration,
'chapters': chapters,
'audioTracks': audioTracks,
}),
title: metadata?['title'] as String?,
author: metadata?['authorName'] as String?,
localCoverPath: cover,
localDirPath: finalDir,
libraryId: item['libraryId'] as String?,
);
await _save();
notifyListeners();
debugPrint('[Download] narration kept as audio for $itemId: ${paths.length} files, ${duration.toStringAsFixed(0)}s');
}
/// A kept narration's chapters and track lengths, read again.
Future<void> updateNarrationTimeline(
String itemId, {
required double duration,
required List<Map<String, dynamic>> chapters,
required List<Map<String, dynamic>> audioTracks,
}) async {
final info = _downloads[itemId];
final raw = info?.sessionData;
if (info == null || raw == null) return;
try {
final data = jsonDecode(raw) as Map<String, dynamic>;
data['duration'] = duration;
data['chapters'] = chapters;
data['audioTracks'] = audioTracks;
final item = data['libraryItem'];
if (item is Map<String, dynamic> && item['media'] is Map<String, dynamic>) {
final media = item['media'] as Map<String, dynamic>;
media['duration'] = duration;
media['chapters'] = chapters;
media['tracks'] = audioTracks;
media['narration'] = {...?(media['narration'] as Map?), 'duration': duration, 'local': true};
}
_downloads[itemId] = DownloadInfo(
itemId: itemId,
status: info.status,
progress: info.progress,
localPaths: info.localPaths,
sessionData: jsonEncode(data),
title: info.title,
author: info.author,
coverUrl: info.coverUrl,
localCoverPath: info.localCoverPath,
localDirPath: info.localDirPath,
libraryId: info.libraryId,
);
await _save();
notifyListeners();
debugPrint('[Download] narration timeline for $itemId: ${chapters.length} chapters, ${duration.toStringAsFixed(0)}s');
} catch (e) {
debugPrint('[Download] narration timeline for $itemId not updated: $e');
}
}
bool isDownloading(String itemId) =>
_downloads[itemId]?.status == DownloadStatus.downloading;
double downloadProgress(String itemId) =>
_downloads[itemId]?.progress ?? 0;
/// Get all downloaded items (for home screen display).
List<DownloadInfo> get downloadedItems =>
_downloads.values
.where((d) => d.status == DownloadStatus.downloaded)
.toList();
/// Get actively downloading items (in progress right now).
List<DownloadInfo> get activeDownloads =>
_downloads.values
.where((d) => d.status == DownloadStatus.downloading && _activeDownloadIds.contains(d.itemId))
.toList();
/// Get queued items (waiting for a download slot).
List<DownloadInfo> get queuedDownloads =>
_queue.map((q) => _downloads[q.itemId]).whereType<DownloadInfo>().toList();
Future<void> init() {
if (AppPlatform.lacksPhonePlugins) {
_initialized = true;
return Future.value();
}
if (_initialized) return Future.value();
final inFlight = _initFuture;
if (inFlight != null) return inFlight;
final completer = Completer<void>();
_initFuture = completer.future;
final initialize = _initializeOverride ?? _initialize;
Future.sync(initialize).then<void>(
(_) {
_initialized = true;
completer.complete();
},
onError: (Object error, StackTrace stackTrace) {
_initFuture = null;
completer.completeError(error, stackTrace);
},
);
return completer.future;
}
Future<void> _initialize() async {
final prefs = await SharedPreferences.getInstance();
_customDownloadUri = prefs.getString('custom_download_uri');
// Legacy raw-path custom folders can't be converted to a SAF content URI
// without a fresh user pick, and we no longer hold the storage permission
// to write them. Drop the old setting so new downloads use SAF or internal.
if (prefs.getString('custom_download_path') != null) {
await prefs.remove('custom_download_path');
}
try {
final origins = jsonDecode(prefs.getString('download_origins') ?? '{}') as Map<String, dynamic>;
for (final e in origins.entries) {
if (e.value is String) _origins[e.key] = e.value as String;
}
} catch (e) {
debugPrint('[Download] download origins init error: $e');
}
final keptJson = prefs.getString('kept_ebooks');
if (keptJson != null) {
try {
final map = jsonDecode(keptJson) as Map<String, dynamic>;
for (final entry in map.entries) {
_keptEbooks[entry.key] =
DownloadInfo.fromJson(entry.value as Map<String, dynamic>);
}
} catch (e) {
debugPrint('[Download] kept ebooks init error: $e');
}
}
final json = prefs.getString('downloads');
if (json != null) {
try {
final map = jsonDecode(json) as Map<String, dynamic>;
for (final entry in map.entries) {
final info =
DownloadInfo.fromJson(entry.value as Map<String, dynamic>);
debugPrint('[Download] Loaded: ${entry.key} '
'title="${info.title}" author="${info.author}" '
'cover=${info.coverUrl != null ? "yes" : "null"} '
'sessionData=${info.sessionData != null ? "${info.sessionData!.length} chars" : "null"}');
if (info.status == DownloadStatus.downloaded) {
_downloads[entry.key] = info;
} else {
debugPrint('[Download] Skipping stale ${info.status} entry: ${entry.key}');
}
}
} catch (e) {
debugPrint('[Download] Init error: $e');
}
}
// On iOS, remap paths when the app container UUID changes after updates
await _migrateIOSPaths();
// On Android, flag downloads still pointing at raw external paths from
// before the SAF switch so the UI can offer a re-download.
await _detectLegacyExternal();
// On iOS, move existing audio downloads from Documents/ into the app
// group container so the widget / native player core can read them.
// Runs in background so it doesn't block init() if the user has many
// gigabytes of downloaded books to relocate.
if (Platform.isIOS) {
_iosAudioMigrationFuture ??= _runIOSAudioMigration();
unawaited(_iosAudioMigrationFuture!);
}
// Re-save to persist any metadata extracted from sessionData
if (_downloads.isNotEmpty) await _save();
// Wire up native background downloads: configure the grouped notification,
// start tracking tasks (so they persist across launches), listen for
// updates, then rehydrate any download that was in flight when we were last
// killed and ask the OS to redeliver completions that landed while dead.
await _configureDownloader();
_updatesSub ??= FileDownloader().updates.listen(_onTaskUpdate);
await FileDownloader().trackTasks();
await _loadPending();
await _loadAutoDownloadBlocks();
await _rehydratePending();
await FileDownloader().resumeFromBackground();
_startReconciler();
notifyListeners();
// Validate files and clean up orphans in background after startup
_validateDownloads();
}
void _startReconciler() {
_reconcileTimer?.cancel();
_reconcileTimer = Timer.periodic(
const Duration(minutes: 2), (_) => unawaited(_reconcilePending()));
}
/// Reconcile in-flight books against the package task DB. Two jobs:
/// 1. If a book's terminal updates were missed (e.g. an OEM ROM killed our
/// callback), finalize / fail it from the DB so its slot frees.
/// 2. If a book has made no progress and gone silent for a while, it's a dead
/// or zombie record (e.g. left over after an app update) holding a slot -
/// fail it so the queue can move on. Healthy or wifi-waiting downloads keep
/// emitting updates, so their lastUpdate stays fresh and they're left be.
Future<void> _reconcilePending() async {
if (_pending.isEmpty) return;
List<TaskRecord> records;
try {
records = await FileDownloader().database.allRecords();
} catch (_) {
return;
}
final byItem = <String, Map<int, TaskStatus>>{};
for (final r in records) {
final meta = _decodeMeta(r.task.metaData);
if (meta == null) continue;
if (!_pending.containsKey(meta.$1)) continue;
(byItem[meta.$1] ??= {})[meta.$2] = r.status;
}
for (final itemId in _pending.keys.toList()) {
final p = _pending[itemId];
if (p == null || p.finalizing) continue;
final statuses = byItem[itemId];
if (statuses != null && statuses.length >= p.trackCount) {
statuses.forEach((i, s) => p.trackStatus[i] = s);
bool allComplete = p.trackCount > 0;
bool allTerminal = true;
for (int i = 0; i < p.trackCount; i++) {
final s = p.trackStatus[i];
if (s != TaskStatus.complete) allComplete = false;
if (s == null || !_terminal.contains(s)) allTerminal = false;
}
if (allComplete) {
debugPrint('[Download] Reconciler finalizing missed-complete $itemId');
p.finalizing = true;
await _finalizeSuccess(itemId);
continue;
}
if (allTerminal) {
debugPrint('[Download] Reconciler failing stalled $itemId');
// Don't pre-set p.finalizing: _failBook bails when it's already
// true, which turned this whole cleanup into a no-op AND made the
// zombie immortal (reconciler and cancel both skip finalizing
// items, and the pending entry stays persisted across restarts).
await _failBook(itemId, cause: 'Interrupted download');
continue;
}
}
// No updates for a while: a dead/zombie slot. Zero-progress books get a
// short leash; ones with partial progress get a longer one - they can be
// zombies too (rehydrated from DB records whose WorkManager jobs are
// gone, so they hold a slot with e.g. 40% forever). A healthy transfer
// emits updates constantly, so real downloads never sit silent this long
// while the app is running.
// A book waiting in the downloader's queue behind another one's files
// hears nothing while the other book moves, and isn't stuck.
var heardAt = p.lastUpdate;
for (final other in _pending.values) {
if (other.lastUpdate.isAfter(heardAt)) heardAt = other.lastUpdate;
}
final silence = DateTime.now().difference(heardAt);
if ((p.overallProgress == 0 && silence > const Duration(minutes: 3)) ||
silence > const Duration(minutes: 10)) {
debugPrint('[Download] Reconciler failing stale $itemId '
'(progress=${p.overallProgress}, silent ${silence.inMinutes}m)');
await _failBook(itemId, cause: 'Interrupted download');
}
}
}
/// Configure the downloader transport plus a fallback notification config
/// for the shared group. The real notifications are configured per task in
/// [_executeDownload] (one per book); this fallback only catches a task that
/// somehow missed its per-task config. The package runs a background
/// URLSession on iOS and a foreground service on Android, so downloads
/// continue when backgrounded, locked, or killed.
Future<void> _configureDownloader() async {
if (_downloaderConfigured) return;
// Run downloads in the Android foreground service. Without this, smaller
// books can run as background WorkManager jobs that some OEM ROMs throttle
// or kill, leaving downloads stuck. Exception: background isolates must NOT
// use the foreground service (see backgroundIsolateMode) - the app's next
// real start reconfigures back to always.
if (Platform.isAndroid) {
try {
await FileDownloader().configure(
// A book in 93 files started all 93 at once, which swamped the
// server and the connection until Absorb's own requests timed out
// and it went offline. The queue is native, so it keeps feeding
// files with the app in the background.
globalConfig: [(Config.holdingQueue, (6, 4, null))],
androidConfig: [
(
Config.runInForeground,
backgroundIsolateMode ? Config.never : Config.always,
),
],
);
debugPrint('[Download] at most 4 files at a time per server, 6 in all');
} catch (e) {
debugPrint('[Download] androidConfig failed: $e');
}
}
final l = _l();
// NOTE: for group notifications, the count tokens ({numFinished}/{numTotal})
// only substitute in the TITLE - in the body they print literally. {progress}
// is valid anywhere. We keep it simple: "Downloading" + a progress bar/%.
FileDownloader().configureNotificationForGroup(
_dlGroup,
running: TaskNotification(
l?.downloadNotifDownloadingTitle ?? 'Downloading',
'{progress}',
),
complete: TaskNotification(
l?.downloadNotifCompleteTitle ?? 'Downloads complete',
'',
),
error: TaskNotification(
l?.downloadNotifFailedTitle ?? 'Download failed',
'',
),
progressBar: true,
);
_downloaderConfigured = true;
}
AppLocalizations? _l() {
final ctx = rootNavigatorKey.currentContext;
return ctx != null ? AppLocalizations.of(ctx) : null;
}
/// On iOS, the app container UUID changes on every update, which breaks
/// stored absolute paths. Detect stale prefixes and remap to the current
/// container path so downloads survive TestFlight / App Store updates.
Future<void> _migrateIOSPaths() async {
if (!Platform.isIOS || _downloads.isEmpty) return;
final appDir = await getApplicationDocumentsDirectory();
final currentPrefix = appDir.path; // .../Documents
// Audio lives in the App Group container - stable across updates in practice
// (unlike Documents), but resolve it so we can remap audio paths too if the
// container ever shifts. Belt and suspenders so downloads survive an update.
final groupAudioBase = await _iosAppGroupAudioBase();
bool changed = false;
final entries = Map<String, DownloadInfo>.from(_downloads);
for (final entry in entries.entries) {
final info = entry.value;
bool needsUpdate = false;
// Remap localPaths (audio sits under the App Group; legacy audio under
// Documents). Apply both: each is a no-op for paths it doesn't own.
final newPaths = <String>[];
for (final path in info.localPaths) {
final remapped =
_remapAppGroupPath(_remapIOSPath(path, currentPrefix), groupAudioBase);
newPaths.add(remapped);
if (remapped != path) needsUpdate = true;
}
// Covers always live in Documents, so only that prefix can go stale.
final newCoverPath = info.localCoverPath != null
? _remapIOSPath(info.localCoverPath!, currentPrefix)
: null;
if (newCoverPath != info.localCoverPath) needsUpdate = true;
final newDirPath = info.localDirPath != null
? _remapAppGroupPath(
_remapIOSPath(info.localDirPath!, currentPrefix), groupAudioBase)
: null;
if (newDirPath != info.localDirPath) needsUpdate = true;
if (needsUpdate) {
_downloads[entry.key] = DownloadInfo(
itemId: info.itemId,
status: info.status,
localPaths: newPaths,
sessionData: info.sessionData,
title: info.title,
author: info.author,
coverUrl: info.coverUrl,
localCoverPath: newCoverPath,
localDirPath: newDirPath,
libraryId: info.libraryId,
);
changed = true;
}
}
if (changed) {
debugPrint('[Download] Migrated iOS paths to current container');
await _save();
}
}
/// Move existing audio files from Documents/ to the iOS app group container
/// so the widget extension / native player core can read them. Files that
/// fail to move stay in Documents/ where they continue to play through
/// Flutter; we'll retry on the next launch. Atomic per-file via
/// `File.rename()` (works because both directories are on APFS).
Future<void> _migrateIOSAudioToAppGroup() async {
if (!Platform.isIOS || _downloads.isEmpty) return;
final groupBase = await _iosAppGroupAudioBase();
if (groupBase == null) {
debugPrint('[Download] App group not available, skipping audio migration');
return;
}
final appDir = await getApplicationDocumentsDirectory();
final docsBase = '${appDir.path}/downloads';
int moved = 0;
int failed = 0;
bool changed = false;
final entries = Map<String, DownloadInfo>.from(_downloads);
for (final entry in entries.entries) {
final info = entry.value;
if (info.status != DownloadStatus.downloaded) continue;
final newPaths = <String>[];
bool needsUpdate = false;
for (final oldPath in info.localPaths) {
// Already in app group? Keep as-is.
if (oldPath.startsWith(groupBase)) {
newPaths.add(oldPath);
continue;
}
// Not under Documents/downloads/? Leave alone (custom path or odd).
if (!oldPath.startsWith(docsBase)) {
newPaths.add(oldPath);
continue;
}
// Build the parallel path under the app group.
final relative = oldPath.substring(docsBase.length);
final newPath = '$groupBase$relative';
try {
final oldFile = File(oldPath);
if (!oldFile.existsSync()) {
// Old file gone; leave the path untouched and let the validator
// mark it broken later.
newPaths.add(oldPath);
continue;
}
// Make sure parent dirs exist on the destination side.
final parent = Directory(newPath.substring(0, newPath.lastIndexOf('/')));
if (!parent.existsSync()) parent.createSync(recursive: true);
// If dest exists already (partial prior run), remove it first.
final newFile = File(newPath);
if (newFile.existsSync()) {
try { newFile.deleteSync(); } catch (_) {}
}
await oldFile.rename(newPath);
await _excludeFromBackup(newPath);
newPaths.add(newPath);
needsUpdate = true;
moved++;
} catch (e) {
debugPrint('[Download] Audio migration failed for $oldPath: $e');
newPaths.add(oldPath);
failed++;
}
}
if (needsUpdate) {
_downloads[entry.key] = DownloadInfo(
itemId: info.itemId,
status: info.status,
progress: info.progress,
localPaths: newPaths,
sessionData: info.sessionData,
title: info.title,
author: info.author,
coverUrl: info.coverUrl,
localCoverPath: info.localCoverPath,
localDirPath: info.localDirPath,
libraryId: info.libraryId,
);
changed = true;
}
}
if (changed) {
debugPrint('[Download] App group audio migration: moved=$moved failed=$failed');
await _save();
notifyListeners();
}
}
Future<void> _runIOSAudioMigration() async {
try {
await _migrateIOSAudioToAppGroup();
} catch (e) {
debugPrint('[Download] App group audio migration failed: $e');
}
}
/// Replace a stale iOS container prefix with the current one.
/// Paths contain `.../Documents/...` and we split on `/Documents/` then
/// rejoin with the current prefix.
String _remapIOSPath(String path, String currentPrefix) {
if (path.startsWith(currentPrefix)) return path;
final marker = '/Documents/';
final idx = path.indexOf(marker);
if (idx < 0) return path;
return '$currentPrefix/${path.substring(idx + marker.length)}';
}
/// Replace a stale App Group container prefix with the current one. Audio is
/// stored at `<group>/audio/downloads/...`; if the container path ever shifts
/// across an update, rejoin the stable `/audio/downloads` tail onto the freshly
/// resolved base so previously-downloaded books keep playing. No-op when the
/// path is already current (the usual case) or for non-audio paths.
String _remapAppGroupPath(String path, String? groupAudioBase) {
if (groupAudioBase == null || path.startsWith(groupAudioBase)) return path;
const marker = '/audio/downloads';
final idx = path.indexOf(marker);
if (idx < 0) return path;
return '$groupAudioBase${path.substring(idx + marker.length)}';
}
/// Flag downloaded items whose files sit at a raw external path from before
/// the SAF switch (not a content URI, not under internal storage). Without
/// the dropped storage permission these can't be read, so they're kept listed
/// for re-download instead of being silently dropped by the validator.
Future<void> _detectLegacyExternal() async {
if (!Platform.isAndroid || _downloads.isEmpty) return;
final appDir = await getApplicationDocumentsDirectory();
final internalPrefix = appDir.path;
for (final entry in _downloads.entries) {
final info = entry.value;
if (info.status != DownloadStatus.downloaded || info.localPaths.isEmpty) {
continue;
}
final first = info.localPaths.first;
if (isContentUri(first) || first.startsWith(internalPrefix)) continue;
_legacyExternalIds.add(entry.key);
}
if (_legacyExternalIds.isNotEmpty) {
debugPrint('[Download] ${_legacyExternalIds.length} legacy external download(s) need re-download');
}
}
/// Drop a legacy external entry (its files are orphaned on storage we can no
/// longer reach) and re-enqueue it from stored metadata so it lands in the
/// current location (SAF folder or internal).
Future<void> redownloadLegacy(ApiService api, String itemId) async {
final info = _downloads[itemId];
if (info == null) return;
_downloads.remove(itemId);
_legacyExternalIds.remove(itemId);
await _save();
notifyListeners();
final episodeId = itemId.length > 36 ? itemId.substring(37) : null;
await downloadItem(
api: api,
itemId: itemId,
title: info.title ?? '',
author: info.author,
coverUrl: info.coverUrl,
episodeId: episodeId,
libraryId: info.libraryId,
);
}
/// Re-download every flagged legacy external item.
Future<void> redownloadAllLegacy(ApiService api) async {
for (final id in _legacyExternalIds.toList()) {
await redownloadLegacy(api, id);
}
}
/// Forget the legacy external entries without re-downloading (user dismissed).
Future<void> dismissLegacyDownloads() async {
if (_legacyExternalIds.isEmpty) return;
for (final id in _legacyExternalIds) {
_downloads.remove(id);
}
_legacyExternalIds.clear();
await _save();
notifyListeners();
}
/// Validate that downloaded files still exist on disk and clean up orphans.
/// Runs in background so it doesn't block app startup.
Future<void> _validateDownloads() async {
try {
final orphanIds = <String>[];
final entries = Map<String, DownloadInfo>.from(_downloads);
for (final entry in entries.entries) {
if (entry.value.status != DownloadStatus.downloaded) continue;
// Legacy external entries are kept for re-download, not validated away.
if (_legacyExternalIds.contains(entry.key)) continue;
bool allExist = true;
for (final path in entry.value.localPaths) {
// No cheap existence check for a SAF content URI; assume present and
// let a real playback failure surface a re-download instead.
if (isContentUri(path)) continue;
try {
final exists = await File(path).exists()
.timeout(const Duration(seconds: 3));
if (!exists) {
allExist = false;
break;
}
} catch (_) {
// Timeout or permission error — treat as missing
allExist = false;
break;
}
}
if (!allExist) {
debugPrint('[Download] Files missing for ${entry.key}, removing');
_downloads.remove(entry.key);
orphanIds.add(entry.key);
}
}
if (orphanIds.isNotEmpty) {
await _save();
notifyListeners();
// Clean up partial/orphaned files on disk
final basePath = await downloadBasePath;
final internalBase = await _internalBasePath;
for (final id in orphanIds) {
debugPrint('[Download] Cleaning up orphaned entry: $id');
try {
final dir = Directory('$basePath/$id');
if (await dir.exists()) await dir.delete(recursive: true);
} catch (_) {}
try {
final coverDir = Directory('$internalBase/$id');
if (await coverDir.exists()) await coverDir.delete(recursive: true);
} catch (_) {}
}
}
} catch (e) {
debugPrint('[Download] Validation error: $e');
}
}
/// Try to fill in missing metadata from the API (for old downloads).
Future<void> enrichMetadata(ApiService api) async {
bool changed = false;
final entries = Map<String, DownloadInfo>.from(_downloads);
for (final entry in entries.entries) {
final info = entry.value;
if (info.status != DownloadStatus.downloaded) continue;
bool needsUpdate = false;
String? title = info.title;
String? author = info.author;
String? coverUrl = info.coverUrl;
String? localCoverPath = info.localCoverPath;
// For podcast episodes, the itemId is a composite "showUUID-episodeId".
// Extract the library item ID (first 36 chars = UUID) for API calls.
final apiItemId = info.itemId.length > 36
? info.itemId.substring(0, 36)
: info.itemId;
// Enrich missing title/author from server
if (title == null || title.isEmpty) {
try {
final item = await api.getLibraryItem(apiItemId);
if (item != null) {
final media = item['media'] as Map<String, dynamic>? ?? {};
final metadata = media['metadata'] as Map<String, dynamic>? ?? {};
title = metadata['title'] as String? ?? title;
author = metadata['authorName'] as String? ?? author;
coverUrl = api.getCoverUrl(apiItemId, width: 1200);
needsUpdate = true;
debugPrint('[Download] Enriched metadata for ${info.itemId}: $title');
}
} catch (e) {
debugPrint('[Download] Enrich failed for ${info.itemId}: $e');
}
}
// Cache cover in internal storage if not already cached
if (localCoverPath == null || !File(localCoverPath).existsSync()) {
final internalBase = await _internalBasePath;
final existingCover = File('$internalBase/${info.itemId}/cover.jpg');
if (existingCover.existsSync()) {
// Already on disk from a previous download, just not tracked
localCoverPath = existingCover.path;
needsUpdate = true;
} else {
// Also check the custom download path (old downloads may have cover there)
final basePath = await downloadBasePath;
final oldCover = File('$basePath/${info.itemId}/cover.jpg');
if (oldCover.existsSync()) {
localCoverPath = oldCover.path;
needsUpdate = true;
} else {
// Download from server into internal storage
final url = _hiResCoverUrl(coverUrl ?? api.getCoverUrl(apiItemId, width: 1200));
try {
final resp = await http.get(Uri.parse(url), headers: api.mediaHeaders)
.timeout(const Duration(seconds: 10));
if (resp.statusCode == 200 && resp.bodyBytes.isNotEmpty) {
final dir = Directory('$internalBase/${info.itemId}');
if (!dir.existsSync()) dir.createSync(recursive: true);
final coverFile = File('${dir.path}/cover.jpg');
await coverFile.writeAsBytes(resp.bodyBytes);
final evicted = PaintingBinding.instance.imageCache
.evict(FileImage(coverFile));
localCoverPath = coverFile.path;
needsUpdate = true;
debugPrint('[Download] Cached cover for ${info.itemId} '
'(${resp.bodyBytes.length} bytes, evict=$evicted)');
}
} catch (e) {
debugPrint('[Download] Cover cache failed for ${info.itemId}: $e');
}
}
}
} else if (_coverUpgradeChecked.add(info.itemId)) {
// Covers saved before the 1200px fetch were 400px thumbnails, which
// look blurry now that the card and full screen player render them at
// near screen width. Replace them in place, once per item per
// session (a book whose original cover really is small would
// otherwise refetch forever).
final width = await _imageFileWidth(localCoverPath);
if (width != null && width < 800) {
final url = _hiResCoverUrl(coverUrl ?? api.getCoverUrl(apiItemId, width: 1200));
try {
final resp = await http.get(Uri.parse(url), headers: api.mediaHeaders)
.timeout(const Duration(seconds: 10));
if (resp.statusCode == 200 && resp.bodyBytes.isNotEmpty) {
final coverFile = File(localCoverPath);
await coverFile.writeAsBytes(resp.bodyBytes);
PaintingBinding.instance.imageCache.evict(FileImage(coverFile));
debugPrint('[Download] Upgraded ${width}px cover for ${info.itemId} '
'(${resp.bodyBytes.length} bytes)');
}
} catch (e) {
debugPrint('[Download] Cover upgrade failed for ${info.itemId}: $e');
}
}
}
if (needsUpdate) {
_downloads[entry.key] = DownloadInfo(
itemId: info.itemId,
status: info.status,
localPaths: info.localPaths,
sessionData: info.sessionData,
title: title ?? info.title,
author: author ?? info.author,
coverUrl: coverUrl ?? info.coverUrl,
localCoverPath: localCoverPath,
libraryId: info.libraryId,
);
changed = true;
}
}
if (changed) {
await _save();
notifyListeners();
}
}
Future<void> _save() async {
final prefs = await SharedPreferences.getInstance();
final map = <String, dynamic>{};
for (final entry in _downloads.entries) {
if (entry.value.status == DownloadStatus.downloaded) {
map[entry.key] = entry.value.toJson();
}
}
await prefs.setString('downloads', jsonEncode(map));
await prefs.setString('kept_ebooks', jsonEncode({
for (final e in _keptEbooks.entries) e.key: e.value.toJson(),
}));
await prefs.setString('download_origins', jsonEncode(_origins));
}
List<String>? getLocalPaths(String itemId) {
final info = _downloads[itemId];
if (info == null || info.status != DownloadStatus.downloaded) return null;
return info.localPaths;
}
String? getCachedSessionData(String itemId) {
return _downloads[itemId]?.sessionData;
}
/// Get the local cover file path for a downloaded item.
/// Checks the persisted path first, then probes internal and download dirs.
Future<String?> getLocalCoverPath(String itemId) async {
final info = _downloads[itemId];
if (info == null || info.status != DownloadStatus.downloaded) return null;
// Check persisted path
if (info.localCoverPath != null && File(info.localCoverPath!).existsSync()) {
return info.localCoverPath;
}
// Check internal storage (where covers are now cached)
final internalBase = await _internalBasePath;
final internalCover = File('$internalBase/$itemId/cover.jpg');
if (internalCover.existsSync()) return internalCover.path;
// Check custom download path (old downloads may have cover there)
final basePath = await downloadBasePath;
if (basePath != internalBase) {
final customCover = File('$basePath/$itemId/cover.jpg');
if (customCover.existsSync()) return customCover.path;
}
return null;
}
/// Returns null on success, error message string on failure.
/// For podcast episodes, pass [episodeId] so the correct API endpoint is used.
/// [shouldStart] lets a caller invalidate the request while setup is waiting.
Future<String?> downloadItem({
required ApiService api,
required String itemId,
required String title,
String? author,
String? coverUrl,
String? episodeId,
String? libraryId,
bool Function()? shouldStart,
// Set by the auto-download planners. An item the user deleted by hand is
// skipped when automatic; a manual (or download-on-stream) call clears
// that block, since the user asked for it back.
bool automatic = false,
}) async {
if (AppPlatform.lacksPhonePlugins) {
return 'Downloads are not available in the browser.';
}
if (shouldStart?.call() == false) return null;
// Episodes are keyed "podcastId-episodeId" everywhere below. A caller
// holding the bare podcast id (the transcription download prompt did)
// used to fail in the key math before a single request went out.
if (episodeId != null && !itemId.endsWith('-$episodeId')) {
debugPrint('[Download] "$title": composing the episode key from '
'podcast $itemId + episode $episodeId');
itemId = '$itemId-$episodeId';
}
_noteOrigin(itemId);
try {
await init().timeout(const Duration(seconds: 8));
} on TimeoutException catch (e) {
debugPrint('[Download] Downloader initialization still in progress: $e');
return 'Downloads are still starting. Please try again in a moment.';
} catch (e) {
debugPrint('[Download] Downloader initialization failed: $e');
return 'Downloads could not start. Please try again.';
}
if (shouldStart?.call() == false) return null;
if (automatic && _autoDownloadBlocked.contains(itemId)) {
debugPrint(
'[Download] skipped auto-download of "$title" ($itemId): the user deleted it. A manual download, or playing it with download-on-stream on, brings it back');
return null;
}
if (!automatic && _autoDownloadBlocked.remove(itemId)) {
await _saveAutoDownloadBlocks();
}
if (_activeDownloadIds.contains(itemId)) return null;
if (isDownloaded(itemId)) return null;
// Already queued — don't duplicate
if (_queue.any((q) => q.itemId == itemId)) return null;
// Check wifi-only setting
final wifiOnly = await PlayerSettings.getWifiOnlyDownloads();
if (shouldStart?.call() == false) return null;
if (wifiOnly) {
final connectivity = await Connectivity().checkConnectivity();
if (shouldStart?.call() == false) return null;
if (!connectivity.contains(ConnectivityResult.wifi)) {
return 'Downloads are set to Wi-Fi only. Connect to Wi-Fi or change this in Settings.';
}
}
final maxConcurrent = await PlayerSettings.getMaxConcurrentDownloads();
if (shouldStart?.call() == false) return null;
// The checks above ran before settings were loaded, so another tap may
// have started or queued this item in the meantime.
if (_activeDownloadIds.contains(itemId) ||
isDownloaded(itemId) ||
_queue.any((q) => q.itemId == itemId)) {
return null;
}
// If at capacity, queue this one
if (_activeDownloadIds.length >= maxConcurrent) {
if (shouldStart?.call() == false) return null;
debugPrint('[Download] Queued "$title" ($itemId); slots ${_activeDownloadIds.length}/$maxConcurrent full, ${_queue.length} waiting');
_queue.add(_QueuedDownload(
api: api,
itemId: itemId,
title: title,
author: author,
coverUrl: coverUrl,
episodeId: episodeId,
libraryId: libraryId,
));
_downloads[itemId] = DownloadInfo(
itemId: itemId,
status: DownloadStatus.downloading,
progress: 0,
title: title,
author: author,
coverUrl: coverUrl,
libraryId: libraryId,
);
notifyListeners();
return null;
}
// Launch immediately (fire-and-forget so caller doesn't block)
if (shouldStart?.call() == false) return null;
unawaited(_executeDownload(
api: api,
itemId: itemId,
title: title,
author: author,
coverUrl: coverUrl,
episodeId: episodeId,
libraryId: libraryId,
));
return null;
}
/// Download entry point for short-lived background isolates (the episode
/// notification job). Same guards as [downloadItem], but awaits the enqueue
/// (the isolate dies as soon as the task returns, which would cut off a
/// fire-and-forget mid-flight) and skips the in-memory concurrency queue
/// (queued entries would die with the isolate; background_downloader
/// schedules the handed-over tasks natively either way).
Future<void> enqueueBackgroundDownload({
required ApiService api,
required String itemId,
required String title,
String? author,
String? coverUrl,
String? episodeId,
String? libraryId,
}) async {
await init();
if (_activeDownloadIds.contains(itemId)) return;
if (isDownloaded(itemId)) return;
if (_queue.any((q) => q.itemId == itemId)) return;
final wifiOnly = await PlayerSettings.getWifiOnlyDownloads();
if (wifiOnly) {
final connectivity = await Connectivity().checkConnectivity();
// Not on WiFi: skip silently - the in-app catch-up still sees the
// episode as new and downloads it on the next open.
if (!connectivity.contains(ConnectivityResult.wifi)) return;
}
await _executeDownload(
api: api,
itemId: itemId,
title: title,
author: author,
coverUrl: coverUrl,
episodeId: episodeId,
libraryId: libraryId,
);
}
/// Fill free download slots from the queue.
Future<void> _processQueue() async {
final maxConcurrent = await PlayerSettings.getMaxConcurrentDownloads();
while (_queue.isNotEmpty && _activeDownloadIds.length < maxConcurrent) {
final next = _queue.removeAt(0);
// Skip if cancelled/removed while waiting
if (isDownloaded(next.itemId)) continue;
if (_activeDownloadIds.contains(next.itemId)) continue;
unawaited(_executeDownload(
api: next.api, itemId: next.itemId, title: next.title,
author: next.author, coverUrl: next.coverUrl, episodeId: next.episodeId,
libraryId: next.libraryId,
));
}
}
static String _taskId(String itemId, int trackIndex) => '$itemId::$trackIndex';
/// Statuses from which a task will never progress further.
static const Set<TaskStatus> _terminal = {
TaskStatus.complete,
TaskStatus.failed,
TaskStatus.notFound,
TaskStatus.canceled,
};
/// Best-effort download of a book's ebook into the persistent reader cache so
/// it reads offline. Swallows errors - the audio download is what matters.
Future<void> _cacheEbookForOffline(
ApiService api, String itemId, Map<String, dynamic> ebookFile, String title) async {
try {
// A narrated EPUB beside the audiobook comes as the reader's copy
// without its audio. Should that fail, the whole file (hundreds of MB
// of narration the audiobook already has) isn't fetched in its place.
final size = ((ebookFile['metadata'] as Map?)?['size'] as num?)?.toInt() ?? 0;
final f = await NarrationService.instance
.readerFile(api, itemId, ebookFile, title, wholeFallback: size < 50 * 1024 * 1024);
await _excludeFromBackup(f.path);
debugPrint('[Download] cached ebook for offline: $itemId');
} catch (e) {
debugPrint('[Download] ebook offline cache failed for $itemId: $e');
}
}
/// Re-fetch any companion ebooks whose fire-and-forget download never landed
/// (killed mid-transfer, offline at the time). Called when the app comes up
/// with a working connection; cheap when everything is already cached.
Future<void> catchUpEbookCaches(ApiService api) async {
// An ebook opened from a streamed book has a cached file and nothing
// that lists it. Give those a record once, so they show offline.
for (final id in await cachedEbookItemIds()) {
if (_downloads.containsKey(id) || _keptEbooks.containsKey(id)) continue;
if (!_ebookRecheckDone.add('kept:$id')) continue;
await keepEbook(api: api, itemId: id);
}
var changed = false;
for (final entry in _downloads.entries.toList()) {
final info = entry.value;
if (info.status != DownloadStatus.downloaded) continue;
if (info.sessionData == null) continue;
try {
final session = jsonDecode(info.sessionData!) as Map<String, dynamic>;
var item = session['libraryItem'] as Map<String, dynamic>?;
var ebookFile = resolveEbookFile(item);
final apiItemId = session['libraryItemId'] as String? ?? info.itemId;
if (ebookFile == null) {
// The record was written when the book was downloaded. An epub
// dropped into the folder later never reaches it, so offline Read
// says there is no ebook while the web app shows one. Ask the
// server once per run for books whose record has none.
if (session['episodeId'] != null || item == null) continue;
if (!_ebookRecheckDone.add(apiItemId)) continue;
final fresh = await api.getLibraryItem(apiItemId);
ebookFile = resolveEbookFile(fresh);
if (fresh == null || ebookFile == null) continue;
final freshMedia = fresh['media'] as Map<String, dynamic>? ?? {};
final media =
Map<String, dynamic>.from(item['media'] as Map<String, dynamic>? ?? {});
media['ebookFile'] = freshMedia['ebookFile'];
item = Map<String, dynamic>.from(item)
..['media'] = media
..['libraryFiles'] = [ebookFile];
session['libraryItem'] = item;
_downloads[entry.key] = DownloadInfo(
itemId: info.itemId,
status: info.status,
progress: info.progress,
localPaths: info.localPaths,
sessionData: jsonEncode(session),
title: info.title,
author: info.author,
coverUrl: info.coverUrl,
localCoverPath: info.localCoverPath,
localDirPath: info.localDirPath,
libraryId: info.libraryId,
);
changed = true;
debugPrint('[Download] ebook appeared on the server after the '
'download: $apiItemId (${ebookFile['ebookFormat'] ?? ebookFile['metadata']?['ext']})');
}
if (await isEbookCached(apiItemId, ebookFile)) continue;
await _cacheEbookForOffline(
api, apiItemId, ebookFile, info.title ?? apiItemId);
} catch (e) {
debugPrint('[Download] ebook catch-up failed for ${info.itemId}: $e');
}
}
if (changed) {
await _save();
notifyListeners();
}
}
// Books already asked about this run, so a library of downloads costs one
// item fetch each per launch, not one per reconnect.
final Set<String> _ebookRecheckDone = {};
/// Resolve a book/episode to durable per-file download tasks and enqueue them.
/// Returns once the tasks are handed to `background_downloader`; progress and
/// completion are driven asynchronously by [_onTaskUpdate] / [_finalizeSuccess]
/// (which also fire after an app relaunch).
Future<void> _executeDownload({
required ApiService api,
required String itemId,
required String title,
String? author,
String? coverUrl,
String? episodeId,
String? libraryId,
}) async {
_activeDownloadIds.add(itemId);
_cancelledIds.remove(itemId);
debugPrint('[Download] Starting "$title" ($itemId)');
_downloads[itemId] = DownloadInfo(
itemId: itemId,
status: DownloadStatus.downloading,
progress: 0,
title: title,
author: author,
coverUrl: coverUrl,
libraryId: libraryId,
);
notifyListeners();
if (episodeId == null && await _isNarratedEpubBook(api, itemId)) {
await _executeNarrationDownload(
api: api, itemId: itemId, title: title, author: author, coverUrl: coverUrl, libraryId: libraryId);
return;
}
// SAF custom folder (Android only): files go to a flat per-book folder
// under the user-granted tree via content URIs, no storage permission.
final useSaf = Platform.isAndroid &&
_customDownloadUri != null &&
_customDownloadUri!.isNotEmpty;
String? bookDirRef; // filesystem path or content:// URI, for cleanup
Directory? bookDir; // filesystem branches only
try {
// For episodes, itemId is a composite key like 'podcastId-episodeId'.
// Extract the real library item ID for the API call.
final apiItemId = episodeId != null
? itemId.substring(0, itemId.length - episodeId.length - 1)
: itemId;
// Offline metadata and the /file/:ino path of every track, read from the
// item itself. A play session carries the same data, but opening one
// makes the server close whatever session this phone is streaming on:
// the stream then died about 20 seconds into every download and had to
// reload, heard as a blip. The session stays as the fallback for a
// server whose item has no track list.
final sessionData =
await _sessionShapedItem(api, apiItemId, episodeId) ??
(episodeId != null
? await api.startEpisodePlaybackSession(apiItemId, episodeId)
: await api.startPlaybackSession(apiItemId));
if (sessionData == null) throw Exception('Failed to start session');
final audioTracks = sessionData['audioTracks'] as List<dynamic>?;
if (audioTracks == null || audioTracks.isEmpty) {
throw Exception('No audio tracks');
}
// The caller's names come from whatever list started the download, and
// a queue entry has been seen carrying another episode's title and an
// episode title as the show. The server's answer is for exactly this
// item, so it names the record and the folder. An episode's "author"
// is its show, which is how downloads are grouped.
final serverMeta = sessionData['mediaMetadata'] as Map<String, dynamic>?;
final serverTitle = (sessionData['displayTitle'] as String?)?.trim() ?? '';
final authorField = episodeId != null ? 'title' : 'authorName';
final serverAuthor = (serverMeta?[authorField] as String?)?.trim() ?? '';
if (serverTitle.isNotEmpty && serverTitle != title) {
debugPrint('[Download] Title from the server: "$serverTitle" (was "$title")');
title = serverTitle;
}
var renamed = false;
if (serverAuthor.isNotEmpty && serverAuthor != author) {
debugPrint('[Download] Author from the server: "$serverAuthor" (was "$author")');
author = serverAuthor;
renamed = true;
}
if (renamed || _downloads[itemId]?.title != title) {
final running = _downloads[itemId];
if (running != null && running.status == DownloadStatus.downloading) {
_downloads[itemId] = DownloadInfo(
itemId: itemId,
status: DownloadStatus.downloading,
progress: running.progress,
title: title,
author: author,
coverUrl: coverUrl,
libraryId: libraryId,
);
notifyListeners();
}
}
final sessionId = sessionData['id'] as String?;
await api.prepareDownload(apiItemId);
final files = _resolveDurableFiles(api, apiItemId, audioTracks,
sessionId: sessionId);
// A server without the permanent file links (an ABS look-alike) only
// gives this session's temporary ones, which die when the session
// closes, so it stays open until the download ends.
final usesSessionLinks = files.any((f) => _isSessionLink(f.url));
if (usesSessionLinks) {
_linkSessions[itemId] = (api: api, sessionId: sessionId!);
debugPrint('[Download] No permanent file links for "$title", downloading '
'through play session $sessionId (kept open until the download ends)');
}
// Pull the companion ebook into the offline cache too, so a downloaded
// book is fully readable offline. Fire-and-forget - never blocks or fails
// the audio download.
final ebookFile =
resolveEbookFile(sessionData['libraryItem'] as Map<String, dynamic>?);
if (ebookFile != null) {
unawaited(_cacheEbookForOffline(api, apiItemId, ebookFile, title));
}
// Per-book destination. Android downloads to internal storage first - for
// both the internal default AND SAF custom folders. SAF books are then
// moved into the user's chosen folder under "Author/Title" on completion
// (a direct SAF write can't nest subfolders). iOS downloads into the app
// group container.
var nestedName = (author != null && author.isNotEmpty)
? '${_sanitizePath(author)}/${_sanitizePath(title)}'
: _sanitizePath(title);
if (_folderTakenByOther(nestedName, itemId)) {
nestedName = '$nestedName (${itemId.substring(itemId.length - 8)})';
}
String? relDir; // Android: relative to applicationDocuments
if (Platform.isIOS) {
final basePath = await downloadBasePath;
bookDir = Directory('$basePath/$nestedName');
} else {
final appDir = await getApplicationDocumentsDirectory();
relDir = 'downloads/$nestedName';
bookDir = Directory('${appDir.path}/$relDir');
}
if (!bookDir.existsSync()) bookDir.createSync(recursive: true);
bookDirRef = bookDir.path;
debugPrint('[Download] "$title" location=${useSaf ? 'SAF' : 'default'} dir=${bookDir.path} tracks=${files.length}');
final localCoverPath = await _cacheCover(api, itemId, coverUrl);
// Keep a trimmed libraryItem in the persisted session: metadata, chapters
// and the ebook info survive for offline Read, while the bulky episode
// and audio file lists are dropped (mirrors _stripLibraryItem).
// libraryFiles shrinks to just the resolved ebook entry, which covers
// audiobooks-only libraries where every ebook is supplementary and
// media.ebookFile is never set.
final slimSession = Map<String, dynamic>.from(sessionData);
final fullItem = sessionData['libraryItem'] as Map<String, dynamic>?;
if (fullItem == null) {
slimSession.remove('libraryItem');
} else {
final slimItem = Map<String, dynamic>.from(fullItem);
final media = slimItem['media'] as Map<String, dynamic>?;
if (media != null) {
final own = ownEpisodeRecord(media, episodeId);
slimItem['media'] = Map<String, dynamic>.from(media)
..remove('episodes')
..remove('audioFiles');
if (own != null) (slimItem['media'] as Map<String, dynamic>)['episodes'] = [own];
}
slimItem['libraryFiles'] = [if (ebookFile != null) ebookFile];
slimSession['libraryItem'] = slimItem;
}
if (sessionId != null && !usesSessionLinks) {
unawaited(api.closePlaybackSession(sessionId));
}
// Cancelled while we were resolving? Bail before enqueueing anything.
if (_cancelledIds.remove(itemId)) {
_closeLinkSession(itemId);
await _cleanupBookDir(bookDirRef, itemId);
_activeDownloadIds.remove(itemId);
_downloads.remove(itemId);
notifyListeners();
unawaited(_processQueue());
return;
}
final expectedPaths = [for (final f in files) '${bookDir.path}/${f.filename}'];
final wifiOnly = await PlayerSettings.getWifiOnlyDownloads();
final pending = _PendingBook(
itemId: itemId,
apiItemId: apiItemId,
episodeId: episodeId,
title: title,
author: author,
coverUrl: coverUrl,
localCoverPath: localCoverPath,
libraryId: libraryId,
bookDir: bookDirRef,
trackCount: files.length,
expectedPaths: expectedPaths,
slimSessionJson: jsonEncode(slimSession),
safTreeUri: useSaf ? _customDownloadUri : null,
safSubfolder: useSaf ? nestedName : null,
);
_pending[itemId] = pending;
await _persistPending();
// One notification per book instead of one per file task. Multi-file
// books group their tasks under a per-book group notification (the
// package's group progress is finished-files / total, so the bar steps
// per file); single-file books keep the byte-accurate per-task progress.
// The title is baked into the strings because task tokens aren't
// substituted in group notifications.
final l = _l();
final multiFile = files.length > 1;
final runningNotif = Platform.isIOS
// Static text on iOS: iOS can't update a notification in place, so
// dynamic tokens would re-issue it on every change.
? TaskNotification(title, l?.downloadNotifDownloadingTitle ?? 'Downloading')
: TaskNotification(title, multiFile ? '{numFinished} / {numTotal}' : '{progress}');
final completeNotif = TaskNotification(
l?.downloadNotifCompleteTitle ?? 'Download Complete',
l?.downloadNotifCompleteBody(title) ?? '$title is ready to listen offline',
);
final errorNotif = TaskNotification(
l?.downloadNotifFailedTitle ?? 'Download Failed',
title,
);
for (int i = 0; i < files.length; i++) {
final meta = jsonEncode({'itemId': itemId, 'i': i, 'n': files.length});
final Task task;
if (Platform.isIOS) {
task = DownloadTask(
taskId: _taskId(itemId, i),
url: files[i].url,
headers: api.downloadHeadersFor(files[i].url),
filename: files[i].filename,
baseDirectory: BaseDirectory.root,
directory: bookDir.path,
group: _dlGroup,
metaData: meta,
updates: Updates.statusAndProgress,
requiresWiFi: wifiOnly,
retries: 3,
allowPause: true,
);
} else {
task = DownloadTask(
taskId: _taskId(itemId, i),
url: files[i].url,
headers: api.downloadHeadersFor(files[i].url),
filename: files[i].filename,
baseDirectory: BaseDirectory.applicationDocuments,
directory: relDir!,
group: _dlGroup,
metaData: meta,
updates: Updates.statusAndProgress,
requiresWiFi: wifiOnly,
retries: 3,
allowPause: true,
);
}
// Must be registered before enqueue - the config is serialized into
// the native task, so it survives app kills along with the task.
FileDownloader().configureNotificationForTask(
task,
running: runningNotif,
complete: completeNotif,
error: errorNotif,
progressBar: true,
groupNotificationId: multiFile ? itemId : '',
);
final ok = await FileDownloader().enqueue(task);
debugPrint('[Download] enqueue ${i + 1}/${files.length} ok=$ok file=${files[i].filename}');
if (!ok) throw Exception('Failed to enqueue track ${i + 1}');
}
debugPrint('[Download] Enqueued ${files.length} task(s) for "$title"');
} catch (e) {
await _failBook(itemId,
cause: e, bookDirRef: bookDirRef, title: title, author: author, coverUrl: coverUrl);
}
}
/// Whether [itemId] is a book whose audio is its EPUB's narration: known on
/// this phone for Audiobookshelf, said by the item itself on BookOrbit.
Future<bool> _isNarratedEpubBook(ApiService api, String itemId) async {
if (!api.isBookOrbit) return NarratedBooks.contains(itemId);
try {
final item = await api.getLibraryItem(itemId);
return (item?['media'] as Map?)?['narration'] != null;
} catch (e) {
debugPrint('[Download] could not tell whether $itemId is narrated: $e');
return false;
}
}
/// An EPUB that reads itself aloud downloads whole, as one background task
/// with the usual notifications, so it carries on with the app in the
/// background or closed. Its audio is taken out once it lands
/// ([_finishNarration]).
Future<void> _executeNarrationDownload({
required ApiService api,
required String itemId,
required String title,
String? author,
String? coverUrl,
String? libraryId,
}) async {
final useSaf = Platform.isAndroid && _customDownloadUri != null && _customDownloadUri!.isNotEmpty;
String? bookDirRef;
try {
final item = await api.getLibraryItem(itemId);
final ebookFile = resolveEbookFile(item);
final ino = ebookFile?['ino'] as String?;
if (item == null || ebookFile == null || ino == null || ino.isEmpty) {
throw Exception('No EPUB to download');
}
final metadata = (item['media'] as Map?)?['metadata'] as Map?;
final serverTitle = (metadata?['title'] as String?)?.trim() ?? '';
final serverAuthor = (metadata?['authorName'] as String?)?.trim() ?? '';
if (serverTitle.isNotEmpty) title = serverTitle;
if (serverAuthor.isNotEmpty) author = serverAuthor;
var nestedName = (author != null && author.isNotEmpty)
? '${_sanitizePath(author)}/${_sanitizePath(title)}'
: _sanitizePath(title);
if (_folderTakenByOther(nestedName, itemId)) {
nestedName = '$nestedName (${itemId.substring(itemId.length - 8)})';
}
final Directory bookDir;
String? relDir;
if (Platform.isIOS) {
bookDir = Directory('${await downloadBasePath}/$nestedName');
} else {
final appDir = await getApplicationDocumentsDirectory();
relDir = 'downloads/$nestedName';
bookDir = Directory('${appDir.path}/$relDir');
}
if (!bookDir.existsSync()) bookDir.createSync(recursive: true);
bookDirRef = bookDir.path;
final localCoverPath = await _cacheCover(api, itemId, coverUrl);
// What taking the audio out needs later, even with the app restarted
// offline: the item, without its bulky file lists.
final slimItem = Map<String, dynamic>.from(item)..remove('userMediaProgress');
slimItem['media'] = Map<String, dynamic>.from(slimItem['media'] as Map? ?? const {})
..remove('audioFiles');
slimItem['libraryFiles'] = [ebookFile];
if (_cancelledIds.remove(itemId)) {
await _cleanupBookDir(bookDirRef, itemId);
_activeDownloadIds.remove(itemId);
_downloads.remove(itemId);
notifyListeners();
unawaited(_processQueue());
return;
}
final fileMeta = ebookFile['metadata'] as Map?;
final filename = _sanitizePath(fileMeta?['filename'] as String? ?? 'book.epub');
final size = (fileMeta?['size'] as num?)?.toInt();
final target = await api.narratedEpubDownload(itemId, ino);
_narrationApis[itemId] = api;
final url = target.url;
final wifiOnly = await PlayerSettings.getWifiOnlyDownloads();
// BookOrbit streams and keeps places by its own timings, so the
// download keeps them too, saved now while the server is reachable.
var serverTimings = false;
if (api.isBookOrbit) {
final timings = await NarrationService.instance.audioNarration(api, itemId);
if (timings != null) {
await NarrationService.instance.keepTimings(itemId, timings);
serverTimings = true;
} else {
debugPrint('[Download] BookOrbit gave no timings for $itemId - the EPUB\'s own will be used');
}
}
_pending[itemId] = _PendingBook(
itemId: itemId,
apiItemId: itemId,
title: title,
author: author,
coverUrl: coverUrl,
localCoverPath: localCoverPath,
libraryId: libraryId,
bookDir: bookDirRef,
trackCount: 1,
expectedPaths: ['${bookDir.path}/$filename'],
slimSessionJson: jsonEncode({'libraryItem': slimItem}),
narration: true,
serverTimings: serverTimings,
);
await _persistPending();
final l = _l();
final runningNotif = Platform.isIOS
? TaskNotification(title, l?.downloadNotifDownloadingTitle ?? 'Downloading')
: TaskNotification(title, '{progress}');
final completeNotif = TaskNotification(
l?.downloadNotifCompleteTitle ?? 'Download Complete',
l?.downloadNotifCompleteBody(title) ?? '$title is ready to listen offline',
);
final errorNotif = TaskNotification(l?.downloadNotifFailedTitle ?? 'Download Failed', title);
final meta = jsonEncode({'itemId': itemId, 'i': 0, 'n': 1});
final DownloadTask task;
if (Platform.isIOS) {
task = DownloadTask(
taskId: _taskId(itemId, 0),
url: url,
headers: target.headers,
filename: filename,
baseDirectory: BaseDirectory.root,
directory: bookDir.path,
group: _dlGroup,
metaData: meta,
updates: Updates.statusAndProgress,
requiresWiFi: wifiOnly,
retries: 3,
allowPause: true,
);
} else {
task = DownloadTask(
taskId: _taskId(itemId, 0),
url: url,
headers: target.headers,
filename: filename,
baseDirectory: BaseDirectory.applicationDocuments,
directory: relDir!,
group: _dlGroup,
metaData: meta,
updates: Updates.statusAndProgress,
requiresWiFi: wifiOnly,
retries: 3,
allowPause: true,
);
}
FileDownloader().configureNotificationForTask(
task,
running: runningNotif,
complete: completeNotif,
error: errorNotif,
progressBar: true,
);
final ok = await FileDownloader().enqueue(task);
debugPrint('[Download] narration EPUB for "$title" ($itemId) enqueued ok=$ok: $filename, '
'${size ?? '?'} bytes, from ${Uri.parse(url).path}, dir=${bookDir.path}, '
'${serverTimings ? "BookOrbit's timings kept, " : ''}'
'audio goes to ${useSaf ? 'the custom folder' : 'app storage'} once it lands');
if (!ok) throw Exception('Failed to enqueue the EPUB');
} catch (e) {
await _failBook(itemId,
cause: e, bookDirRef: bookDirRef, title: title, author: author, coverUrl: coverUrl);
}
}
/// A narrated EPUB landed: its audio is taken out and kept as the book's
/// download, the reader gets a copy without the audio, and the EPUB is
/// deleted. Runs when the download finishes, or as the app starts when it
/// finished while the app was closed, so it never holds the caller up.
Future<void> _finishNarration(String itemId, _PendingBook p, String epubPath) async {
final started = DateTime.now();
var bytes = 0;
try {
bytes = File(epubPath).lengthSync();
} catch (_) {}
debugPrint('[Download] narration EPUB for "${p.title}" ($itemId) landed ($bytes bytes) - taking its audio out');
Map<String, dynamic>? item;
try {
item = (jsonDecode(p.slimSessionJson ?? '{}') as Map<String, dynamic>)['libraryItem']
as Map<String, dynamic>?;
} catch (_) {}
var ok = false;
try {
if (item != null) {
ok = await NarrationService.instance.keepFromEpub(item, itemId, epubPath, p.bookDir,
localCoverPath: p.localCoverPath, serverTimings: p.serverTimings);
} else {
debugPrint('[Download] narration for $itemId has no saved item to keep it with');
}
} catch (e) {
debugPrint('[Download] taking the narration out of "${p.title}" ($itemId) failed: $e');
}
if (!ok) {
p.finalizing = false; // let _failBook proceed
await _failBook(itemId, cause: 'The narration could not be taken out of the EPUB');
return;
}
_activeDownloadIds.remove(itemId);
_pending.remove(itemId);
await _persistPending();
await _deleteDbRecords(itemId, p.trackCount);
notifyListeners();
debugPrint('[Download] Complete: ${p.title} (narration, kept '
'${DateTime.now().difference(started).inMilliseconds}ms after the EPUB landed)');
unawaited(_processQueue());
}
/// Rebuild forced-direct-play track URLs against the current server/token so
/// native tasks can outlive the playback session that supplied the metadata.
/// What a download needs from a play session - tracks, chapters, duration
/// and the item for offline metadata - built from the item instead, in the
/// session's shape so everything that reads a stored download is unchanged.
/// Null when the item does not give a usable track list; the caller then
/// falls back to a real session.
Future<Map<String, dynamic>?> _sessionShapedItem(
ApiService api, String apiItemId, String? episodeId) async {
try {
final fetched = await api.getLibraryItem(apiItemId);
if (fetched == null) return null;
final item = Map<String, dynamic>.from(fetched)..remove('userMediaProgress');
final media = item['media'] as Map<String, dynamic>? ?? const {};
final metadata = media['metadata'] as Map<String, dynamic>? ?? const {};
List<dynamic> tracks;
List<dynamic> chapters;
num? duration;
String? title;
String? author;
if (episodeId != null) {
final episode = (media['episodes'] as List<dynamic>? ?? const [])
.whereType<Map<String, dynamic>>()
.where((e) => e['id'] == episodeId)
.firstOrNull;
final track = episode?['audioTrack'];
if (episode == null || track is! Map<String, dynamic>) return null;
tracks = [track];
chapters = episode['chapters'] as List<dynamic>? ?? const [];
duration = episode['duration'] as num? ?? track['duration'] as num?;
title = episode['title'] as String?;
author = metadata['author'] as String?;
} else {
tracks = media['tracks'] as List<dynamic>? ?? const [];
chapters = media['chapters'] as List<dynamic>? ?? const [];
duration = media['duration'] as num?;
title = metadata['title'] as String?;
author = metadata['authorName'] as String?;
}
if (tracks.isEmpty || duration == null || duration <= 0) return null;
// Throws on a track without a /file/:ino path.
_resolveDurableFiles(api, apiItemId, tracks);
debugPrint('[Download] Track list read from the item, no play session opened '
'(${tracks.length} tracks)');
return {
'libraryItemId': apiItemId,
'episodeId': episodeId,
'mediaType': item['mediaType'],
'mediaMetadata': metadata,
'displayTitle': title,
'displayAuthor': author,
'duration': duration,
'chapters': chapters,
'audioTracks': tracks,
'libraryItem': item,
};
} catch (e) {
debugPrint('[Download] Item has no usable track list ($e) - using a play session');
return null;
}
}
/// The permanent `/api/items/:id/file/:ino` link of every track. With a
/// play session's [sessionId], a track that has none may use that
/// session's temporary `/public/session/:id/track/:index` link instead.
List<({String url, String filename})> _resolveDurableFiles(
ApiService api, String apiItemId, List<dynamic> audioTracks,
{String? sessionId}) {
final out = <({String url, String filename})>[];
for (int i = 0; i < audioTracks.length; i++) {
final track = audioTracks[i] as Map<String, dynamic>;
final contentUrl = track['contentUrl'] as String? ?? '';
final uri = Uri.tryParse(contentUrl);
if (uri == null) {
throw Exception('Invalid direct file URL for track ${i + 1}');
}
if (uri.hasScheme || uri.hasAuthority) {
final serverUri = Uri.parse(api.cleanBaseUrl);
if (!uri.hasScheme ||
!uri.hasAuthority ||
(uri.scheme != 'http' && uri.scheme != 'https') ||
uri.origin != serverUri.origin) {
throw Exception('Track ${i + 1} points to a different server');
}
}
// A narrated EPUB's audio, on servers that serve it file by file.
final narration = api.buildNarrationDownloadUrl(apiItemId, contentUrl);
if (narration != null) {
out.add((url: narration, filename: _trackFileName(track, i)));
continue;
}
final segments = uri.pathSegments;
String? ino;
for (int segment = 0; segment + 4 < segments.length; segment++) {
if (segments[segment] != 'api' ||
segments[segment + 1] != 'items' ||
segments[segment + 3] != 'file' ||
segment + 5 != segments.length) {
continue;
}
if (segments[segment + 2] != apiItemId) {
throw Exception('Track ${i + 1} belongs to a different library item');
}
ino = segments[segment + 4];
break;
}
if (ino == null &&
sessionId != null &&
sessionId.isNotEmpty &&
uri.path.contains('/public/session/$sessionId/track/')) {
out.add((url: api.buildTrackUrl(contentUrl), filename: _trackFileName(track, i)));
continue;
}
if (ino == null ||
ino.isEmpty ||
ino.contains('/') ||
ino.contains('?') ||
ino.contains('#')) {
throw Exception('Missing direct file URL for track ${i + 1}');
}
out.add((url: api.buildDownloadFileUrl(apiItemId, ino), filename: _trackFileName(track, i)));
}
return out;
}
/// Derive the on-disk filename for a track, preferring its original name so
/// the layout matches what older (http-based) downloads produced.
String _trackFileName(Map<String, dynamic> track, int i) {
final contentUrl = track['contentUrl'] as String? ?? '';
final trackMeta = track['metadata'] as Map<String, dynamic>?;
var originalName = trackMeta?['filename'] as String? ?? '';
if (originalName.isEmpty) {
final contentPath = Uri.tryParse(contentUrl)?.path ?? contentUrl;
originalName = undoPercentEscapes(contentPath.split('/').last);
if (originalName.contains('?')) originalName = originalName.split('?').first;
}
if (originalName.isNotEmpty && originalName.contains('.')) {
return _sanitizePath(originalName.replaceAll(RegExp(r'\.[^.]+$'), '')) +
originalName.substring(originalName.lastIndexOf('.'));
}
final mimeType = track['mimeType'] as String? ?? 'audio/mpeg';
final ext = mimeType.contains('mp4')
? 'm4a'
: mimeType.contains('flac')
? 'flac'
: mimeType.contains('ogg')
? 'ogg'
: 'mp3';
return 'track_${i.toString().padLeft(3, '0')}.$ext';
}
/// The player card and full screen player render the downloaded cover at
/// near screen width, so the stored copy has to be sharper than the 400px
/// thumbnail URL most callers hold. Leaves local paths and widthless URLs
/// alone.
static String _hiResCoverUrl(String url) =>
url.replaceAllMapped(RegExp(r'width=\d+'), (_) => 'width=1200');
/// Pixel width of an image file without fully decoding it. Returns null
/// when the file can't be read as an image.
static Future<int?> _imageFileWidth(String path) async {
try {
final buffer = await ui.ImmutableBuffer.fromFilePath(path);
final descriptor = await ui.ImageDescriptor.encoded(buffer);
final w = descriptor.width;
descriptor.dispose();
buffer.dispose();
return w;
} catch (_) {
return null;
}
}
/// Cache the cover into INTERNAL storage (lockscreen / Android Auto / offline).
/// Always internal, since a custom external audio path may lack write access.
Future<String?> _cacheCover(ApiService api, String itemId, String? coverUrl) async {
if (coverUrl == null || coverUrl.isEmpty) return null;
try {
final coverResp = await http.get(Uri.parse(_hiResCoverUrl(coverUrl)), headers: api.mediaHeaders)
.timeout(const Duration(seconds: 10));
if (coverResp.statusCode == 200 && coverResp.bodyBytes.isNotEmpty) {
final internalBase = await _internalBasePath;
final coverDir = Directory('$internalBase/$itemId');
if (!coverDir.existsSync()) coverDir.createSync(recursive: true);
final coverFile = File('${coverDir.path}/cover.jpg');
await coverFile.writeAsBytes(coverResp.bodyBytes);
debugPrint('[Download] Cached cover image: ${coverFile.path}');
return coverFile.path;
}
} catch (e) {
debugPrint('[Download] Cover cache failed (non-fatal): $e');
}
return null;
}
// ── background_downloader update handling ──
(String, int)? _decodeMeta(String metaData) {
if (metaData.isEmpty) return null;
try {
final m = jsonDecode(metaData) as Map<String, dynamic>;
final itemId = m['itemId'] as String?;
final i = m['i'] as int?;
if (itemId == null || i == null) return null;
return (itemId, i);
} catch (_) {
return null;
}
}
void _onTaskUpdate(TaskUpdate update) {
final meta = _decodeMeta(update.task.metaData);
if (meta == null) return;
final itemId = meta.$1;
final i = meta.$2;
final p = _pending[itemId];
if (p == null) return;
p.lastUpdate = DateTime.now();
if (update is TaskProgressUpdate) {
final prog = update.progress;
if (prog >= 0 && prog <= 1) {
p.trackProgress[i] = prog;
_emitBookProgress(itemId, p);
}
} else if (update is TaskStatusUpdate) {
if (_signInRanOut(itemId, p, update)) {
p.signInRenewals++;
unawaited(_carryOnWithFreshSignIn(itemId, i, update));
return;
}
unawaited(
_handleTaskStatus(
itemId: itemId,
trackIndex: i,
status: update.status,
exception: update.exception,
responseCode: update.responseStatusCode,
),
);
}
}
/// A narrated EPUB downloads whole as one long request, signed in once.
/// When it has to start a new request (a dropped connection, Android's
/// nine-minute work limit) after BookOrbit's 15-minute sign-in has lapsed,
/// the server says 401 and the plugin retries with the same headers.
bool _signInRanOut(String itemId, _PendingBook p, TaskStatusUpdate update) {
if (update.status != TaskStatus.failed || !p.narration) return false;
if (p.cancelled || p.failing || p.signInRenewals >= 2) return false;
if (!_narrationApis.containsKey(itemId)) return false;
final ex = update.exception;
final code = update.responseStatusCode ?? (ex is TaskHttpException ? ex.httpResponseCode : null);
return code == 401;
}
Future<void> _carryOnWithFreshSignIn(String itemId, int trackIndex, TaskStatusUpdate update) async {
final task = update.task;
final api = _narrationApis[itemId];
if (task is DownloadTask && api != null) {
try {
final headers = await api.renewedMediaHeaders();
final renewed = task.copyWith(headers: {...task.headers, ...headers});
final resumed = await FileDownloader().resume(renewed);
final ok = resumed || await FileDownloader().enqueue(renewed);
debugPrint('[Download] $itemId: the sign-in ran out mid-download, '
'${ok ? (resumed ? 'resuming' : 'starting over') : 'could not go on'} with a fresh one');
if (ok) return;
} catch (e) {
debugPrint('[Download] $itemId: could not renew the download sign-in: $e');
}
}
await _handleTaskStatus(
itemId: itemId,
trackIndex: trackIndex,
status: update.status,
exception: update.exception,
responseCode: update.responseStatusCode,
);
}
Future<void> _handleTaskStatus({
required String itemId,
required int trackIndex,
required TaskStatus status,
TaskException? exception,
int? responseCode,
}) async {
final p = _pending[itemId];
if (p == null) return;
p.lastUpdate = DateTime.now();
p.trackStatus[trackIndex] = status;
debugPrint(
'[Download] task $itemId #$trackIndex status=${status.name}'
'${exception != null ? ' ex=$exception' : ''}'
'${responseCode != null ? ' code=$responseCode' : ''}',
);
if (status == TaskStatus.complete) p.trackProgress[trackIndex] = 1.0;
// A hard failure aborts the whole book so it does not wait forever for
// sibling tracks that will never finish on their own.
if ((status == TaskStatus.failed || status == TaskStatus.notFound) && !p.cancelled && !p.failing) {
p.failing = true;
p.failException = exception;
p.failCode = responseCode;
unawaited(_cancelSiblings(itemId, p));
}
await _checkBookTerminal(itemId, p);
}
void _emitBookProgress(String itemId, _PendingBook p) {
final now = DateTime.now();
if (now.difference(p.lastUi).inMilliseconds < 250) return;
p.lastUi = now;
unawaited(_updateBookNotification(itemId, p, now));
_downloads[itemId] = DownloadInfo(
itemId: itemId,
status: DownloadStatus.downloading,
progress: p.overallProgress,
title: p.title,
author: p.author,
coverUrl: p.coverUrl,
libraryId: p.libraryId,
);
notifyListeners();
}
/// Once every track of a book is terminal, route to success / fail / cancel.
Future<void> _checkBookTerminal(String itemId, _PendingBook p) async {
if (p.finalizing) return;
for (int i = 0; i < p.trackCount; i++) {
final s = p.trackStatus[i];
if (s == null || !_terminal.contains(s)) return;
}
_narrationApis.remove(itemId);
if (p.trackStatus.values.every((s) => s == TaskStatus.complete)) {
p.finalizing = true;
await _finalizeSuccess(itemId);
} else if (p.failing) {
await _failBook(
itemId,
taskException: p.failException,
responseCode: p.failCode,
);
} else {
p.finalizing = true;
await _handleCanceled(itemId);
}
}
@visibleForTesting
Future<void> debugSeedPendingDownload({
required String itemId,
required int trackCount,
}) async {
final bookDir = '${Directory.systemTemp.path}/absorb_download_service_test/$itemId';
_pending[itemId] = _PendingBook(
itemId: itemId,
apiItemId: itemId,
title: 'Test download',
bookDir: bookDir,
trackCount: trackCount,
expectedPaths: List.generate(
trackCount,
(index) => '$bookDir/$index.mp3',
),
);
_activeDownloadIds.add(itemId);
_downloads[itemId] = DownloadInfo(
itemId: itemId,
status: DownloadStatus.downloading,
title: 'Test download',
);
await _persistPending();
}
@visibleForTesting
Future<void> debugHandleTaskStatus({
required String itemId,
required int trackIndex,
required TaskStatus status,
int? responseCode,
}) =>
_handleTaskStatus(
itemId: itemId,
trackIndex: trackIndex,
status: status,
responseCode: responseCode,
);
@visibleForTesting
List<({String url, String filename})> debugResolveDurableFiles({
required ApiService api,
required String itemId,
required List<dynamic> audioTracks,
String? sessionId,
}) =>
_resolveDurableFiles(api, itemId, audioTracks, sessionId: sessionId);
@visibleForTesting
void debugPutDownload(DownloadInfo info) => _downloads[info.itemId] = info;
@visibleForTesting
void debugPutKeptEbook(DownloadInfo info) => _keptEbooks[info.itemId] = info;
@visibleForTesting
Future<void> debugReset() async {
_reconcileTimer?.cancel();
_reconcileTimer = null;
await _updatesSub?.cancel();
_updatesSub = null;
_downloads.clear();
_keptEbooks.clear();
_activeDownloadIds.clear();
_cancelledIds.clear();
_pending.clear();
_queue.clear();
_downloaderConfigured = false;
_initFuture = null;
_iosAudioMigrationFuture = null;
_initialized = false;
backgroundIsolateMode = false;
final prefs = await SharedPreferences.getInstance();
await prefs.remove('pending_downloads');
}
/// Move a completed book's internal files into the SAF folder [treeUri] under
/// [subfolder] (e.g. "Author/Title"), via the native DocumentFile helper.
/// Returns the created folder URI and the per-file content URIs, or null if
/// the move failed.
Future<({String dirUri, List<String> fileUris})?> _moveBookToSaf(
String treeUri, String subfolder, List<String> filenames, List<String> tempPaths) async {
try {
final res = await _storageChannel.invokeMethod<Map>('moveBookToSaf', {
'treeUri': treeUri,
'subfolder': subfolder,
'filenames': filenames,
'tempPaths': tempPaths,
});
final dirUri = res?['dirUri'] as String?;
final fileUris = (res?['fileUris'] as List?)?.map((e) => e as String).toList();
if (dirUri == null || fileUris == null || fileUris.length != filenames.length) {
return null;
}
return (dirUri: dirUri, fileUris: fileUris);
} catch (e) {
debugPrint('[Download] moveBookToSaf failed: $e');
return null;
}
}
static bool _isSessionLink(String url) =>
Uri.tryParse(url)?.path.contains('/public/session/') ?? false;
/// Close the play session a download used for temporary links. Kept in
/// memory only: after an app restart the session is left for the server
/// to clear.
void _closeLinkSession(String itemId) {
final link = _linkSessions.remove(itemId);
if (link == null) return;
debugPrint('[Download] Closing play session ${link.sessionId} used for "$itemId"');
unawaited(link.api.closePlaybackSession(link.sessionId));
}
Future<void> _finalizeSuccess(String itemId) async {
final p = _pending[itemId];
if (p == null) return;
_closeLinkSession(itemId);
// Files always land in internal storage first.
final localPaths = p.expectedPaths.where((path) => File(path).existsSync()).toList();
if (localPaths.length != p.trackCount) {
debugPrint('[Download] Finalize "$itemId": only ${localPaths.length}/${p.trackCount} '
'files present, treating as failure');
p.finalizing = false; // let _failBook proceed
await _failBook(itemId, cause: 'Missing files after download');
return;
}
if (p.narration) {
unawaited(_finishNarration(itemId, p, localPaths.first));
return;
}
var finalPaths = localPaths;
String? finalDirPath = p.bookDir;
// SAF: move the downloaded files into the user's chosen folder under
// "Author/Title" and play/delete via the returned content URIs. If the move
// fails the book stays usable from its internal copy.
if (p.isSaf) {
final filenames = [for (final path in localPaths) path.split('/').last];
final moved = await _moveBookToSaf(
p.safTreeUri!, p.safSubfolder ?? '', filenames, localPaths);
if (moved != null) {
finalPaths = moved.fileUris;
finalDirPath = moved.dirUri;
await _cleanupBookDir(p.bookDir, p.itemId); // drop the now-empty internal temp dir
} else {
debugPrint('[Download] SAF move failed for "$itemId", keeping internal copy');
}
} else if (Platform.isIOS) {
for (final path in localPaths) {
await _excludeFromBackup(path);
}
}
_downloads[itemId] = DownloadInfo(
itemId: itemId,
status: DownloadStatus.downloaded,
localPaths: finalPaths,
sessionData: p.slimSessionJson,
title: p.title,
author: p.author,
coverUrl: p.coverUrl,
localCoverPath: p.localCoverPath,
localDirPath: finalDirPath,
libraryId: p.libraryId,
);
await _save();
_activeDownloadIds.remove(itemId);
_pending.remove(itemId);
await _persistPending();
await _deleteDbRecords(itemId, p.trackCount);
notifyListeners();
// Hot-swap if this book is currently streaming. switchToLocal reads the
// live position, so it's safe even when this fires from a background update.
try {
final player = AudioPlayerService();
if (player.hasBook) {
await player.switchToLocal(itemId);
}
} catch (_) {}
debugPrint('[Download] Complete: ${p.title} (${localPaths.length} files)');
unawaited(_processQueue());
}
Future<void> _failBook(
String itemId, {
Object? cause,
TaskException? taskException,
int? responseCode,
String? title,
String? author,
String? coverUrl,
String? bookDirRef,
}) async {
final p = _pending[itemId];
if (p != null) {
if (p.finalizing) return;
p.finalizing = true;
}
_closeLinkSession(itemId);
final t = title ?? p?.title ?? '';
final a = author ?? p?.author;
final c = coverUrl ?? p?.coverUrl;
final dir = bookDirRef ?? p?.bookDir;
if (p != null) await _cancelSiblings(itemId, p, force: true);
// Stall/zombie fails have no errored task, so the canceled siblings end
// the group notification as "complete" - dismiss it. When a task really
// failed the group correctly shows the error notification; leave that.
if (p != null && !p.failing && p.trackCount > 1) {
_dismissGroupNotification(itemId);
}
await _cleanupBookDir(dir, itemId);
final msg = _mapError(cause, taskException, responseCode);
_downloads[itemId] = DownloadInfo(
itemId: itemId,
status: DownloadStatus.error,
title: t,
author: a,
coverUrl: c,
);
_activeDownloadIds.remove(itemId);
_pending.remove(itemId);
await _persistPending();
await _deleteDbRecords(itemId, p?.trackCount ?? 0);
_cancelledIds.remove(itemId);
debugPrint('[Download] Failed "$t": $msg (${cause ?? taskException?.description})');
_toastFailure(t, cause, taskException, responseCode);
notifyListeners();
unawaited(_processQueue());
}
/// A failed book used to just drop back to the download button, so a book
/// whose server folder holds a file the server 404s looked like it never
/// started (GH #310). Say what went wrong.
void _toastFailure(
String title, Object? cause, TaskException? te, int? code) {
final navigator = rootNavigatorKey.currentState;
if (navigator == null) return;
final l = AppLocalizations.of(navigator.context);
if (l == null) return;
final s = '${cause ?? ''} ${te?.description ?? ''}'.toLowerCase();
final String message;
if (code == 404) {
message = l.downloadFailedMissingFile(title);
} else if (s.contains('no space') || s.contains('enospc')) {
message = l.downloadFailedNoSpace(title);
} else if (s.contains('permission') ||
s.contains('not permitted') ||
code == 403) {
message = l.downloadFailedPermission(title);
} else {
message = l.downloadFailedGeneric(title);
}
showNavigatorOverlayToast(navigator, message,
icon: Icons.error_outline_rounded);
}
Future<void> _handleCanceled(String itemId) async {
final p = _pending[itemId];
_closeLinkSession(itemId);
// A canceled book still ends its group notification as "complete" (the
// package counts canceled tasks as finished, not failed), which would
// leave a lingering "Download Complete" for a book the user just
// canceled - dismiss it.
if ((p?.trackCount ?? 0) > 1) _dismissGroupNotification(itemId);
await _cleanupBookDir(p?.bookDir, itemId);
_downloads.remove(itemId);
_activeDownloadIds.remove(itemId);
_pending.remove(itemId);
await _persistPending();
await _deleteDbRecords(itemId, p?.trackCount ?? 0);
_cancelledIds.remove(itemId);
debugPrint('[Download] Cancelled: ${p?.title ?? itemId}');
notifyListeners();
unawaited(_processQueue());
}
/// Dismiss a book's group download notification. The package posts the
/// terminal group notification from native workers slightly after the last
/// task ends, so sweep twice. Android only: on iOS the package posts under
/// string identifiers flutter_local_notifications can't target, and there a
/// stray "complete" only sits silently in the notification center.
void _dismissGroupNotification(String itemId) {
if (!Platform.isAndroid) return;
final id = _groupNotifId(itemId);
for (final delay in const [Duration(seconds: 1), Duration(seconds: 4)]) {
Future.delayed(delay, () async {
try {
await FlutterLocalNotificationsPlugin().cancel(id);
} catch (e) {
debugPrint('[Download] dismiss group notification failed: $e');
}
});
}
}
/// The package derives its group notification id on the Kotlin side as
/// "groupNotification$name".hashCode() - reproduce Java's string hash so we
/// can address the same notification.
int _groupNotifId(String itemId) {
var h = 0;
for (final u in 'groupNotification$itemId'.codeUnits) {
h = (h * 31 + u) & 0xFFFFFFFF;
}
return h >= 0x80000000 ? h - 0x100000000 : h;
}
/// Byte-accurate progress for a multi-file book's notification (Android).
/// The package's group notification only counts finished files, so with
/// parallel per-file tasks the bar sits at 0 until files start completing
/// (a half-downloaded book reads "0 / 5"). We already aggregate the real
/// byte progress for the in-app UI, so post it onto the same notification
/// id the package uses. The package only re-posts on task state changes
/// (enqueue/start/finish), so between those moments this owns the
/// notification, and the package's terminal complete/error post still
/// lands last.
Future<void> _updateBookNotification(String itemId, _PendingBook p, DateTime now) async {
if (!Platform.isAndroid || p.trackCount <= 1) return;
if (p.finalizing || p.cancelled) return;
final done = p.trackStatus.values.where((s) => s == TaskStatus.complete).length;
if (done >= p.trackCount) return; // the terminal post owns it from here
final pct = (p.overallProgress * 100).clamp(0.0, 100.0).round();
if (pct == p.notifPct && done == p.notifDone) return;
if (now.difference(p.notifPost).inMilliseconds < 1000) return;
p.notifPct = pct;
p.notifDone = done;
p.notifPost = now;
try {
await FlutterLocalNotificationsPlugin().show(
_groupNotifId(itemId),
p.title,
'$done / ${p.trackCount}',
NotificationDetails(
// Same channel the package posts on, so no second channel shows up
// in the app's notification settings.
android: AndroidNotificationDetails(
'background_downloader',
'Downloads',
importance: Importance.low,
priority: Priority.low,
ongoing: true,
autoCancel: false,
onlyAlertOnce: true,
showProgress: true,
maxProgress: 100,
progress: pct,
// The package's own download icon (kept alive by its Kotlin R
// reference), so the icon doesn't flick when the package posts.
icon: 'outline_file_download_24',
),
),
);
} catch (e) {
debugPrint('[Download] progress notification failed: $e');
}
}
Future<void> _cancelSiblings(
String itemId,
_PendingBook p, {
bool force = false,
}) async {
final ids = <String>[];
for (int i = 0; i < p.trackCount; i++) {
final s = p.trackStatus[i];
if (force || s == null || !_terminal.contains(s)) ids.add(_taskId(itemId, i));
}
if (ids.isNotEmpty) {
try {
final cancelTasks = _cancelTasksOverride;
if (cancelTasks != null) {
await cancelTasks(ids);
} else {
await FileDownloader().cancelTasksWithIds(ids);
}
} catch (_) {}
}
}
/// Remove a book's download folder. [bookDir] is a filesystem path. SAF
/// downloads share the user's granted folder, so there's no per-book folder
/// to remove (cleanup of SAF files is per-file via [deleteDownload]).
Future<void> _cleanupBookDir(String? bookDir, String itemId) async {
if (bookDir == null || isContentUri(bookDir)) return;
if (_dirSharedWithOther(bookDir, itemId)) return;
final dir = Directory(bookDir);
try {
if (dir.existsSync()) {
dir.deleteSync(recursive: true);
final parent = dir.parent;
if (parent.existsSync() && parent.listSync().isEmpty) parent.deleteSync();
}
} catch (_) {}
}
/// True when another download already lives in [nestedName] ("Author/Title").
/// Books sharing a title and author (a release split into parts) used to
/// share one folder, so deleting or failing one wiped the others' files.
bool _folderTakenByOther(String nestedName, String itemId) {
bool matches(String? dir) {
if (dir == null) return false;
final d = undoPercentEscapes(dir).replaceAll(r'\', '/');
return d.endsWith('/$nestedName');
}
for (final e in _downloads.entries) {
if (e.key != itemId && matches(e.value.localDirPath)) return true;
}
for (final p in _pending.values) {
if (p.itemId != itemId &&
(matches(p.bookDir) || p.safSubfolder == nestedName)) {
return true;
}
}
return false;
}
/// Whether any other download keeps files in [dirPath]. Downloads made
/// before folders were made unique can still share one, and removing the
/// whole folder then deletes books the user never touched.
bool _dirSharedWithOther(String dirPath, String itemId) {
final prefix = dirPath.endsWith('/') ? dirPath : '$dirPath/';
for (final e in _downloads.entries) {
if (e.key == itemId) continue;
final info = e.value;
if (info.localDirPath == dirPath) return true;
if (info.localPaths.any((p) => p.startsWith(prefix))) return true;
}
for (final p in _pending.values) {
if (p.itemId != itemId && p.bookDir == dirPath) return true;
}
return false;
}
String _mapError(Object? cause, TaskException? te, int? code) {
final s = '${cause ?? ''} ${te?.description ?? ''}'.toLowerCase();
if (s.contains('no space') || s.contains('enospc')) return 'Not enough storage space';
if (s.contains('permission') || s.contains('not permitted') || code == 403) {
return 'Permission denied - check download location in Settings';
}
return 'Download failed';
}
Future<void> _deleteDbRecords(String itemId, int trackCount) async {
for (int i = 0; i < trackCount; i++) {
try {
final taskId = _taskId(itemId, i);
final deleteTaskRecord = _deleteTaskRecordOverride;
if (deleteTaskRecord != null) {
await deleteTaskRecord(taskId);
} else {
await FileDownloader().database.deleteRecordWithId(taskId);
}
} catch (_) {}
}
}
// ── Resume-after-kill persistence ──
Future<void> _persistPending() async {
final prefs = await SharedPreferences.getInstance();
if (_pending.isEmpty) {
await prefs.remove('pending_downloads');
return;
}
final map = {for (final e in _pending.entries) e.key: e.value.toJson()};
await prefs.setString('pending_downloads', jsonEncode(map));
}
Future<void> _loadPending() async {
final prefs = await SharedPreferences.getInstance();
final json = prefs.getString('pending_downloads');
if (json == null) return;
try {
final map = jsonDecode(json) as Map<String, dynamic>;
for (final e in map.entries) {
final p = _PendingBook.fromJson(e.value as Map<String, dynamic>);
_pending[e.key] = p;
_activeDownloadIds.add(e.key);
_downloads[e.key] = DownloadInfo(
itemId: e.key,
status: DownloadStatus.downloading,
progress: 0,
title: p.title,
author: p.author,
coverUrl: p.coverUrl,
libraryId: p.libraryId,
);
}
} catch (e) {
debugPrint('[Download] loadPending error: $e');
}
}
Future<void> _loadAutoDownloadBlocks() async {
final prefs = await SharedPreferences.getInstance();
_autoDownloadBlocked
..clear()
..addAll(prefs.getStringList(_autoDownloadBlockedKey) ?? const []);
}
Future<void> _saveAutoDownloadBlocks() async {
final prefs = await SharedPreferences.getInstance();
if (_autoDownloadBlocked.isEmpty) {
await prefs.remove(_autoDownloadBlockedKey);
} else {
await prefs.setStringList(
_autoDownloadBlockedKey, _autoDownloadBlocked.toList());
}
}
/// Rebuild in-flight progress from the package task DB after a relaunch, then
/// finalize books that finished while we were dead and drop ones whose tasks
/// are gone. Tasks still in flight keep running; their updates (plus
/// resumeFromBackground) drive them to terminal.
Future<void> _rehydratePending() async {
if (_pending.isEmpty) return;
List<TaskRecord> records;
try {
records = await FileDownloader().database.allRecords();
} catch (_) {
records = const [];
}
final tracked = <String, Set<int>>{};
for (final r in records) {
final meta = _decodeMeta(r.task.metaData);
if (meta == null) continue;
final p = _pending[meta.$1];
if (p == null) continue;
final i = meta.$2;
p.trackStatus[i] = r.status;
p.trackProgress[i] = r.status == TaskStatus.complete
? 1.0
: (r.progress >= 0 && r.progress <= 1 ? r.progress : 0.0);
(tracked[meta.$1] ??= {}).add(i);
}
for (final itemId in _pending.keys.toList()) {
final p = _pending[itemId]!;
bool allComplete = p.trackCount > 0;
bool allTerminal = true;
for (int i = 0; i < p.trackCount; i++) {
final s = p.trackStatus[i];
if (s != TaskStatus.complete) allComplete = false;
if (s == null || !_terminal.contains(s)) allTerminal = false;
}
if (allComplete) {
p.finalizing = true;
await _finalizeSuccess(itemId);
} else if (allTerminal) {
// No p.finalizing pre-set here or below: _failBook refuses to run
// when it's already true (see the reconciler note).
await _failBook(itemId, cause: 'Interrupted download');
} else if ((tracked[itemId]?.isEmpty ?? true)) {
// The package has no record of these tasks (DB wiped) and we can't
// rebuild durable URLs here, so surface as failed for a manual retry.
await _failBook(itemId, cause: 'Interrupted download');
} else {
// Still in flight: leave it; updates + resumeFromBackground finish it.
_emitBookProgress(itemId, p);
}
}
}
/// [byUser] marks a deliberate removal: the auto-download planners then
/// leave this item alone until a manual download, or a play with
/// download-on-stream on, brings it back - see [downloadItem].
Future<void> deleteDownload(
String itemId, {
bool skipStopCheck = false,
bool byUser = false,
}) async {
if (byUser && _autoDownloadBlocked.add(itemId)) {
debugPrint(
'[Download] $itemId removed by the user - auto-download leaves it alone from now on');
await _saveAutoDownloadBlocks();
}
// If this is still downloading or waiting for a slot, cancel it (which
// cleans up partial files and the background tasks) rather than deleting.
if (_pending.containsKey(itemId) || _queue.any((q) => q.itemId == itemId)) {
cancelDownload(itemId);
return;
}
final info = _downloads[itemId];
if (info == null) return;
// Stop playback if this item is currently playing to avoid crashes. An
// episode key has to match the playing episode, not just its show:
// matching on the show alone stopped whatever was playing whenever
// another episode of the same podcast was deleted.
if (!skipStopCheck) {
final player = AudioPlayerService();
final playingId = player.currentItemId;
final playingKey = playingId == null
? null
: player.currentEpisodeId == null
? playingId
: '$playingId-${player.currentEpisodeId}';
if (playingKey == itemId) {
await player.stop();
}
}
final sharedPaths = <String>{
for (final e in _downloads.entries)
if (e.key != itemId) ...e.value.localPaths,
};
for (final path in info.localPaths) {
if (sharedPaths.contains(path)) continue;
try {
if (isContentUri(path)) {
await FileDownloader().uri.deleteFile(Uri.parse(path));
} else {
final file = File(path);
if (file.existsSync()) file.deleteSync();
}
} catch (_) {}
}
// Remove the download directory (new-style path from DownloadInfo, or legacy UUID path)
try {
final dirPath = info.localDirPath;
if (dirPath != null && _dirSharedWithOther(dirPath, itemId)) {
// Other books still have files here: only this book's files go.
} else if (dirPath != null && isContentUri(dirPath)) {
// SAF book folder: best-effort delete (harmless if already emptied).
try {
await FileDownloader().uri.deleteFile(Uri.parse(dirPath));
} catch (_) {}
} else if (dirPath != null && Directory(dirPath).existsSync()) {
Directory(dirPath).deleteSync(recursive: true);
// Clean up empty parent (Author folder) if it's now empty
final parent = Directory(dirPath).parent;
if (parent.existsSync() && parent.listSync().isEmpty) {
parent.deleteSync();
}
} else {
// Legacy fallback: UUID-based directory
final basePath = await downloadBasePath;
final bookDir = Directory('$basePath/$itemId');
if (bookDir.existsSync()) bookDir.deleteSync(recursive: true);
}
} catch (_) {}
try {
final internalBase = await _internalBasePath;
final coverDir = Directory('$internalBase/$itemId');
final coverFile = File('$internalBase/$itemId/cover.jpg');
// FileImage caches by path; evict so a re-download at the same path renders fresh.
if (coverFile.existsSync()) {
final evicted = PaintingBinding.instance.imageCache
.evict(FileImage(coverFile));
debugPrint('[Download] evict cover ${coverFile.path} -> $evicted');
}
if (coverDir.existsSync()) coverDir.deleteSync(recursive: true);
} catch (e) {
debugPrint('[Download] cover cleanup failed: $e');
}
// Drop the offline ebook copy too, unless the reader has a claim on it.
if (!_keptEbooks.containsKey(itemId)) await deleteCachedEbook(itemId);
_downloads.remove(itemId);
if (!_keptEbooks.containsKey(itemId)) _origins.remove(itemId);
await _save();
notifyListeners();
}
void cancelDownload(String itemId) {
// Drop it from the waiting queue if it never started.
_queue.removeWhere((q) => q.itemId == itemId);
// Flag so an in-flight _executeDownload bails before enqueueing, and so a
// book mid-resolution doesn't leak an active slot.
_cancelledIds.add(itemId);
final p = _pending[itemId];
if (p != null && !p.finalizing) {
p.cancelled = true;
// Ask the package to cancel any live tasks, then clean up ourselves. We do
// NOT wait for the package's `canceled` update: it never fires for tasks
// the package no longer tracks (e.g. records left over after an app
// update), which would leak the slot and wedge the whole queue.
final ids = [for (int i = 0; i < p.trackCount; i++) _taskId(itemId, i)];
unawaited(FileDownloader().cancelTasksWithIds(ids));
unawaited(_handleCanceled(itemId)); // frees the slot + processes the queue
} else {
_activeDownloadIds.remove(itemId);
}
// Drop a companion ebook the fire-and-forget fetch may have already
// landed, so a cancelled download doesn't orphan it.
unawaited(deleteCachedEbook(itemId));
// Instant UI feedback (cleanup paths also notify).
_downloads.remove(itemId);
notifyListeners();
}
}