cr2xt

E-book to XTC format converter based on Cool Reader and crengine.

About

cr2xt is an umbrella project that combines two forked repositories into a unified build:

• crengine-ng - Cross-platform C++ library for e-book rendering (backend/engine)
• crqt-ng - Qt frontend application

The primary purpose of this project is to convert e-books (EPUB, FB2, MOBI, etc.) into bitmap images optimized for ESP32 e-paper display devices such
as Xteink X4.

Xteink X4 is based on ESP32-C3 and only has 400KB RAM, making it challenging to render books with good formatting. The converter renders book pages and exports them to custom container formats (XTC/XTCH) containing monochrome or 4-level grayscale images (XTG/XTH).

XTC Export dialog supports single file and batch export modes.

<img src="docs/export-single.png" alt="Single file export dialog">

Supported Input Formats

The converter supports all e-book formats handled by crengine:

• EPUB, FB2, FB3, MOBI, PRC, AZW
• DOC, RTF, TXT, HTML
• CHM, TCR, PDB
• And more

Supported Output Formats

See XtcFormat.md for the format specification provided by Xteink.
Also check *.ksy files in the same folder for Kaitai Struct format specification. These can be used to automatically generate parsers for different languages.

How to Use

• File | Open and select your e-book file
• File | Settings (F9) to access formatting and font settings (or Settings from the context menu)
• View | Rotate (Ctrl+R) to change orientation (portrait or landscape)
• File | Export (Ctrl+S) to open the export dialog (or use Export from the context menu)

Export preview supports mouse wheel scrolling and zooming (with Ctrl+Mouse Wheel). Double-click to reset zoom.

Windows release builds

Download the latest release version from the Releases page.

• Unpack and run crqt.exe

macOS release builds

Download the DMG from the Releases page. macOS 26+ is required.

Important: The app is ad-hoc signed (not notarized by Apple). macOS Gatekeeper will block it on first run. To open:

1. Option A - Right-click method:

   • Right-click (or Control-click) on cr2xt.app
   • Select Open from the context menu
   • Click Open in the dialog that appears

2. Option B - System Settings:

   • Try to open the app normally (it will be blocked)
   • Go to System Settings → Privacy & Security
   • Scroll down and click Open Anyway next to the cr2xt message

3. Option C - Terminal (removes quarantine flag):

   bashCopy
   xattr -cr /Applications/cr2xt.app

After allowing once, the app will open normally.

Linux release builds

Use the AppImage package from the Releases page. It includes all dependencies and should work on most modern Linux distributions.

Tips

• Stock English firmware renders 2-bit grayscale images too slowly, it's recommended to use 1-bit monochrome mode.
  It has been improved in CN firmware, and it works faster in CrossPoint custom firmware
• For 1-bit mode, try to find a font that looks best without antialiasing (Verdana, Tahoma, Roboto, old fonts with good hinting)
• For 2-bit mode, make sure to enable antialiasing in Settings | Styles and use Font gamma to control contrast
• Play with the font size / weight and avoid synthetic weights (Roboto family supports all weights natively)
• Some fonts work better with Autohinting (Roboto), others work better with Bytecode (Verdana)
• Adjust page margins and interline spacing to fit as many lines as possible but so that it's still comfortable to read
• Disable page number / page counter and other text in the header to save vertical space
• Further adjust header navigation bar margins for minimal look
• Use Settings | Stylesheet to adjust element margins and justification
• For advanced users, enable "Use expanded CSS file" and edit the <format>-expanded.css file, changes will be applied on the fly

Export Dialog Features

• Batch export - Convert multiple files at once (with file mask filtering and recursive folder processing)
• Profile-based settings - Pre-configured profiles for XTC (1-bit) and XTCH (2-bit) formats
• Live preview - See exactly how each page will look after export
• Dithering options - Floyd-Steinberg, ordered dithering, or none
• Page range selection - Export specific page ranges
• Chapter support - Include table of contents in export
• Metadata editing - Customize title and author

Differences from crqt-ng / crengine-ng

This project is a converter-focused fork with several key differences:

UI Changes

• New formatting and preview options for fine-tuning font rendering
• More options for footer / header customization (custom margins)
• Individual left/right/top/bottom page margins
• Space width / letter spacing
• CSS stylesheets export for manual editing and full customization
• XT* Export dialog with preview and batch mode
• Preserve last settings tab
• Use current page contents for Style Preview
• Default window size adjusts to the export resolution from the profile

Backend Changes

• Advanced dithering options for images
• Page header / footer rendering customization
• XTC converter

TODO

Planned features

• cr2xt CLI converter
• Docker image with CLI converter
• macOS builds
• Linux builds
• Unofficial compression for XTC format to be used in custom firmwares
• New custom XTB format with compression

Building

The project requires:

• Qt6 (Core, Gui, Widgets modules)
• CMake 3.16+
• C++17 compatible compiler
• freetype / fontconfig and other dependencies for crengine

Windows (MSYS2/MinGW64):

Use scripts/build-dist-windows.ps1 or manually run the following commands:

bashCopy
# Configure
cmake -B build/release -G Ninja \
    -DCMAKE_BUILD_TYPE=Release \
    -DUSE_QT=QT6 \
    -DUSE_COLOR_BACKBUFFER=OFF \
    -DGRAY_BACKBUFFER_BITS=2

# Build
cmake --build build/release --target all -j$(nproc)

# Install
cmake --build build/release --target install

macOS:

Install dependencies via Homebrew:

bashCopy
brew install cmake qt@6 freetype harfbuzz libpng jpeg-turbo webp fribidi zstd utf8proc fontconfig create-dmg

Use scripts/build-dist-macos.sh to build and create a DMG:

bashCopy
# Full build with DMG creation
./scripts/build-dist-macos.sh --clean

# Build only (skip DMG)
./scripts/build-dist-macos.sh --clean --skip-dmg

# Universal Binary (Intel + Apple Silicon)
./scripts/build-dist-macos.sh --clean --universal

Or build manually:

bashCopy
# Configure
cmake -B build/release \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_PREFIX_PATH=/opt/homebrew \
    -DUSE_QT=QT6 \
    -DUSE_COLOR_BACKBUFFER=OFF \
    -DGRAY_BACKBUFFER_BITS=2

# Build
cmake --build build/release -j$(sysctl -n hw.ncpu)

# Install to dist/macos
cmake --build build/release --target install

Linux:

Use scripts/create-appimage.sh or manually run the following commands:

bashCopy
cmake -B build/release \
    -DCMAKE_BUILD_TYPE=Release \
    -DUSE_QT=QT6 \
    -DUSE_COLOR_BACKBUFFER=OFF \
    -DGRAY_BACKBUFFER_BITS=2

cmake --build build/release -j$(nproc)

You will need to install dependencies for crengine.

License

This project inherits the licenses from its upstream components:

• crengine-ng: GPL-2.0
• crqt-ng: GPL-2.0

Acknowledgments

• Cool Reader - Original Cool Reader / crengine project by @buggins (Vadim Lopatin)
• crqt-ng - Next-generation Qt Cool Reader frontend fork by Aleksey Chernov
• crengine-ng - Next-generation crengine fork by Aleksey Chernov