Kindle Comic Converter (ciromattia/kcc)

Kindle Comic Converter

https://github.com/ciromattia/kcc
Admin
Kindle Comic Converter optimizes black and white or color comics and manga for e-ink ereaders like...

Tokens:14,637
Snippets:192
Trust Score:7.3
Update:1 month ago
Show doc for...
Context Summary (auto-generated)
Raw
# Kindle Comic Converter (KCC)

Kindle Comic Converter (KCC) is an open-source tool that optimizes comics, manga, and webtoons for E-ink e-readers including Kindle, Kobo, and reMarkable devices. It processes image files from various input formats (folders, CBZ, CBR, PDF) and outputs optimized ebooks in MOBI, EPUB, KEPUB, CBZ, or PDF format with proper fixed-layout support for fullscreen display without margins.

The application provides extensive image processing capabilities specifically designed for E-ink displays, including gamma correction, automatic margin cropping, page number removal, double-page spread handling, and rainbow artifact removal for color E-ink screens. KCC automatically scales images to your device's resolution, converts to appropriate color palettes, and can split large files for memory-constrained devices. It runs on Windows, macOS, and Linux with both GUI and command-line interfaces.

## GUI Application

### Running the GUI

Launch the graphical interface for drag-and-drop conversion with visual settings.

```bash
# From source
python kcc.py

# Windows setup from source
python -m venv venv
venv\Scripts\activate.bat
pip install -r requirements.txt
python kcc.py

# macOS/Linux setup from source
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python kcc.py
```

## Command Line Interface (kcc-c2e)

### Basic Conversion

Convert comics to ebook format using the `kcc-c2e` command-line tool with device-specific profiles and processing options.

```bash
# Basic conversion for Kindle Voyage (default profile)
kcc-c2e /path/to/manga.cbz

# Convert for Kindle Paperwhite 5 with manga mode (right-to-left)
kcc-c2e -p KPW5 -m /path/to/manga_volume/

# Convert for Kobo Libra Colour with color output
kcc-c2e -p KoLC --forcecolor /path/to/color_comic.pdf

# Convert for reMarkable 2 (auto-selects PDF output)
kcc-c2e -p Rmk2 /path/to/document.cbz

# Convert for Kindle Scribe with high quality panel view
kcc-c2e -p KS -q /path/to/manga.cbr

# Specify output directory and custom title
kcc-c2e -p KO -o /output/directory -t "My Manga Vol 1" /path/to/source.cbz

# Batch convert multiple files
kcc-c2e -p KPW5 -m /path/to/vol1.cbz /path/to/vol2.cbz /path/to/vol3.cbz
```

### Device Profiles

Select the appropriate device profile to optimize output for your specific e-reader's screen resolution.

```bash
# Kindle devices
kcc-c2e -p K11 input.cbz      # Kindle 11 (1072x1448)
kcc-c2e -p KPW5 input.cbz     # Kindle Paperwhite 5 (1236x1648)
kcc-c2e -p KO input.cbz       # Kindle Oasis 2/3/Paperwhite 12 (1264x1680)
kcc-c2e -p KS input.cbz       # Kindle Scribe 1/2 (1860x2480)
kcc-c2e -p KCS input.cbz      # Kindle Colorsoft (1264x1680)
kcc-c2e -p KDX input.cbz      # Kindle DX (824x1000) - outputs CBZ

# Kobo devices
kcc-c2e -p KoC input.cbz      # Kobo Clara HD/Clara 2E (1072x1448)
kcc-c2e -p KoCC input.cbz     # Kobo Clara Colour (1072x1448)
kcc-c2e -p KoL input.cbz      # Kobo Libra H2O/Libra 2 (1264x1680)
kcc-c2e -p KoLC input.cbz     # Kobo Libra Colour (1264x1680)
kcc-c2e -p KoF input.cbz      # Kobo Forma (1440x1920)
kcc-c2e -p KoS input.cbz      # Kobo Sage (1440x1920)

# reMarkable devices
kcc-c2e -p Rmk2 input.cbz     # reMarkable 2 (1404x1872)
kcc-c2e -p RmkPP input.cbz    # reMarkable Paper Pro (1620x2160)

# Custom resolution
kcc-c2e --customwidth 1200 --customheight 1600 input.cbz
```

### Output Formats

Configure the output format based on your device and reading software requirements.

