Komga Cover Extractor

https://github.com/zachstultz/komga-cover-extractor
Admin
Komga Cover Extractor is a Python automation script that automates the detection and extraction of...
Tokens:7,414
Snippets:58
Trust Score:5
License:MIT
Update:10 months ago
Show doc for...
Tokens:
Raw
### Manual Installation Steps (Bash)

Source: https://github.com/zachstultz/komga-cover-extractor/blob/master/README.md

Commands for manually installing the Komga Cover Extractor. This involves cloning the repository using Git and then installing the required Python packages using pip.

```bash
git clone https://github.com/zachstultz/komga-cover-extractor.git
cd komga-cover-extractor
pip3 install -r requirements.txt
```

--------------------------------

### Configure Python Settings for Komga Cover Extractor

Source: https://github.com/zachstultz/komga-cover-extractor/wiki/How-to-Setup-QBitorrent-Addon-(DOCKER-ONLY)

Modify the settings.py file to configure the Komga Cover Extractor. Set 'uncheck_non_qbit_upgrades_toggle' to True to prevent unnecessary upgrades and fill in your connection details for qBittorrent and Komga. Optionally, set 'delete_unacceptable_torrent_titles_in_qbit' to True to automatically remove torrents with specific keywords.

```python
uncheck_non_qbit_upgrades_toggle = True

# Fill out connection details here
KOMGA_URL = ""
KOMGA_USERNAME = ""
KOMGA_PASSWORD = ""
QBITTORRENT_URL = ""
QBITTORRENT_USERNAME = ""
QBITTORRENT_PASSWORD = ""

# Optional: Set to True to purge torrents whose titles contain an unacceptable keyword.
delete_unacceptable_torrent_titles_in_qbit = True

```

--------------------------------

### Komga Cover Extractor Example: With Compression

Source: https://github.com/zachstultz/komga-cover-extractor/blob/master/README.md

An example demonstrating how to use the Komga Cover Extractor with image compression enabled. This command scans specified paths, compresses extracted covers to 40% quality, and potentially sends notifications via webhook.

```bash
python3 komga_cover_extractor.py -p "/path/to/manga" -p "/path/to/novels" -c "True" -cq "40"
```

--------------------------------

### Komga Cover Extractor Example: Without Compression

Source: https://github.com/zachstultz/komga-cover-extractor/blob/master/README.md

An example of running the Komga Cover Extractor without image compression. This command scans the provided paths and extracts covers at their original resolution.

```bash
python3 komga_cover_extractor.py -p "/path/to/manga" -p "/path/to/novels"
```

--------------------------------

### Install Unrar on Linux (Bash)

Source: https://github.com/zachstultz/komga-cover-extractor/blob/master/README.md

Command to install the 'unrar' utility on Debian-based Linux distributions, which may be required for advanced RAR features in the Komga Cover Extractor.

```bash
sudo apt-get install unrar
```

--------------------------------

### Docker Configuration for Komga Cover Extractor Settings

Source: https://github.com/zachstultz/komga-cover-extractor/wiki/How-to-Setup-QBitorrent-Addon-(DOCKER-ONLY)

Configure Docker to use a custom settings.py file for the Komga Cover Extractor. This ensures that your specific settings are loaded, overriding any default configurations within the container. The volume is mounted read-only.

```yaml
- /path/to/custom/settings.py:/app/settings.py:ro
```

```bash
-v /path/to/custom/settings.py:/app/settings.py:ro \
```

--------------------------------

### Configure Webhook Notifications in CLI

Source: https://context7.com/zachstultz/komga-cover-extractor/llms.txt

Set up webhook notifications for Komga Cover Extractor using the command-line interface. This allows for real-time alerts on various events like execution start, progress, new series detection, and errors. Multiple webhooks can be configured.

