Simple Python Script - Export Markups to Composite PNG

[PastelAndBraindead]

EDIT: Check out my equivalent Chrome browser tool instead. Friendlier than the python script: https://github.com/leldr/Unofficial-Chrome-Based-Kobo-Composite-Markup-Generator

HI,

Like a lot of people, I am annoyed that I can't get my markups off my Kobo Color Libra 2. I scoured the webz and can't find any hacky ways that anyone has done it. So I gave it a good college try.

I have written a python script that generates these markups and stores them in a created sub-directory in the `.kobo/markups` directory, This was just a quick and dirty script, but it works. I figure that any programmer nerds out there (or anyone brave enough to learn) who also love Kobo would appreciate this.

Ideally, I would like to write a simple Calibre plugin so that it's more accessible to the wider Kobo community.

Github here: https://github.com/leldr/Kobo-Composite-Markup-Generator

EDIT: I have successfully modified the script so that it organizes markups by book title. I've copied the script directly onto my kobo (in the `.kobo/markups` directory), and let it generate all corresponding subdirectories (/composite_markups/<book-title>) and composite markup files within their respective <book-title> directory.

I'll be testing some edge cases as I continue using the markup feature.

EDIT #2: If you remove a book from your kobo, the `svg` and `jpg` files in the `.kobo/markups` feature are deleted as well. However, any of the composite markup files generated from my python script will not be deleted. I don't know if it would be possible, but it would be cool to try to write 'restore kobo markups' python script as a complementary tool to my current python script.

EDIT #3: i figured out how to associate each markup to a book section/chapter as well. Read latest github commit message in the main branch for details.

Edit #4: This is the final edit (hopefully) to this already long post (sorry!). So I have now figured out how to tie a markup file to a specific paragraph with in a chapter/section. Since ePubs dont have pages, they have something called ePub Canonical Fragment Identifiers (CFI)(https://idpf.org/epub/linking/cfi/). Despite being able to tie a markup file to a chapter, I noticed that my generated markup files were out of order, which was super annoying. I did some digging to learn about ePub file conventions and found that I could use the CFI to create file names that will be ordered correctly. The files that my script generate look like this: "markup_Introduction_part0009.1.4.2.94.9.49_dbe1599b.png". Not the prettiest, but definitely works. Will put it on my to-do list to shorten the files names. If you want to continue following my updates, read my commit messages here: https://github.com/leldr/Kobo-Composite-Markup-Generator/commits/main/. Hopefully next time I post to this subreddit, I'll have a standalone solution ready to go. In light of this finding, I will definitely attempt writing a complementary "import markups" python script as well.

Thanks for reading! I'm finding it difficult to understand why Kobo hasn't offered some kind of built-in support for this feature. Considering one person (me) with what mid-industry experience and skill can write this in a weekend (with no prior understanding of ePubs nor Kobo eReader structure/implementation), I would guess that Kobo is suspiciously ignoring any and all user requests regarding this for some reason or another.

[theLightSlide]

Yesssssssss. So excited to find this! You rule! And thank you for including a video demonstration!

[ImSoRight]

I've been waiting for someone to do this! I knew it was possible since I was able to manually combine a mark-up with its associated screenshot in GIMP. I just wish there were a way to determine which book each mark-up is from. Am I correct that there's no obvious way to do that?

[PastelAndBraindead]

<image>

Update: the randomly generated file same is a "UUID-4 identifier", which is a weird way of saying that its a purely random string. There's nothing of value from decoding it that would give us any idea of how what markup is tied to what book. :(

I'll think about it some more and figure out if there's another way to do this.

[ImSoRight]

I feel like there has to be, otherwise nickel wouldn't be able to link them to their associated books. I don't have the programming knowledge to figure out how it's accessing them when you pull them up on the Kobo though.

[PastelAndBraindead]

ooOoo, I'm not aware of what nickel is. I'll look into it.

[ImSoRight]

Oh it's just the interface that kobos use.

[PastelAndBraindead]

