A cross platform Audiobookshelf client for Android and iOS
Dart
import 'dart:convert';
import 'dart:io';
import 'package:flutter/foundation.dart';
import 'package:path_provider/path_provider.dart';
/// One displayed transcript line: a Whisper segment (or its ebook-corrected
/// replacement), timed in the item's own seconds (episode-relative for
/// podcast episodes, global book time for audiobooks).
class TranscriptLine {
final double start;
final double end;
final String text;
/// True when the text came from the ebook's real words, not Whisper.
final bool exact;
/// Start time of each whitespace-separated word in [text], for read-along
/// word tracking. Empty on lines cached before word timing existed, and on
/// anything the timing couldn't be worked out for - callers fall back to
/// whole-line highlighting.
final List<double> wordStarts;
/// True for an estimated preview: the book's next sentences after the last
/// transcribed stretch, timed by pace guess rather than heard audio. Shown
/// dimmed, never counted as coverage, and replaced the moment the real
/// transcription of that stretch lands.
final bool approx;
const TranscriptLine(this.start, this.end, this.text,
{this.exact = false, this.wordStarts = const [], this.approx = false});
/// The words [wordStarts] is indexed against.
List<String> get words =>
text.trim().split(RegExp(r'\s+')).where((w) => w.isNotEmpty).toList();
/// Index into [words] of the word being spoken at [t], or -1 when the line
/// has no word timing or [t] sits before the first word.
int wordIndexAt(double t) {
if (wordStarts.isEmpty) return -1;
if (t < wordStarts.first) return -1;
var lo = 0, hi = wordStarts.length - 1;
while (lo < hi) {
final mid = (lo + hi + 1) >> 1;
if (wordStarts[mid] <= t) {
lo = mid;
} else {
hi = mid - 1;
}
}
return lo;
}
Map<String, dynamic> toJson() => {
's': start,
'e': end,
't': text,
if (exact) 'x': true,
if (approx) 'a': true,
if (wordStarts.isNotEmpty)
'w': [for (final w in wordStarts) double.parse(w.toStringAsFixed(2))],
};
factory TranscriptLine.fromJson(Map<String, dynamic> j) => TranscriptLine(
(j['s'] as num).toDouble(),
(j['e'] as num).toDouble(),
j['t'] as String? ?? '',
exact: j['x'] == true,
approx: j['a'] == true,
wordStarts: [
for (final w in (j['w'] as List<dynamic>? ?? const []))
(w as num).toDouble(),
],
);
}
/// Per-book / per-episode cache of transcript lines, so audio is transcribed
/// once ever: replays, seeks and app restarts are lookups. Keys are the same
/// composite the rest of the app uses - itemId for books,
/// "itemId-episodeId" for podcast episodes. One JSON file per key under
/// app support; writes are debounced so the transcribe-ahead loop doesn't
/// grind the disk.
class TranscriptLineStore {
TranscriptLineStore._();
static final TranscriptLineStore instance = TranscriptLineStore._();
final Map<String, List<TranscriptLine>> _cache = {};
final Set<String> _dirty = {};
bool _flushScheduled = false;
Future<Directory> _dir() async {
final base = await getApplicationSupportDirectory();
final dir = Directory('${base.path}/transcript_lines');
if (!dir.existsSync()) dir.createSync(recursive: true);
return dir;
}
Future<File> _fileFor(String key) async =>
File('${(await _dir()).path}/$key.json');
Future<List<TranscriptLine>> _load(String key) async {
final cached = _cache[key];
if (cached != null) return cached;
var lines = <TranscriptLine>[];
try {
final f = await _fileFor(key);
if (f.existsSync()) {
final j = jsonDecode(await f.readAsString()) as Map<String, dynamic>;
lines = (j['lines'] as List<dynamic>? ?? const [])
.map((e) => TranscriptLine.fromJson(e as Map<String, dynamic>))
.toList();
}
} catch (e) {
debugPrint('[Lyrics] store load failed for $key: $e');
}
lines.sort((a, b) => a.start.compareTo(b.start));
_cache[key] = lines;
return lines;
}
/// Warm the in-memory cache; call before the sync lookups below.
Future<void> hydrate(String key) => _load(key);
/// The line containing [t], or null when that moment isn't transcribed yet
/// (or was silence/music). Binary search over the sorted cache.
TranscriptLine? lineAt(String key, double t) {
final lines = _cache[key];
if (lines == null || lines.isEmpty) return null;
var lo = 0, hi = lines.length - 1;
while (lo <= hi) {
final mid = (lo + hi) >> 1;
final l = lines[mid];
if (t < l.start) {
hi = mid - 1;
} else if (t > l.end) {
lo = mid + 1;
} else {
return l;
}
}
return null;
}
/// Like [lineAt], but forgiving around the gaps Whisper's VAD leaves
/// between segments: holds the previous line up to [holdAfter] seconds past
/// its end, and shows the next line up to [preShow] seconds early - so
/// inter-sentence silences don't blank the overlay.
TranscriptLine? lineNear(String key, double t,
{double holdAfter = 2.5, double preShow = 0.8}) {
final exact = lineAt(key, t);
if (exact != null) return exact;
final lines = _cache[key];
if (lines == null || lines.isEmpty) return null;
TranscriptLine? prev;
for (final l in lines) {
if (l.start > t) {
if (l.start - t <= preShow && l.text.trim().isNotEmpty) return l;
break;
}
prev = l;
}
if (prev != null && t - prev.end <= holdAfter && prev.text.trim().isNotEmpty) {
return prev;
}
return null;
}
/// The first real, ebook-exact line starting at or after [t] within
/// [within] seconds, or null. Read along can only find the book's own
/// words on the page, so with no anchor yet it looks ahead for one.
TranscriptLine? nextExactLine(String key, double t, {double within = 90}) {
final lines = _cache[key];
if (lines == null || lines.isEmpty) return null;
for (final l in lines) {
if (l.start < t) continue;
if (l.start > t + within) break;
if (l.exact && !l.approx && l.text.trim().isNotEmpty) return l;
}
return null;
}
/// Up to [count] lines running on from the one that begins at [start],
/// for filling a page of transcript downwards. Silence placeholders are
/// left out. Empty when that line isn't in the cache.
List<TranscriptLine> fromLine(String key, double start, int count) {
final lines = _cache[key];
if (lines == null || lines.isEmpty) return const [];
final idx = lines.indexWhere((l) => l.start == start);
if (idx < 0) return const [];
final out = <TranscriptLine>[];
for (var i = idx; i < lines.length && out.length < count; i++) {
if (lines[i].text.trim().isNotEmpty) out.add(lines[i]);
}
return out;
}
/// Total seconds of this item that have been transcribed, gaps excluded.
/// Silence placeholders count - that stretch is done with either way.
double preparedSeconds(String key) {
final lines = _cache[key];
if (lines == null || lines.isEmpty) return 0;
var total = 0.0;
var last = double.negativeInfinity;
for (final l in lines) {
if (l.approx) continue;
final from = l.start > last ? l.start : last;
if (l.end > from) total += l.end - from;
if (l.end > last) last = l.end;
}
return total;
}
/// How far continuous coverage extends from [from]: the end of the chained
/// lines starting at or before [from], tolerating small inter-line gaps
/// (Whisper trims silence between segments). Returns [from] when nothing
/// covers it yet.
double coveredUntil(String key, double from) {
final lines = _cache[key];
if (lines == null || lines.isEmpty) return from;
const gapTolerance = 4.0;
var covered = from;
for (final l in lines) {
// Estimated previews are display-only - counting them as coverage
// would stop the loop from ever really transcribing that stretch.
if (l.approx) continue;
if (l.end <= covered) continue;
if (l.start > covered + gapTolerance) break;
covered = l.end;
}
return covered;
}
/// Merge [fresh] into the cache. Lines overlapping an existing one are
/// dropped unless they're exact and the existing one isn't - an ebook
/// correction may upgrade a line, but a re-transcription never downgrades.
/// Estimated previews are the weakest of all: real lines always replace
/// them, and they never displace anything real.
Future<void> addLines(String key, List<TranscriptLine> fresh) async {
final lines = await _load(key);
var changed = false;
for (final nl in fresh) {
if (nl.text.trim().isEmpty) continue;
final overlapIdx = lines.indexWhere((e) =>
nl.start < e.end - 0.3 && nl.end > e.start + 0.3);
if (overlapIdx >= 0) {
final old = lines[overlapIdx];
final upgrade = old.approx
? true // anything beats a preview, and a newer preview is fresher
: (!nl.approx && nl.exact && !old.exact);
if (upgrade) {
lines[overlapIdx] = nl;
// One real line can span several stale previews - sweep the rest.
lines.removeWhere((e) =>
!identical(e, nl) &&
e.approx &&
nl.start < e.end - 0.3 &&
nl.end > e.start + 0.3);
changed = true;
}
continue;
}
lines.add(nl);
changed = true;
}
if (!changed) return;
lines.sort((a, b) => a.start.compareTo(b.start));
_dirty.add(key);
_scheduleFlush();
}
/// Total bytes the on-disk transcript cache occupies.
Future<int> cacheBytes() async {
var total = 0;
try {
final dir = await _dir();
for (final f in dir.listSync()) {
if (f is File) total += f.lengthSync();
}
} catch (_) {}
return total;
}
/// Wipe every cached transcript, memory and disk. Emptying [_cache] also
/// defuses any flush in flight - it re-reads the cache per key and skips
/// keys that are gone, so a pending write can't resurrect a file.
Future<void> clearAll() async {
_cache.clear();
_dirty.clear();
try {
final dir = await _dir();
for (final f in dir.listSync()) {
if (f is! File) continue;
try {
await f.delete();
} catch (_) {}
}
} catch (e) {
debugPrint('[Lyrics] store clear failed: $e');
}
}
void _scheduleFlush() {
if (_flushScheduled) return;
_flushScheduled = true;
Future.delayed(const Duration(seconds: 3), () async {
_flushScheduled = false;
final keys = _dirty.toList();
_dirty.clear();
for (final key in keys) {
final lines = _cache[key];
if (lines == null) continue;
try {
final f = await _fileFor(key);
await f.writeAsString(jsonEncode({
'v': 1,
'lines': [for (final l in lines) l.toJson()],
}));
} catch (e) {
debugPrint('[Lyrics] store write failed for $key: $e');
}
}
});
}
}