kepubify v3: A fast, standalone EPUB to KEPUB converter (plus covergen/seriesmeta)

[geek1011]

kepubify (v3)
Kepubify converts EPUBs to KEPUBs. Kepubify also includes two standalone utilities: covergen (which pre-generates cover images), and seriesmeta (which updates the database with Calibre or EPUB3 series metadata).
___



Features:

• Batch conversion
• Standalone and cross platform
• Works from the command line or by dragging and dropping on Windows
• Fast (15x faster than converting in Calibre)
• Add custom CSS
• Smarten punctuation
• Can optionally pre-convert books for use in Calibre
• Complete control over output structure (see here for detailed examples)
• Almost identical output compared to original Kobo KEPUBs
• Standalone tool to pre-generate cover images (including aspect ratio changes, grayscale, and color inversion) (you can use this without kepubify)
• Standalone tool to update the database with Calibre or EPUB3 series metadata (you can use this without kepubify)

Usage (Windows) (drag and drop):

1. Download kepubify from the releases page.
2. Drag your EPUB files on to the EXE you downloaded in Windows Explorer to convert them.
3. Optionally, to use covergen or seriesmeta, download the binary and run it.

Usage (Windows):

1. Download kepubify from the releases page.
2. Open a Command Prompt window in the folder you downloaded the EXE into.
3. Type "kepubify" and press enter to see the available options.

Usage (Linux/macOS):

1. Download kepubify from the releases page.
2. Open a terminal window in the folder you downloaded, and run "chmod +x kepubify-*". If you're on macOS, you can also type "chmod +x ", drag kepubify-darwin-64bit on to the terminal, and press enter.
3. Type "./kepubify" (or drag and drop kepubify-darwin-64bit), and press enter to see the available options. If you're on macOS, you may need to allow kepubify through GateKeeper under System Preferences > Security.

Full usage info:

Usage: kepubify [options] input_path [input_path]...

Version:
  kepubify v3.1.0

General Options:
  -v, --verbose   Show extra information in output
      --version   Show the version
  -h, --help      Show this help text

Output Options:
  -u, --update             Don't reconvert files which have already been converted (i.e. don't overwrite output files)
  -i, --inplace            Don't add the _converted suffix to converted files and directories
      --no-preserve-dirs   Flatten the directory structure of the input (an error will be shown if there are conflicts)
  -o, --output string      [>1 inputs || 1 file input with existing dir output]: Directory to place converted files/dirs under; [1 file input with
                           nonexistent output]: Output filename; [1 dir input]: Output directory for contents of input (default: current directory)
      --calibre            Use .kepub instead of .kepub.epub as the output extension (for Calibre compatibility, only use if you know what you are doing)
  -x, --copy strings       Copy files with the specified extension (with a leading period) to the output unchanged (no effect if the filename ends up the same)

Conversion Options:
      --smarten-punctuation        Smarten punctuation (smart quotes, dashes, etc) (excluding pre and code tags)
  -c, --css stringArray            Custom CSS to add to ebook
      --hyphenate                  Force enable hyphenation
      --no-hyphenate               Force disable hyphenation
      --fullscreen-reading-fixes   Enable fullscreen reading bugfixes based on https://www.mobileread.com/forums/showpost.php?p=3113460&postcount=16
  -r, --replace stringArray        Find and replace on all html files (repeat any number of times) (format: find|replace)

Seriesmeta:

Spoiler:

Usage: seriesmeta [options] [kobo_path]

Version:
  seriesmeta v3.1.0

Options:
  -h, --help         Show this help message
  -p, --no-persist   Don't ensure metadata is always set (this will cause series metadata to be lost if opening a book after an import but before a reboot)
  -n, --no-replace   Don't replace existing series metadata (you probably don't want this option)
  -u, --uninstall    Uninstall seriesmeta table and hooks (imported series metadata will be left untouched)

Arguments:
  kobo_path is the path to the Kobo eReader. If not specified, seriesmeta will try to automatically detect the Kobo.

Covergen:

Spoiler:

Usage: covergen [options] [kobo_path]

Version:
  covergen v3.1.0

Options:
  -a, --aspect-ratio float   Stretch the covers to fit a specific aspect ratio (for example 1.3, 1.5, 1.6)
  -g, --grayscale            Convert images to grayscale
  -h, --help                 Show this help message
  -i, --invert               Invert images
  -m, --method string        Resize algorithm to use (bilinear, bicubic, lanczos2, lanczos3) (default "lanczos3")
  -r, --regenerate           Re-generate all covers

Arguments:
  kobo_path is the path to the Kobo eReader. If not specified, covergen will try to automatically detect the Kobo.

What features do KEPUBs offer?

• Faster page turning
• Book progress panel and chapter graph
• Pop-up footnotes (on books which support it)
• Double-tap to zoom images
• Faster text selection
• A few other features

Download | Website

[geek1011]

What's new in Kepubify v3?
Kepubify v3 is the next major release of kepubify.

New features:
- Kepubify now gives you much more control over the output location and naming. See the help text (if you want, there are more detailed examples here).
- Covergen now supports grayscale and color inversion.

