[Feature Request] Native Support for kepub files in library

[Blendman974]

What problem or limitation are you encountering?
Booklore recently added support for Kobo sync, which works great. Kobo devices use their own .kepub format that extends .epub with extra functionalities (progress tracking, panels, etc.).
Currently, Booklore converts .epub files to .kepub on download (via PR #969).
The limitation is that .kepub files already present in the library are not recognized as valid book files. As a result:

• .kepub files don’t show up in the library.
• There are valid cases for storing books as .kepub in the library (e.g., comics/manga converted with KCC). Currently, these cannot be sent directly to Kobo and are re-converted instead, which can break the intended formatting (as with KCC outputs).

What solution or improvement do you propose?
Allow Booklore to natively treat .kepub files as valid book files in the library:

• If a .kepub exists in the library, serve it directly to Kobo without conversion.
• If only an .epub exists (or other convertible format like .cbz), convert it to .kepub on download if configured to do so (current behavior only for .epub files).

These changes would integrate well with the upcoming PR #868, which adds support for multiple file formats per book.

Have you found any workarounds or alternatives?
Special .kepub has to be transferred manually to the e-reader

[acx10]

Yup, this is next on my list. I’m planning to add proper support for parsing and displaying .kepub files in Booklore so they’re treated as first-class book files, just like .epub and .cbz. That way, if a .kepub already exists in the library (e.g. from KCC or other tools), Booklore will recognize it and serve it directly to Kobo without re-conversion. The current conversion-on-download flow for .epub → .kepub will stay as-is, so both cases will work smoothly. This should tie in nicely with the upcoming multiple file format support and remove the need to manually manage .kepub files outside Booklore.

[acx10]

@Blendman974 I did some research on .kepub files and found that they are essentially standard EPUB files with some extra Kobo-specific tags, and they are often named like bookname.kepub.epub. Booklore already picks up these files without issues. Based on this, I don’t think additional changes for native .kepub support are necessary at the moment.

[Blendman974]

There are still issues with .kepub.epub files in Booklore:

• On import via the web UI, kepubs lose their cover with an error (logs in gist).
• Uploading via the web UI strips the .kepub.epub extension and stores them as plain .epub losing the format information.
• In libraries containing kepub, if the option to convert to kepub on download is enabled, download on kobo will fail because of kepubify that errors on files already in kepub.epub format.

Because of these issues, .kepub files don’t quite behave the same as regular .epub right now. It would help if Booklore preserved the .kepub.epub extension on upload and simply skipped conversion when the file is already in kepub format.

[GianniBYoung]

fwiw I have found that storing books natively as epub is the best for compatibility/usability. My main device is a kobo libra colour and I tried converting and storing my epubs as kepubs using calibre web automated and ran into a lot of the issues mentioned above.

Since kepubs are just extra kobo specific features on top of the epub spec converting on demand via kepubify has been the least problematic in my experience.

[Blendman974]

It looks like the cover rendering issue is actually related to how kepubify generates its ZIP files (some ZIP implementations fail to open them, the Java library used seems to be unable to properly parse them).

You can "fix" the kepub file by using the zip command:

zip -FF original.kepub.epub --out fixed.kepub.epub

After this, importing the fixed file on Booklore works fine (the cover displays properly, and there’s no exception in the logs).

Since kepubify hasn’t been maintained for ~3 years, it might be wise to consider reimplementing or replacing its functionality directly in Booklore, rather than relying on a tool that’s effectively abandoned.

On the other hand, .kepub.epub files generated by KCC are properly formed and can be imported without issues.

Moreover, if they are renamed as .epub inside the Booklore library, they don’t seem to have issues being re-converted with kepubify (from what I’ve tested, the resulting files work fine on the reader and preserve the formatting as intended by KCC).

So the best current workaround is to store KCC-generated files as .epub in Booklore and let kepubify handle them a second time on download.

[SirBisgaard]

I did not want to create a new issue, so I am just adding to this one.

It would be fantastic if Booklore could convert ePubs to KEPUBs when sending them to a Kobo device, supporting that file format and syncing only that format to the Kobo.

Support for KEPUB will unlock many on‑device features such as highlighting, notes, and pen‑selection features. These annotations would sync to our Kobo account (storing them ourselves could be nice, but that is out of scope).

The last thing missing is syncing collections, which is not implemented in Booklore because it is not a shelf per se or a magic shelf (perhaps I’m interpreting the name as a real‑world concept).

[foinse]

Booklore already does have the ability to convert epub to KEPUB when using Kobo Sync.

[SirBisgaard]

ability to convert epub to KEPUB

How can I turn it on because it does not seem to work with the default configuration.
Because I am not able to take any note or highlight any of my synced books.

Do you know how or is it working for you @foinse?

Edit:
Found it. 🤦‍♂️