A cross platform Audiobookshelf client for Android and iOS
Dart
import 'dart:convert';
import 'package:flutter/foundation.dart';
import 'package:shared_preferences/shared_preferences.dart';
import '../utils/episode_key.dart';
import 'api_service.dart';
import 'scoped_prefs.dart';
import 'settings_sync_service.dart';
import 'user_account_service.dart';
/// A single bookmark in an audiobook.
class Bookmark {
final String id;
final double positionSeconds;
final DateTime created;
String title;
String? note;
Bookmark({
required this.id,
required this.positionSeconds,
required this.created,
required this.title,
this.note,
});
/// Combined text for syncing to ABS server (which only has a single "title" field).
String get serverTitle {
if (note != null && note!.isNotEmpty) return '$title - $note';
return title;
}
/// The inverse of [serverTitle]: split a server title back into title and
/// note at the first " - ", so a bookmark written on one phone comes apart
/// the same way on another. Re-encoding the split pair yields the identical
/// server string, so nothing is ever lost - at worst a title that itself
/// contains " - " moves its tail into the note.
static ({String title, String? note}) splitServerTitle(String raw) {
final i = raw.indexOf(' - ');
if (i <= 0) return (title: raw.trim(), note: null);
final title = raw.substring(0, i).trim();
final note = raw.substring(i + 3).trim();
if (title.isEmpty || note.isEmpty) return (title: raw.trim(), note: null);
return (title: title, note: note);
}
Map<String, dynamic> toJson() => {
'id': id,
'pos': positionSeconds,
'ts': created.millisecondsSinceEpoch,
'title': title,
if (note != null && note!.isNotEmpty) 'note': note,
};
factory Bookmark.fromJson(Map<String, dynamic> json) {
var title = json['title'] as String? ?? 'Bookmark';
var note = json['note'] as String?;
// Bookmarks pulled from the server before splitServerTitle existed were
// stored with the combined "title - note" as their title - come apart now.
if (note == null || note.isEmpty) {
final parts = splitServerTitle(title);
title = parts.title;
note = parts.note;
}
return Bookmark(
id: json['id'] as String? ?? '${DateTime.now().millisecondsSinceEpoch}',
positionSeconds: (json['pos'] as num?)?.toDouble() ?? (json['time'] as num?)?.toDouble() ?? 0,
created: json['ts'] != null
? DateTime.fromMillisecondsSinceEpoch(json['ts'] as int)
: json['createdAt'] != null
? DateTime.fromMillisecondsSinceEpoch((json['createdAt'] as num).toInt())
: DateTime.now(),
title: title,
note: note,
);
}
/// Create from ABS server bookmark format: { title, time, createdAt }.
/// The server only has "title", carrying our "title - note" encoding.
factory Bookmark.fromServer(Map<String, dynamic> json) {
final parts = splitServerTitle(json['title'] as String? ?? 'Bookmark');
return Bookmark(
id: '${(json['createdAt'] as num?)?.toInt() ?? DateTime.now().millisecondsSinceEpoch}',
positionSeconds: (json['time'] as num?)?.toDouble() ?? 0,
created: json['createdAt'] != null
? DateTime.fromMillisecondsSinceEpoch((json['createdAt'] as num).toInt())
: DateTime.now(),
title: parts.title,
note: parts.note,
);
}
String get formattedPosition => formattedAt(1.0);
/// Position formatted for display at [speed] (stored seconds / speed), so
/// lists can honor the speed-adjusted-time setting. The stored position and
/// everything sent to the server stay raw book seconds.
String formattedAt(double speed) {
final div = speed > 0 ? speed : 1.0;
// Guard against a negative stored position (e.g. a stray -1): Dart's modulo
// on negatives would otherwise render -1s as "59:59".
final p = positionSeconds < 0 ? 0.0 : positionSeconds / div;
final h = p ~/ 3600;
final m = (p % 3600) ~/ 60;
final s = p.toInt() % 60;
if (h > 0) {
return '$h:${m.toString().padLeft(2, '0')}:${s.toString().padLeft(2, '0')}';
}
return '$m:${s.toString().padLeft(2, '0')}';
}
}
/// Stores per-book bookmarks in SharedPreferences with server sync.
///
/// Podcast episodes are keyed by the compound "showId-episodeId" key. Those
/// stay on the device: an ABS bookmark carries a library item id and nothing
/// else, so a pushed episode bookmark would come back attached to the whole
/// show, landing every episode's marks in one pile at times that mean nothing
/// outside the episode they were made in. They travel between devices in the
/// settings backup instead, which is why every local change nudges the sync.
class BookmarkService {
static final BookmarkService _instance = BookmarkService._();
factory BookmarkService() => _instance;
BookmarkService._();
static const int _maxBookmarksPerBook = 100;
static const _keyPrefix = 'bookmarks_';
// Persisted via ScopedPrefs so offline pending state survives app restart.
static const _pendingCreatesKey = 'bookmarks_pending_creates';
static const _pendingDeletesKey = 'bookmarks_pending_deletes';
// Track bookmarks not yet pushed to server (created offline).
final Set<String> _unpushed = {}; // "itemId::position" keys
// Track bookmarks deleted offline that need to be deleted on server.
final Map<String, Set<double>> _pendingDeletes = {}; // itemId -> positions
// Scope key whose pending state is currently hydrated into the two fields above.
String? _hydratedScope;
/// Lazily load pending creates/deletes from prefs, re-hydrating when the
/// active account scope changes.
Future<void> _ensureHydrated() async {
final scope = UserAccountService().activeScopeKey;
if (_hydratedScope == scope) return;
_unpushed.clear();
_pendingDeletes.clear();
final createsJson = await ScopedPrefs.getString(_pendingCreatesKey);
if (createsJson != null && createsJson.isNotEmpty) {
try {
final list = jsonDecode(createsJson) as List<dynamic>;
_unpushed.addAll(list.whereType<String>());
} catch (e) {
debugPrint('[Bookmarks] Failed to parse pending creates: $e');
}
}
final deletesJson = await ScopedPrefs.getString(_pendingDeletesKey);
if (deletesJson != null && deletesJson.isNotEmpty) {
try {
final map = jsonDecode(deletesJson) as Map<String, dynamic>;
for (final entry in map.entries) {
final positions = (entry.value as List<dynamic>)
.whereType<num>()
.map((n) => n.toDouble())
.toSet();
if (positions.isNotEmpty) _pendingDeletes[entry.key] = positions;
}
} catch (e) {
debugPrint('[Bookmarks] Failed to parse pending deletes: $e');
}
}
// Episode bookmarks are local-only now. Older builds queued them for a
// push that the server can only 404, so clear out any that are still
// sitting in the queue instead of retrying them forever.
final strandedCreates =
_unpushed.where((k) => isEpisodeKey(k.split('::').first)).toList();
if (strandedCreates.isNotEmpty) {
_unpushed.removeAll(strandedCreates);
await _persistUnpushed();
}
final strandedDeletes = _pendingDeletes.keys.where(isEpisodeKey).toList();
if (strandedDeletes.isNotEmpty) {
for (final k in strandedDeletes) {
_pendingDeletes.remove(k);
}
await _persistPendingDeletes();
}
_hydratedScope = scope;
}
Future<void> _persistUnpushed() async {
await ScopedPrefs.setString(_pendingCreatesKey, jsonEncode(_unpushed.toList()));
}
Future<void> _persistPendingDeletes() async {
final out = <String, List<double>>{};
for (final entry in _pendingDeletes.entries) {
if (entry.value.isNotEmpty) out[entry.key] = entry.value.toList();
}
await ScopedPrefs.setString(_pendingDeletesKey, jsonEncode(out));
}
/// Get all bookmarks for a book.
Future<List<Bookmark>> getBookmarks(String itemId, {String sort = 'newest'}) async {
final stored = await ScopedPrefs.getStringList('$_keyPrefix$itemId');
final bookmarks = <Bookmark>[];
for (final json in stored) {
try {
bookmarks.add(Bookmark.fromJson(jsonDecode(json)));
} catch (e) {
debugPrint('[Bookmarks] Failed to parse: $e');
}
}
if (sort == 'position') {
bookmarks.sort((a, b) => a.positionSeconds.compareTo(b.positionSeconds));
} else if (sort == 'position_desc') {
bookmarks.sort((a, b) => b.positionSeconds.compareTo(a.positionSeconds));
} else {
bookmarks.sort((a, b) => b.created.compareTo(a.created));
}
return bookmarks;
}
/// Add a bookmark. Returns the new bookmark.
Future<Bookmark> addBookmark({
required String itemId,
required double positionSeconds,
required String title,
String? note,
ApiService? api,
}) async {
final bookmark = Bookmark(
id: '${DateTime.now().millisecondsSinceEpoch}',
positionSeconds: positionSeconds,
created: DateTime.now(),
title: title,
note: note,
);
final key = '$_keyPrefix$itemId';
final existing = (await ScopedPrefs.getStringList(key)).toList();
existing.add(jsonEncode(bookmark.toJson()));
if (existing.length > _maxBookmarksPerBook) {
existing.removeRange(0, existing.length - _maxBookmarksPerBook);
}
await ScopedPrefs.setStringList(key, existing);
debugPrint('[Bookmarks] Added "${bookmark.title}" at ${bookmark.formattedPosition}');
await _ensureHydrated();
if (isEpisodeKey(itemId)) {
SettingsSyncService().noteLocalChange();
return bookmark;
}
// Flag the bookmark pending BEFORE pushing it to the server. If the app is
// suspended or killed mid-push (common on iOS right after bookmarking then
// pausing), the flag is already persisted, so the next sync keeps and
// retries it instead of seeing it missing on the server and deleting it.
// Cleared only once the server confirms the create.
final unpushedKey = '$itemId::${positionSeconds.toStringAsFixed(1)}';
_unpushed.add(unpushedKey);
await _persistUnpushed();
if (api != null &&
await api.createBookmark(itemId, time: positionSeconds, title: bookmark.serverTitle)) {
_unpushed.remove(unpushedKey);
await _persistUnpushed();
}
return bookmark;
}
/// Update a bookmark's title and/or note.
Future<void> updateBookmark({
required String itemId,
required String bookmarkId,
String? title,
String? note,
ApiService? api,
}) async {
final key = '$_keyPrefix$itemId';
final stored = await ScopedPrefs.getStringList(key);
double? time;
String? serverTitle;
final updated = <String>[];
for (final json in stored) {
try {
final bm = Bookmark.fromJson(jsonDecode(json));
if (bm.id == bookmarkId) {
if (title != null) bm.title = title;
// null = leave the note as-is; empty string = clear it.
if (note != null) bm.note = note.isEmpty ? null : note;
time = bm.positionSeconds;
serverTitle = bm.serverTitle;
updated.add(jsonEncode(bm.toJson()));
} else {
updated.add(json);
}
} catch (_) {
updated.add(json);
}
}
await ScopedPrefs.setStringList(key, updated);
if (isEpisodeKey(itemId)) {
SettingsSyncService().noteLocalChange();
return;
}
// Update on server
if (api != null && time != null && serverTitle != null) {
await api.updateBookmark(itemId, time: time, title: serverTitle);
}
}
/// Move a bookmark to a new time. Updates locally and re-points the server
/// entry - ABS keys bookmarks by time, so moving is delete-old + create-new.
/// Falls back to the offline pending queues when the server can't be reached.
Future<void> moveBookmark({
required String itemId,
required String bookmarkId,
required double newPositionSeconds,
ApiService? api,
}) async {
final newPos = newPositionSeconds < 0 ? 0.0 : newPositionSeconds;
final key = '$_keyPrefix$itemId';
final stored = await ScopedPrefs.getStringList(key);
double? oldTime;
String? serverTitle;
final updated = <String>[];
for (final json in stored) {
try {
final bm = Bookmark.fromJson(jsonDecode(json));
if (bm.id == bookmarkId) {
oldTime = bm.positionSeconds;
serverTitle = bm.serverTitle;
updated.add(jsonEncode(Bookmark(
id: bm.id,
positionSeconds: newPos,
created: bm.created,
title: bm.title,
note: bm.note,
).toJson()));
} else {
updated.add(json);
}
} catch (_) {
updated.add(json);
}
}
if (oldTime == null) return; // bookmark not found
await ScopedPrefs.setStringList(key, updated);
if ((oldTime - newPos).abs() < 0.05) return; // no real change
await _ensureHydrated();
if (isEpisodeKey(itemId)) {
SettingsSyncService().noteLocalChange();
debugPrint('[Bookmarks] Moved $bookmarkId: ${oldTime}s -> ${newPos}s (local)');
return;
}
// The old position's pending-create (if any) no longer applies. Flag the
// new position pending BEFORE the network calls (same write-ahead reasoning
// as addBookmark) so a suspend or kill mid-move can't orphan the moved
// bookmark and have the next sync delete it. Cleared once the server
// confirms the create.
final newKey = '$itemId::${newPos.toStringAsFixed(1)}';
_unpushed.remove('$itemId::${oldTime.toStringAsFixed(1)}');
_unpushed.add(newKey);
await _persistUnpushed();
bool deletedOk = false;
bool createdOk = false;
if (api != null) {
deletedOk = await api.deleteBookmark(itemId, time: oldTime);
createdOk = await api.createBookmark(itemId, time: newPos, title: serverTitle ?? '');
}
if (createdOk) _unpushed.remove(newKey);
if (!deletedOk) _pendingDeletes.putIfAbsent(itemId, () => {}).add(oldTime);
await _persistUnpushed();
await _persistPendingDeletes();
debugPrint('[Bookmarks] Moved $bookmarkId: ${oldTime}s -> ${newPos}s');
}
/// Delete a bookmark.
Future<void> deleteBookmark({
required String itemId,
required String bookmarkId,
ApiService? api,
}) async {
final key = '$_keyPrefix$itemId';
final stored = await ScopedPrefs.getStringList(key);
double? time;
final updated = <String>[];
for (final json in stored) {
try {
final bm = Bookmark.fromJson(jsonDecode(json));
if (bm.id != bookmarkId) {
updated.add(json);
} else {
time = bm.positionSeconds;
}
} catch (_) {
updated.add(json);
}
}
await ScopedPrefs.setStringList(key, updated);
debugPrint('[Bookmarks] Deleted bookmark $bookmarkId');
await _ensureHydrated();
if (isEpisodeKey(itemId)) {
SettingsSyncService().noteLocalChange();
return;
}
// If this bookmark was an unpushed offline create, drop the pending-create
// flag - the server never knew about it, so there's nothing to delete.
if (time != null) {
final unpushedKey = '$itemId::${time.toStringAsFixed(1)}';
if (_unpushed.remove(unpushedKey)) {
await _persistUnpushed();
return;
}
}
// Delete on server
if (time != null) {
bool needsPersist = false;
if (api != null) {
final ok = await api.deleteBookmark(itemId, time: time);
if (!ok) {
_pendingDeletes.putIfAbsent(itemId, () => {}).add(time);
needsPersist = true;
}
} else {
_pendingDeletes.putIfAbsent(itemId, () => {}).add(time);
needsPersist = true;
}
if (needsPersist) await _persistPendingDeletes();
}
}
/// Sync bookmarks for a specific item with the server.
/// Merges local and server bookmarks by position (time).
/// If [preloadedServerBookmarks] is provided, uses that instead of fetching.
Future<void> syncBookmarks(String itemId, ApiService api, {List<Map<String, dynamic>>? preloadedServerBookmarks}) async {
// Episode bookmarks never reach the server, so there is nothing to merge -
// and an empty server list here would read as "deleted everywhere" and
// wipe them.
if (isEpisodeKey(itemId)) return;
try {
await _ensureHydrated();
// Flush any pending deletes first. Keep entries that still failed so we
// can retry next sync instead of silently dropping them.
final pendingDels = _pendingDeletes[itemId];
if (pendingDels != null && pendingDels.isNotEmpty) {
final stillPending = <double>{};
for (final time in pendingDels) {
final deleted = await api.deleteBookmark(itemId, time: time);
if (deleted) {
debugPrint('[Bookmarks] Flushed pending delete at ${time}s');
} else {
stillPending.add(time);
}
}
if (stillPending.isEmpty) {
_pendingDeletes.remove(itemId);
} else {
_pendingDeletes[itemId] = stillPending;
}
await _persistPendingDeletes();
}
final serverBookmarks = preloadedServerBookmarks ?? await api.getServerBookmarks(itemId);
if (serverBookmarks == null) return; // offline or error
final localBookmarks = await getBookmarks(itemId);
// Build position-based lookup (with 1s tolerance)
bool posMatch(double a, double b) => (a - b).abs() < 1.0;
// Find server bookmarks not in local
for (final sb in serverBookmarks) {
final serverBm = Bookmark.fromServer(sb);
final localMatch = localBookmarks.where((lb) => posMatch(lb.positionSeconds, serverBm.positionSeconds)).firstOrNull;
if (localMatch == null) {
// Server has it, local doesn't - add locally
final key = '$_keyPrefix$itemId';
final existing = (await ScopedPrefs.getStringList(key)).toList();
existing.add(jsonEncode(serverBm.toJson()));
await ScopedPrefs.setStringList(key, existing);
debugPrint('[Bookmarks] Synced from server: "${serverBm.title}" at ${serverBm.formattedPosition}');
} else if (serverBm.serverTitle != localMatch.serverTitle && serverBm.created.isAfter(localMatch.created)) {
// Server is newer - take its title and note (fromServer already
// split the combined server string back into the two fields).
localMatch
..title = serverBm.title
..note = serverBm.note;
await _saveAll(itemId, localBookmarks);
debugPrint('[Bookmarks] Updated from server: "${serverBm.title}"');
}
}
// Remove local bookmarks that no longer exist on server,
// but push any that were created offline and haven't been synced yet.
final refreshedLocal = await getBookmarks(itemId);
final kept = <Bookmark>[];
bool localChanged = false;
bool unpushedChanged = false;
for (final lb in refreshedLocal) {
final serverMatch = serverBookmarks.whereType<Map<String, dynamic>>().where((sb) =>
posMatch((sb['time'] as num?)?.toDouble() ?? 0, lb.positionSeconds)).firstOrNull;
if (serverMatch != null) {
kept.add(lb);
continue;
}
final unpushedKey = '$itemId::${lb.positionSeconds.toStringAsFixed(1)}';
if (_unpushed.contains(unpushedKey)) {
// Created offline, try to push now. Only clear the pending flag if
// the push actually succeeded - otherwise we keep retrying on the
// next sync instead of silently losing the bookmark.
final pushed = await api.createBookmark(itemId, time: lb.positionSeconds, title: lb.serverTitle);
if (pushed) {
_unpushed.remove(unpushedKey);
unpushedChanged = true;
debugPrint('[Bookmarks] Pushed offline bookmark: "${lb.title}" at ${lb.formattedPosition}');
} else {
debugPrint('[Bookmarks] Push failed, will retry: "${lb.title}" at ${lb.formattedPosition}');
}
kept.add(lb);
} else {
debugPrint('[Bookmarks] Removed locally (deleted on server): "${lb.title}" at ${lb.formattedPosition}');
localChanged = true;
}
}
if (localChanged) await _saveAll(itemId, kept);
if (unpushedChanged) await _persistUnpushed();
} catch (e) {
debugPrint('[Bookmarks] Sync error: $e');
}
}
/// Save all bookmarks for an item (used internally after batch updates).
Future<void> _saveAll(String itemId, List<Bookmark> bookmarks) async {
final key = '$_keyPrefix$itemId';
await ScopedPrefs.setStringList(key, bookmarks.map((b) => jsonEncode(b.toJson())).toList());
}
/// Get all bookmarks across all books for the current account, keyed by itemId.
Future<Map<String, List<Bookmark>>> getAllBookmarks({String sort = 'newest'}) async {
final prefs = await SharedPreferences.getInstance();
final scope = UserAccountService().activeScopeKey;
final scopedPrefix = scope.isNotEmpty ? '$scope:$_keyPrefix' : _keyPrefix;
final result = <String, List<Bookmark>>{};
for (final key in prefs.getKeys()) {
if (!key.startsWith(scopedPrefix)) continue;
final itemId = key.substring(scopedPrefix.length);
// The service's own offline-sync keys (bookmarks_pending_creates /
// bookmarks_pending_deletes) live under the same "bookmarks_" prefix but
// are Strings, not String lists. getStringList() throws on them, which
// used to leave the Bookmarks screen spinning forever for any account
// that had made offline bookmark changes. Skip them (and guard defensively).
if (itemId == 'pending_creates' || itemId == 'pending_deletes') continue;
final List<String> stored;
try {
stored = prefs.getStringList(key) ?? [];
} catch (_) {
continue;
}
final bookmarks = <Bookmark>[];
for (final json in stored) {
try {
bookmarks.add(Bookmark.fromJson(jsonDecode(json)));
} catch (_) {}
}
if (bookmarks.isNotEmpty) {
if (sort == 'position') {
bookmarks.sort((a, b) => a.positionSeconds.compareTo(b.positionSeconds));
} else if (sort == 'position_desc') {
bookmarks.sort((a, b) => b.positionSeconds.compareTo(a.positionSeconds));
} else {
bookmarks.sort((a, b) => b.created.compareTo(a.created));
}
result[itemId] = bookmarks;
}
}
if (sort == 'newest') {
final sorted = Map.fromEntries(
result.entries.toList()..sort((a, b) => b.value.first.created.compareTo(a.value.first.created)),
);
return sorted;
}
return result;
}
/// Get bookmark count for a book.
Future<int> getCount(String itemId) async {
return (await ScopedPrefs.getStringList('$_keyPrefix$itemId')).length;
}
/// Clear all bookmarks for a book.
Future<void> clearBookmarks(String itemId) async {
await ScopedPrefs.remove('$_keyPrefix$itemId');
await _ensureHydrated();
final prefix = '$itemId::';
final dropped = _unpushed.where((k) => k.startsWith(prefix)).toList();
if (dropped.isNotEmpty) {
_unpushed.removeAll(dropped);
await _persistUnpushed();
}
if (_pendingDeletes.remove(itemId) != null) {
await _persistPendingDeletes();
}
}
}