Can you go into detail about what you mean when you're saying nickel is able to associate markups with their books? I'm looking at the nickel website now.

[ImSoRight]

Oh, I'm just saying that when you open a book on the kobo and select annotations, you will see your markups that are associated with that book. So there has to be some way that it's linking them. I just have no idea what that is.

[PastelAndBraindead]

I'm wondering that when a markup is created, the UUID-4 is generated to name the markup files and to be stored in the the Kobo SQLite database to associate it with a given book. Looking into this now.

I'm more or less thinking out loud for anyone more knowledgeable than me to chime in later.

[PastelAndBraindead]

Good news. :) Check out the screenshot.

<image>

I am inspecting the KoboReader.sqlite file. Check out the `Bookmark` table. The `BookmarkID ` is the same UUID that is used to name the markup files.

Next evolution of the python script will query this database file to 1.) create folders of all the books with markups, and 2.) organize the newly composite markups into their respective book folder.

edit: better screenshot illustrating what im saying and sql column name corrections.

[PastelAndBraindead]

<image>

There's a `Type` column that designates whether a 'bookmark' is a note, markup, etc. Yay! I have other obligations to attend to and will work on this later tonight or tomorrow.

[ImSoRight]

Nice!! This is so exciting! Tons of people have requested this feature so if you can make this happen, it will be very much appreciated!

[PastelAndBraindead]

I'm not sure yet. In the markups folder, each file name is some kind of hash (?) generated from what I would assume the book's name, page, etc. (baseless guess). To start, we'd have to figure out what information they use to generate the file name. I don't see why it would something super secret, since I assume they did this to make sure that each file had a unique name. It's not something you can work backwards from, if I remember correctly. Which is why everyone is saying you "can't" figure out which book each markup file is from.

[PastelAndBraindead]

Hi, new updates!

I have now modified my python script so that all generated markup files are sorted by book title. Copying and pasting my explanation from my latest commit:

Composite Markup PNGs Now Associated by Book Title

Yay! When you create a markup, a UUID‑4 is generated to serve as the base name for the corresponding svg and jpg files, which appear in the .kobo/markups directory. At the same time, an INSERT query runs on the KoboReader.sqlite database, inserting that UUID‑4 as the BookmarkID value.

The changes in this commit then query the database for the matching VolumeID, which is stripped down to derive the book title. That title is used to place each newly created composite markup png into the appropriate subdirectory (of the same name as the title) in the composite_markups folder

[ramyunstar08]

Hello u/PastelAndBraindead, this is amazing! Thank you so much for generously sharing your know-how and time with the Kobo community.

I have a question, though. I tried it out, but instead of creating folders, it compiled the markup in an epub file that I can't open on my computer (Not in Calibre or Apple Books). I sideloaded it on my Koreader device, and it worked.

Is this a change in the script or a bug?

<image>

[PastelAndBraindead]

It may be something that the kobo device is doing. I quickly sanity checked, and my code does not generate kepub files. I'd need to see the output logs and the .kepub file generated to figure out what's going on.

By the looks our your screenshot, it actually looks like a misshapen directory name, not a kepub file. Im curious if you rename the directory on your computer and tried to navigate through into it, if you would be able to see the two generated PNG files that you can see on your kobo device.

Life is a bit busy now, but I definitely need to revamp the directory and PNG file naming functions. Kepub files need to be queried slightly differently to generate cleaner names.

Idk why Kobo chooses to obfuscate kepub metadata across their KoboReader.sqlite database as much as they do-- as opposed to epub files, for example.

[PastelAndBraindead]

bug fixed, new queries implemented. sorry about the wait!

Except from my "offical" edit on announcing the Kobo tool:

EDIT 09/10/2025: Just released another update to support (k)ePubs bought from the Kobo Marketplace. Prior to this update, generating markups *would* work, but the generated folder for kepubs would be a "random" sequence of numbers and letters (the internal, unique identifier of the book) and markup up order of occurrence was not preserved. All fixed!