Improvements:
- Kepubify now converts books 15-30% faster and uses 50-70% less memory (Update: As of v3.1.1, it's now 40-70% faster than that for batch conversions, making it at least twice as fast as v2.x, and almost 30x faster than Calibre overall).
- Kepubify now has a 50% smaller binary.
- Smartening punctuation is now more robust and supports more punctuation.
- Seriesmeta and covergen are now built for ARM and 32-bit Linux.
- The help text for kepubify is now split into sections.
- There are now comprehensive unit tests for Kepubify, especially around the span adding.
- Kepubify is now automatically tested on Windows and macOS in addition to Linux.
- Kepubify now processes files in a deterministic order (i.e. the files are listed in alphabetic order during conversion).
- You can now add more than one additional stylesheet from the command line.

Breaking changes:
- Smartening punctuation has been disabled by default.
- Span adding has been refactored and improved to better match Kobo. This means that the numbering of spans may be different if you reconvert a book.
- Optional stylesheet inlining has been removed.
- The API for the kepub package has been redesigned. See the godoc for more information.

Bugfixes:
- Kepubify now works better on books with deeply nested structures.
- Race conditions in the parallel processing code have been eliminated.
- The bugfixes for #36, #29, #28, #26, #21, #14, #10, #5, and #2 have been improved.
- The HTML parser now deals with XML declarations and self-closing tags in a better way.
- Adding spans doesn't swallow whitespace under certain conditions anymore.

See the commit log for more detailed information.

[geek1011]

Changelogs

v3.1.6:

Spoiler:

802f8df all: Updated dependencies
b860308 all: Updated Go to 1.14.10
ce139fd cmd/seriesmeta: Added note about my NickelSeries mod
47a7200 kepub: Fixed hyphenation CSS
f89126d all: Use Go 1.14.7 for release builds

v3.1.5:

Spoiler:

874c34d kepub: Also skip svg and math tags when adding spans

v3.1.4:

Spoiler:

ea356a3 all: Updated GitHub username
da5ac4f Updated AppVeyor URL

v3.1.3:

Spoiler:

0b73d39 Changed default Windows binary to 64-bit
888158c cmd/seriesmeta: Switched from zglob to filepath.Walk (#49)
00da6b2 cmd/covergen: Switched from zglob to filepath.Walk (closes #49)
1190d03 Added arm64 builds (closes #51)

v3.1.2:

Spoiler:

2196def kepub: Fixed FD leak in content transformation

v3.1.1:

Spoiler:

c6b1733 cmd/*: Added godoc comments for commands
b5a2f26 all: Reorganized commands into cmd/* dir, simplified build script
35fe4c4 docs: Updated supported platforms for seriesmeta
cbb9af0 kepubify: Made book processing concurrent
754582f all: Updated dependencies
53941ba all: Updated Go to 1.14
840d343 kepub: Fixed double-escaping of entities during punctuation smartening

v3.1.0:

Spoiler:

cd976a0 seriesmeta: Added support for updating SeriesID (fixes #48)
cd2ae60 Fixed errors list
b83515a Added option for copying other filetypes as-is to output directory

v3.0.0:

Spoiler:

8883b94 Updated godoc link in README
6be3e40 Fixed debian package build
c5c8432 Improved build scripts
c997674 Added Converter tests, implemented (*Converter).Convert
fefa22c Added EPUB tests
201ab03 Improved some kepub span stuff
48ee277 Updated kobotest script
0f40d7a Fixed span logic for images
ecc488f Added tool for testing span logic
54cdf6a Improved path transformation logic for a single file with a nonexistent dir output
3b3da2c Updated span logic for when to wrap whitespace
f3746e8 Fixed release notes changelog generation
889fe54 Fixed number alignment for kepubify progress info
f3e412c Run tests on macOS
8b0eda5 Prevent GitHub Pages from triggering builds incorrectly
a557365 Updated documentation
beb1969 seriesmeta: Made CLI consistent with kepubify
1f96e85 covergen: Made CLI consistent with kepubify
deb20af Updated go.sum
e9edcac covergen: Added grayscale and invert options
e80f0bc covergen: Sort file list
ba287b1 Improved path transformation logic for inplace without an explicit output dir
1268ee6 Fixed book counts in status messages
3bd6432 Fixed path transformation in kepubify command
4caf608 Updated README badges
bb3c13f Merge branch 'refactor-kepubify-command' (#34)
451ec01 Merge branch 'refactor-kepub-processing' (#34)
af91c60 Switch to v3 go.mod (#34)
0c40cc7 Rewrote kepubify command (#34)
1282954 Completely rewrote kepub code

[geek1011]

Examples / FAQ
Coming soon. See here for examples of input/output options for now.

[ilovejedd]

Awesome. Thanks!

Just a question though, the font size for kepub is much, much, much smaller compared to epub on my Libra H2O so if I read books in different formats, I need to adjust the font size.

I saw this post which I believe refers to the Kobo Touch Extended driver. What's the syntax to do something similar using kepubify's --css option? Thanks!

Originally Posted by jackie_w

Are you already using the 'Modify CSS' option in the calibre driver with a kobo_extra.css file on your H2O? If so, I found the easiest way to apply the font-size change is by adding an extra line to the kobo_extra.css file so it automatically gets added on-the-fly during send-to-device:

body>div#book-columns>div#book-inner {font-size:1.5em}

This works well on my H2O (and GloHD) and I don't need to keep changing the slider when I switch between epub and kepub. Surprisingly the KA1 'just works' without needing to do any kind of font-size adjustment.

[geek1011]

Originally Posted by ilovejedd

Awesome. Thanks!

Just a question though, the font size for kepub is much, much, much smaller compared to epub on my Libra H2O so if I read books in different formats, I need to adjust the font size.

I saw this post which I believe refers to the Kobo Touch Extended driver. What's the syntax to do something similar using kepubify's --css option? Thanks!

I'd suggest '--css "body>div#book-columns>div#book-inner {font-size:1.5em}"'.

[stumped]

getting this through various protections ( win 10) is a hassle
first, chrome warns don't download it
then windows warns don't run the installer
then it fails anyway because panda Av has helpfully quarantined a component...
would it be better packaged as an .msi ?
( I am trying to use the win 64 exe , from the 21 download options, as that seemed the best choice ? )

[jackie_w]

Originally Posted by ilovejedd

Just a question though, the font size for kepub is much, much, much smaller compared to epub on my Libra H2O so if I read books in different formats, I need to adjust the font size.

FYI. Since I made that post you quoted, there is now another option you could use.

I don't know whether you're a kobopatch user but, if so, there's a patch available which will equalise the font-sizes in epub and kepub at the device level without needing to adjust font-size in each individual kepub. It's the one named 'ePub uniform font scale' in libnickel.so.1.0.0.yaml.

Not all Kobo models have the epub/kepub font-size mismatch (e.g. KA1, Forma don't have it). If you only have one Kobo device it doesn't really matter which option you choose, but for users with multiple Kobo models kobopatch is the more flexible option because you could use the same saved kepubs on all devices.

[JSWolf]

Originally Posted by geek1011

[*]Fast (15x faster than converting in Calibre)

Does this mean 15x faster then the KoboTouchExtended driver or 15x faster then a conversion using the KePub Output plugin?

[JSWolf]

Originally Posted by ilovejedd

Awesome. Thanks!

Just a question though, the font size for kepub is much, much, much smaller compared to epub on my Libra H2O so if I read books in different formats, I need to adjust the font size.

I saw this post which I believe refers to the Kobo Touch Extended driver. What's the syntax to do something similar using kepubify's --css option? Thanks!

There area couple of patches to make the font sizes for ePub and KePub match. They do work well.

[JSWolf]

Originally Posted by stumped

getting this through various protections ( win 10) is a hassle
first, chrome warns don't download it
then windows warns don't run the installer
then it fails anyway because panda Av has helpfully quarantined a component...
would it be better packaged as an .msi ?
( I am trying to use the win 64 exe , from the 21 download options, as that seemed the best choice ? )

Couple of fixes. Dump Chrome for Firefox. Then dump Panda AV (crap) and go with Windows Security.

So there you go for some fixes to fix most of your trouble.

[stumped]

Originally Posted by JSWolf

Couple of fixes. Dump Chrome for Firefox. Then dump Panda AV (crap) and go with Windows Security.

So there you go for some fixes to fix most of your trouble.

have you actually checked if firefox warns of it being unsafe ?

also, its windows security ( the smart somethign or other ) that says "don't run it "

maybe there's nothing a small indie developer can do to avoid suspicion ?

[geek1011]

Originally Posted by stumped

have you actually checked if firefox warns of it being unsafe ?

also, its windows security ( the smart somethign or other ) that says "don't run it "

maybe there's nothing a small indie developer can do to avoid suspicion ?

You wouldn't be having issues with virus scanners: https://www.virustotal.com/gui/file/...74fe/detection . The issues you're having are due to the code being unsigned, as I don't currently own a code signing certificate for Windows (those cost a fair bit of money, and I don't even use Windows much myself).

[geek1011]

Originally Posted by JSWolf

Does this mean 15x faster then the KoboTouchExtended driver or 15x faster then a conversion using the KePub Output plugin?

15x faster than a full conversion. I haven't tested, but it's probably ~2x as fast as directly sending, assuming it's transfer-bound.

[stumped]

Originally Posted by geek1011

You wouldn't be having issues with virus scanners: https://www.virustotal.com/gui/file/...74fe/detection . The issues you're having are due to the code being unsigned, as I don't currently own a code signing certificate for Windows (those cost a fair bit of money, and I don't even use Windows much myself).

panda av ( not on that virustotal page) reported it as suspicious but maybe only because it did not recognize the name
my "removed from quarantine" entry says
kepubify-windows-64bit (unknown name)

malwarebytes pro did not flag it

i guessed it might be an unsigned code issue- calibre still has the same problem sometimes.

its not a problem so long as windows don't make it any harder to run unsigned code
& I think chrome disapproves on principle of anyone downloading anything.exe