```bash
webhook_url = "https://discord.com/api/webhooks/123456789/your-webhook-token"

# Run with webhook notifications
python3 komga_cover_extractor.py \
  -p "/library/manga" \
  -wh webhook_url

# Multiple webhooks supported
python3 komga_cover_extractor.py \
  -p "/library/manga" \
  -wh "webhook1,webhook2,webhook3"
```

--------------------------------

### Install Unrar on MacOS (Bash)

Source: https://github.com/zachstultz/komga-cover-extractor/blob/master/README.md

Command to install the 'rar' utility (which includes unrar functionality) on MacOS using Homebrew. This is an optional step for users who need to process RAR archives.

```bash
brew install rar
```

--------------------------------

### Docker Configuration for Komga Cover Extractor Logs

Source: https://github.com/zachstultz/komga-cover-extractor/wiki/How-to-Setup-QBitorrent-Addon-(DOCKER-ONLY)

Configure Docker to persist logs generated by the Komga Cover Extractor outside the container. This allows you to access and manage logs effectively. The volume maps a local directory to the container's log location.

```yaml
- /path/to/logs/storage/location:/app/logs
```

```bash
-v /path/to/logs/storage/location:/app/logs \
```

--------------------------------

### Discord Webhook Notification Setup

Source: https://context7.com/zachstultz/komga-cover-extractor/llms.txt

The tool integrates with Discord to send rich embedded notifications about file operations, errors, and library updates. This integration uses webhooks to post messages to specified Discord channels, enhancing real-time monitoring and communication for the Komga cover extractor process.

```python
from discord_webhook import DiscordWebhook, DiscordEmbed

```

--------------------------------

### Settings Configuration for Komga Cover Extractor

Source: https://context7.com/zachstultz/komga-cover-extractor/llms.txt

The settings.py file allows granular control over various processing features using toggle flags and configuration parameters. It manages cover extraction, file conversion, renaming, duplicate checking, and integration settings for Komga and qBittorrent. Settings are imported at runtime and persist across runs.

```python
# settings.py configuration example

# Enable/disable core features
extract_covers_toggle = True  # Extract covers from manga/novel files
convert_to_cbz_toggle = False  # Convert RAR/CBR/7zip to CBZ
delete_chapters_from_downloads_toggle = False  # Remove chapter releases
check_for_duplicate_volumes_toggle = False  # Find and remove duplicates
rename_files_in_download_folders_toggle = False  # Standardize file names

# Renaming configuration
preferred_volume_renaming_format = "v"  # Results in: "Series v01.cbz"
add_volume_one_number_to_one_shots = False  # Add v01 to one-shots
manual_rename = True  # Prompt for approval before renaming

# Cover extraction settings
compare_detected_cover_to_blank_images = False  # Avoid blank covers
use_latest_volume_cover_as_series_cover = False  # Use latest instead of v01
output_covers_as_webp = False  # Output WebP instead of JPG

# Image compression
compress_image_option = False  # Set via CLI with -c flag
image_quality = 40  # JPEG quality (1-100), set via CLI with -cq

# Upgrading configuration
match_through_identifiers = False  # Match via ISBN/series_id
required_similarity_score = 0.9790  # String matching threshold (0.0-1.0)

# Quality scoring keywords for upgrade detection
from settings import Keyword

ranked_keywords = [
    Keyword(r"Digital", 10, "both"),
    Keyword(r"Official", 8, "both"),
    Keyword(r"HQ", 5, "both"),
    Keyword(r"LQ", -5, "both"),
]

# Komga integration
send_scan_request_to_komga_libraries_toggle = False
komga_ip = "http://localhost"
komga_port = "25600"
komga_login_email = "admin@example.com"
komga_login_password = "your_password"

# qBittorrent integration
uncheck_non_qbit_upgrades_toggle = False
qbittorrent_ip = "localhost"
qbittorrent_port = "8080"
qbittorrent_target_category = "manga"
qbittorrent_username = ""  # Optional
qbittorrent_password = ""  # Optional

# Expected behavior:
# - All toggle features are disabled unless explicitly enabled
# - Settings are imported at runtime into main script
# - Each toggle independently controls a specific feature
# - Configuration persists across runs

```

