CBZOptimizer

CBZOptimizer is a Go-based tool designed to optimize CBZ (Comic Book Zip) and CBR (Comic Book RAR) files by converting images to a specified format and quality. This tool is useful for reducing the size of comic book archives while maintaining acceptable image quality.

Note: CBR files are supported as input but are always converted to CBZ format for output.

Features

• Convert images within CBZ and CBR files to different formats (e.g., WebP).
• Support for multiple archive formats including CBZ and CBR (CBR files are converted to CBZ format).
• Adjust the quality of the converted images.
• Process multiple chapters in parallel.
• Option to override the original files (CBR files are converted to CBZ and original CBR is deleted).
• Watch a folder for new CBZ/CBR files and optimize them automatically.
• Set time limits for chapter conversion to avoid hanging on problematic files.

Installation

Download Binary

Download the latest release from GitHub Releases.

Docker

Pull the Docker image:

docker pull ghcr.io/belphemur/cbzoptimizer:latest

Usage

Command Line Interface

The tool provides CLI commands to optimize and watch CBZ/CBR files. Below are examples of how to use them:

Optimize Command

Optimize all CBZ/CBR files in a folder recursively:

cbzconverter optimize [folder] --quality 85 --parallelism 2 --override --format webp --split

The format flag can be specified in multiple ways:

# Using space-separated syntax
cbzconverter optimize [folder] --format webp

# Using short form with space
cbzconverter optimize [folder] -f webp

# Using equals syntax
cbzconverter optimize [folder] --format=webp

# Format is case-insensitive
cbzconverter optimize [folder] --format WEBP

With timeout to avoid hanging on problematic chapters:

cbzconverter optimize [folder] --timeout 10m --quality 85

Or with Docker:

docker run -v /path/to/comics:/comics ghcr.io/belphemur/cbzoptimizer:latest optimize /comics --quality 85 --parallelism 2 --override --format webp --split

Watch Command

Watch a folder for new CBZ/CBR files and optimize them automatically:

cbzconverter watch [folder] --quality 85 --override --format webp --split

Or with Docker:

docker run -v /path/to/comics:/comics ghcr.io/belphemur/cbzoptimizer:latest watch /comics --quality 85 --override --format webp --split

Flags

• --quality, -q: Quality for conversion (0-100). Default is 85.
• --parallelism, -n: Number of chapters to convert in parallel. Default is 2.
• --override, -o: Override the original files. For CBZ files, overwrites the original. For CBR files, deletes the original CBR and creates a new CBZ. Default is false.
• --split, -s: Split long pages into smaller chunks. Default is false.
• --format, -f: Format to convert the images to (currently supports: webp). Default is webp.
  • Can be specified as: --format webp, -f webp, or --format=webp
  • Case-insensitive: webp, WEBP, and WebP are all valid
• --timeout, -t: Maximum time allowed for converting a single chapter (e.g., 30s, 5m, 1h). 0 means no timeout. Default is 0.
• --log, -l: Set log level; can be 'panic', 'fatal', 'error', 'warn', 'info', 'debug', or 'trace'. Default is info.

Logging

CBZOptimizer uses structured logging with zerolog for consistent and performant logging output.

Log Levels

You can control the verbosity of logging using either command-line flags or environment variables:

Command Line:

# Set log level to debug for detailed output
cbzconverter --log debug optimize [folder]

# Set log level to error for minimal output
cbzconverter --log error optimize [folder]

Environment Variable:

# Set log level via environment variable
LOG_LEVEL=debug cbzconverter optimize [folder]

Docker:

# Set log level via environment variable in Docker
docker run -e LOG_LEVEL=debug -v /path/to/comics:/comics ghcr.io/belphemur/cbzoptimizer:latest optimize /comics

Available Log Levels

• panic: Logs panic level messages and above
• fatal: Logs fatal level messages and above
• error: Logs error level messages and above
• warn: Logs warning level messages and above
• info: Logs info level messages and above (default)
• debug: Logs debug level messages and above
• trace: Logs all messages including trace level

Examples

# Default info level logging
cbzconverter optimize comics/

# Debug level for troubleshooting
cbzconverter --log debug optimize comics/

# Quiet operation (only errors and above)
cbzconverter --log error optimize comics/

# Using environment variable
LOG_LEVEL=warn cbzconverter optimize comics/

# Docker with debug logging
docker run -e LOG_LEVEL=debug -v /path/to/comics:/comics ghcr.io/belphemur/cbzoptimizer:latest optimize /comics

Docker Image

The official Docker image is available at: ghcr.io/belphemur/cbzoptimizer:latest

Docker Compose

You can use Docker Compose to run CBZOptimizer with persistent configuration. Create a docker-compose.yml file:

version: '3.8'

services:
  cbzoptimizer:
    image: ghcr.io/belphemur/cbzoptimizer:latest
    container_name: cbzoptimizer
    environment:
      # Set log level (panic, fatal, error, warn, info, debug, trace)
      - LOG_LEVEL=info
      # User and Group ID for file permissions
      - PUID=99
      - PGID=100
    volumes:
      # Mount your comics directory
      - /path/to/your/comics:/comics
      # Optional: Mount a config directory for persistent settings
      - ./config:/config
    # Example: Optimize all comics in the /comics directory
    command: optimize /comics --quality 85 --parallelism 2 --override --format webp --split
    restart: unless-stopped

For watch mode, you can create a separate service:

  cbzoptimizer-watch:
    image: ghcr.io/belphemur/cbzoptimizer:latest
    container_name: cbzoptimizer-watch
    environment:
      - LOG_LEVEL=info
      - PUID=99
      - PGID=100
    volumes:
      - /path/to/watch/directory:/watch
      - ./config:/config
    # Watch for new files and automatically optimize them
    command: watch /watch --quality 85 --override --format webp --split
    restart: unless-stopped

Important Notes:

• Replace /path/to/your/comics and /path/to/watch/directory with your actual directory paths
• The PUID and PGID environment variables control file permissions (default: 99/100)
• The LOG_LEVEL environment variable sets the logging verbosity
• For one-time optimization, remove the restart: unless-stopped line
• Watch mode only works on Linux systems

Running with Docker Compose

# Start the service (one-time optimization)
docker-compose up cbzoptimizer

# Start in detached mode
docker-compose up -d cbzoptimizer

# Start watch mode service
docker-compose up -d cbzoptimizer-watch

# View logs
docker-compose logs -f cbzoptimizer

# Stop services
docker-compose down

Troubleshooting

If you encounter issues:

1. Use --log debug for detailed logging output
2. Check that all required dependencies are installed
3. Ensure proper file permissions for input/output directories
4. For Docker usage, verify volume mounts are correct

Support

For issues and questions, please use GitHub Issues.

License

This project is licensed under the MIT License. See the LICENSE file for details.