Specification · §4
Library index
The derived index, .boeks/cache/library.json, that lets a device list a library without opening every EPUB.
4. Library index
The index lets a device list and search the library without opening, or even having, every EPUB. It's derived from the files: read it for speed, and rebuild what's stale or missing.
{
"version": 1,
"books": {
"01j9z3k4m5n6p7q8r9s0t1v2w3": {
"path": "Frank Herbert/Dune",
"editions": {
"01j9z3k4m5n6p7q8r9s0t1v2w4": {
"file": "Ebook/Dune - Frank Herbert.epub",
"hash": "9f86d081884c7d65…",
"metadata": { "title": "Dune", "creators": [{ "name": "Frank Herbert", "roles": ["aut"] }] },
"epub": "3.0"
}
}
}
}
}
- Books are keyed by book ID, each with its folder (
path, relative to the root, with/separators) and its editions, keyed by edition ID. - Each edition has the path of its
filein the book folder, thehashof the file it was read from, itsmetadataas read from the file (before any pending edits, §3.3), itsdrmif it's encrypted (adept,lcp, orother), and its EPUB version (epub), or an audiobook's length in milliseconds (duration) with its metadata read from its tags (§9). An audiobook in several files also has itstracks, in the order they play: each file's name in the folder (file), its title tag (title), and its length in milliseconds (duration). - An entry is stale when the edition's file no longer has its
hash, or when the index'sversionis lower than the one the device reads files as. The version is this specification's, now 1, and goes up with a new version of it when reading a file gives something else, such as a field read that wasn't before: an implementation writes the version whose reading it follows, never a number of its own. An index a newer version wrote is read as it is and left alone, as that version reads files at least as well: otherwise two devices on different versions would each read the whole library again whenever the other had written it. Any device can rebuild the entries it finds stale; one whose file isn't here keeps what the index knew. An entry stale only byversion, whosehashis the one the edition's logs name, is read from the file again without hashing it: hashing every audiobook would hold up opening the library. - Covers are at
.boeks/cache/covers/<edition-id>.<ext>, one per edition, taken from its file, or from the image of a cover edit not yet written (§3.6), with the extension of the image's type. The book's cover is its primary edition's. An empty file isn't a cover, and is extracted again. - Both are disposable, as everything in
.boeks/cache/is. A missing or unreadable index is an empty one. A sync-conflict copy oflibrary.jsonis deleted, and the index rebuilt.