```bash
# MOBI format for Kindle (default for Kindle profiles)
kcc-c2e -p KPW5 -f MOBI /path/to/comic.cbz

# EPUB format for Kobo (default for Kobo profiles)
kcc-c2e -p KoL -f EPUB /path/to/comic.cbz

# KEPUB format (Kobo-optimized EPUB with .kepub.epub extension)
kcc-c2e -p KoL -f EPUB /path/to/comic.cbz  # Creates .kepub.epub by default
kcc-c2e -p KoL -f EPUB --nokepub /path/to/comic.cbz  # Creates standard .epub

# CBZ format (for KDX or Koreader)
kcc-c2e -p KDX -f CBZ /path/to/comic.cbz

# PDF format for reMarkable (default for reMarkable profiles)
kcc-c2e -p Rmk2 -f PDF /path/to/comic.cbz

# MOBI+EPUB (keep both formats)
kcc-c2e -p KPW5 -f MOBI+EPUB /path/to/comic.cbz

# KFX format (creates EPUB for Calibre KFX Output plugin)
kcc-c2e -p KPW5 -f KFX /path/to/comic.cbz
```

### Image Processing Options

Control how images are processed, cropped, and enhanced for optimal E-ink display.

```bash
# Manga mode with automatic margin and page number cropping
kcc-c2e -p KPW5 -m -c 2 /path/to/manga.cbz

# Disable all image processing (passthrough mode)
kcc-c2e -p KPW5 -n /path/to/already_optimized.cbz

# Cropping options
kcc-c2e -p KPW5 -c 0 input.cbz  # Disabled
kcc-c2e -p KPW5 -c 1 input.cbz  # Margins only
kcc-c2e -p KPW5 -c 2 input.cbz  # Margins + page numbers (default)

# Cropping power and minimum area
kcc-c2e -p KPW5 --cp 1.5 --cm 0.1 input.cbz

# Preserve margin percentage after cropping
kcc-c2e -p KPW5 --preservemargin 5 input.cbz

# Inter-panel cropping for empty sections
kcc-c2e -p KPW5 --ipc 1 input.cbz  # Horizontal only
kcc-c2e -p KPW5 --ipc 2 input.cbz  # Both directions

# Gamma correction (default auto ~1.8 for B&W, 1.0 for color)
kcc-c2e -p KPW5 -g 1.0 input.cbz   # Disable gamma correction
kcc-c2e -p KPW5 -g 1.5 input.cbz   # Custom gamma value

# Auto-leveling for faded artwork
kcc-c2e -p KPW5 --autolevel input.cbz

# Disable autocontrast
kcc-c2e -p KPW5 --noautocontrast input.cbz

# Force color autocontrast
kcc-c2e -p KPW5 --colorautocontrast --forcecolor input.cbz
```

### Double-Page Spread Handling

Configure how double-page spreads (landscape images) are processed for portrait e-readers.

```bash
# Split double-page spreads (default)
kcc-c2e -p KPW5 -r 0 input.cbz

# Rotate double-page spreads only
kcc-c2e -p KPW5 -r 1 input.cbz

# Both split and rotate (creates 3 pages per spread)
kcc-c2e -p KPW5 -r 2 input.cbz

# Don't rotate spreads when using split+rotate mode
kcc-c2e -p KPW5 -r 2 --norotate input.cbz

# Rotate in opposite direction
kcc-c2e -p KPW5 -r 1 --rotateright input.cbz

# Put rotated spread first (before split pages)
kcc-c2e -p KPW5 -r 2 --rotatefirst input.cbz

# Spread alignment shift for two-page landscape reading
kcc-c2e -p KPW5 --spreadshift input.cbz
```

### Image Scaling and Quality

Control upscaling, stretching, and image quality settings for your output.

```bash
# Upscale small images to device resolution
kcc-c2e -p KPW5 -u input.cbz

# Stretch images to fit device resolution
kcc-c2e -p KPW5 -s input.cbz

# High quality panel view (1.5x resolution)
kcc-c2e -p KPW5 -q input.cbz

# Two-panel view instead of four-panel
kcc-c2e -p KPW5 -2 input.cbz

# Force color output (don't convert to grayscale)
kcc-c2e -p KPW5 --forcecolor input.cbz

# Force PNG output for B&W images
kcc-c2e -p KPW5 --forcepng input.cbz

# Force PNG for color images
kcc-c2e -p KPW5 --forcecolor --force-png-rgb input.cbz

# Disable PNG quantization to 16 colors
kcc-c2e -p KPW5 --forcepng --noquantize input.cbz

# Use mozJpeg for better JPEG compression
kcc-c2e -p KPW5 --mozjpeg input.cbz

# Custom JPEG quality (0-95, default 85)
kcc-c2e -p KPW5 --jpeg-quality 90 input.cbz

# Erase rainbow artifacts on color E-ink screens
kcc-c2e -p KoCC --forcecolor --eraserainbow input.cbz
```

