Skip to content

A cross platform Audiobookshelf client for Android and iOS

Dart

Make library search forgiving of word order, punctuation, and typos

Barnabasc2d6fb2541ce
diff --git a/lib/providers/auth_provider.dart b/lib/providers/auth_provider.dart
index ade5ad92..c9df4ca0 100644
--- a/lib/providers/auth_provider.dart
+++ b/lib/providers/auth_provider.dart
@@ -5,6 +5,7 @@ import 'package:flutter/material.dart';
import 'package:shared_preferences/shared_preferences.dart';
import '../services/api_service.dart';
import '../services/android_auto_service.dart';
+import '../services/book_search_index.dart';
import '../services/carplay_service.dart';
import '../services/audio_player_service.dart';
import '../services/equalizer_service.dart';
@@ -858,6 +859,9 @@ class AuthProvider extends ChangeNotifier {
AndroidAutoService().clearCache();
CarPlayService().clearAndRefresh();
+ // Drop the per-library search index so the next account can't reuse it.
+ BookSearchIndex().clear();
+
// Clear the stats widget so the previous user's numbers don't linger.
await HomeWidgetService().clearStats();
diff --git a/lib/screens/library_screen.dart b/lib/screens/library_screen.dart
index 32ee3690..7cfc0cb3 100644
--- a/lib/screens/library_screen.dart
+++ b/lib/screens/library_screen.dart
@@ -9,6 +9,7 @@ import 'package:provider/provider.dart';
import '../providers/auth_provider.dart';
import '../providers/library_provider.dart';
import '../services/api_service.dart';
+import '../services/book_search_index.dart';
import '../services/download_service.dart';
import '../services/audio_player_service.dart';
import '../widgets/absorb_page_header.dart';
@@ -1393,6 +1394,34 @@ class LibraryScreenState extends State<LibraryScreen> with TickerProviderStateMi
_hasSearched = true;
});
}
+
+ // Upgrade book results to the lenient client-side index (out-of-order
+ // words, punctuation, typos). The server results above show instantly;
+ // this replaces them once the index is built (instant on later searches).
+ // Only override when the index actually built, so a failed fetch keeps the
+ // server results instead of blanking them.
+ if (!isPodcast) {
+ final libId = lib.selectedLibraryId!;
+ await BookSearchIndex().ensureIndex(api, libId);
+ if (mounted &&
+ BookSearchIndex().isReady(libId) &&
+ _searchController.text.trim() == query) {
+ var books = BookSearchIndex()
+ .search(libId, query)
+ .map((h) => <String, dynamic>{
+ 'libraryItem': h.item,
+ '_titleMatch': h.titleMatch,
+ })
+ .toList();
+ if (_hideEbookOnly) {
+ books = books
+ .where((r) =>
+ !PlayerSettings.isEbookOnly(r['libraryItem'] as Map<String, dynamic>))
+ .toList();
+ }
+ setState(() => _searchBookResults = books);
+ }
+ }
}
Future<void> _searchNarrators(String query, String libraryId, dynamic api) async {
@@ -2429,6 +2458,10 @@ class LibraryScreenState extends State<LibraryScreen> with TickerProviderStateMi
...() {
final query = _searchController.text.trim().toLowerCase();
final titleMatches = _searchBookResults.where((result) {
+ // Fuzzy index results carry their own title-match flag; fall back
+ // to a substring check for server/podcast results.
+ final tm = result['_titleMatch'];
+ if (tm is bool) return tm;
final item = result['libraryItem'] as Map<String, dynamic>? ?? {};
final media = item['media'] as Map<String, dynamic>? ?? {};
final metadata = media['metadata'] as Map<String, dynamic>? ?? {};
diff --git a/lib/services/book_search_index.dart b/lib/services/book_search_index.dart
new file mode 100644
index 00000000..50b19c7c
--- /dev/null
+++ b/lib/services/book_search_index.dart
@@ -0,0 +1,133 @@
+import 'package:flutter/foundation.dart';
+import '../utils/fuzzy_search.dart';
+import 'api_service.dart';
+
+/// A scored search result: the raw library item plus whether it matched on the
+/// title (so callers can keep a "Books" section to title hits).
+class BookSearchHit {
+ final Map<String, dynamic> item;
+ final double score;
+ final bool titleMatch;
+ const BookSearchHit(this.item, this.score, this.titleMatch);
+}
+
+class _Indexed {
+ final Map<String, dynamic> item;
+ final String normTitle;
+ final List<String> titleTokens; // title + subtitle words
+ final List<String> authorTokens;
+ final List<String> seriesTokens;
+ const _Indexed(this.item, this.normTitle, this.titleTokens, this.authorTokens,
+ this.seriesTokens);
+}
+
+/// In-memory, per-library index of all book items, used for lenient client-side
+/// search (out-of-order words, punctuation, typos) that the strict server
+/// `/search` endpoint can't do. Built once per library per session.
+class BookSearchIndex {
+ BookSearchIndex._();
+ static final BookSearchIndex instance = BookSearchIndex._();
+ factory BookSearchIndex() => instance;
+
+ final Map<String, List<_Indexed>> _cache = {};
+ final Map<String, Future<void>> _inFlight = {};
+
+ bool isReady(String libraryId) => _cache.containsKey(libraryId);
+
+ /// Drop everything (call on logout / account switch so a reused libraryId
+ /// can't serve another account's items).
+ void clear() {
+ _cache.clear();
+ _inFlight.clear();
+ }
+
+ /// Build the index for [libraryId] if not already cached. Concurrent callers
+ /// share the same in-flight build. A failed fetch is not cached, so the next
+ /// call retries.
+ Future<void> ensureIndex(ApiService api, String libraryId) {
+ if (_cache.containsKey(libraryId)) return Future.value();
+ final existing = _inFlight[libraryId];
+ if (existing != null) return existing;
+ final f = _build(api, libraryId);
+ _inFlight[libraryId] = f;
+ return f.whenComplete(() => _inFlight.remove(libraryId));
+ }
+
+ Future<void> _build(ApiService api, String libraryId) async {
+ const pageSize = 100;
+ const maxPages = 100; // ~10k items safety cap
+
+ final first =
+ await api.getLibraryItems(libraryId, page: 0, limit: pageSize);
+ if (first == null) return; // offline / error: leave uncached for retry
+ final items = <Map<String, dynamic>>[];
+ _collect(first, items);
+ final total = (first['total'] as num?)?.toInt() ?? items.length;
+ final pages = (total / pageSize).ceil();
+ final lastPage = pages > maxPages ? maxPages : pages;
+
+ if (lastPage > 1) {
+ final futures = <Future<Map<String, dynamic>?>>[
+ for (var p = 1; p < lastPage; p++)
+ api.getLibraryItems(libraryId, page: p, limit: pageSize),
+ ];
+ for (final pd in await Future.wait(futures)) {
+ if (pd != null) _collect(pd, items);
+ }
+ }
+ if (pages > maxPages) {
+ debugPrint('[BookSearchIndex] $libraryId has $total items; indexed first '
+ '${maxPages * pageSize}. Search may miss the rest.');
+ }
+ _cache[libraryId] = items.map(_indexItem).toList();
+ }
+
+ void _collect(Map<String, dynamic> page, List<Map<String, dynamic>> out) {
+ final results = page['results'] as List<dynamic>? ?? [];
+ for (final r in results) {
+ final m = (r['libraryItem'] ?? r);
+ if (m is Map<String, dynamic>) out.add(m);
+ }
+ }
+
+ _Indexed _indexItem(Map<String, dynamic> item) {
+ final media = item['media'] as Map<String, dynamic>? ?? {};
+ final md = media['metadata'] as Map<String, dynamic>? ?? {};
+ final title = md['title'] as String? ?? '';
+ final subtitle = md['subtitle'] as String? ?? '';
+ final author = md['authorName'] as String? ?? '';
+ final series = md['seriesName'] as String? ?? '';
+ final normTitle = normalizeForSearch(title);
+ final titleTokens = tokenize(
+ subtitle.isEmpty ? normTitle : '$normTitle ${normalizeForSearch(subtitle)}'.trim());
+ return _Indexed(
+ item,
+ normTitle,
+ titleTokens,
+ tokenize(normalizeForSearch(author)),
+ tokenize(normalizeForSearch(series)),
+ );
+ }
+
+ List<BookSearchHit> search(String libraryId, String query, {int limit = 40}) {
+ final idx = _cache[libraryId];
+ if (idx == null) return const [];
+ final normQuery = normalizeForSearch(query);
+ final qTokens = tokenize(normQuery);
+ if (qTokens.isEmpty) return const [];
+ final hits = <BookSearchHit>[];
+ for (final e in idx) {
+ final r = scoreTokens(
+ qTokens: qTokens,
+ normQuery: normQuery,
+ normTitle: e.normTitle,
+ titleTokens: e.titleTokens,
+ authorTokens: e.authorTokens,
+ seriesTokens: e.seriesTokens,
+ );
+ if (r != null) hits.add(BookSearchHit(e.item, r.score, r.titleMatch));
+ }
+ hits.sort((a, b) => b.score.compareTo(a.score));
+ return hits.length > limit ? hits.sublist(0, limit) : hits;
+ }
+}
diff --git a/lib/utils/fuzzy_search.dart b/lib/utils/fuzzy_search.dart
new file mode 100644
index 00000000..4fcdd602
--- /dev/null
+++ b/lib/utils/fuzzy_search.dart
@@ -0,0 +1,151 @@
+// Lenient, typo-tolerant matching shared by the library search and the
+// add-books picker.
+//
+// Matching is:
+// - token-based, so query words can be in any order
+// ("peregrine museum" finds "Miss Peregrine's Museum of Wonders"),
+// - punctuation/diacritic-insensitive (commas, apostrophes, accents ignored),
+// - tolerant of small typos via a bounded edit distance.
+
+const Map<String, String> _diacritics = {
+ 'á': 'a', 'à': 'a', 'â': 'a', 'ä': 'a', 'ã': 'a', 'å': 'a', 'ā': 'a',
+ 'é': 'e', 'è': 'e', 'ê': 'e', 'ë': 'e', 'ē': 'e',
+ 'í': 'i', 'ì': 'i', 'î': 'i', 'ï': 'i', 'ī': 'i',
+ 'ó': 'o', 'ò': 'o', 'ô': 'o', 'ö': 'o', 'õ': 'o', 'ø': 'o', 'ō': 'o',
+ 'ú': 'u', 'ù': 'u', 'û': 'u', 'ü': 'u', 'ū': 'u',
+ 'ñ': 'n', 'ç': 'c', 'ß': 'ss', 'æ': 'ae', 'œ': 'oe', 'ý': 'y', 'ÿ': 'y',
+};
+
+// Strip common punctuation to spaces, but keep letters of any script (so CJK
+// titles aren't wiped). Apostrophes include the curly variant.
+final RegExp _punct = RegExp("['\"’‘`,:;.!?\\-_/\\\\()\\[\\]{}&+@#%^*~|<>=—–]");
+final RegExp _ws = RegExp(r'\s+');
+
+String normalizeForSearch(String input) {
+ if (input.isEmpty) return '';
+ final lower = input.toLowerCase();
+ final sb = StringBuffer();
+ for (final ch in lower.split('')) {
+ sb.write(_diacritics[ch] ?? ch);
+ }
+ return sb
+ .toString()
+ .replaceAll(_punct, ' ')
+ .replaceAll(_ws, ' ')
+ .trim();
+}
+
+List<String> tokenize(String normalized) =>
+ normalized.isEmpty ? const [] : normalized.split(' ');
+
+/// Bounded Levenshtein distance. Returns [max] + 1 as soon as the distance is
+/// known to exceed [max], so it stays cheap for typo checks on short tokens.
+int boundedLevenshtein(String a, String b, int max) {
+ final la = a.length, lb = b.length;
+ if ((la - lb).abs() > max) return max + 1;
+ if (la == 0) return lb;
+ if (lb == 0) return la;
+ var prev = List<int>.generate(lb + 1, (i) => i);
+ var curr = List<int>.filled(lb + 1, 0);
+ for (var i = 1; i <= la; i++) {
+ curr[0] = i;
+ var rowMin = curr[0];
+ final ca = a.codeUnitAt(i - 1);
+ for (var j = 1; j <= lb; j++) {
+ final cost = ca == b.codeUnitAt(j - 1) ? 0 : 1;
+ var v = prev[j - 1] + cost;
+ final del = prev[j] + 1;
+ final ins = curr[j - 1] + 1;
+ if (del < v) v = del;
+ if (ins < v) v = ins;
+ curr[j] = v;
+ if (v < rowMin) rowMin = v;
+ }
+ if (rowMin > max) return max + 1;
+ final tmp = prev;
+ prev = curr;
+ curr = tmp;
+ }
+ return prev[lb];
+}
+
+/// Best match of query token [q] against any of [tokens]:
+/// 4 exact, 3 prefix, 2 substring, 1.5/1 fuzzy (edit distance 1/2), 0 none.
+double bestTokenScore(String q, List<String> tokens) {
+ double best = 0;
+ final maxD = q.length >= 7 ? 2 : (q.length >= 4 ? 1 : 0);
+ for (final t in tokens) {
+ double s;
+ if (t == q) {
+ s = 4;
+ } else if (t.startsWith(q)) {
+ s = 3;
+ } else if (q.length >= 3 && t.contains(q)) {
+ s = 2;
+ } else if (maxD > 0) {
+ final d = boundedLevenshtein(q, t, maxD);
+ s = d <= maxD ? (d == 1 ? 1.5 : 1.0) : 0;
+ } else {
+ s = 0;
+ }
+ if (s > best) best = s;
+ if (best >= 4) break;
+ }
+ return best;
+}
+
+// Short, common words that shouldn't, on their own, exclude a match - so
+// "the peregrine museum" still finds "Miss Peregrine's Museum of Wonders".
+const Set<String> _stopWords = {
+ 'the', 'a', 'an', 'of', 'and', 'or', 'to', 'in', 'on', 'for', 'with',
+ 'at', 'by', 'from', 'as', 'is',
+};
+
+/// Score a target (pre-normalized) against the query tokens. Every meaningful
+/// query word must match somewhere (AND semantics keeps noise down), but short
+/// or stop words are optional - they add to the score when present and are
+/// ignored when absent. Returns null when the item shouldn't appear at all.
+/// [titleMatch] is true when a query token matched the title (or subtitle), so
+/// the caller can keep "Books" sections to title hits.
+({double score, bool titleMatch})? scoreTokens({
+ required List<String> qTokens,
+ required String normQuery,
+ required String normTitle,
+ required List<String> titleTokens,
+ required List<String> authorTokens,
+ required List<String> seriesTokens,
+}) {
+ if (qTokens.isEmpty) return null;
+ double total = 0;
+ bool titleMatch = false;
+ int matched = 0;
+ for (final q in qTokens) {
+ final ts = bestTokenScore(q, titleTokens);
+ final aScore = bestTokenScore(q, authorTokens) * 0.6;
+ final sScore = bestTokenScore(q, seriesTokens) * 0.5;
+ var best = ts;
+ if (aScore > best) best = aScore;
+ if (sScore > best) best = sScore;
+ final optional = q.length <= 2 || _stopWords.contains(q);
+ if (best <= 0) {
+ if (!optional) return null; // a meaningful query word didn't match
+ continue; // ignore an unmatched short/stop word
+ }
+ matched++;
+ if (ts > 0) titleMatch = true;
+ total += optional ? best * 0.5 : best;
+ }
+ if (matched == 0) return null;
+ // Whole-query phrase bonus so close, contiguous matches rank first.
+ if (normTitle == normQuery) {
+ total += 8;
+ } else if (normTitle.startsWith(normQuery)) {
+ total += 6;
+ } else if (normTitle.contains(normQuery)) {
+ total += 5;
+ }
+ // Nudge shorter titles up so an exact short title beats a long one that
+ // merely contains the words.
+ total += 1.0 / (1 + titleTokens.length);
+ return (score: total, titleMatch: titleMatch);
+}