mangapress

mangapress resizes and optimizes a manga/comic .cbz for e-ink reading, generating a fixed-layout EPUB (or CBZ/PDF) tuned to a target device's screen resolution and grayscale palette. It is an independent, CLI-first reimplementation in Rust of what KCC (Kindle Comic Converter)'s conversion pipeline does, distributed as a single static binary.

Raw chapters (folder or .cbz per chapter)
    -> Mangabind (groups chapters into per-volume .cbz)
    -> mangapress (crops/resizes/optimizes for e-ink, writes EPUB/CBZ/PDF)
    -> KOReader / Kindle / Kobo / reMarkable

The problem

KCC already solves the image-processing side well — cropping, resizing, contrast correction, double-page-spread splitting, all tuned per device. What it doesn't solve is how it's shipped: its CLI mode (kcc-c2e.py) is packaged as a single install_requires list with no CLI-only split, so even headless/CLI use pulls in a full PySide6/Qt install. That's a real, reproducible packaging gap (see docs/adr/0002-pip-workaround-tested-and-rejected.md) — workable with a venv that skips PySide6, but still a Python runtime plus its dependency tree to install and keep working across OS/distro updates. It also has no automated test suite validating that any of its image-processing math still behaves the same after a change.

mangapress reimplements that pipeline in Rust: a single static binary with no interpreter or Qt runtime to install, and every algorithm — cropping, resizing, contrast, spread detection, rainbow- artifact removal — covered by an automated test suite, validated against a real Mangabind-produced volume and cross-checked against KCC's own output. See docs/adr/0007-gplv3-boundary-kcc-image-rs.md for how upstream KCC is used as a specification to reimplement independently, not code that gets copied.

Out of scope: MOBI/AZW3 output. mangapress's target reader is KOReader, not a Kindle's native firmware, and KOReader already reads fixed-layout EPUB well — see docs/adr/0008-mobi-azw3-permanently-out-of-scope.md. mangapress also doesn't download or organize chapters — that's Mangabind's job; mangapress only ever reads a finished .cbz/folder and writes a converted book.

Color output is opt-in. By default every page comes out grayscale, as upstream's does; --forcecolor keeps color pages (and the cover) in color, on any profile, while pages with no real color are still converted. Unlike upstream's window, the command line does not turn it on by itself for a color-capable profile (KCS Kindle Colorsoft, KoCC Kobo Clara Colour, KoLC Kobo Libra Colour): pass the flag. --eraserainbow (below) is a separate thing — it fixes a display artifact of color e-ink screens, on grayscale and color pages alike.

Status

Functional: device profiles for ~40 Kindle/Kobo/reMarkable/generic targets, the full image pipeline (per-page background and color detection, margin and page-number-aware cropping, inter-panel cropping, resize, gamma/autocontrast, double-page-spread split/rotate, rainbow-artifact removal, grayscale or color output, palette quantization), webtoon mode (long strips cut into pages between panels), ComicInfo.xml metadata and bookmarks, and EPUB/CBZ/PDF output all work end to end and are covered by an extensive test suite, checked page by page against upstream KCC 12.0.0 by running KCC's own code next to it (tools/parity) — see docs/adr for the design decisions made so far, and open an issue if you hit a rough edge. Still pre-1.0.

Install

macOS/Linux:

curl -fsSL https://raw.githubusercontent.com/gustavommcv/mangapress/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/gustavommcv/mangapress/main/install.ps1 | iex

Both scripts download the right binary for your OS/architecture from the latest release and put it on your PATH — no need to install Rust. Prebuilt binaries and checksums for every release are also available there directly, if you'd rather install manually. Each archive holds the binary, the two license texts and THIRD-PARTY-NOTICES.md.

Already have Rust and want the dev version instead:

cargo install --git https://github.com/gustavommcv/mangapress mangapress-cli

Update

Run the same install command again — it always fetches the latest release and overwrites the existing binary in place. mangapress --version tells you what you currently have installed.

Uninstall

mangapress is a single self-contained binary; there's no installer state to clean up beyond it.

• macOS/Linux: rm ~/.local/bin/mangapress
• Windows: delete the folder %LOCALAPPDATA%\Programs\mangapress (the executable and the license files beside it). The installer added that folder to your user PATH; if you'd rather remove that entry too, it's under Settings > System > About > Advanced system settings > Environment Variables > Path (User variables).
• cargo install: cargo uninstall mangapress-cli.

Usage

mangapress /path/to/volume.cbz --profile KV --format epub

The input can be a .cbz file or a folder of chapter subfolders (the layout Mangabind produces — see docs/adr/0005-mangabind-contract.md). If --output isn't given, the result is written next to the input with the right extension for --format — for a Kobo profile's EPUB that is .kepub.epub, which Kobo's own reader wants (--nokepub for a plain .epub).

mangapress warns, and carries on, when over a quarter of the pages are smaller than the device's screen and nothing enlarges them (--upscale, --stretch), and when the pages look like KCC already converted them once.

A few of the more commonly used flags:

