reCBZ 0.5.1

Utility for repacking and optmizing manga & comic book archives

reCBZ - CBZ repacker

CLI utility for repacking comic book archives. Can be used to convert, upscale, and optimize comics & manga for reading on e-Readers and mobile devices. Also doubles as an extremely fast image converter.

Purpose

I own a fairly large library of manga, which takes quite a bit of space on disk — this isn't really a problem most of the time, but it limits what I can put on my Kobo e-Reader (which has "only" 32GB of storage). I prefer to keep the original files intact on calibre on my computer, but use this tool to optimize the .cbz files in bulk so they use less space on my Kobo.

For example, by repacking with WebP at default settings, this cut the size of the first volume of Chainsaw Man from 180MB to just under 96MB, without affecting image quality. Over the 11 published volumes, that amounts to over 1GB saved (which is a lot when you consider many e-Readers still have only 4GB)! And that's without touching the resolution, the size can be further reduced by another 50MB by downscaling to the actual display resolution — easily tripling the amount of manga that can be stored on your device (while maintaining the same perceived quality).

EPUBs

This tool can also be used to convert CBZ files to EPUB on the fly so they can be read on Kindle devices, which now support EPUB through "send to Kindle". Disclaimer: huge files might be discarded by the service, ask Amazon to properly support this format if you're upset with this.

EPUB conversion is still a work in progress, and might stretch landscape (double page) images. If your device supports CBZ, you might prefer it over EPUB.

Converting pages

The thing with CBZ files (which are essentially just ZIP files under a different name), is that they are often published with little to no image compression. This is good for the purposes of preservation, but is usually overkill for the type of devices many people read from. Additionally, if you're reading from a black and white screen, removing the color information can save another 20% to 30% in size. I wouldn't advise using this on your entire library, specially if you have the storage to spare, but if you're like me and want to carry 200 high quality tankobons on your pocket, this is one way to achieve it.

