DOCSEARCHbyAlgolia
Submit Docs

kepubify

repository·master·Indexed 21 days ago

https://github.com/pgaskin/kepubify

A high-performance tool for converting EPUB files into Kobo-compatible KEPUB files. It includes the core kepubify conversion engine, covergen for pre-generating optimized cover images, and seriesmeta for updating Kobo database series metadata using Calibre or EPUB3 standards. Available as a standalone CLI, library, or web application.

Tokens
3.2K
Snippets
12
Records
16
Agent score
75%

What's inside kepubify

  1. Overview of kepubify and included utilities

    master

    Kepubify is a high-performance tool designed to convert EPUBs to Kobo EPUBs (KEPUBs). It is designed to be safe with untrusted books and handles malformed HTML/XHTML efficiently.

    Included Utilities

    • kepubify: The core conversion engine.
    • covergen: Pre-generates cover images to improve library browsing speed and quality on Kobo eReaders.
    • seriesmeta: Scans for books and updates Kobo series metadata using Calibre or EPUB3 standards.

  2. Build kepubify from source

    master

    To build kepubify from source, clone the repository and use the go build command targeting the kepubify command directory.

    Performance Optimizations

    • Go 1.17+: Optimizations are applied automatically to prevent re-compressing unchanged files.
    • Go 1.16: To use the performance optimizations (backported from Go 1.17) on Go 1.16, you must include the -tags zip117 flag during installation or building.
    # Standard build
go build ./cmd/kepubify

# Build with performance optimizations for Go 1.16
go install github.com/pgaskin/kepubify@latest -tags zip117

  3. Build seriesmeta from source

    master

    The seriesmeta utility scans for EPUBs and KEPUBs and updates the Kobo database with Calibre or EPUB3 series metadata.

    To build seriesmeta from source, you must have a C compiler installed and CGO enabled.

  4. Install kepubify

    master

    You can install the kepubify standalone utility directly using Go. This requires Go 1.16 or later.

    Alternatively, you can download pre-built binaries for Windows, Linux, and macOS from the official releases page or the download site.

    go install github.com/pgaskin/kepubify@latest

  5. Use the covergen CLI to pre-generate book covers

    master

    The covergen command scans a Kobo eReader for EPUB/KEPUB books and pre-generates optimized cover images for them. It automatically detects connected Kobo devices, but you can specify a path to a specific Kobo reader. The tool extracts covers from the EPUB files, applies resizing, aspect ratio stretching, grayscale conversion, or color inversion based on your flags, and saves the resulting images to the device.

    covergen [options] [kobo_path]

  6. Use the kepubify CLI to convert EPUBs

    master

    The kepubify command is a standalone tool for converting standard EPUB files into Kobo-optimized EPUBs (KEPUBs). You can provide one or multiple input paths (files or directories) as arguments. By default, converted files will have the .kepub.epub extension.

    kepubify [options] input_path [input_path]...

  7. Configure path transformation behavior

    master

    The transformer struct controls how input file paths are mapped to output file paths during the conversion process. You can configure suffix matching, directory preservation, and update logic using the following fields:

    • NoPreserveDirs: If true, the directory structure of the input is flattened, and only the base filename is used for the target.
    • Inplace: If true, files are processed within their existing directory structure rather than being moved to a new output location.
    • Update: If true, the transformer will skip files that already exist at the target output path.
    • Suffixes: A list of file extensions (case-insensitive) that should be replaced by the TargetSuffix.
    • ExcludeSuffixes: A list of file extensions that should be ignored during the scan.
    • PreserveSuffixes: A list of file extensions that should be kept as-is in the output. These are only included if they differ from the original filename.
    • TargetSuffix: The new extension to be applied to files matched by Suffixes.

  8. Use find-and-replace during conversion

    master

    You can perform string replacements across all HTML files in the EPUB using the --replace flag. The format must be find|replace. You can provide this flag multiple times to perform multiple different replacements.

    kepubify --replace "old_text|new_text" --replace "foo|bar" input.epub

  10. Transform input paths to output paths

    master

    The TransformPaths method calculates the mapping between input files and their intended output destinations based on the transformer configuration.

    Signature: func (t transformer) TransformPaths(output string, inputs ...string) (map[string]string, []string, error)

    Parameters:

    • output: The destination directory or filename. If empty, the output path is not specified by the user. If a single input is provided and output is a directory, files are placed inside it.
    • inputs: One or more paths to files or directories to be processed.

    Returns:

    • map[string]string: A mapping where the key is the original input file path and the value is the calculated target output path.
    • []string: A list of input files that were skipped because their target output file already exists (only when Update is set to true).
    • error: An error if path resolution fails, suffixes overlap, or if multiple inputs result in the same output file (overlapping output).

  11. Configure kepubify conversion options

    master

    Customize the ebook content during the conversion process using these flags:

    --smarten-punctuation	Smarten punctuation (smart quotes, dashes, etc) (excluding pre and code tags)
--css, -c	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
--add-dummy-titlepage	Force-enables the dummy titlepage to fix layout issues with the first content file on certain books (this is enabled when needed using a heuristic if not specified)
--no-add-dummy-titlepage	Force-disables the dummy titlepage
--replace, -r	Find and replace on all html files (repeat any number of times) (format: find|replace)
--charset	Override the HTML charset (use "auto" to detect it from the content)

  12. Reference the covergen CLI options

    master

    The covergen command supports the following flags to customize cover generation:

    • -r, --regenerate: Re-generate all covers, even if they already exist.
    • -m, --method <algorithm>: Resize algorithm to use. Options: bilinear, bicubic, lanczos2, lanczos3 (default: lanczos3).
    • -a, --aspect-ratio <float>: Stretch the covers to fit a specific aspect ratio (e.g., 1.3, 1.5, 1.6).
    • -g, --grayscale: Convert images to grayscale.
    • -i, --invert: Invert images.
    • -h, --help: Show this help message.
    Options:
  -r, --regenerate
        Re-generate all covers
  -m, --method string
        Resize algorithm to use (bilinear, bicubic, lanczos2, lanczos3) (default "lanczos3")
  -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
  -i, --invert
        Invert images
  -h, --help
        Show this help message

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