cbz2xtc

Convert CBZ comics to XTC for the XTEink X4 e-reader.

Community-maintained successor inspired by tazua/cbz2xtc, packaged for PyPI with a native XTC encoder — no external png2xtc.py or git clone required.

Status

v0.1.0 — CBZ→XTC pipeline, full legacy CLI parity, and tiered programmatic tests are in place.

Scope

In scope: CBZ in, XTC out — CLI and importable library for the XTEink X4.

Out of scope for v0.1.0:

• legacy/image2bw.py (BMP wallpaper conversion) — reference only; may become a separate subcommand later
• EPUB/PDF conversion
• Byte-exact golden-file regression tests

See docs/design.md for behavioral decisions and the v0.1.0 release bar.

Install

pip install cbz2xtc

Input format

A CBZ file is a ZIP archive of images (PNG, JPEG, GIF, BMP, or WebP). Pages are processed in sorted zip entry order (by filename inside the archive).

Migrating from tazua/cbz2xtc

CLI flags match the legacy tazua/cbz2xtc tool. Install with pip — no png2xtc.py, epub2xtc clone, or separate git checkout required.

CLI usage

Convert every .cbz in a directory (searches immediate subdirectories if none are found in the root):

cbz2xtc /path/to/manga

Output lands in xtc_output/ beside the input; intermediate PNGs go under .temp_png/.

Copy xtc_output/*.xtc to your XTEink X4 to read them.

Common options (full list: cbz2xtc --help):

cbz2xtc /path/to/manga --clean              # remove temp PNGs after conversion
cbz2xtc /path/to/manga --no-dither          # sharper line art (encoder thresholds at 200)
cbz2xtc /path/to/manga --skip 2,3           # skip pages
cbz2xtc /path/to/manga --only 1             # convert page 1 only
cbz2xtc /path/to/manga --margin 5           # crop margins (percent)
cbz2xtc /path/to/manga --pad-black          # black padding instead of white
cbz2xtc /path/to/manga --split-spreads all  # split horizontal spreads

Exit code 0 when all conversions succeed; 1 if any fail or no CBZ files are found.

Library usage

from pathlib import Path

from cbz2xtc import BatchResult, ConvertOptions, ConversionResult, convert_directory, convert_file

# Single file
result: ConversionResult = convert_file(
    Path("chapter.cbz"),
    options=ConvertOptions(clean_temp=True, dither=False),
)
if result.success:
    print(result.output_path)

# Directory batch (parallel when multiple CBZ files)
batch: BatchResult = convert_directory(
    Path("./manga"),
    options=ConvertOptions(clean_temp=True, max_workers=4),
)
print(batch.succeeded, batch.failed)

Library-only ConvertOptions fields (no CLI flags in v0.1.0):

• target_width / target_height (default 480×800)
• max_workers — parallel CBZ processing

For development, testing, CI, and releases, see CONTRIBUTING.md.

License

MIT — see LICENSE.

Attribution

• Inspired by tazua/cbz2xtc and community contributions
• XTC format reference: phrozen/xtx SPEC
• No code from unlicensed epub2xtc is included