A cross platform Audiobookshelf client for Android and iOS
Dart
import 'dart:ui' as ui;
import 'package:flutter/material.dart';
import 'package:just_audio/just_audio.dart';
import 'package:shared_preferences/shared_preferences.dart';
import 'narrated_books.dart';
import 'scoped_prefs.dart';
import '../widgets/card_button_config.dart';
typedef QueueModeSnapshot = ({
String bookMode,
String podcastMode,
String? playlistId,
String? collectionId,
String? collectionName,
});
// ─── Auto-rewind settings ───
class AutoRewindSettings {
final bool enabled;
final double minRewind;
final double maxRewind;
final double
activationDelay; // seconds — how long pause must be before rewind kicks in
final bool
chapterBarrier; // don't rewind past the start of the current chapter
final bool
sessionStartRewind; // rewind by maxRewind when starting a new session
const AutoRewindSettings({
this.enabled = true,
this.minRewind = 1.0,
this.maxRewind = 30.0,
this.activationDelay = 0.0, // 0 = always rewind on resume
this.chapterBarrier = false,
this.sessionStartRewind = false,
});
static Future<AutoRewindSettings> load() async {
return AutoRewindSettings(
enabled: await ScopedPrefs.getBool('autoRewind_enabled') ?? true,
minRewind: await ScopedPrefs.getDouble('autoRewind_min') ?? 1.0,
maxRewind: await ScopedPrefs.getDouble('autoRewind_max') ?? 30.0,
activationDelay: await ScopedPrefs.getDouble('autoRewind_delay') ?? 0.0,
chapterBarrier:
await ScopedPrefs.getBool('autoRewind_chapterBarrier') ?? false,
sessionStartRewind:
await ScopedPrefs.getBool('autoRewind_sessionStart') ?? false,
);
}
Future<void> save() async {
await ScopedPrefs.setBool('autoRewind_enabled', enabled);
await ScopedPrefs.setDouble('autoRewind_min', minRewind);
await ScopedPrefs.setDouble('autoRewind_max', maxRewind);
await ScopedPrefs.setDouble('autoRewind_delay', activationDelay);
await ScopedPrefs.setBool('autoRewind_chapterBarrier', chapterBarrier);
await ScopedPrefs.setBool('autoRewind_sessionStart', sessionStartRewind);
}
}
enum CardScrubberMode { both, chapter, locked }
extension CardScrubberModeBehavior on CardScrubberMode {
bool get allowsBookSeeking => this == CardScrubberMode.both;
bool get allowsChapterSeeking => this != CardScrubberMode.locked;
}
class PlayerSettings {
/// Swatches offered for the read along and live transcript color.
static const List<int> readAlongPalette = [
0xFFFFC400,
0xFFFF6D00,
0xFFFF1744,
0xFFFF4081,
0xFFD500F9,
0xFF2979FF,
0xFF00B8D4,
0xFF00C853,
];
/// Notifier that fires when any player setting changes.
/// Widgets can listen to this instead of polling SharedPreferences.
static final ChangeNotifier settingsChanged = ChangeNotifier();
static Future<void> _queueModeMutation = Future.value();
static Future<T> _serializeQueueModeMutation<T>(
Future<T> Function() mutation,
) {
final result = _queueModeMutation.then((_) => mutation());
_queueModeMutation = result.then<void>(
(_) {},
onError: (Object _, StackTrace __) {},
);
return result;
}
static void _notify() {
// ignore: invalid_use_of_protected_member, invalid_use_of_visible_for_testing_member
settingsChanged.notifyListeners();
}
/// Public trigger for external callers that save settings directly.
static void notifySettingsChanged() => _notify();
// ── Private helpers to eliminate boilerplate ──
static Future<T> _get<T>(String key, T defaultValue) async {
Object? value;
if (defaultValue is bool) {
value = await ScopedPrefs.getBool(key);
} else if (defaultValue is int) {
value = await ScopedPrefs.getInt(key);
} else if (defaultValue is double) {
value = await ScopedPrefs.getDouble(key);
} else if (defaultValue is String) {
value = await ScopedPrefs.getString(key);
}
if (value is T) return value;
return defaultValue;
}
static Future<void> _set<T>(
String key,
T value, {
bool notify = false,
}) async {
if (value is bool) {
await ScopedPrefs.setBool(key, value);
} else if (value is int) {
await ScopedPrefs.setInt(key, value);
} else if (value is double) {
await ScopedPrefs.setDouble(key, value);
} else if (value is String) {
await ScopedPrefs.setString(key, value);
}
if (notify) _notify();
}
// ── General settings ──
static Future<double> getDefaultSpeed() => _get('defaultSpeed', 1.0);
static Future<void> setDefaultSpeed(double speed) =>
_set('defaultSpeed', speed);
/// Per-library default speed: a library (podcasts, say) can start its items
/// at its own speed instead of the global default. null = no override.
static Future<double?> getSpeedOverride(String libraryId) =>
ScopedPrefs.getDouble('speedOverride_$libraryId');
static Future<void> setSpeedOverride(String libraryId, double? speed) async {
if (speed == null) {
await ScopedPrefs.remove('speedOverride_$libraryId');
} else {
await ScopedPrefs.setDouble('speedOverride_$libraryId', speed);
}
_notify();
}
/// The speed a book or episode starts at before it has one of its own.
static Future<double> defaultSpeedFor({String? libraryId}) async {
if (libraryId != null && libraryId.isNotEmpty) {
final override = await getSpeedOverride(libraryId);
if (override != null) return override;
}
return getDefaultSpeed();
}
static const List<double> defaultSpeedPresets = [
0.75,
1.0,
1.25,
1.5,
1.75,
2.0,
2.5,
];
static Future<List<double>> getSpeedPresets() async {
final raw = await _get('speedPresets', '');
if (raw.isEmpty) return List<double>.from(defaultSpeedPresets);
final parsed = <double>[];
for (final part in raw.split(',')) {
final v = double.tryParse(part);
if (v != null) parsed.add(v);
}
if (parsed.isEmpty) return List<double>.from(defaultSpeedPresets);
parsed.sort();
return parsed;
}
static Future<void> setSpeedPresets(List<double> presets) async {
final sorted = [...presets]..sort();
await _set(
'speedPresets',
sorted.map((s) => s.toStringAsFixed(2)).join(','),
notify: true,
);
}
static Future<void> resetSpeedPresets() async {
await _set('speedPresets', '', notify: true);
}
/// Audible region override for Find Missing Books (e.g. "us", "uk", "de").
/// Empty string means use device locale.
static Future<String> getAudibleRegion() => _get('audibleRegion', '');
static Future<void> setAudibleRegion(String value) =>
_set('audibleRegion', value);
/// Font-size multiplier for the elapsed/remaining/percent text on the player
/// card (GH #230, accessibility). 1.0 = default.
static Future<double> getProgressTextScale() =>
_get('progressTextScale', 1.0);
static Future<void> setProgressTextScale(double v) =>
_set('progressTextScale', v, notify: true);
static Future<bool> getUpcomingReleasesSortByDate() =>
_get('upcomingReleasesSortByDate', false);
static Future<void> setUpcomingReleasesSortByDate(bool value) =>
_set('upcomingReleasesSortByDate', value);
/// Years without a new release before the upcoming-releases scan considers
/// a series finished and stops checking it every time (0 = never skip).
static Future<int> getUpcomingFinishedAfterYears() =>
_get('upcomingFinishedAfterYears', 3);
static Future<void> setUpcomingFinishedAfterYears(int value) =>
_set('upcomingFinishedAfterYears', value);
/// Last state of the "delete files from the server" checkbox in the delete
/// confirm. Starts ticked and remembers what you picked, same as the web UI
/// (which keeps `softDeleteDefault` in localStorage).
static Future<bool> getDeleteFromFileSystem() =>
_get('deleteFromFileSystem', true);
static Future<void> setDeleteFromFileSystem(bool value) =>
_set('deleteFromFileSystem', value);
static Future<bool> getWifiOnlyDownloads() =>
_get('wifiOnlyDownloads', false);
static Future<void> setWifiOnlyDownloads(bool value) =>
_set('wifiOnlyDownloads', value);
static Future<int> getRollingDownloadCount() =>
_get('rollingDownloadCount', 3);
static Future<void> setRollingDownloadCount(int value) =>
_set('rollingDownloadCount', value);
static Future<bool> getRollingDownloadDeleteFinished() =>
_get('rollingDownloadDeleteFinished', false);
static Future<void> setRollingDownloadDeleteFinished(bool value) =>
_set('rollingDownloadDeleteFinished', value);
static Future<bool> getQueueAutoDownload() =>
_get('queueAutoDownload', false);
static Future<void> setQueueAutoDownload(bool value) =>
_set('queueAutoDownload', value);
static Future<bool> getAutoDownloadOnStream() =>
_get('autoDownloadOnStream', false);
static Future<void> setAutoDownloadOnStream(bool value) =>
_set('autoDownloadOnStream', value);
/// When on, starting a book that's part of a series automatically turns on
/// series auto-download for that series (the same per-series toggle shown in
/// the series sheet). Default off.
static Future<bool> getAutoSeriesDownloadDefault() =>
_get('autoSeriesDownloadDefault', false);
static Future<void> setAutoSeriesDownloadDefault(bool value) =>
_set('autoSeriesDownloadDefault', value);
/// Bookmark sort: 'newest' (default) or 'position'
static Future<String> getBookmarkSort() => _get('bookmarkSort', 'newest');
static Future<void> setBookmarkSort(String value) =>
_set('bookmarkSort', value);
// On-device bookmark transcription (Whisper, opt-in). Stored globally
// (raw SharedPreferences, not per-account) because the downloaded Whisper
// model is shared across every profile on the device.
/// Moves the ebook to where listening stopped, and the audiobook to where
/// reading stopped, for books with both (transcription does the finding).
static Future<bool> getSyncReadingListening() async {
final prefs = await SharedPreferences.getInstance();
return prefs.getBool('syncReadingListening') ?? false;
}
static Future<void> setSyncReadingListening(bool value) async {
final prefs = await SharedPreferences.getInstance();
await prefs.setBool('syncReadingListening', value);
}
static Future<bool> getTranscriptionEnabled() async {
final prefs = await SharedPreferences.getInstance();
return prefs.getBool('transcriptionEnabled') ?? false;
}
static Future<void> setTranscriptionEnabled(bool value) async {
final prefs = await SharedPreferences.getInstance();
await prefs.setBool('transcriptionEnabled', value);
_notify();
}
/// How much audio a bookmark transcription covers, in seconds.
static Future<int> getTranscriptionWindowSeconds() async {
final prefs = await SharedPreferences.getInstance();
return prefs.getInt('transcriptionWindowSeconds') ?? 30;
}
static Future<void> setTranscriptionWindowSeconds(int value) async {
final prefs = await SharedPreferences.getInstance();
await prefs.setInt('transcriptionWindowSeconds', value);
}
/// Live transcript overlay: line font size and how many lines may wrap.
static Future<double> getLyricsFontSize() async {
final prefs = await SharedPreferences.getInstance();
return prefs.getDouble('lyricsFontSize') ?? 16;
}
static Future<void> setLyricsFontSize(double value) async {
final prefs = await SharedPreferences.getInstance();
await prefs.setDouble('lyricsFontSize', value);
}
static Future<bool> getLyricsIntroShown() async {
final prefs = await SharedPreferences.getInstance();
return prefs.getBool('lyricsIntroShown') ?? false;
}
static Future<void> setLyricsIntroShown() async {
final prefs = await SharedPreferences.getInstance();
await prefs.setBool('lyricsIntroShown', true);
}
/// Color the spoken words are painted in for read along and the live
/// transcript overlay, as an ARGB value. Amber by default: it stays legible
/// on the light, sepia and dark reader themes alike.
static const int defaultReadAlongColor = 0xFFFFC400;
static Future<int> getReadAlongColor() async {
final prefs = await SharedPreferences.getInstance();
return prefs.getInt('readAlongColor') ?? defaultReadAlongColor;
}
static Future<void> setReadAlongColor(int value) async {
final prefs = await SharedPreferences.getInstance();
await prefs.setInt('readAlongColor', value);
}
/// How closely read along follows the narration: 'word' colors one word at
/// a time with the rest of the sentence dimmed, 'sentence' colors the whole
/// sentence at once.
static Future<String> getReadAlongMode() async {
final prefs = await SharedPreferences.getInstance();
return prefs.getString('readAlongMode') ?? 'word';
}
static Future<void> setReadAlongMode(String value) async {
final prefs = await SharedPreferences.getInstance();
await prefs.setString('readAlongMode', value);
}
/// How far ahead of your ears the playhead runs, in milliseconds, so the
/// transcript can be held back to match. Bluetooth adds a couple of hundred
/// milliseconds that the phone's own speaker doesn't, so the two are
/// remembered separately and picked by whatever you are listening on.
static Future<int> getTranscriptOffsetMs({required bool bluetooth}) async {
final prefs = await SharedPreferences.getInstance();
return prefs.getInt(bluetooth ? 'transcriptOffsetBt' : 'transcriptOffset') ?? 0;
}
static Future<void> setTranscriptOffsetMs(int value,
{required bool bluetooth}) async {
final prefs = await SharedPreferences.getInstance();
await prefs.setInt(
bluetooth ? 'transcriptOffsetBt' : 'transcriptOffset', value);
}
/// Whether the live transcript takes over the whole cover instead of
/// sitting in a strip across the bottom of it.
static Future<bool> getLyricsFullCover() async {
final prefs = await SharedPreferences.getInstance();
return prefs.getBool('lyricsFullCover') ?? true;
}
static Future<void> setLyricsFullCover(bool value) async {
final prefs = await SharedPreferences.getInstance();
await prefs.setBool('lyricsFullCover', value);
}
static Future<int> getLyricsMaxLines() async {
final prefs = await SharedPreferences.getInstance();
return prefs.getInt('lyricsMaxLines') ?? 3;
}
static Future<void> setLyricsMaxLines(int value) async {
final prefs = await SharedPreferences.getInstance();
await prefs.setInt('lyricsMaxLines', value);
}
/// Where Find in audiobook lands on success: true = switch to the player,
/// false = stay in the reader while the audio plays.
/// Where a successful Find in audiobook lands: 'stay' in the reader,
/// 'player', or 'readalong' - stay and switch read along on from there.
static Future<String> getFindInAudiobookAfter() async {
final prefs = await SharedPreferences.getInstance();
final v = prefs.getString('findInAudiobookAfter');
if (v != null) return v;
// The setting used to be a two-way switch.
final old = prefs.getBool('findInAudiobookGoToPlayer');
return old == false ? 'stay' : 'player';
}
static Future<void> setFindInAudiobookAfter(String value) async {
final prefs = await SharedPreferences.getInstance();
await prefs.setString('findInAudiobookAfter', value);
}
// The dedicated Podcasts tab implies merged behavior: playback must survive
// the tab-driven library flips and the Absorbing tab must keep showing the
// playing item from either tab.
static Future<bool> getMergeAbsorbingLibraries() async =>
await _get('mergeAbsorbingLibraries', false) ||
await getPodcastTabEnabled();
/// The stored toggle value, without the Podcasts-tab implication. For the
/// settings UI and backups - exporting the effective value would bake
/// merge=true into a restore permanently.
static Future<bool> getMergeAbsorbingLibrariesRaw() =>
_get('mergeAbsorbingLibraries', false);
static Future<void> setMergeAbsorbingLibraries(bool value) =>
_set('mergeAbsorbingLibraries', value);
// Dedicated bottom-nav Podcasts tab (pinned to one podcast library).
static Future<bool> getPodcastTabEnabled() =>
_get('podcastTabEnabled', false);
static Future<void> setPodcastTabEnabled(bool value) =>
_set('podcastTabEnabled', value, notify: true);
static Future<String> getPodcastTabLibraryId() =>
_get('podcastTabLibraryId', '');
static Future<void> setPodcastTabLibraryId(String value) =>
_set('podcastTabLibraryId', value, notify: true);
// Background new-episode notification checks, in minutes (0 = off).
// WorkManager's floor for periodic jobs is 15 minutes.
static Future<int> getEpisodeNotifIntervalMinutes() =>
_get('episodeNotifIntervalMinutes', 0);
static Future<void> setEpisodeNotifIntervalMinutes(int value) =>
_set('episodeNotifIntervalMinutes', value, notify: true);
static Future<int> getMaxConcurrentDownloads() =>
_get('maxConcurrentDownloads', 1);
static Future<void> setMaxConcurrentDownloads(int value) =>
_set('maxConcurrentDownloads', value);
// ── Stats page ──
/// Listening goal periods, in the order they're shown.
static const statsGoalPeriods = ['daily', 'weekly', 'monthly'];
static String _statsGoalKey(String period) => 'stats_goal_${period}_minutes';
static String _statsGoalOnKey(String period) => 'stats_goal_${period}_on';
/// Target used when a period is first switched on, so the goal card starts
/// somewhere sensible instead of at 0%.
static int defaultStatsGoalMinutes(String period) => switch (period) {
'weekly' => 7 * 60,
'monthly' => 30 * 60,
_ => 60,
};
/// The most a period's target can be: all the time that period holds. These
/// match the rolling windows the stats page actually sums (7 and 30 days
/// back from today), not calendar weeks or months.
static int maxStatsGoalMinutes(String period) => switch (period) {
'weekly' => 7 * 24 * 60,
'monthly' => 30 * 24 * 60,
_ => 24 * 60,
};
/// Target listening minutes for one goal period, or 0 when that goal is
/// switched off. All three periods can be on at once. The target survives
/// being switched off, so turning a goal back on restores the number you
/// set instead of dropping back to the default.
static Future<int> getStatsGoalMinutesFor(String period) async {
await _migrateStatsGoals();
if (!await _get(_statsGoalOnKey(period), false)) return 0;
return _get(_statsGoalKey(period), defaultStatsGoalMinutes(period));
}
static Future<void> setStatsGoalMinutesFor(String period, int minutes) async {
await _migrateStatsGoals();
if (minutes <= 0) {
await _set(_statsGoalOnKey(period), false, notify: true);
return;
}
await _set(
_statsGoalKey(period),
minutes.clamp(1, maxStatsGoalMinutes(period)),
);
await _set(_statsGoalOnKey(period), true, notify: true);
}
/// Switch a period's goal on or off without disturbing its target.
static Future<void> setStatsGoalEnabled(String period, bool on) async {
await _migrateStatsGoals();
await _set(_statsGoalOnKey(period), on, notify: true);
}
/// One-time migration from the single active-period goal to per-period
/// targets, so an existing goal survives the upgrade. Runs per account,
/// which is why it hangs off the getters instead of app start.
static Future<void> _migrateStatsGoals() async {
if (await ScopedPrefs.containsKey('stats_goal_migrated')) return;
final oldPeriod = await _get('stats_goal_type', 'off');
if (statsGoalPeriods.contains(oldPeriod)) {
final oldMinutes = await _get('stats_goal_minutes', 30);
await _set(
_statsGoalKey(oldPeriod),
oldMinutes.clamp(1, maxStatsGoalMinutes(oldPeriod)),
);
await _set(_statsGoalOnKey(oldPeriod), true);
}
await _set('stats_goal_migrated', true);
}
/// Territories that start the week on Sunday or Saturday, from CLDR.
/// Everywhere else starts on Monday, which is most of the world.
static const _sundayFirstCountries = {
'AG',
'AS',
'BD',
'BR',
'BS',
'BT',
'BW',
'BZ',
'CA',
'CN',
'CO',
'DM',
'DO',
'ET',
'GT',
'GU',
'HK',
'HN',
'ID',
'IL',
'IN',
'JM',
'JP',
'KE',
'KH',
'KR',
'LA',
'MH',
'MM',
'MO',
'MT',
'MX',
'MZ',
'NI',
'NP',
'PA',
'PE',
'PH',
'PK',
'PR',
'PY',
'SA',
'SG',
'SV',
'TH',
'TT',
'TW',
'UM',
'US',
'VE',
'VI',
'WS',
'YE',
'ZA',
'ZW',
};
static const _saturdayFirstCountries = {
'AE',
'AF',
'BH',
'DJ',
'DZ',
'EG',
'IQ',
'IR',
'JO',
'KW',
'LY',
'OM',
'QA',
'SD',
'SY',
};
/// Day the stats week starts on: 0 = Sunday, 1 = Monday, 6 = Saturday. Same
/// numbering as `MaterialLocalizations.firstDayOfWeekIndex`.
///
/// Defaults from the DEVICE locale's country rather than the app's language
/// setting - the language picker stores a bare language code with no region,
/// so an English UI would otherwise report Sunday for the whole world.
static int defaultStatsWeekStart() {
final country = ui.PlatformDispatcher.instance.locale.countryCode
?.toUpperCase();
if (country == null) return 1;
if (_sundayFirstCountries.contains(country)) return 0;
if (_saturdayFirstCountries.contains(country)) return 6;
return 1;
}
static Future<int> getStatsWeekStart() async =>
await ScopedPrefs.getInt('stats_week_start') ?? defaultStatsWeekStart();
static Future<void> setStatsWeekStart(int day) =>
_set('stats_week_start', day, notify: true);
/// Yearly book-challenge target. 0 = off.
static Future<int> getStatsBookGoal() => _get('stats_book_goal', 0);
static Future<void> setStatsBookGoal(int value) =>
_set('stats_book_goal', value, notify: true);
/// Wall-clock seconds saved by listening above 1x. Banked live by the
/// player as listening time accrues; read-only here.
static Future<double> getStatsTimeSaved() => _get('stats_time_saved', 0.0);
/// When the time-saved counter started accruing (null until the first
/// banked second). Set once in progress_sync_service.addTimeSaved.
static Future<DateTime?> getStatsTimeSavedSince() async {
final ms = await ScopedPrefs.getInt('stats_time_saved_since');
return ms == null ? null : DateTime.fromMillisecondsSinceEpoch(ms);
}
/// Clear the time-saved total and its start date so it counts fresh from
/// the next second listened above 1x.
static Future<void> resetStatsTimeSaved() async {
await ScopedPrefs.remove('stats_time_saved');
await ScopedPrefs.remove('stats_time_saved_since');
_notify();
}
/// Listening chart style on the stats page: 'bar' | 'line'.
/// 'heatmap' used to be a chart style; it's now its own stats section, so a
/// saved 'heatmap' value is coerced back to 'bar'.
static Future<String> getStatsChartStyle() async {
final v = await _get('stats_chart_style', 'bar');
return v == 'heatmap' ? 'bar' : v;
}
static Future<void> setStatsChartStyle(String value) =>
_set('stats_chart_style', value, notify: true);
/// Days covered by the bar/line chart: 7 or 30. The heatmap is always a year.
static Future<int> getStatsChartRange() => _get('stats_chart_range', 7);
static Future<void> setStatsChartRange(int value) =>
_set('stats_chart_range', value, notify: true);
/// Stats page section layout (ids ordered / hidden), per account.
static Future<List<String>> getStatsSectionOrder() =>
ScopedPrefs.getStringList('stats_section_order');
static Future<void> setStatsSectionOrder(List<String> order) async {
await ScopedPrefs.setStringList('stats_section_order', order);
_notify();
}
static Future<List<String>> getStatsHiddenSections() =>
ScopedPrefs.getStringList('stats_hidden_sections');
static Future<void> setStatsHiddenSections(List<String> hidden) async {
await ScopedPrefs.setStringList('stats_hidden_sections', hidden);
_notify();
}
// ── Queue mode (replaces autoPlayNextBook + autoPlayNextPodcast) ──
// Values: 'off', 'manual', 'auto_next', 'playlist'
static Future<String> getQueueMode() => _get('queueMode', 'off');
static Future<void> setQueueMode(String value) => _set('queueMode', value);
static Future<String> getBookQueueMode() async {
final value = await ScopedPrefs.getString('bookQueueMode');
return value ?? await getQueueMode();
}
static Future<void> setBookQueueMode(String value) {
debugPrint('[Queue] Book queue mode -> $value');
return _serializeQueueModeMutation(
() => _set('bookQueueMode', value, notify: true),
);
}
static Future<bool> getShowUpNextLabel() => _get('showUpNextLabel', true);
static Future<void> setShowUpNextLabel(bool value) =>
_set('showUpNextLabel', value, notify: true);
static Future<String> getPodcastQueueMode() async {
final value = await ScopedPrefs.getString('podcastQueueMode');
return value ?? await getQueueMode();
}
static Future<void> setPodcastQueueMode(String value) {
debugPrint('[Queue] Podcast queue mode -> $value');
return _serializeQueueModeMutation(
() => _set('podcastQueueMode', value, notify: true),
);
}
/// Per-show podcast auto-advance direction: 'oldest_first' (default) or
/// 'newest_first'. Stored under a raw (un-scoped) key because the advance
/// logic in _lp_absorbing reads it straight from SharedPreferences.
static Future<String> getPodcastAdvanceDir(String showId) async {
final prefs = await SharedPreferences.getInstance();
return prefs.getString('podcast_advance_dir_$showId') ?? 'oldest_first';
}
static Future<void> setPodcastAdvanceDir(String showId, String value) async {
final prefs = await SharedPreferences.getInstance();
await prefs.setString('podcast_advance_dir_$showId', value);
_notify();
}
/// Where a subscribed show's auto-downloaded new episode lands in the
/// absorbing queue: 'start' (top, default), 'second' (2nd), or 'end'. Per
/// show, stored under a raw key like the advance direction above.
static Future<String> getPodcastNewEpisodePosition(String showId) async {
final prefs = await SharedPreferences.getInstance();
return prefs.getString('podcast_new_ep_pos_$showId') ?? 'start';
}
static Future<void> setPodcastNewEpisodePosition(
String showId,
String value,
) async {
final prefs = await SharedPreferences.getInstance();
await prefs.setString('podcast_new_ep_pos_$showId', value);
_notify();
}
/// Active playlist ID for playlist queue mode. Null when no playlist is selected.
static Future<String?> getQueuePlaylistId() async {
final s = await ScopedPrefs.getString('queuePlaylistId');
return (s == null || s.isEmpty) ? null : s;
}
static Future<void> setQueuePlaylistId(String? id) =>
_serializeQueueModeMutation(() async {
if (id == null || id.isEmpty) {
await ScopedPrefs.remove('queuePlaylistId');
} else {
await ScopedPrefs.setString('queuePlaylistId', id);
}
_notify();
});
/// Enter playlist queue mode atomically: both book and podcast modes flip to
/// 'playlist' and the active playlist is set. Playlists can mix book and
/// podcast items, so the two modes always agree when in playlist mode.
static Future<void> setQueueModePlaylist(String playlistId) =>
_serializeQueueModeMutation(() async {
await ScopedPrefs.setString('bookQueueMode', 'playlist');
await ScopedPrefs.setString('podcastQueueMode', 'playlist');
await ScopedPrefs.setString('queuePlaylistId', playlistId);
_notify();
});
/// Exit playlist queue mode: both modes back to 'off' and active playlist cleared.
static Future<void> clearQueueModePlaylist() =>
_serializeQueueModeMutation(() async {
await ScopedPrefs.setString('bookQueueMode', 'off');
await ScopedPrefs.setString('podcastQueueMode', 'off');
await ScopedPrefs.remove('queuePlaylistId');
_notify();
});
static Future<bool> clearQueueModePlaylistIfActive(String playlistId) =>
_serializeQueueModeMutation(() async {
if (await getBookQueueMode() != 'playlist' ||
await getPodcastQueueMode() != 'playlist' ||
await getQueuePlaylistId() != playlistId) {
return false;
}
await ScopedPrefs.setString('bookQueueMode', 'off');
await ScopedPrefs.setString('podcastQueueMode', 'off');
await ScopedPrefs.remove('queuePlaylistId');
_notify();
return true;
});
// ── Collection queue mode (books only) ──
// Mirrors playlist queue mode but plays through a collection's books. Drives
// bookQueueMode = 'collection' + queueCollectionId; the name is stored too so
// the now-playing chip needn't fetch the collection.
static Future<String?> getQueueCollectionId() async {
final s = await ScopedPrefs.getString('queueCollectionId');
return (s == null || s.isEmpty) ? null : s;
}
static Future<String?> getQueueCollectionName() =>
ScopedPrefs.getString('queueCollectionName');
static Future<void> setQueueModeCollection(
String collectionId,
String name,
) => _serializeQueueModeMutation(() async {
await ScopedPrefs.setString('bookQueueMode', 'collection');
await ScopedPrefs.setString('queueCollectionId', collectionId);
await ScopedPrefs.setString('queueCollectionName', name);
// Collection mode replaces any active playlist queue.
await ScopedPrefs.remove('queuePlaylistId');
if ((await ScopedPrefs.getString('podcastQueueMode')) == 'playlist') {
await ScopedPrefs.setString('podcastQueueMode', 'off');
}
_notify();
});
static Future<void> clearQueueModeCollection() =>
_serializeQueueModeMutation(() async {
await ScopedPrefs.setString('bookQueueMode', 'off');
await ScopedPrefs.remove('queueCollectionId');
await ScopedPrefs.remove('queueCollectionName');
_notify();
});
static Future<bool> clearQueueModeCollectionIfActive(String collectionId) =>
_serializeQueueModeMutation(() async {
if (await getBookQueueMode() != 'collection' ||
await getQueueCollectionId() != collectionId) {
return false;
}
await ScopedPrefs.setString('bookQueueMode', 'off');
await ScopedPrefs.remove('queueCollectionId');
await ScopedPrefs.remove('queueCollectionName');
_notify();
return true;
});
/// Snapshot of the queue-mode settings, taken before a play activates a
/// playlist/collection queue so a failed play can put them back.
static Future<QueueModeSnapshot> queueModeSnapshot() async => (
bookMode: await getBookQueueMode(),
podcastMode: await getPodcastQueueMode(),
playlistId: await ScopedPrefs.getString('queuePlaylistId'),
collectionId: await ScopedPrefs.getString('queueCollectionId'),
collectionName: await ScopedPrefs.getString('queueCollectionName'),
);
/// Restore a [queueModeSnapshot] if the given playlist queue is still the
/// active one - same guard as [clearQueueModePlaylistIfActive], so a mode
/// the user changed again in the meantime is left alone.
static Future<bool> restoreQueueModeIfPlaylistActive(
String playlistId,
QueueModeSnapshot snapshot,
) => _serializeQueueModeMutation(() async {
if (await getBookQueueMode() != 'playlist' ||
await getPodcastQueueMode() != 'playlist' ||
await getQueuePlaylistId() != playlistId) {
return false;
}
await _applyQueueModeSnapshot(snapshot);
return true;
});
static Future<bool> restoreQueueModeIfCollectionActive(
String collectionId,
QueueModeSnapshot snapshot,
) => _serializeQueueModeMutation(() async {
if (await getBookQueueMode() != 'collection' ||
await getQueueCollectionId() != collectionId) {
return false;
}
await _applyQueueModeSnapshot(snapshot);
return true;
});
static Future<void> _applyQueueModeSnapshot(QueueModeSnapshot s) async {
Future<void> put(String key, String? value) => value == null
? ScopedPrefs.remove(key)
: ScopedPrefs.setString(key, value);
await put('bookQueueMode', s.bookMode);
await put('podcastQueueMode', s.podcastMode);
await put('queuePlaylistId', s.playlistId);
await put('queueCollectionId', s.collectionId);
await put('queueCollectionName', s.collectionName);
_notify();
}
/// One-time migration from the old boolean auto-play settings to queueMode.
static Future<void> migrateQueueMode() async {
if (await ScopedPrefs.containsKey('queueMode')) return;
final autoBook = await ScopedPrefs.getBool('autoPlayNextBook') ?? false;
final autoPod = await ScopedPrefs.getBool('autoPlayNextPodcast') ?? false;
await ScopedPrefs.setString(
'queueMode',
(autoBook || autoPod) ? 'auto_next' : 'off',
);
}
/// One-time migration from the unified queueMode to per-type book/podcast modes.
static Future<void> migrateBookPodcastQueueMode() async {
if (await ScopedPrefs.containsKey('bookQueueMode')) return;
final existing = await getQueueMode();
await setBookQueueMode(existing);
await setPodcastQueueMode(existing);
}
// Legacy getters kept for backup service compatibility
static Future<bool> getAutoPlayNextBook() => _get('autoPlayNextBook', false);
static Future<void> setAutoPlayNextBook(bool value) =>
_set('autoPlayNextBook', value);
static Future<bool> getAutoPlayNextPodcast() =>
_get('autoPlayNextPodcast', false);
static Future<void> setAutoPlayNextPodcast(bool value) =>
_set('autoPlayNextPodcast', value);
static Future<String> getWhenFinished() =>
_get('whenFinished', 'auto_remove');
static Future<void> setWhenFinished(String value) =>
_set('whenFinished', value);
// ── Player UI settings (notify listeners on change) ──
static Future<CardScrubberMode> getCardScrubberMode() async {
final stored = await _get('cardScrubberMode', '');
for (final mode in CardScrubberMode.values) {
if (mode.name == stored) return mode;
}
final legacyBookSlider = await _get('showBookSlider', false);
return legacyBookSlider ? CardScrubberMode.both : CardScrubberMode.chapter;
}
static Future<void> setCardScrubberMode(CardScrubberMode mode) async {
await _set('cardScrubberMode', mode.name);
await _set('showBookSlider', mode == CardScrubberMode.both);
_notify();
}
static Future<bool> getShowBookSlider() async =>
await getCardScrubberMode() == CardScrubberMode.both;
static Future<void> setShowBookSlider(bool value) => setCardScrubberMode(
value ? CardScrubberMode.both : CardScrubberMode.chapter,
);
static Future<bool> getSpeedAdjustedTime() => _get('speedAdjustedTime', true);
static Future<void> setSpeedAdjustedTime(bool value) =>
_set('speedAdjustedTime', value, notify: true);
static Future<int> getForwardSkip() => _get('forwardSkip', 30);
static Future<void> setForwardSkip(int seconds) =>
_set('forwardSkip', seconds, notify: true);
static Future<int> getBackSkip() => _get('backSkip', 10);
static Future<void> setBackSkip(int seconds) =>
_set('backSkip', seconds, notify: true);
static Future<bool> getSkipChapterBarrier() =>
_get('skipChapterBarrier', true);
static Future<void> setSkipChapterBarrier(bool value) =>
_set('skipChapterBarrier', value);
/// Per-library skip override: a library (podcast or book) can use its own
/// forward/back amounts instead of the global ones. Both are set together;
/// null = no override for that library.
static Future<({int forward, int back})?> getSkipOverride(
String libraryId,
) async {
final fwd = await ScopedPrefs.getInt('skipOverrideForward_$libraryId');
final back = await ScopedPrefs.getInt('skipOverrideBack_$libraryId');
if (fwd == null || back == null) return null;
return (forward: fwd, back: back);
}
static Future<void> setSkipOverride(
String libraryId, {
int? forward,
int? back,
}) async {
if (forward == null || back == null) {
await ScopedPrefs.remove('skipOverrideForward_$libraryId');
await ScopedPrefs.remove('skipOverrideBack_$libraryId');
} else {
await ScopedPrefs.setInt('skipOverrideForward_$libraryId', forward);
await ScopedPrefs.setInt('skipOverrideBack_$libraryId', back);
}
_notify();
}
/// Skip amounts that respect a library's override, if it has one.
static Future<int> getEffectiveForwardSkip({String? libraryId}) async {
if (libraryId != null) {
final o = await getSkipOverride(libraryId);
if (o != null) return o.forward;
}
return getForwardSkip();
}
static Future<int> getEffectiveBackSkip({String? libraryId}) async {
if (libraryId != null) {
final o = await getSkipOverride(libraryId);
if (o != null) return o.back;
}
return getBackSkip();
}
// Optional second, bigger skip pair on the player card (GH #242).
static Future<bool> getLongSkipButtons() => _get('longSkipButtons', false);
static Future<void> setLongSkipButtons(bool value) =>
_set('longSkipButtons', value, notify: true);
static Future<int> getLongForwardSkip() => _get('longForwardSkip', 60);
static Future<void> setLongForwardSkip(int seconds) =>
_set('longForwardSkip', seconds, notify: true);
static Future<int> getLongBackSkip() => _get('longBackSkip', 60);
static Future<void> setLongBackSkip(int seconds) =>
_set('longBackSkip', seconds, notify: true);
/// Cached value for synchronous access in widget build methods.
static bool showExplicitBadge = true;
static Future<bool> getShowExplicitBadge() => _get('showExplicitBadge', true);
static Future<void> setShowExplicitBadge(bool value) async {
showExplicitBadge = value;
await _set('showExplicitBadge', value);
}
static bool showEbookBadge = true;
static Future<bool> getShowEbookBadge() => _get('showEbookBadge', true);
static Future<void> setShowEbookBadge(bool value) async {
showEbookBadge = value;
await _set('showEbookBadge', value, notify: true);
}
/// Cached value for synchronous access when building audio sources.
static bool mp3IndexSeeking = false;
static Future<bool> getMp3IndexSeeking() => _get('mp3IndexSeeking', false);
static Future<void> setMp3IndexSeeking(bool value) async {
mp3IndexSeeking = value;
await _set('mp3IndexSeeking', value);
}
static Future<bool> getNotificationChapterProgress() =>
_get('notificationChapterProgress', false);
static Future<void> setNotificationChapterProgress(bool value) =>
_set('notificationChapterProgress', value, notify: true);
// Which pieces the media controls show on each line, as
// NowPlayingLayout JSON. Empty = the standard layout.
static Future<String> getNowPlayingLayout() => _get('nowPlayingLayout', '');
static Future<void> setNowPlayingLayout(String json) => _set('nowPlayingLayout', json, notify: true);
// Android only: when true, the phone media controls show speed + bookmark in
// the two extra slots instead of chapter skip. Android Auto shows all of them
// either way; this just reorders which pair the phone "borrows".
static Future<bool> getMediaControlsSpeedBookmark() =>
_get('mediaControlsSpeedBookmark', false);
static Future<void> setMediaControlsSpeedBookmark(bool value) =>
_set('mediaControlsSpeedBookmark', value, notify: true);
// Android only: lower the volume for brief focus interruptions instead of
// pausing. Pausing remains the default.
static Future<bool> getDuckBriefInterruptions() =>
_get('duckBriefInterruptions', false);
static Future<void> setDuckBriefInterruptions(bool value) =>
_set('duckBriefInterruptions', value, notify: true);
// Android only: keep playing when another app starts its own audio, instead
// of stopping for it. Calls and navigation prompts still pause or duck.
static Future<bool> getKeepPlayingWithOtherApps() =>
_get('keepPlayingWithOtherApps', false);
static Future<void> setKeepPlayingWithOtherApps(bool value) =>
_set('keepPlayingWithOtherApps', value, notify: true);
// GH #371: start the last played book when the car (Android Auto or
// CarPlay) connects and nothing is loaded yet. The warm case (session
// alive but paused) belongs to the car system's own resume behavior; this
// covers the cold start where no session exists for it to resume.
static Future<bool> getAutoplayOnCarConnect() => _get('autoplayOnCarConnect', false);
static Future<bool> getKeepScreenOnInPlayer() => _get('keepScreenOnPlayer', false);
static Future<void> setKeepScreenOnInPlayer(bool value) =>
_set('keepScreenOnPlayer', value, notify: true);
static Future<bool> getKeepScreenOnInCarMode() => _get('keepScreenOnCarMode', false);
static Future<void> setKeepScreenOnInCarMode(bool value) =>
_set('keepScreenOnCarMode', value, notify: true);
// Android Auto / CarPlay library browsing. Book sort is 'title', 'author' or
// 'added' (newest first); reverse flips whichever is picked. Podcast shows
// sort 'title' or 'added'.
static Future<String> getCarBookSort() => _get('carBookSort', 'title');
static Future<void> setCarBookSort(String value) => _set('carBookSort', value);
static Future<bool> getCarBookSortReverse() => _get('carBookSortReverse', false);
static Future<void> setCarBookSortReverse(bool value) =>
_set('carBookSortReverse', value);
static Future<String> getCarPodcastSort() => _get('carPodcastSort', 'title');
static Future<void> setCarPodcastSort(String value) => _set('carPodcastSort', value);
static Future<bool> getCarEpisodesOldestFirst() =>
_get('carEpisodesOldestFirst', false);
static Future<void> setCarEpisodesOldestFirst(bool value) =>
_set('carEpisodesOldestFirst', value);
static Future<void> setAutoplayOnCarConnect(bool value) =>
_set('autoplayOnCarConnect', value);
// When true, the system media scrubber still shows progress but can't be
// dragged to seek - stops accidental position jumps from the notification,
// lockscreen, Android Auto and CarPlay. Implemented by dropping the seek
// action from the playback state (Android ACTION_SEEK_TO / iOS
// changePlaybackPositionCommand). Default off.
static Future<bool> getLockSeekBar() => _get('lockSeekBar', false);
static Future<void> setLockSeekBar(bool value) =>
_set('lockSeekBar', value, notify: true);
// ── Sleep timer settings ──
// 'off', 'addTime', 'resetTimer'
static Future<String> getShakeMode() => _get('shakeMode', 'addTime');
static Future<void> setShakeMode(String value) => _set('shakeMode', value);
static Future<int> getShakeAddMinutes() => _get('shakeAddMinutes', 5);
static Future<void> setShakeAddMinutes(int minutes) =>
_set('shakeAddMinutes', minutes);
// 'veryLow', 'low', 'medium', 'high', 'veryHigh'
static Future<String> getShakeSensitivity() =>
_get('shakeSensitivity', 'medium');
static Future<void> setShakeSensitivity(String value) =>
_set('shakeSensitivity', value);
/// Linear-acceleration threshold (m/s², gravity excluded) that a shake must
/// exceed to be registered. Lower = more sensitive.
static double shakeThresholdFor(String sensitivity) {
switch (sensitivity) {
case 'veryHigh':
return 8.0;
case 'high':
return 13.0;
case 'low':
return 23.0;
case 'veryLow':
return 28.0;
case 'medium':
default:
return 18.0;
}
}
static Future<int> getSleepTimerMinutes() => _get('sleepTimerMinutes', 30);
static Future<void> setSleepTimerMinutes(int minutes) =>
_set('sleepTimerMinutes', minutes);
static Future<int> getSleepTimerChapters() => _get('sleepTimerChapters', 1);
static Future<void> setSleepTimerChapters(int chapters) =>
_set('sleepTimerChapters', chapters);
/// Media-button snooze during the sleep timer wind-down (GH #333):
/// 'off' | 'addTime' | 'resetTimer'. A press inside the wind-down window
/// resets or extends the timer instead of pausing.
static Future<String> getSleepButtonMode() => _get('sleepButtonMode', 'off');
static Future<void> setSleepButtonMode(String v) => _set('sleepButtonMode', v);
static Future<bool> getResetSleepOnPause() => _get('resetSleepOnPause', false);
static Future<void> setResetSleepOnPause(bool value) => _set('resetSleepOnPause', value);
static Future<bool> getSleepFadeOut() => _get('sleepFadeOut', true);
static Future<void> setSleepFadeOut(bool value) =>
_set('sleepFadeOut', value);
static Future<int> getSleepFadeDuration() => _get('sleepFadeDuration', 30);
static Future<void> setSleepFadeDuration(int seconds) =>
_set('sleepFadeDuration', seconds);
static Future<bool> getSleepChime() => _get('sleepChime', false);
static Future<void> setSleepChime(bool value) => _set('sleepChime', value);
static Future<double> getSleepChimeVolume() => _get('sleepChimeVolume', 2.0);
static Future<void> setSleepChimeVolume(double value) =>
_set('sleepChimeVolume', value);
static Future<int> getSleepRewindSeconds() => _get('sleepRewindSeconds', 0);
static Future<void> setSleepRewindSeconds(int seconds) =>
_set('sleepRewindSeconds', seconds);
static Future<int> getSleepTimerTab() => _get('sleepTimerTab', 0);
static Future<void> setSleepTimerTab(int tab) => _set('sleepTimerTab', tab);
static Future<bool> getSheetGridView() => _get('sheetGridView', false);
static Future<void> setSheetGridView(bool value) =>
_set('sheetGridView', value);
static Future<bool> getSheetCollapseSeries() =>
_get('sheetCollapseSeries', true);
static Future<void> setSheetCollapseSeries(bool value) =>
_set('sheetCollapseSeries', value);
static Future<bool> getCollapseBookSeries() =>
_get('collapseBookSeries', false);
static Future<void> setCollapseBookSeries(bool value) =>
_set('collapseBookSeries', value);
static Future<bool> getHideEbookOnly() => _get('hideEbookOnly', false);
static Future<void> setHideEbookOnly(bool value) =>
_set('hideEbookOnly', value, notify: true);
/// Tapping a Continue Listening or Continue Reading card on Home opens its
/// details instead of picking up where it left off.
static Future<bool> getHomeCardsOpenDetails() => _get('homeCardsOpenDetails', false);
static Future<void> setHomeCardsOpenDetails(bool value) => _set('homeCardsOpenDetails', value, notify: true);
static Future<bool> getCollapseSeries() => _get('collapseSeries', false);
static Future<void> setCollapseSeries(bool value) =>
_set('collapseSeries', value, notify: true);
// ── Streaming cache ──
/// 0 = disabled, > 0 = cache size in MB (LRU eviction)
static Future<int> getStreamingCacheSizeMb() =>
_get('streamingCacheSizeMb', 256);
static Future<void> setStreamingCacheSizeMb(int value) async {
debugPrint('[Settings] Streaming cache set to: $value MB');
await _set('streamingCacheSizeMb', value);
// Reconfigure the cache immediately
try {
await AudioPlayer.configureStreamingCache(value);
debugPrint('[Settings] Streaming cache configured on native side');
} catch (e) {
debugPrint('[Settings] Streaming cache configure failed: $e');
}
}
// ── Library sort/filter persistence ──
static const List<int> bookshelfCoverSizes = [
60,
80,
100,
120,
140,
160,
180,
200,
220,
];
static int _snapBookshelfCoverSize(int value) {
var closest = bookshelfCoverSizes.first;
for (final size in bookshelfCoverSizes.skip(1)) {
if ((size - value).abs() < (closest - value).abs()) {
closest = size;
}
}
return closest;
}
static Future<int> getBookshelfCoverSize() async {
final value = await _get('bookshelfCoverSize', 120);
return _snapBookshelfCoverSize(value);
}
static Future<void> setBookshelfCoverSize(int value) =>
_set('bookshelfCoverSize', _snapBookshelfCoverSize(value), notify: true);
static Future<String> getLibrarySort() =>
_get('librarySort', 'recentlyAdded');
static Future<void> setLibrarySort(String value) =>
_set('librarySort', value);
static Future<bool> getLibrarySortAsc() => _get('librarySortAsc', false);
static Future<void> setLibrarySortAsc(bool value) =>
_set('librarySortAsc', value);
static Future<String> getLibraryFilter() => _get('libraryFilter', 'none');
static Future<void> setLibraryFilter(String value) =>
_set('libraryFilter', value);
static Future<String> getLibraryGenreFilter() =>
_get('libraryGenreFilter', '');
static Future<void> setLibraryGenreFilter(String? value) =>
_set('libraryGenreFilter', value ?? '');
static Future<String> getLibraryTagFilter() => _get('libraryTagFilter', '');
static Future<void> setLibraryTagFilter(String? value) =>
_set('libraryTagFilter', value ?? '');
static Future<String> getLibraryMissingMetadataFilter() =>
_get('libraryMissingMetadataFilter', '');
static Future<void> setLibraryMissingMetadataFilter(String? value) =>
_set('libraryMissingMetadataFilter', value ?? '');
static Future<String> getLibraryFilterValue() =>
_get('libraryFilterValue', '');
static Future<void> setLibraryFilterValue(String? value) =>
_set('libraryFilterValue', value ?? '');
static Future<String> getLibraryFilterValueLabel() =>
_get('libraryFilterValueLabel', '');
static Future<void> setLibraryFilterValueLabel(String? value) =>
_set('libraryFilterValueLabel', value ?? '');
static Future<String> getLibrarySeriesFilter() =>
_get('librarySeriesFilter', 'none');
static Future<void> setLibrarySeriesFilter(String value) =>
_set('librarySeriesFilter', value);
static Future<int> getLibraryTab() => _get('libraryTab', 0);
static Future<void> setLibraryTab(int value) => _set('libraryTab', value);
/// Podcast library view: 0 = Shows grid, 1 = Episodes feed.
static Future<int> getPodcastView() => _get('podcastView', 0);
static Future<void> setPodcastView(int value) => _set('podcastView', value);
// ── Podcast library sort persistence ──
static Future<String> getPodcastSort() =>
_get('podcastSort', 'recentlyAdded');
static Future<void> setPodcastSort(String value) =>
_set('podcastSort', value);
static Future<bool> getPodcastSortAsc() => _get('podcastSortAsc', false);
static Future<void> setPodcastSortAsc(bool value) =>
_set('podcastSortAsc', value);
static Future<String> getPodcastFilter() => _get('podcastFilter', 'none');
static Future<void> setPodcastFilter(String value) =>
_set('podcastFilter', value);
static Future<String> getPodcastGenreFilter() =>
_get('podcastGenreFilter', '');
static Future<void> setPodcastGenreFilter(String? value) =>
_set('podcastGenreFilter', value ?? '');
static Future<String> getPodcastTagFilter() => _get('podcastTagFilter', '');
static Future<void> setPodcastTagFilter(String? value) =>
_set('podcastTagFilter', value ?? '');
static Future<String> getPodcastFilterValue() =>
_get('podcastFilterValue', '');
static Future<void> setPodcastFilterValue(String? value) =>
_set('podcastFilterValue', value ?? '');
static Future<String> getPodcastFilterValueLabel() =>
_get('podcastFilterValueLabel', '');
static Future<void> setPodcastFilterValueLabel(String? value) =>
_set('podcastFilterValueLabel', value ?? '');
static Future<String> getSeriesSort() => _get('seriesSort', 'alphabetical');
static Future<void> setSeriesSort(String value) => _set('seriesSort', value);
static Future<bool> getSeriesSortAsc() => _get('seriesSortAsc', true);
static Future<void> setSeriesSortAsc(bool value) =>
_set('seriesSortAsc', value);
static Future<String> getListsSort() => _get('listsSort', 'alphabetical');
static Future<void> setListsSort(String value) => _set('listsSort', value);
static Future<bool> getListsSortAsc() => _get('listsSortAsc', true);
static Future<void> setListsSortAsc(bool value) =>
_set('listsSortAsc', value);
static Future<String> getAuthorSort() => _get('authorSort', 'alphabetical');
static Future<void> setAuthorSort(String value) => _set('authorSort', value);
static Future<bool> getAuthorSortAsc() => _get('authorSortAsc', true);
static Future<void> setAuthorSortAsc(bool value) =>
_set('authorSortAsc', value);
static Future<String> getNarratorSort() =>
_get('narratorSort', 'alphabetical');
static Future<void> setNarratorSort(String value) =>
_set('narratorSort', value);
static Future<bool> getNarratorSortAsc() => _get('narratorSortAsc', true);
static Future<void> setNarratorSortAsc(bool value) =>
_set('narratorSortAsc', value);
static Future<bool> getShowGoodreadsButton() =>
_get('showGoodreadsButton', false);
static Future<void> setShowGoodreadsButton(bool value) =>
_set('showGoodreadsButton', value);
static Future<bool> getLoggingEnabled() async {
final prefs = await SharedPreferences.getInstance();
return prefs.getBool('loggingEnabled') ?? false;
}
static Future<void> setLoggingEnabled(bool value) async {
final prefs = await SharedPreferences.getInstance();
await prefs.setBool('loggingEnabled', value);
}
/// Whether the logging switch was ever set, by hand or from a backup.
static Future<bool> loggingChosen() async =>
(await SharedPreferences.getInstance()).containsKey('loggingEnabled');
static Future<bool> getFullScreenPlayer() => _get('fullScreenPlayer', false);
static Future<void> setFullScreenPlayer(bool value) =>
_set('fullScreenPlayer', value);
// The Audible stars on the book detail sheet, and the lookup behind them.
static Future<bool> getShowAudibleRating() => _get('showAudibleRating', true);
static Future<void> setShowAudibleRating(bool value) =>
_set('showAudibleRating', value);
// Ebook reader: turn pages with the volume keys. 'off' | 'normal'
// (up = previous page, down = next, matching the ABS app) | 'mirrored'.
static Future<String> getEreaderVolumeNav() =>
_get('ereaderVolumeNav', 'off');
static Future<void> setEreaderVolumeNav(String value) =>
_set('ereaderVolumeNav', value, notify: true);
// Keep turning pages with the volume keys even while audio is playing
// (off = playing audio gives the keys back to system volume).
static Future<bool> getEreaderVolumeNavWhilePlaying() =>
_get('ereaderVolumeNavWhilePlaying', false);
static Future<void> setEreaderVolumeNavWhilePlaying(bool value) =>
_set('ereaderVolumeNavWhilePlaying', value, notify: true);
// Ebook reader: where the Translate button sends a selection. Empty means
// the first translator this device has (see TranslateService).
static Future<String> getEreaderTranslateWith() => _get('ereaderTranslateWith', '');
static Future<void> setEreaderTranslateWith(String value) => _set('ereaderTranslateWith', value);
static Future<double> getEreaderAutoScrollSpeed() => _get('ereaderAutoScrollSpeed', 40.0);
static Future<void> setEreaderAutoScrollSpeed(double value) => _set('ereaderAutoScrollSpeed', value);
static Future<int> getEreaderAutoScrollSleepMinutes() => _get('ereaderAutoScrollSleepMinutes', 30);
static Future<void> setEreaderAutoScrollSleepMinutes(int value) => _set('ereaderAutoScrollSleepMinutes', value);
/// When on, the screen is locked to portrait (rotation disabled). Default off
/// keeps the current behaviour where all orientations are allowed.
static Future<bool> getLockPortrait() => _get('lockPortrait', false);
static Future<void> setLockPortrait(bool value) =>
_set('lockPortrait', value);
static Future<bool> getSnappyTransitions() =>
_get('snappyTransitions', false);
static Future<void> setSnappyTransitions(bool value) =>
_set('snappyTransitions', value);
static Future<bool> getClassicWording() => _get('classicWording', false);
static Future<void> setClassicWording(bool value) =>
_set('classicWording', value);
static Future<bool> getRectangleCovers() => _get('rectangleCovers', false);
static Future<void> setRectangleCovers(bool value) =>
_set('rectangleCovers', value, notify: true);
/// How the player card's buttons are filled: 'clear' (no fill or edge),
/// 'subtle' (the long-standing look) or 'solid'. Cached for builders.
static String cardButtonFill = 'subtle';
static Future<String> getCardButtonFill() => _get('cardButtonFill', 'subtle');
static Future<void> setCardButtonFill(String value) async {
cardButtonFill = value;
await _set('cardButtonFill', value, notify: true);
}
/// Cached value for synchronous access in grid builders.
/// 'small' | 'medium' | 'large'; medium keeps the long-standing layout.
static String coverSize = 'medium';
static Future<String> getCoverSize() => _get('coverSize', 'medium');
static Future<void> setCoverSize(String value) async {
coverSize = value;
await _set('coverSize', value, notify: true);
}
/// Per-library cover-shape override: 'rect', 'square', or null (= follow
/// the global toggle). Lets an ebook library run tall covers while the
/// audiobook libraries stay square.
static Future<String?> getRectangleCoversOverride(String libraryId) async {
final v = await ScopedPrefs.getString('rectangleCovers_$libraryId');
return (v == 'rect' || v == 'square') ? v : null;
}
static Future<void> setRectangleCoversOverride(
String libraryId,
String? value,
) async {
if (value == null) {
await ScopedPrefs.remove('rectangleCovers_$libraryId');
} else {
await ScopedPrefs.setString('rectangleCovers_$libraryId', value);
}
_notify();
}
/// Cover shape for a library: its override if set, else the global toggle.
static Future<bool> getRectangleCoversFor(String? libraryId) async {
if (libraryId != null) {
final v = await getRectangleCoversOverride(libraryId);
if (v != null) return v == 'rect';
}
return getRectangleCovers();
}
static Future<bool> getShowSubtitles() => _get('showSubtitles', false);
static Future<void> setShowSubtitles(bool value) => _set('showSubtitles', value, notify: true);
/// Per-library subtitle override: 'show', 'hide', or null (= follow the
/// global toggle). Most libraries leave the field empty, so a library that
/// does fill it in can show subtitles without the rest going taller.
static Future<String?> getShowSubtitlesOverride(String libraryId) async {
final v = await ScopedPrefs.getString('showSubtitles_$libraryId');
return (v == 'show' || v == 'hide') ? v : null;
}
static Future<void> setShowSubtitlesOverride(String libraryId, String? value) async {
if (value == null) {
await ScopedPrefs.remove('showSubtitles_$libraryId');
} else {
await ScopedPrefs.setString('showSubtitles_$libraryId', value);
}
_notify();
}
/// Subtitle visibility for a library: its override if set, else the global
/// toggle.
static Future<bool> getShowSubtitlesFor(String? libraryId) async {
if (libraryId != null) {
final v = await getShowSubtitlesOverride(libraryId);
if (v != null) return v == 'show';
}
return getShowSubtitles();
}
static Future<bool> getSectionGridView() => _get('sectionGridView', false);
static Future<void> setSectionGridView(bool value) =>
_set('sectionGridView', value);
static Future<bool> getCoverPlayButton() => _get('coverPlayButton', false);
static Future<void> setCoverPlayButton(bool value) =>
_set('coverPlayButton', value, notify: true);
/// Absorbing-card background style: 'blurred' (cover blur, default), 'gradient'
/// (gradient from the extracted cover colors), or 'off' (plain theme surface).
static Future<String> getCardBackground() async =>
einkMode ? 'off' : await getCardBackgroundRaw();
/// The stored value, for backup/sync export - the plain getter reports
/// 'off' while e-ink mode is on, which must not leak into synced settings.
static Future<String> getCardBackgroundRaw() =>
_get('cardBackground', 'blurred');
static Future<void> setCardBackground(String value) => _set('cardBackground', value, notify: true);
// ── Self-signed certificates (global, not per-user) ──
static Future<bool> getTrustAllCerts() async {
final prefs = await SharedPreferences.getInstance();
return prefs.getBool('trustAllCerts') ?? false;
}
static Future<void> setTrustAllCerts(bool value) async {
final prefs = await SharedPreferences.getInstance();
await prefs.setBool('trustAllCerts', value);
}
// ── Pre-release updates (GitHub build only) ──
static Future<bool> getIncludePreReleases() async {
final prefs = await SharedPreferences.getInstance();
return prefs.getBool('includePreReleases') ?? false;
}
static Future<void> setIncludePreReleases(bool value) async {
final prefs = await SharedPreferences.getInstance();
await prefs.setBool('includePreReleases', value);
}
// ── Local server ──
static Future<bool> getLocalServerEnabled() =>
_get('localServerEnabled', false);
static Future<void> setLocalServerEnabled(bool value) =>
_set('localServerEnabled', value);
static Future<String> getLocalServerUrl() => _get('localServerUrl', '');
static Future<void> setLocalServerUrl(String value) =>
_set('localServerUrl', value);
// ── Card button order ──
static const defaultButtonOrder = ['chapters', 'speed', 'sleep', 'bookmarks', 'details', 'ebook', 'findinebook', 'lyrics', 'equalizer', 'cast', 'airplay', 'history', 'remove', 'car', 'notes', 'wake', 'download'];
static Future<List<String>> getCardButtonOrder() async {
final stored = await ScopedPrefs.getStringList('card_button_order');
if (stored.isEmpty) {
final knownIds = allCardButtons.map((b) => b.id).toSet();
return defaultButtonOrder.where((id) => knownIds.contains(id)).toList();
}
// Append any new buttons that were added since the user last saved their order
final knownIds = allCardButtons.map((b) => b.id).toSet();
final result = stored
.where((id) => knownIds.contains(id) || id == '_more')
.toList();
for (final b in allCardButtons) {
if (!result.contains(b.id)) result.add(b.id);
}
return result;
}
static Future<void> setCardButtonOrder(List<String> order) async {
await ScopedPrefs.setStringList('card_button_order', order);
_notify();
}
// ── Card button layout ──
static const defaultButtonVisibleCount = 4;
static Future<int> getCardButtonVisibleCount() async {
// Migrate old layout string to count on first load
final oldLayout = await ScopedPrefs.getString('card_button_layout');
if (oldLayout != null) {
final count = _layoutToCount(oldLayout);
await ScopedPrefs.remove('card_button_layout');
await _set('card_button_visible_count', count);
return count;
}
final v = await ScopedPrefs.getInt('card_button_visible_count');
final raw = v ?? defaultButtonVisibleCount;
return raw.clamp(1, 9);
}
static Future<void> setCardButtonVisibleCount(int count) async {
await _set('card_button_visible_count', count.clamp(1, 9));
_notify();
}
static int _layoutToCount(String layout) {
switch (layout) {
case 'compact':
return 3;
case 'standard':
return 4;
case 'row':
return 5;
case 'expanded':
return 6;
case 'full':
return 9;
default:
return 4;
}
}
static Future<bool> getCardIconsOnly() => _get('card_icons_only', false);
static Future<void> setCardIconsOnly(bool v) async {
await _set('card_icons_only', v);
_notify();
}
static Future<bool> getCardSingleRow() => _get('card_single_row', false);
static Future<void> setCardSingleRow(bool v) async {
await _set('card_single_row', v);
_notify();
}
static Future<bool> getCardMoreInline() => _get('card_more_inline', false);
static Future<void> setCardMoreInline(bool v) async {
await _set('card_more_inline', v);
_notify();
}
// ── Appearance ──
static Future<String> getThemeMode() => _get('themeMode', 'dark');
static Future<void> setThemeMode(String value) => _set('themeMode', value);
/// Language override. Empty string means follow the system language.
/// Otherwise an ISO 639-1 code matching a supported locale (e.g. 'en', 'de', 'zh').
/// Stored globally (not per-user) so it persists across cold start before any
/// account scope is active — and so all profiles on the device share one UI language.
static Future<String> getLanguage() async {
final prefs = await SharedPreferences.getInstance();
return prefs.getString('language') ?? '';
}
static Future<void> setLanguage(String value) async {
final prefs = await SharedPreferences.getInstance();
await prefs.setString('language', value);
}
/// App color source: 'dynamic' follows the playing book cover (default),
/// 'manual' pins the app to [getManualSeedColor]. (Legacy values fall through
/// to dynamic since only 'manual' is special-cased.)
static Future<String> getColorSource() => _get('colorSource', 'dynamic');
static Future<void> setColorSource(String value) =>
_set('colorSource', value);
/// Whether the background gradient is removed (flat). In dark mode this also
/// switches surfaces to pure black (OLED); in light mode to flat white.
static Future<bool> getFlatBackground() => _get('flatBackground', false);
static Future<void> setFlatBackground(bool v) => _set('flatBackground', v);
/// E-ink mode: an override layer for e-ink screens - light flat monochrome
/// theme, no animations, plain cards, and the live socket stays down for
/// battery. The user's individual appearance settings are left untouched so
/// turning it off restores everything. Device-specific by nature, so it is
/// deliberately absent from settings sync and backups. The static mirrors
/// the stored value for cheap checks from non-async code.
static bool einkMode = false;
static Future<bool> getEinkMode() => _get('einkMode', false);
static Future<void> setEinkMode(bool v) => _set('einkMode', v);
/// Seed color (ARGB int) used when [getColorSource] is 'manual'.
static Future<int> getManualSeedColor() =>
_get('manualSeedColor', 0xFF7C6FBF);
static Future<void> setManualSeedColor(int v) => _set('manualSeedColor', v);
/// Strength of the primary-tinted background gradient (top alpha, 0 = flat).
static Future<double> getGradientIntensity() =>
_get('gradientIntensity', 0.06);
static Future<void> setGradientIntensity(double v) =>
_set('gradientIntensity', v);
/// When manual color is on, also apply it to per-book surfaces (detail sheets,
/// absorbing card background) instead of each book's cover color.
static Future<bool> getUseColorEverywhere() =>
_get('useColorEverywhere', false);
static Future<void> setUseColorEverywhere(bool v) =>
_set('useColorEverywhere', v);
/// Default start screen tab index: 0=Home, 1=Library, 2=Absorbing, 3=Stats, 4=Settings
static Future<int> getStartScreen() => _get('startScreen', 2);
static Future<void> setStartScreen(int value) => _set('startScreen', value);
/// Cached seed color from the last cover-art derivation, so we can show
/// the correct color immediately on restart without waiting for the image.
static Future<int?> getCoverSeedColor() async =>
await ScopedPrefs.getInt('coverSeedColor');
static Future<void> setCoverSeedColor(int value) =>
_set('coverSeedColor', value);
/// Check if an item has no audio content.
/// For minified responses (library list), duration == 0 means no audio files.
/// For full responses (detail sheet), we also check ebookFile + audioFiles.
/// [countNarration] off asks about the server's own audio only, leaving
/// out an EPUB found to read itself aloud.
static bool isEbookOnly(Map<String, dynamic> item, {bool countNarration = true}) {
// Podcasts are never eBook-only (minified podcasts lack duration/audioFiles)
if ((item['mediaType'] as String?) == 'podcast') return false;
// BookOrbit Book Dock files have no tracks until they are filed.
if (item['bookDock'] != null) return false;
if (countNarration && NarratedBooks.contains(item['id'])) return false;
final media = item['media'] as Map<String, dynamic>? ?? {};
final duration = (media['duration'] as num?)?.toDouble() ?? 0;
if (duration > 0) return false; // Has audio content
// No duration — check if there's any audio indicator at all
final audioFiles = media['audioFiles'] as List<dynamic>?;
final tracks = media['tracks'] as List<dynamic>?;
final numAudioFiles = (media['numAudioFiles'] as num?)?.toInt() ?? 0;
if ((audioFiles != null && audioFiles.isNotEmpty) ||
(tracks != null && tracks.isNotEmpty) ||
numAudioFiles > 0)
return false;
return true; // No audio by any measure
}
// ── Per-book speed persistence ──
static Future<double?> getBookSpeed(String itemId) =>
ScopedPrefs.getDouble('bookSpeed_$itemId');
static Future<void> setBookSpeed(String itemId, double speed) =>
_set('bookSpeed_$itemId', speed);
// ── Per-book sleep-rewind override (falls back to the global default) ──
static Future<int?> getBookSleepRewindSeconds(String itemId) =>
ScopedPrefs.getInt('sleepRewind_$itemId');
static Future<void> setBookSleepRewindSeconds(String itemId, int seconds) =>
_set('sleepRewind_$itemId', seconds);
/// Per-book override if one is set for [itemId], otherwise the global default.
static Future<int> getEffectiveSleepRewindSeconds(String? itemId) async {
if (itemId != null) {
final book = await getBookSleepRewindSeconds(itemId);
if (book != null) return book;
}
return getSleepRewindSeconds();
}
}