### Border and Background Options

Configure border detection and background color handling for optimal display.

```bash
# Force black borders/backgrounds
kcc-c2e -p KPW5 --blackborders input.cbz

# Force white borders/backgrounds
kcc-c2e -p KPW5 --whiteborders input.cbz

# Center-crop cover to fill screen
kcc-c2e -p KPW5 --coverfill input.cbz
```

### Webtoon Processing

Process vertical-scrolling webtoons with automatic panel detection and splitting.

```bash
# Enable webtoon mode (auto white borders, no upscale)
kcc-c2e -p KPW5 -w /path/to/webtoon/

# Webtoon with custom target file size (100MB default)
kcc-c2e -p KPW5 -w --ts 50 /path/to/webtoon/
```

### File Splitting and Batch Processing

Handle large files and batch operations with automatic splitting options.

```bash
# Automatic file splitting for large comics (400MB default)
kcc-c2e -p KPW5 -b 1 input.cbz

# Treat each subdirectory as separate volume
kcc-c2e -p KPW5 -b 2 /path/to/series/

# Custom target file size in MB
kcc-c2e -p KPW5 --ts 200 -b 1 input.cbz

# Combine multiple input files into single output
kcc-c2e -p KPW5 --filefusion input1.cbz input2.cbz input3.cbz

# Delete source files after conversion (DESTRUCTIVE)
kcc-c2e -p KPW5 -d input.cbz
```

### PDF Input Processing

Configure how PDF files are processed and images are extracted.

```bash
# Default: Render PDF pages at device height resolution
kcc-c2e -p KPW5 input.pdf

# Render vector PDFs based on device width instead
kcc-c2e -p KPW5 --pdfwidth input.pdf

# Use legacy image extraction method (KCC 8 and earlier)
kcc-c2e -p KPW5 --pdfextract input.pdf
```

### Metadata Options

Set title, author, and use embedded metadata from ComicInfo.xml.

```bash
# Set custom title
kcc-c2e -p KPW5 -t "My Comic Title" input.cbz

# Set author name
kcc-c2e -p KPW5 -a "Author Name" input.cbz

# Use title from ComicInfo.xml metadata
kcc-c2e -p KPW5 --metadatatitle 2 input.cbz

# Combine metadata title with default schema
kcc-c2e -p KPW5 --metadatatitle 1 input.cbz
```

## Command Line Interface (kcc-c2p)

### Panel Splitting for Webtoons

The `kcc-c2p` tool merges and splits long webtoon images into pages optimized for your device.

```bash
# Split webtoon images to device height
kcc-c2p -y 1648 /path/to/webtoon/

# Split with device dimensions
kcc-c2p -y 1648 -x 1236 /path/to/webtoon/

# Merge chapter folders before splitting
kcc-c2p -y 1648 -m /path/to/webtoon/

# In-place processing (overwrite source)
kcc-c2p -y 1648 -i /path/to/webtoon/

# Debug mode (creates visual debug images)
kcc-c2p -y 1648 -d /path/to/webtoon/
```

## Docker Usage

### Running KCC in Docker

Use Docker for containerized conversion without local Python installation.

```bash
# Pull the latest image
docker pull ghcr.io/ciromattia/kcc:latest

# Basic conversion
docker run --rm -v "$(pwd):/opt/kcc" ghcr.io/ciromattia/kcc:latest -p KPW5 ./comic.cbz

# With KindleGen for MOBI output
docker run --rm \
  -v "/path/to/kindlegen:/opt/kcc/kindlegen" \
  -v "/path/to/sourcefiles:/opt/kcc/files" \
  ghcr.io/ciromattia/kcc:latest -p KPW5 files/comic.cbz

# Run kcc-c2p instead
docker run --rm -v "$(pwd):/opt/kcc" -e KCC_MODE=c2p ghcr.io/ciromattia/kcc:latest -y 1648 ./webtoon/
```

## Flatpak Usage

### Running KCC from Flatpak

Use Flatpak-installed KCC on Linux systems.

```bash
# Run GUI
flatpak run io.github.ciromattia.kcc

# Run kcc-c2e command line
flatpak run --command=kcc-c2e io.github.ciromattia.kcc -p KPW5 ./comic.cbz

# Run kcc-c2p command line
flatpak run --command=kcc-c2p io.github.ciromattia.kcc -y 1648 ./webtoon/
```

