A cross platform Audiobookshelf client for Android and iOS
Dart
import 'dart:convert';
import 'dart:math';
import 'package:archive/archive_io.dart';
import '../utils/percent_escapes.dart';
/// One narrated sentence: where its text is and which stretch of which audio
/// file reads it.
class OverlayClip {
final int section;
final String textHref;
final String? fragment;
final int track;
final double begin;
final double end;
const OverlayClip({
required this.section,
required this.textHref,
required this.fragment,
required this.track,
required this.begin,
required this.end,
});
/// The sentence the way the SMIL file names it, document and id. BookOrbit's
/// read along keeps its place in this form and only matches it exactly.
String get textSrc => fragment == null ? textHref : '$textHref#$fragment';
}
/// An audio file inside the EPUB, placed on the book's timeline.
class OverlayTrack {
final String href;
final String mediaType;
final double duration;
final double start;
const OverlayTrack(this.href, this.mediaType, this.duration, this.start);
}
/// A narrated chapter (spine item) and where its narration starts.
class OverlaySection {
final int index;
final String href;
final String? label;
final double start;
const OverlaySection(this.index, this.href, this.label, this.start);
}
class _RawClip {
final int section;
final String textHref;
final String? fragment;
final String audioHref;
final double begin;
double? end;
_RawClip(this.section, this.textHref, this.fragment, this.audioHref, this.begin, this.end);
}
/// An EPUB 3 media overlay (a narrated or "read along" EPUB) laid out the way
/// the player sees it: the audio files end to end, each sentence a stretch of
/// one file. Built from BookOrbit's playlist or straight from the EPUB.
class MediaOverlay {
final List<OverlayTrack> tracks;
final List<OverlayClip> clips;
final List<OverlaySection> sections;
final List<List<int>> _byTrack;
MediaOverlay._(this.tracks, this.clips, this.sections)
: _byTrack = List.generate(tracks.length, (_) => <int>[]) {
for (var i = 0; i < clips.length; i++) {
_byTrack[clips[i].track].add(i);
}
for (final list in _byTrack) {
list.sort((a, b) => clips[a].begin.compareTo(clips[b].begin));
}
}
double get duration => tracks.isEmpty ? 0 : tracks.last.start + tracks.last.duration;
bool get isEmpty => clips.isEmpty;
static MediaOverlay? _build(
List<_RawClip> raw, {
required Map<String, String> mediaTypes,
required Map<int, ({String href, String? label})> sectionInfo,
}) {
if (raw.isEmpty) return null;
final order = <String, int>{};
for (final c in raw) {
order.putIfAbsent(c.audioHref, () => order.length);
}
// A clip with no end runs to the next clip in the same file.
final byFile = <String, List<_RawClip>>{};
for (final c in raw) {
(byFile[c.audioHref] ??= []).add(c);
}
for (final list in byFile.values) {
list.sort((a, b) => a.begin.compareTo(b.begin));
for (var i = 0; i < list.length; i++) {
if (list[i].end != null) continue;
list[i].end = i + 1 < list.length ? list[i + 1].begin : list[i].begin;
}
}
final tracks = <OverlayTrack>[];
var start = 0.0;
for (final href in order.keys) {
final d = byFile[href]!.fold<double>(0, (m, c) => max(m, c.end ?? c.begin));
tracks.add(OverlayTrack(href, mediaTypes[href] ?? _guessType(href), d, start));
start += d;
}
final clips = [
for (final c in raw)
OverlayClip(
section: c.section,
textHref: c.textHref,
fragment: c.fragment,
track: order[c.audioHref]!,
begin: c.begin,
end: c.end ?? c.begin,
),
];
final sections = <OverlaySection>[];
final seen = <int>{};
for (final c in clips) {
if (!seen.add(c.section)) continue;
final info = sectionInfo[c.section];
sections.add(OverlaySection(
c.section,
info?.href ?? c.textHref,
info?.label,
tracks[c.track].start + c.begin,
));
}
sections.sort((a, b) => a.start.compareTo(b.start));
return MediaOverlay._(tracks, clips, sections);
}
static String _guessType(String href) {
final ext = href.split('.').last.toLowerCase();
return switch (ext) {
'mp3' => 'audio/mpeg',
'm4a' || 'm4b' || 'mp4' || 'aac' => 'audio/mp4',
'ogg' || 'oga' || 'opus' => 'audio/ogg',
'wav' => 'audio/wav',
_ => 'application/octet-stream',
};
}
/// The track playing at book time [t].
int trackAt(double t) {
var lo = 0, hi = tracks.length - 1, ans = 0;
while (lo <= hi) {
final mid = (lo + hi) >> 1;
if (tracks[mid].start <= t) {
ans = mid;
lo = mid + 1;
} else {
hi = mid - 1;
}
}
return ans;
}
/// The sentence being read at book time [t]: the last one to have started
/// in the file playing then, so the gap after a sentence keeps it lit.
OverlayClip? clipAt(double t) {
if (tracks.isEmpty) return null;
final track = trackAt(t);
final local = t - tracks[track].start;
final list = _byTrack[track];
var lo = 0, hi = list.length - 1, ans = -1;
while (lo <= hi) {
final mid = (lo + hi) >> 1;
if (clips[list[mid]].begin <= local + 0.001) {
ans = mid;
lo = mid + 1;
} else {
hi = mid - 1;
}
}
if (ans < 0) return list.isEmpty ? null : clips[list.first];
return clips[list[ans]];
}
/// Book time where [clip] starts.
double startOf(OverlayClip clip) => tracks[clip.track].start + clip.begin;
static bool sameDoc(String a, String b) {
if (a == b) return true;
final x = _docPath(a), y = _docPath(b);
return x == y || x.endsWith('/$y') || y.endsWith('/$x');
}
// BookOrbit's timings can keep a name escaped (%2C) where the EPUB's own
// path has it plain, so both are compared with every escape undone.
static String _docPath(String href) {
final path = href.split('#').first;
return undoPathEscapes(path);
}
/// The sentence whose element is [fragment], in [section] when given (an
/// id can repeat across sections). The id can come bare or with its
/// document in front (`text/ch1.xhtml#s12`), the way BookOrbit keeps it.
/// Null when nothing narrated has it.
OverlayClip? clipByFragment(String fragment, int? section) {
final hash = fragment.indexOf('#');
final id = hash < 0 ? fragment : fragment.substring(hash + 1);
final doc = hash > 0 ? fragment.substring(0, hash) : null;
OverlayClip? any;
for (final c in clips) {
if (c.fragment != id) continue;
if (doc != null && !sameDoc(c.textHref, doc)) continue;
if (section == null || c.section == section) return c;
any ??= c;
}
return any;
}
/// The first sentence whose element is [fragment] in [href], or the first
/// one in [href] when the fragment isn't narrated.
OverlayClip? clipFor(String href, String? fragment) {
OverlayClip? first;
for (final c in clips) {
if (!sameDoc(c.textHref, href)) continue;
first ??= c;
if (fragment != null && c.fragment == fragment) return c;
}
return first;
}
/// The chapters Absorb shows. With the book's contents to go by, each
/// named section starts a chapter and the sections after it that the
/// contents leave out carry it on (one chapter split over several files),
/// and an unnamed opening, such as the title read aloud, joins the first
/// chapter. A book with no usable contents gets one chapter per section.
List<Map<String, dynamic>> chapters() {
final named = sections.any((s) => s.label?.trim().isNotEmpty == true);
final out = <Map<String, dynamic>>[];
var openingUnnamed = false;
for (var i = 0; i < sections.length; i++) {
final s = sections[i];
final end = i + 1 < sections.length ? sections[i + 1].start : duration;
if (end <= s.start) continue;
final label = s.label?.trim() ?? '';
if (named && label.isEmpty && out.isNotEmpty) {
out.last['end'] = end;
continue;
}
if (out.isEmpty) openingUnnamed = named && label.isEmpty;
out.add({
'id': out.length,
'start': s.start,
'end': end,
'title': label.isNotEmpty ? label : 'Chapter ${out.length + 1}',
});
}
if (openingUnnamed && out.length > 1) {
out[1]['start'] = out[0]['start'];
out.removeAt(0);
for (var i = 0; i < out.length; i++) {
out[i]['id'] = i;
}
}
return out;
}
/// The sections named from the book's contents: [spine] is every file in
/// reading order, [labels] the first contents entry pointing into each.
/// An entry on a file with no narration (a chapter's title page) names
/// the next narrated file the contents leave out.
MediaOverlay withContents(List<String> spine, Map<String, String> labels) {
final names = <int, String?>{};
String? pending;
for (final href in spine) {
final own = labels[href];
OverlaySection? section;
for (final s in sections) {
if (sameDoc(s.href, href)) {
section = s;
break;
}
}
if (section == null) {
if (own != null) pending = own;
continue;
}
names[section.index] = own ?? pending ?? section.label;
pending = null;
}
return MediaOverlay._(tracks, clips, [
for (final s in sections)
OverlaySection(s.index, s.href, names.containsKey(s.index) ? names[s.index] : s.label, s.start),
]);
}
/// Audiobookshelf-shaped audio tracks, with [url] giving each file's address.
List<Map<String, dynamic>> audioTracks(String Function(OverlayTrack track) url) => [
for (var i = 0; i < tracks.length; i++)
{
'index': i + 1,
'startOffset': tracks[i].start,
'duration': tracks[i].duration,
'title': tracks[i].href.split('/').last,
'contentUrl': url(tracks[i]),
'mimeType': tracks[i].mediaType,
// Numbered, so same-named files in different folders can't collide.
'metadata': {'filename': '${(i + 1).toString().padLeft(3, '0')} ${tracks[i].href.split('/').last}'},
},
];
/// The same narration laid out on each audio file's measured length. A
/// missing measurement, or one shorter than the file's last sentence, keeps
/// the length the timings imply.
MediaOverlay withTrackDurations(List<double?> measured) {
final laid = <OverlayTrack>[];
var start = 0.0;
for (var i = 0; i < tracks.length; i++) {
final m = i < measured.length ? measured[i] : null;
final d = m != null && m >= tracks[i].duration - 0.5 ? m : tracks[i].duration;
laid.add(OverlayTrack(tracks[i].href, tracks[i].mediaType, d, start));
start += d;
}
final first = <int, OverlayClip>{};
for (final c in clips) {
first.putIfAbsent(c.section, () => c);
}
final secs = [
for (final s in sections)
OverlaySection(s.index, s.href, s.label,
first[s.index] == null ? s.start : laid[first[s.index]!.track].start + first[s.index]!.begin),
];
return MediaOverlay._(laid, clips, secs);
}
/// This narration stretched evenly to last [total] seconds: a read along
/// EPUB laid on its audiobook's own timeline, the way BookOrbit maps one
/// onto the other.
MediaOverlay scaledTo(double total) {
final d = duration;
if (d <= 0 || total <= 0) return this;
final f = total / d;
return MediaOverlay._(
[for (final t in tracks) OverlayTrack(t.href, t.mediaType, t.duration * f, t.start * f)],
[
for (final c in clips)
OverlayClip(
section: c.section,
textHref: c.textHref,
fragment: c.fragment,
track: c.track,
begin: c.begin * f,
end: c.end * f,
),
],
[for (final s in sections) OverlaySection(s.index, s.href, s.label, s.start * f)],
);
}
/// The clip in this narration reading the same sentence as [other], which
/// may come from an earlier layout of it.
OverlayClip? sameClip(OverlayClip other) {
for (final c in clips) {
if (c.fragment == other.fragment && c.textHref == other.textHref && c.begin == other.begin) return c;
}
return null;
}
Map<String, dynamic> toJson() => {
'tracks': [
for (final t in tracks)
{'href': t.href, 'type': t.mediaType, 'duration': t.duration, 'start': t.start},
],
'clips': [
for (final c in clips)
[c.section, c.textHref, c.fragment, c.track, c.begin, c.end],
],
'sections': [
for (final s in sections) {'index': s.index, 'href': s.href, 'label': s.label, 'start': s.start},
],
};
static MediaOverlay? fromJson(Map<String, dynamic> j) {
try {
final tracks = [
for (final t in (j['tracks'] as List<dynamic>).cast<Map<String, dynamic>>())
OverlayTrack(t['href'] as String, t['type'] as String, (t['duration'] as num).toDouble(),
(t['start'] as num).toDouble()),
];
final clips = [
for (final c in (j['clips'] as List<dynamic>).cast<List<dynamic>>())
OverlayClip(
section: (c[0] as num).toInt(),
textHref: c[1] as String,
fragment: c[2] as String?,
track: (c[3] as num).toInt(),
begin: (c[4] as num).toDouble(),
end: (c[5] as num).toDouble(),
),
];
final sections = [
for (final s in (j['sections'] as List<dynamic>).cast<Map<String, dynamic>>())
OverlaySection((s['index'] as num).toInt(), s['href'] as String, s['label'] as String?,
(s['start'] as num).toDouble()),
];
if (tracks.isEmpty || clips.isEmpty) return null;
return MediaOverlay._(tracks, clips, sections);
} catch (_) {
return null;
}
}
/// From BookOrbit's `/epub/:bookId/media-overlay` playlist.
static MediaOverlay? fromBookOrbit(Map<String, dynamic> playlist) {
final types = <String, String>{
for (final r in (playlist['resources'] as List<dynamic>? ?? const []).whereType<Map<String, dynamic>>())
if (r['href'] is String) r['href'] as String: r['mediaType'] as String? ?? '',
};
final sectionInfo = <int, ({String href, String? label})>{
for (final s in (playlist['sections'] as List<dynamic>? ?? const []).whereType<Map<String, dynamic>>())
if (s['index'] is num && s['href'] is String)
(s['index'] as num).toInt(): (href: s['href'] as String, label: s['label'] as String?),
};
final raw = <_RawClip>[];
for (final i in (playlist['items'] as List<dynamic>? ?? const []).whereType<Map<String, dynamic>>()) {
final audio = i['audioHref'] as String?;
final text = i['textHref'] as String?;
final begin = (i['clipBeginSeconds'] as num?)?.toDouble();
if (audio == null || text == null || begin == null) continue;
final section = (i['sectionIndex'] as num?)?.toInt() ?? 0;
raw.add(_RawClip(section, text, i['textFragment'] as String?, audio, begin,
(i['clipEndSeconds'] as num?)?.toDouble()));
if (!sectionInfo.containsKey(section) && i['label'] is String) {
sectionInfo[section] = (href: text, label: i['label'] as String);
}
}
types.removeWhere((_, v) => v.isEmpty);
return _build(raw, mediaTypes: types, sectionInfo: sectionInfo);
}
/// Straight from an EPUB's package and SMIL files. Null when the book has
/// no narration.
static Future<MediaOverlay?> fromEpub(Archive archive) =>
fromFiles((name) async => _text(archive, name));
/// The same, with the EPUB's files read through [load] (a local zip, or
/// range requests to one on the server). [onNarrated] hears as soon as the
/// package shows the book reads itself aloud, with the length it states,
/// before the timing files are read.
static Future<MediaOverlay?> fromFiles(
Future<String?> Function(String name) load, {
void Function(double? duration)? onNarrated,
}) async {
final container = await load('META-INF/container.xml');
if (container == null) return null;
final rootfile = _rootfileTag.firstMatch(container);
final opfPath = rootfile == null ? null : _attrs(rootfile.group(0)!)['full-path'];
if (opfPath == null) return null;
final opf = await load(opfPath);
if (opf == null) return null;
final byId = <String, ({String href, String type, String? overlay, String props})>{};
for (final m in _itemTag.allMatches(opf)) {
final a = _attrs(m.group(0)!);
final id = a['id'], href = a['href'];
if (id == null || href == null) continue;
byId[id] = (
href: _resolve(opfPath, href),
type: a['media-type'] ?? '',
overlay: a['media-overlay'],
props: a['properties'] ?? '',
);
}
final types = {for (final v in byId.values) v.href: v.type};
final overlayIds = {for (final v in byId.values) if (v.overlay != null) v.overlay!};
if (overlayIds.isEmpty) return null;
onNarrated?.call(_packageDuration(opf));
final labels = await _navLabels(load, byId.values.where((v) => v.props.split(' ').contains('nav')).map((v) => v.href));
// On a server each timing file is a request of its own, so they come a
// few at a time; one after another took half a minute on a big book.
final smilPaths = <String>[];
for (final m in _itemrefTag.allMatches(opf)) {
final ref = _attrs(m.group(0)!)['idref'];
final overlayId = ref == null ? null : byId[ref]?.overlay;
final path = overlayId == null ? null : byId[overlayId]?.href;
if (path != null && !smilPaths.contains(path)) smilPaths.add(path);
}
final smils = <String, String?>{};
for (var i = 0; i < smilPaths.length; i += 8) {
final batch = smilPaths.sublist(i, min(i + 8, smilPaths.length));
final got = await Future.wait(batch.map(load));
for (var j = 0; j < batch.length; j++) {
smils[batch[j]] = got[j];
}
}
final raw = <_RawClip>[];
final sectionInfo = <int, ({String href, String? label})>{};
final spine = <String>[];
var index = 0;
for (final m in _itemrefTag.allMatches(opf)) {
final spineIndex = index++;
final ref = _attrs(m.group(0)!)['idref'];
final item = ref == null ? null : byId[ref];
if (item != null) spine.add(item.href);
final overlayId = item?.overlay;
if (item == null || overlayId == null) continue;
final smilPath = byId[overlayId]?.href;
final smil = smilPath == null ? null : smils[smilPath];
if (smil == null) continue;
sectionInfo[spineIndex] = (href: item.href, label: labels[item.href]);
for (final par in _parBlock.allMatches(smil)) {
final body = par.group(1)!;
final text = _textTag.firstMatch(body);
final audio = _audioTag.firstMatch(body);
if (text == null || audio == null) continue;
final t = _attrs(text.group(0)!), au = _attrs(audio.group(0)!);
final src = t['src'], audioSrc = au['src'];
if (src == null || audioSrc == null) continue;
final begin = parseClock(au['clipbegin']) ?? 0;
final hash = src.indexOf('#');
raw.add(_RawClip(
spineIndex,
_resolve(smilPath!, src),
hash < 0 ? null : undoPercentEscapes(src.substring(hash + 1)),
_resolve(smilPath, audioSrc),
begin,
parseClock(au['clipend']),
));
}
}
return _build(raw, mediaTypes: types, sectionInfo: sectionInfo)?.withContents(spine, labels);
}
/// The narration's whole length as the package states it: the
/// `media:duration` meta that refines nothing. Null when it isn't given.
static double? _packageDuration(String opf) {
for (final m in _metaTag.allMatches(opf)) {
final a = _attrs(m.group(1)!);
if (a['property'] != 'media:duration' || a.containsKey('refines')) continue;
return parseClock(m.group(2)!.trim());
}
return null;
}
static final _metaTag = RegExp(r'<(?:\w+:)?meta\b([^>]*)>([^<]*)</(?:\w+:)?meta>', caseSensitive: false);
/// [withContents] from BookOrbit's book info: its spine and table of
/// contents, the first entry in each file.
MediaOverlay withBookOrbitContents(Map<String, dynamic> info) {
final spine = [
for (final s in (info['spine'] as List<dynamic>? ?? const []).whereType<Map<String, dynamic>>())
if (s['href'] is String) s['href'] as String,
];
final labels = <String, String>{};
void visit(Object? node) {
if (node is! Map) return;
final href = node['href'], label = node['label'];
if (href is String && label is String && label.trim().isNotEmpty) {
labels.putIfAbsent(href.split('#').first, () => label.trim());
}
for (final child in (node['children'] as List<dynamic>? ?? const [])) {
visit(child);
}
}
visit(info['toc']);
if (spine.isEmpty || labels.isEmpty) return this;
return withContents(spine, labels);
}
/// SMIL clock values: "1:02:03.5", "02:03.5", "12.5s", "250ms", "1.5min",
/// "2h", or plain seconds.
static double? parseClock(String? v) {
if (v == null) return null;
final s = v.trim();
if (s.isEmpty) return null;
if (s.contains(':')) {
final parts = s.split(':').map((p) => double.tryParse(p.trim())).toList();
if (parts.any((p) => p == null)) return null;
return parts.fold<double>(0, (acc, p) => acc * 60 + p!);
}
final m = RegExp(r'^([\d.]+)\s*(h|min|s|ms)?$').firstMatch(s);
if (m == null) return null;
final n = double.tryParse(m.group(1)!);
if (n == null) return null;
return switch (m.group(2)) {
'h' => n * 3600,
'min' => n * 60,
'ms' => n / 1000,
_ => n,
};
}
}
final _attr = RegExp(r'''([\w:.-]+)\s*=\s*("([^"]*)"|'([^']*)')''');
final _itemTag = RegExp(r'<(?:\w+:)?item\b[^>]*>', caseSensitive: false);
final _itemrefTag = RegExp(r'<(?:\w+:)?itemref\b[^>]*>', caseSensitive: false);
final _rootfileTag = RegExp(r'<(?:\w+:)?rootfile\b[^>]*>', caseSensitive: false);
final _parBlock = RegExp(r'<(?:\w+:)?par\b[^>]*>(.*?)</(?:\w+:)?par\s*>', caseSensitive: false, dotAll: true);
final _textTag = RegExp(r'<(?:\w+:)?text\b[^>]*>', caseSensitive: false);
final _audioTag = RegExp(r'<(?:\w+:)?audio\b[^>]*>', caseSensitive: false);
final _navLink = RegExp(r'''<a\b[^>]*href\s*=\s*("([^"]*)"|'([^']*)')[^>]*>(.*?)</a\s*>''', caseSensitive: false, dotAll: true);
final _tags = RegExp(r'<[^>]*>');
final _space = RegExp(r'\s+');
Map<String, String> _attrs(String tag) {
final out = <String, String>{};
for (final m in _attr.allMatches(tag)) {
var name = m.group(1)!.toLowerCase();
final colon = name.lastIndexOf(':');
if (colon >= 0 && !name.startsWith('xml')) name = name.substring(colon + 1);
out.putIfAbsent(name, () => _unescape(m.group(3) ?? m.group(4) ?? ''));
}
return out;
}
String _unescape(String s) => s
.replaceAll('&', '&')
.replaceAll('"', '"')
.replaceAll(''', "'")
.replaceAll('<', '<')
.replaceAll('>', '>');
String _dir(String path) {
final i = path.lastIndexOf('/');
return i < 0 ? '' : path.substring(0, i + 1);
}
/// [href] relative to [base]'s folder, as a path inside the zip.
String _resolve(String base, String href) {
// Every escape undone, segment by segment: Uri.decodeFull leaves reserved
// characters like %2C (a comma) encoded, and a file with one in its name
// was then looked for under a name the zip doesn't have.
final clean = undoPathEscapes(href.split('#').first.split('?').first);
final parts = <String>[];
for (final p in '${_dir(base)}$clean'.split('/')) {
if (p.isEmpty || p == '.') continue;
if (p == '..') {
if (parts.isNotEmpty) parts.removeLast();
} else {
parts.add(p);
}
}
return parts.join('/');
}
String? _text(Archive archive, String name) {
final f = archive.findFile(name);
if (f == null) return null;
return utf8.decode(f.content as List<int>, allowMalformed: true);
}
/// Chapter names from the navigation document, by the file they point at.
Future<Map<String, String>> _navLabels(
Future<String?> Function(String name) load, Iterable<String> navPaths) async {
final out = <String, String>{};
for (final path in navPaths) {
final doc = await load(path);
if (doc == null) continue;
for (final m in _navLink.allMatches(doc)) {
final href = m.group(2) ?? m.group(3) ?? '';
final label = _unescape(m.group(4)!.replaceAll(_tags, ' ')).replaceAll(_space, ' ').trim();
if (href.isEmpty || label.isEmpty) continue;
out.putIfAbsent(_resolve(path, href), () => label);
}
}
return out;
}