--------------------------------

### Run with Download Folder Processing and Series Matching

Source: https://context7.com/zachstultz/komga-cover-extractor/llms.txt

This command initiates the Komga Cover Extractor with both download folder processing and series matching enabled via the CLI. It specifies the library and download paths, allowing the script to automatically find, match, and integrate new downloads into the existing library structure.

```bash
# Run with download folder processing
python3 komga_cover_extractor.py \
  -p "/library/manga" \
  --download_folders "/downloads/manga"
```

--------------------------------

### Docker Deployment for Komga Cover Extractor

Source: https://context7.com/zachstultz/komga-cover-extractor/llms.txt

This project includes a Dockerfile for containerized deployment. Users can build the image with default settings or enable optional addons like manga ISBN tagging and EPUB conversion. The container can be run with environment variables to configure paths, download folders, webhooks, compression settings, and watchdog mode, utilizing mounted volumes for data persistence.

```bash
# Build the Docker image with default settings
docker build -t komga-cover-extractor .

# Build with optional manga ISBN addon
docker build --build-arg MANGA_ISBN=true -t komga-cover-extractor .

# Build with EPUB converter addon
docker build --build-arg EPUB_CONVERTER=true -t komga-cover-extractor .

# Run the container with environment variables
docker run -d \
  --name komga-cover-extractor \
  -e PATHS="/library/manga\1/library/novels" \
  -e DOWNLOAD_FOLDERS="/downloads/manga" \
  -e WEBHOOK="https://discord.com/api/webhooks/your-url" \
  -e COMPRESS="True" \
  -e COMPRESS_QUALITY="40" \
  -e WATCHDOG="True" \
  -v /host/library:/library:ro \
  -v /host/downloads:/downloads \
  komga-cover-extractor

# With BookWalker release checking
docker run -d \
  --name komga-cover-extractor \
  -e PATHS="/library/manga" \
  -e BOOKWALKER_CHECK="True" \
  -e BOOKWALKER_WEBHOOK_URLS="https://webhook1,https://webhook2" \
  -v /host/library:/library \
  komga-cover-extractor

# Expected behavior:
# - Runs as non-root appuser (PUID/PGID configurable)
# - Monitors paths for changes in watchdog mode
# - Extracts covers automatically
# - Sends notifications via Discord webhook
# - Persists data through mounted volumes

```

--------------------------------

### Configure qBittorrent Addon for Unchecking Non-Upgrades

Source: https://context7.com/zachstultz/komga-cover-extractor/llms.txt

Integrate the Komga Cover Extractor with qBittorrent to automatically uncheck torrents that are not upgrades to existing files in your library. This prevents unnecessary downloads and saves bandwidth. Configuration involves setting qBittorrent credentials and enabling specific toggles in `settings.py`.

```python
# addons/qbit_torrent_unchecker/qbit_torrent_unchecker.py

# Configure qBittorrent credentials in settings.py
qbittorrent_ip = "localhost"
qbittorrent_port = "8080"
qbittorrent_target_category = "manga"
qbittorrent_username = "admin"
qbittorrent_password = "adminpass"

# Enable features in settings.py
uncheck_non_qbit_upgrades_toggle = True
check_for_existing_series_toggle = True

# Run addon standalone
python3 addons/qbit_torrent_unchecker/qbit_torrent_unchecker.py \
  -p "/library/manga" \
  -df "/downloads/manga"

# Or run automatically via Docker (addon runs in background)
# The addon:
# 1. Connects to qBittorrent API
# 2. Monitors paused/stopped torrents in target category
# 3. Checks if torrent would be upgrade to existing file
# 4. Unchecks non-upgrades automatically
# 5. Logs all decisions to qbit_torrent_unchecker_log

```

--------------------------------