• --profile <CODE> — target device (e.g. KV Kindle Voyage, KPW5 Kindle Paperwhite 5, KoAO Kobo Aura ONE, Rmk2 reMarkable 2, OTHER for --customwidth/--customheight).
• --format <auto|epub|cbz|pdf> — output format (default auto: CBZ for the four oldest Kindles, PDF for reMarkable, EPUB for everything else).
• --manga-style — right-to-left reading order and spread-split order.
• --cropping <disabled|margins|margins-and-page-numbers> — margin detection, with or without page-number-aware trimming (default: both).
• --splitter <split|rotate|both> — how to handle double-page spreads.
• --upscale — enlarge pages smaller than the screen to fit it. Off by default, as in KCC's command line.
• --webtoon — for long vertical strips: join each chapter's images and cut them into screen-sized pages between panels, not across them.
• --forcecolor — keep color pages in color (see "Color output is opt-in" above).
• --eraserainbow — attenuate Moire interference between halftone screentone and a color e-ink (Kaleido-style) panel's diagonal subpixel grid. A display-artifact fix, not color output (for that, see --forcecolor above).
• --forcepng — dither each page down to the device's own gray levels (16 on most e-ink screens) and save it as PNG, instead of full-tone JPEG.
• --cover <FILE> — use this image as the book's cover instead of the first page. Without it, a folder named Covers beside the input is looked in: an image there named like the input (Covers/Vol 3.jpg for Vol 3.cbz) is its cover; if no image there is named after a book, the Nth image is the cover of the Nth book beside the input, as in KCC.
• --spreads <FILE> — join pages that are the two halves of one double-page spread, stored as separate images, back into one before anything else is done to them. The file is JSON listing the position (counting from 0) of the first page of each pair: {"spreads": [12, 40]}. That is the file KCC's "Label Spreads" window writes, and without the option one named like the input plus .json beside it is used.
• --keepcomicinfo — carry the source's ComicInfo.xml through into .cbz output.
• --nested-toc — build a two-level table of contents (a volume entry, its chapters nested underneath) instead of the usual flat, one-entry-per-chapter list. For an input whose chapter folders are themselves nested one level under a volume folder — what Mangabind's -combine mode produces. EPUB output only for now; combined with --format cbz or --format pdf it's refused with a clear error. See docs/adr/0012-nested-toc-for-combined-volumes.md.

Run mangapress --help for the full list, including cropping-aggressiveness tuning (--croppingpower, --croppingminimum, --preservemargin, --ipc), resize behavior (--stretch, --wallpaper, --blackborders, --whiteborders), contrast (--gamma, --autolevel, --noautocontrast, --colorautocontrast), what becomes of a double-page spread (--norotate, --rotatefirst, --rotateright, --maximizestrips), how pages sit in a two-page view (--invertdirection, --spreadshift, --onepagelandscape — for readers that lay out fixed-layout spreads, like Kobo's and Kindle's own; KOReader ignores them), the cover (--smartcovercrop, --coverfill), the PNG variants (--pnglegacy, --noquantize, --force-png-rgb), --noprocessing to package images untouched, and metadata overrides (--title, --author, --metadatatitle, --language). The names are KCC's wherever the option means the same thing; one takes a different unit — --croppingminimum is a percentage here and a fraction in KCC.

Machine-readable integration

--json-events emits a versioned JSON Lines stream containing stage, chapter, source-page, warning, error, and result events. It is an additional mode; ordinary terminal output is unchanged when the flag is absent:

mangapress volume.cbz --profile KV --output volume.epub --json-events
mangapress volume.cbz --profile KV --output volume.epub --dry-run --json-events

Device profiles are available as structured events with --list-profiles --json-events. mangapress --protocol-version returns the compatibility handshake used by GUI consumers. See the machine protocol v1 specification and ADR 0011. Consumers must check protocol_version rather than infer compatibility from the release version.

Relationship to upstream KCC

mangapress is a separate project, not affiliated with or endorsed by KCC or its authors. It takes KCC's behavior as its specification and reimplements it; it does not include KCC's code. See docs/adr/0007-gplv3-boundary-kcc-image-rs.md for how that line is kept, and why it matters most for image.py and dualmetafix.py, which are GPLv3-licensed, unlike the rest of the ISC-licensed repository. What mangapress does share with KCC's own text — EPUB markup, option names — and KCC's license notice are in THIRD-PARTY-NOTICES.md.

Given the same pages and options, mangapress is meant to produce the pages KCC 12.0.0 does, and tools/parity checks that it does. Where it differs, it is on purpose — ADR 0013 has the whole list and the reasons — and mostly because mangapress is made for books read in KOReader rather than by Amazon's own reader:

• No MOBI/AZW3, and none of what KCC does only for Amazon's converter: no Panel View, no page splitting for the Kindle Scribe.
• --forcepng always writes PNG. KCC writes GIF for a Kindle profile's EPUB; the palette PNG holds the same pixels in a smaller file.
• A spread kept upright with --norotate may be as large as two screens side by side on every device. KCC caps it at 1920x1920 for a Kindle profile's EPUB.
• A cover in the Covers folder can be matched by name, not only by position, and the Covers folder is not itself counted as a book when the input is a folder.
• Only .cbz and folders are read — no .cbr, .cb7, PDF or EPUB input, which is what lets mangapress be one binary with nothing else to install.
• Grouping chapters into volumes and splitting volumes by size are left to Mangabind.
• No WebP output yet, and no repacked (mozJPEG-style) JPEG. WebP was measured — about 38% smaller than JPEG at the same quality setting, with higher fidelity, and slower to decode — and both are deferred: ADR 0014.

License

Dual-licensed under MIT or Apache-2.0, at your option.

THIRD-PARTY-NOTICES.md acknowledges the two projects whose work mangapress reproduces — KCC, and Pillow, which KCC's image processing is built on — and carries their license notices.