knyga — relink PocketBook notes after editing EPUB metadata

[foresle]

Hi all,

I wrote a small CLI tool to scratch a long-standing itch with PocketBook readers and figured it might be useful to others here.

The problem

PocketBook identifies books in its on-device library by the MD5 hash of the whole EPUB file, not by ISBN or any stable identifier embedded in the OPF. The moment you touch metadata — fix a typo in the author field, replace the cover, normalize the title — the file hash changes. The device then treats the file as a brand-new book, and every highlight, bookmark and note you made silently becomes an orphan. The annotations are still in the device databases, they just point at a hash that no longer matches anything on disk.

The fix

knyga rewrites the old hash to the new hash inside PocketBook's databases so the existing annotations reattach to the re-tagged file. No re-reading, no manually re-creating highlights.

The intended workflow is:

1. Connect the PocketBook over USB.
2. Copy the EPUB off the device to your computer — this is the "old" file, the one whose hash the device already knows and has notes against.
3. Make a duplicate of it and edit the metadata in the duplicate. This is the "new" file.
4. Run "knyga", passing both files (old + new) as arguments. The tool hashes both, backs up the relevant device databases, and replaces the old hash with the new one wherever it appears.
5. Copy the edited file onto the device. The existing notes are now linked to it.

Demo / links

- Source and README: https://crates.io/crates/knyga
- Short walkthrough video: https://peertube.in.ua/w/81NSTkvzFCJAEay9zpDGPd

Caveats

- Tested on my own device (Pocket Book 628) and library

Feel free to ask if anything is unclear, and any feedback or bug reports are very welcome.

[nhedgehog]

Nice one, only had a look at that video and it seems very helpful. Will not test it though since my books are on a win10 machine and I don't use annotations very often and KoReader is the standard reader I'm using.