### Command-Line Interface for Komga Cover Extractor

Source: https://context7.com/zachstultz/komga-cover-extractor/llms.txt

The script's CLI allows various library management operations with configurable parameters. Users can specify paths, enable/disable compression, set compression quality, and configure Discord webhook notifications. It also supports a watchdog mode for real-time monitoring of download directories and can output covers in WebP format.

```bash
# Basic cover extraction with compression
python3 komga_cover_extractor.py \
  -p "/media/library/manga" \
  -p "/media/library/light-novels" \
  -c "True" \
  -cq "40"

# Without compression (preserve original quality)
python3 komga_cover_extractor.py \
  -p "/media/library/manga" \
  -p "/media/library/novels"

# With Discord webhook notifications
python3 komga_cover_extractor.py \
  -p "/media/library/manga" \
  -wh "https://discord.com/api/webhooks/your-webhook-url" \
  -c "True" \
  -cq "50"

# Watchdog mode for real-time monitoring
python3 komga_cover_extractor.py \
  -p "/media/library/manga" \
  --download_folders "/downloads/manga" \
  --watchdog "True" \
  --webhook "https://discord.com/api/webhooks/your-webhook-url"

# Output covers as WebP format instead of JPG
python3 komga_cover_extractor.py \
  -p "/media/library/manga" \
  --output_covers_as_webp "True"

# Expected behavior:
# - Scans all paths recursively
# - Extracts cover images from supported archive formats
# - Compresses images if enabled (default quality: 40)
# - Sends Discord notifications about changes and errors
# - Watchdog mode monitors download folders for new files

```

--------------------------------

### Enable Watchdog via Docker

Source: https://context7.com/zachstultz/komga-cover-extractor/llms.txt

This Docker command runs the Komga Cover Extractor with the watchdog feature enabled using environment variables. It maps host directories for library and downloads, and configures watchdog parameters. The watchdog processes files after transfer completion, verifies file types, and handles various file system events.

```bash
docker run -d \
  -e PATHS="/library/manga" \
  -e DOWNLOAD_FOLDERS="/downloads/manga" \
  -e WATCHDOG="True" \
  -e WATCHDOG_DISCOVER_NEW_FILES_CHECK_INTERVAL="5" \
  -e WATCHDOG_FILE_TRANSFERRED_CHECK_INTERVAL="1" \
  -v /host/library:/library \
  -v /host/downloads:/downloads \
  komga-cover-extractor
```

--------------------------------

### Enable Watchdog via CLI

Source: https://context7.com/zachstultz/komga-cover-extractor/llms.txt

This command enables the watchdog feature for the Komga Cover Extractor using the Python CLI. It specifies library and download paths, enables watchdog, and sets intervals for discovering new files and checking file transfers. The watchdog monitors for new, moved, or modified files and directories.

```bash
python3 komga_cover_extractor.py \
  -p "/library/manga" \
  --download_folders "/downloads/manga" \
  --watchdog "True" \
  --watchdog_discover_new_files_check_interval "5" \
  --watchdog_file_transferred_check_interval "1"
```

--------------------------------

### Configure Watchdog Intervals in Python

Source: https://context7.com/zachstultz/komga-cover-extractor/llms.txt

These Python settings in `settings.py` define the intervals for the watchdog's file monitoring. `watchdog_discover_new_files_check_interval` sets how often the script scans for new files, while `watchdog_file_transferred_check_interval` determines the frequency of checks to ensure file transfers are complete. `auto_classify_watchdog_paths` controls automatic detection of library types.

```python
# Settings for watchdog behavior in settings.py
watchdog_discover_new_files_check_interval = 5  # Seconds between scans
watchdog_file_transferred_check_interval = 1  # Seconds between size checks
auto_classify_watchdog_paths = False  # Auto-detect library types
```

--------------------------------

### Enable Series Matching in Python

Source: https://context7.com/zachstultz/komga-cover-extractor/llms.txt

