Calibre XTC Output Plugin

A Calibre output plugin that converts ebooks to XTC format for Xteink e-readers.

What is XTC?

XTC is a bitmap-based e-ink format used by Xteink devices. It stores pre-rendered pages as 1-bit black and white images, optimized for e-ink displays. This plugin handles the complete conversion pipeline: HTML rendering, dithering, and binary encoding.

Features

• Converts any Calibre-supported ebook format to XTC
• Supersampling for sharper text rendering (2x by default)
• Floyd-Steinberg dithering for smooth images on e-ink
• Cover image support
• Chapter/TOC extraction and embedding
• Configurable page dimensions, margins, and font size
• GUI configuration panel in Calibre
• Debug mode for troubleshooting

Requirements

• Calibre 5.0.0 or later
• Qt WebEngine (included with Calibre)

Installation

From Source

# Clone the repository
git clone https://github.com/thirteen37/calibre-xtc.git
cd calibre-xtc

# Install directly to Calibre
calibre-customize -b calibre_xtc_plugin/

As Plugin ZIP

# Build the plugin ZIP
python build_plugin.py

# Install via Calibre GUI or command line
calibre-customize -a calibre-xtc-output.zip

Usage

Command Line

# Basic conversion
ebook-convert input.epub output.xtc

# With options
ebook-convert input.epub output.xtc \
  --xtc-width 480 \
  --xtc-height 800 \
  --xtc-font-size 18 \
  --xtc-zoom 1.5

Calibre GUI

1. Select a book in your library
2. Click "Convert books"
3. Choose "XTC" as the output format
4. Configure options in the "XTC Output" panel
5. Click "OK" to convert

Options

Option	Default	Description
--xtc-width	480	Page width in pixels
--xtc-height	800	Page height in pixels
--xtc-margin-left	20	Left margin in pixels
--xtc-margin-top	20	Top margin in pixels
--xtc-margin-right	20	Right margin in pixels
--xtc-margin-bottom	40	Bottom margin in pixels
--xtc-font-size	16	Base font size in points
--xtc-zoom	1.5	WebEngine zoom factor (1.0 = 100%)
--xtc-contrast	1.5	Contrast enhancement (1.0 = none)
--xtc-sharpness	2.0	Sharpness enhancement (1.0 = none)
--xtc-render-scale	2	Supersampling factor
--xtc-include-cover	True	Include cover as first page
--xtc-debug-dir	None	Save debug images to directory
--xtc-max-pages	0	Limit pages (0 = unlimited)

Development

Running Tests

# Unit tests (requires Calibre environment)
calibre-debug -e tests/test_xtc_encoder.py

# Verify generated XTC files
python3 tests/verify_xtc.py output/test.xtc --verbose

Debug Conversion

# Convert with debug output (first 10 pages only)
ebook-convert input.epub output.xtc \
  --xtc-debug-dir debug_images \
  --xtc-max-pages 10 \
  --verbose

This saves raw (pre-dithered) and processed PNG images for inspection.

Project Structure

calibre_xtc_plugin/
├── __init__.py        # Plugin entry point
├── xtc_output.py      # Conversion orchestrator
├── renderer.py        # Qt WebEngine HTML→Image
├── image_processor.py # Floyd-Steinberg dithering
├── xtc_encoder.py     # Binary XTC writer
└── config.py          # GUI configuration

tests/                 # Test and verification scripts
docs/                  # Format documentation

Format Notes

This plugin implements the official XTC format specification.

License

MIT License

Author

Yu-Xi Lim