Although this was explicitly created with manga and comics in mind, it can be used for bulk rescaling and conversion of images in general (it's pretty fast at that thanks to parallel processing), you just need to pack them into a ZIP archive first. There's an important caveat: non-image files will be automatically discarded, be very careful when using --overwrite.

Note that due to how lossy images formats like JPEG/WebP work, compressing and overwriting the same file many times over will eventually lead to image degradation that is noticeable to the naked eye, so by default this program creates an optimized copy while preserving the original, although lossless formats are also available. As a general rule, you can be more aggressive with compression (--quality) on black and white images.

Install

python -m pip install reCBZ

or build from source:

git clone https://github.com/avalonv/reCBZ

python -m pip install -e reCBZ

Usage

recbz [options] files

Accepts a valid .cbz or .zip file, or a collection of files. With no arguments passed, it will try to repack the file(s) with slightly more compression.

The output file(s) will always be saved to the current directory as filename [reCBZ].extension, unless --overwrite is specified.

Examples:

Click to expand

Convert pages in 'Blame! Master Edition v06.cbz' to various formats and ask which one to repack with:

recbz --assist 'Blame! Master Edition v06.cbz'

Rescale two volumes to the Kindle Paperwhite resolution, and save as EPUB:

recbz --epub --size 1125x1500 'Our Dreams at Dusk v01.cbz' 'Our Dreams at Dusk v02.cbz'

To repack all books in the current directory (e.g. a series), use a '*' to match .cbz files:

recbz ./*.cbz

• On Windows, slashes '/' should be replaced with backslashes '\'

Automatically convert and repack all books on the 'Blame!' folder:

recbz --auto ./'Blame!'/*.cbz

Rescale all books on the "Saga" folder to 1440p 3:4, convert pages to grayscale and save as high quality JPEG:

recbz --size 1440x1920 -bw --quality 90 --fmt jpeg ./Saga/*.cbz

Configuration

General options:

Click to expand

--nowrite -nw

Dry run. The repacked archive isn't saved at the end, making other options completely safe.

--overwrite -O

Overwrite original archive. Specifically, it will be converted to a valid .cbz structure, meaning that non-image files will be discarded. Make sure you understand what this means before using this.

--compare -c

Does a dry run with a small sample of images, converting them to available formats using current settings, then displays a disk usage summary for each.

--assist -a

Same as --compare, except it then asks you which format to use for a real run.

--auto -A

Same as --compare, except it automatically picks the best/smallest format for a real run.

Most of the time this will be a .webp. If you wish to exclude this format, you can add --nowebp.

--recursive -R (TODO/Unimplemented) see #examples

Search all subfolders in the current path for .cbz or .zip files to convert.

Exercise caution when using with --overwrite, may lead to loss of data.

--verbose -v

More progress messages. Can be repeated (-vv) for debug output.

--silent -s

No progress messages.

--processes 1 - 32
default: Core count - 1 (close to 100% utilization)

Max number of processes to spawn. This will only improve performance if your CPU has cores to spare (it's not magic!). Warning: May choke lower end systems, set this to 2 or 4 if you're experiencing high memory usage.

--sequential

Disable multiprocessing altogether. Use this only if you're still experiencing memory issues, or for debugging.

Archive options:

Click to expand

--epub

Save archive as EPUB. -- WORK IN PROGRESS

--zip

Save archive as ZIP.

--cbz

Save archive as CBZ. This is the default.

--unpack (TODO/Unimplemented)

Extract archive contents to a folder

--compress

Attempt to further compress the archive after images have been converted. This will have a very negligible effect on file size, and is generally not recommended.

Image options:

Click to expand

--fmt format
default: same as source

Format to convert images to. One of: jpeg, png, webp or webpll — png and webpll are lossless. Try -c to get an idea of how they compare, this will vary depending on the source format. Omitting this option will preserve the original format.

--quality 0 - 95
default: 80

Image compression quality for lossy formats, will have a large impact on file size. Smaller values produce smaller files at the cost of visual quality. This option only applies to lossy formats

Notes:
Low values degrade image quality less in WebP than they do in JPEG. Similarly, grayscale images are less affected by this setting that color ones, so generally speaking, you can lower it even more when using --fmt webp or --grayscale to save extra space.
Values higher than 95 will usually increase file size without actually improving quality.

--size WidthxHeight
default: don't rescale

Rescale images to the specified resolution, using Lanczos interpolation. Does its best to detect and preserve landscape images.

Add --noupscale to disable upscaling, so images can only be downscaled (as long as they're greater than value).

Add --nodownscale to disable downscaling, so images can only be upscaled (as long as they're less than value).

1440x1920 (3:4) is more than suitable for 6"/7" e-Reader screens. For smaller devices, setting this to 150% of your screen's resolution is usually the best compromise between quality and file size, still allowing you to zoom-in to read the lore critical thoughts of that moe character.

Note: this isn't magic. Please don't upscale a low quality source to upload to manga sites and claim yours is higher quality, because it isn't, and it will annoy people.

--grayscale -bw

Convert images to grayscale. Useful for e-Paper screens, reducing file size by another 10% to 20%. Provides no benefit to comics which only have a few coloured pages (manga).

Default can be changed in defaults.toml

Note about WebP

Generally speaking, the WebP format tends to compress images more efficiently than both JPEG and PNG, allowing both lossy and lossless methods. This leads to a few noticeable quirks when converting from lossy to lossless and vice versa, which are covered here, but overall, if you're confident your reading software supports it, this is probably the best option for saving disk space.

It isn't perfect however: WebP adoption outside of web browsers has been glacial, and it is not universally supported yet, meaning it might not open on older devices and the vast majority of e-Readers (Kindle/Kobo) — although Koreader allows you to get around this limitation.

TL;DR If you're repacking content for the purpose of sharing with others on the web, it is strongly advised to avoid this format, as many devices still aren't incapable of displaying them.

Why not support .cbr and .cb7 archives?

Both WinRAR (.cbr) and 7zip (.cb7) are non-standard file compression programs. Undoubtedly they have helped many people compress files on PC, but they are not pre-installed on most operating systems, and thus cannot be opened on most mobile devices and e-Readers without some tinkering. Additionally, WinRAR is a proprietary program which limits official access to Windows, as the name suggests, which makes it annoying for future users that plan to read in other devices, and cannot be bundled with free software (such as this).

Also, the compression algorithm used to pack images into a comic book archive has a negligible effect on the finished archive size, as the images are already compressed, so even if these programs can achieve higher compression ratios than zlib/zip in most cases, they offer little to no advantage for image content.

TL;DR If distributing manga or comics over the high seas PLEASE stick to the standard .cbz format, as it's guaranteed to work on nearly every device. RAR is bad. Stop using RAR for this.

You can use 7zip to convert .cbr and .cb7 files to .cbz.

Credits

Thanks to aerkalov for creating Ebooklib, which provides EPUB conversion.