This Python configuration enables and sets parameters for series matching in the Komga Cover Extractor. `check_for_existing_series_toggle` activates the matching feature, while `required_similarity_score` defines the minimum string similarity needed to consider a match. Caching is also enabled for performance.

```python
# Enable series matching in settings.py
check_for_existing_series_toggle = True
required_similarity_score = 0.9790  # 97.9% match required

# Configure cache for faster matching
cache_each_root_for_each_path_in_paths_at_beginning_toggle = True
```

--------------------------------

### Configure Similarity Matching Thresholds

Source: https://context7.com/zachstultz/komga-cover-extractor/llms.txt

These Python settings define the thresholds for similarity matching. `required_similarity_score` sets the minimum string similarity for a match, while `match_through_image_similarity` enables image-based comparison, with `required_image_similarity_score` setting the threshold for cover image similarity.

```python
# Similarity matching configuration
required_similarity_score = 0.9790  # String similarity threshold
match_through_image_similarity = True  # Compare cover images
required_image_similarity_score = 0.9  # Image similarity threshold
```

--------------------------------

### Komga Cover Extractor CLI Usage

Source: https://github.com/zachstultz/komga-cover-extractor/blob/master/README.md

The command-line interface for the Komga Cover Extractor script. It allows users to specify paths for scanning, configure compression settings, and optionally provide Discord webhook URLs for notifications.

```bash
python3 komga_cover_extractor.py [-h] [-p [PATHS [PATHS ...]]] -wh WEBHOOK1,WEBHOOK2,upto N [-c COMPRESS] [-cq COMPRESS_QUALITY]
```

--------------------------------

### File Type Detection using File Headers

Source: https://context7.com/zachstultz/komga-cover-extractor/llms.txt

This script uses file header detection to verify the actual file type, irrespective of the file extension. The `get_header_extension()` function reads the file's magic numbers to determine its true format, supporting common archives and image types. This prevents processing errors caused by misnamed files and can be automatically corrected if `correct_file_extensions_toggle` is enabled in settings.

```python
import filetype
from komga_cover_extractor import get_header_extension

# Detect actual file type from header
file_path = "/downloads/manga/series_v01.cbz"
actual_extension = get_header_extension(file_path)

# Returns the true extension based on file magic numbers:
# - ".zip" for ZIP/CBZ files (PK header)
# - ".rar" for RAR/CBR files
# - ".7z" for 7-Zip files
# - ".epub" for EPUB files (ZIP-based)
# - ".jpg", ".png", ".webp" for images
# - None if unrecognized

if actual_extension != ".cbz":
    print(f"Warning: File has wrong extension. Actual type: {actual_extension}")

# Correct wrong extensions automatically
from komga_cover_extractor import correct_file_extensions_toggle

# In settings.py, enable:
# correct_file_extensions_toggle = True

# Expected behavior:
# - Reads first bytes of file to determine format
# - Independent of file extension
# - Prevents processing errors from misnamed files
# - Supports all common archive and image formats

```

--------------------------------

### Extract Covers from Archives using Python

Source: https://context7.com/zachstultz/komga-cover-extractor/llms.txt

This Python function recursively scans specified directories for supported archive files (CBZ, ZIP, EPUB, RAR, CBR, 7Z) and extracts the first image as a cover. It saves the cover as 'cover.jpg' or 'cover.webp' in the parent folder and logs the extraction count. The function ensures that processed folders have updated modification timestamps.

```python
#!/usr/bin/env python3
from komga_cover_extractor import extract_covers

# Define library paths to scan for cover extraction
paths_to_process = [
    "/media/library/manga",
    "/media/library/light-novels"
]

# Extract covers from all archive files in the specified paths
# This will:
# - Scan all subdirectories recursively
# - Open CBZ, ZIP, EPUB, RAR, CBR, and 7Z files
# - Extract the first image or cover page
# - Save as cover.jpg or cover.webp in the parent folder
extract_covers(paths_to_process=paths_to_process)

# Expected output:
# - Creates cover.jpg files in each series folder
# - Logs extraction count and any errors
# - Updates modification timestamps to track processed folders

```

