RogerBW's Blog

I recently got a Kobo Libra 2, after my Aura ONE died. And I've been looking into its series tagging features.

I haven't bothered with this before, because I tend to run fairly "light": I load up the next ten or so books that I'm planning to read, delete each one once I've read it, and repeat. Chances are I don't have more than one entry in a given series loaded at a time.

But my wife now also has a Libra 2, and she would rather have lots of books available at once. So I looked into how the things can be organised.

I have ePUB files from a variety of sources, and their tagging is not consistent. One way of fixing that, the way most people use as far as I can see, is to use calibre – which is fine as far as it goes, but it really wants to be in charge of your entire collection. The site recommends not using a distro packaged version, but rather running their own installer, which runs arbitrary commands in a root shell and won't let you have anything but the newest and shiniest version. It's not bad if you want a GUI, but if anything doesn't work (like auto-detecting the device it's connected to to run the appropriate plugin for talking to it, which was the case for me) you're on your own.

But that's OK. ePUB is an open standard, if an unreasonably flexible one, and I can dig in to tweak the dc:creator and dc:title tags as needed. So far so good.

It turns out that the ePUB standard doesn't include any way to denote series membership. It runs off the Dublin Core metadata system, which is similarly lacking. The only thing that comes close to being a standard for this is in fact calibre, which uses e.g.:

<meta name="calibre:series" content="The Lord of the Rhngs">
<meta name="calibre:series_index" content="1"/>

Unsurprisingly, if you load an ePUB onto a Kobo, with these tags or not, it won't be recognised as part of a series. If you buy from the Kobo Store, it will be, but really, who'd want to do that?

So off to the Kobo itself, and the place to find this stuff is all in /.kobo/KoboReader.sqlite, which is indeed an SQLite3 database. Hurrah! And it turns out that the important bits for our purposes are all in the content table.

Now, this gets a bit fiddly, because when the Kobo loads an ePUB file, every text file within it also gets read, and all of them have entries in the table. Those internal files have ContentType 9, while the reference to the overall book has ContentType 6.

Also there are a bunch of entries (mostly titles and blurbs) which are for things one can buy in the Kobo Store. I suspect it would do no harm to delete them, but I don't want to do it accidentally. Those are distinguished because their ContentID is a hex-and-hyphen string rather than a filename; the ones I want will look something like

file:///mnt/onboard/Blandings Castle and Elsewhere - P. G. Wodehouse.epub

(The sub-files start similarly but go on with a # and individual filename.)

The fields that need to be set in that database entry are:

• Series - the human-readable series name.
• SeriesID - a unique identifier for the series. Can be the series name, if that is unique.
• SeriesNumber - a string value for the series position (e.g. "1").
• SeriesNumberFloat - a floating-point value ditto, presumably used for sorting.

Set all of these and disconnect, and the Kobo will display the book as part of a series.

Then it's just a matter of linking it all together, interrogating the Calibre series tags in the ePUB file to get hold of the series membership information… and this is what I've now done. One program lets you tweak series information (and also author and title, because sometimes that's done oddly) in ePUB files; the other connects to a Kobo, looks as the ePUB files on it and the database, and pokes the database to include any relevant series information.

Tools on GitHub