# img2cbz: Folder to CBZ Archive Converter

`img2cbz` is a powerful, user-friendly Python command-line utility to convert folders of images (including WebP, JPEG, PNG, GIF, BMP, and TIFF) into CBZ (Comic Book Zip) archives. It is located at [img2cbz](file:///var/home/david/.local/bin/img2cbz) and is globally runnable from the terminal.

## Key Features

- **Multi-Format Support**: Processes `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.bmp`, and `.tiff`.
- **Natural Sorting (Alphanumeric)**: Sorts filenames naturally (e.g., `page_2.png` comes before `page_10.png` rather than alphabetical order).
- **Parallel Image Conversion**: Convert images to `webp`, `jpg`, or `png` in parallel using multithreading.
  - **Space Saving**: Converting images to WebP can compress the CBZ size by 30-70% with virtually no loss in quality.
  - **Maximum Compatibility**: Convert WebP/PNG to JPEG with automatic transparency flattening (pasting transparent images over a solid white background to avoid black-background issues).
- **Recursive Mode (`-r`)**: Scan a parent directory recursively to locate all directories that contain image files, converting each folder into its own CBZ archive.
- **Dry-Run Mode (`-d`)**: Safely test commands and see what files would be processed and where archives would be saved without making modifications.
- **Interactive Mode**: If run without arguments, it launches a step-by-step interactive setup wizard guiding you through configuration.
- **Verify & Clean (`--clean`)**: Safely deletes source folders only after verifying the created CBZ archive is complete, uncorrupted, and has a matching file count.

---

## Command-Line Arguments Reference

| Option | Long Option | Description |
| :--- | :--- | :--- |
| `DIR` | | One or more folders containing images to convert. |
| `-r` | `--recursive` | Find subdirectories containing images and convert each to a CBZ. |
| `-o` | `--output-dir` | Path to save CBZ files (defaults to next to each source folder). |
| `-e` | `--extensions` | Comma-separated list of image extensions to scan (default: all). |
| `-c` | `--convert` | Convert images to `webp`, `jpg`, or `png` before archiving. |
| `-q` | `--quality` | Compression quality (`1`-`100`) for WebP/JPEG conversions (default: `85`). |
| `-j` | `--jobs` | Number of parallel threads to use for conversion (default: CPU core count). |
| `--overwrite` | | Replace existing `.cbz` files if they exist. |
| `--clean` | | Delete source folders after successful CBZ creation & integrity checks. |
| `-d` | `--dry-run` | Show planned archive creations and image conversions without executing them. |
| `--verbose` | | Print debug information. |
| `--quiet` | | Suppress standard log output (only outputs errors). |

---

## Common Usage Examples

### 1. Simple Single-Folder Conversion
Create `Chapter_01.cbz` in the same directory as `Chapter_01/`:
```bash
img2cbz Chapter_01/
```

### 2. Recursive Multi-Folder Conversion
Convert all subdirectories containing images in a series folder (e.g., `Manga_Series/Volume_1/Chapter_1/`, `Manga_Series/Volume_1/Chapter_2/`) into separate CBZ archives (`Chapter_1.cbz`, `Chapter_2.cbz`):
```bash
img2cbz -r Manga_Series/
```

### 3. Compress Archives to WebP
Convert all images to space-saving WebP format with `80%` quality during archiving:
```bash
img2cbz -c webp -q 80 Chapter_01/
```

### 4. Output to a Specific Directory
Save all created CBZ archives in a separate `Comics/` folder instead of next to the source directories:
```bash
img2cbz -r -o ~/Comics/ Manga_Series/
```

### 5. Safe Conversion & Cleanup
Convert to WebP, save to a separate directory, verify archives, and then delete the original uncompressed source folders:
```bash
img2cbz -r -c webp -o ~/Comics/ --clean Manga_Series/
```

### 6. Dry Run (Test First)
Preview which folders and images would be processed by a command:
```bash
img2cbz -r -c webp -o ~/Comics/ --clean -d Manga_Series/
```