--------------------------------

### Extract Series Name and Volume from Filename

Source: https://context7.com/zachstultz/komga-cover-extractor/llms.txt

This Python code demonstrates how to use the `komga_cover_extractor` library to parse filenames and extract the series name and volume number. It supports various common naming conventions for comic book and manga files.

```python
from komga_cover_extractor import get_series_name_from_volume

# Parse various file name formats
examples = [
    "Series Name v01 (2020) (Digital) (Publisher).cbz",
    "Series Name Volume 01 (2020).cbz",
    "Series Name - Vol. 01.cbz",
    "[Publisher] Series Name v01.epub",
    "Series Name LN01 (Light Novel).epub",
]

for filename in examples:
    series_name = get_series_name_from_volume(
        name=filename,
        root="/library/manga",
        test_mode=True
    )
    print(f"{filename} -> {series_name}")

# Volume number extraction
from komga_cover_extractor import contains_volume_keywords
import re

filename = "Series Name v01 (2020).cbz"
if contains_volume_keywords(filename):
    # Extract volume number using regex
    volume_match = re.search(r'v(\d+)', filename, re.IGNORECASE)
    if volume_match:
        volume_number = volume_match.group(1)
        print(f"Volume number: {volume_number}")

```

--------------------------------

### Define Ranked Keywords for Series Matching Scoring

Source: https://context7.com/zachstultz/komga-cover-extractor/llms.txt

This Python code defines a list of `Keyword` objects used for scoring series matches. Each keyword has a regular expression and an associated score, allowing the script to prioritize certain attributes (like 'Digital' or 'Official') when comparing downloaded files to existing library entries.

```python
# Example ranked keywords for scoring
from settings import Keyword

ranked_keywords = [
    Keyword(r"(Digital|デジタル)", 10),
    Keyword(r"Official", 8),
    Keyword(r"(Premium|Bookwalker)", 5),
    Keyword(r"(HQ|High(-| )Quality)", 3),
    Keyword(r"(Repack|Fixed)", 2),
    Keyword(r"(LQ|Low(-| )Quality)", -5),
    Keyword(r"(Watermark|WM)", -8),
]
```

--------------------------------

### Compress Image Function for Komga Cover Extractor

Source: https://context7.com/zachstultz/komga-cover-extractor/llms.txt

The `compress_image()` function reduces the file size of extracted cover images. It can process image files directly or raw image data, allowing for adjustable JPEG quality and conversion to JPG format. The function overwrites the original file if an `image_path` is provided, or returns compressed bytes if `raw_data` is used.

```python
from komga_cover_extractor import compress_image
from PIL import Image

# Compress an existing image file
image_path = "/library/manga/Series Name/cover.jpg"
compress_image(
    image_path=image_path,
    quality=60,  # JPEG quality 1-100
    to_jpg=False  # Convert PNG to JPG if True
)

# Compress raw image data
with open("original_cover.jpg", "rb") as f:
    raw_image_data = f.read()

compressed_data = compress_image(
    image_path=None,
    quality=40,
    to_jpg=True,
    raw_data=raw_image_data
)

# Save compressed result
with open("compressed_cover.jpg", "wb") as f:
    f.write(compressed_data)

# Typical quality settings:
# - quality=90: Minimal compression, ~10-20% size reduction
# - quality=60: Balanced, ~50% size reduction
# - quality=40: High compression, ~70% size reduction
# - quality=20: Maximum compression, noticeable artifacts

# Expected behavior:
# - Reduces file size while preserving visual quality
# - Maintains aspect ratio and dimensions
# - Returns compressed bytes when raw_data is provided
# - Overwrites original file when image_path is provided

```
Tokens:
Raw