## Python API Usage

### Programmatic Conversion

Use KCC as a Python library for integration into custom workflows.

```python
from kindlecomicconverter import comic2ebook
from kindlecomicconverter.image import ProfileData

# Get available device profiles
profiles = ProfileData.Profiles
print(profiles.keys())
# dict_keys(['K1', 'K2', 'KDX', 'K34', 'K57', 'KPW', 'KV', 'KPW34', 'K810',
#            'KO', 'K11', 'KPW5', 'KS', 'KCS', 'KS3', 'KSCS', 'KoMT', 'KoG', ...])

# Check profile details (name, resolution, palette, gamma)
print(ProfileData.Profiles['KPW5'])
# ('Kindle Paperwhite 5/Signature Edition', (1236, 1648), [...], 1.0)

# Convert using command-line argument style
comic2ebook.main([
    '-p', 'KPW5',           # Device profile
    '-m',                   # Manga mode
    '-f', 'EPUB',           # Output format
    '-o', '/output/dir',    # Output directory
    '/path/to/manga.cbz'    # Input file
])

# Convert with more options
comic2ebook.main([
    '-p', 'KO',
    '-m',                   # Manga (right-to-left)
    '-q',                   # High quality
    '-g', '1.5',           # Gamma correction
    '-c', '2',             # Crop margins + page numbers
    '--forcecolor',        # Keep color output
    '--mozjpeg',           # Use mozJpeg compression
    '--jpeg-quality', '90',
    '-t', 'My Manga Vol 1',
    '-a', 'Author Name',
    '/path/to/manga.cbz'
])
```

### Image Processing Classes

Use the image processing classes directly for custom image manipulation.

```python
from kindlecomicconverter.image import ComicPage, ComicPageParser, Cover, ProfileData
from PIL import Image
from types import SimpleNamespace

# Create options namespace mimicking CLI options
options = SimpleNamespace(
    profileData=ProfileData.Profiles['KPW5'],
    profile='KPW5',
    hq=False,
    righttoleft=True,
    webtoon=False,
    splitter=0,
    maximizestrips=False,
    bordersColor=None,
    forcecolor=False,
    norotate=False,
    rotateright=False,
    rotatefirst=False,
    gamma=0.0,
    noautocontrast=False,
    colorautocontrast=False,
    autolevel=False,
    cropping=2,
    croppingp=1.0,
    croppingm=0.0,
    preservemargin=0,
    interpanelcrop=0,
    upscale=False,
    stretch=False,
    forcepng=False,
    force_png_rgb=False,
    noquantize=False,
    mozjpeg=False,
    jpegquality=85,
    format='EPUB',
    kindle_azw3=False,
    kindle_scribe_azw3=False,
    kfx=False,
    iskindle=False,
    eraserainbow=False
)

# Parse and split comic page
source = ('/path/to/images', 'page001.jpg')
parser = ComicPageParser(source, options)

# Process each resulting page (may be split for double-page spreads)
for mode, path, image, fill in parser.payload:
    page = ComicPage(options, mode, path, image, fill)

    # Apply processing steps
    page.cropPageNumber(power=1.0, minimum=0.0)
    page.gammaCorrectImage()
    page.convertToGrayscale()
    page.autocontrastImage()
    page.resizeImage()

    # Save processed image
    output_path = page.saveToDir()
    print(f"Saved: {output_path}")
```

## Summary

Kindle Comic Converter is the definitive solution for preparing comics, manga, and webtoons for E-ink e-readers. Its primary use cases include converting CBZ/CBR/PDF comic archives to device-optimized MOBI files for Kindle devices, creating KEPUB files for Kobo readers, generating PDFs for reMarkable tablets, and processing vertical-scrolling webtoons with intelligent panel detection. The tool excels at batch processing entire manga series with consistent settings, automatically handling double-page spreads, and optimizing images specifically for the unique characteristics of E-ink displays.

Integration patterns typically involve using the command-line tools in automated workflows or shell scripts for batch processing, running KCC in Docker containers for reproducible builds, or importing the Python modules directly for custom processing pipelines. The tool follows a straightforward pattern: select a device profile, choose processing options (manga mode, cropping, quality), specify output format, and provide input files. Output files can be directly transferred to e-readers via USB or synced through device-specific applications like Amazon's Send to Kindle or Kobo's desktop software.