Files

T

John O'Keefe 0be70f0051 docs: drop AZW3 from documented format expectations

AZW3/KF8 is a proprietary legacy Amazon format (the pipeline moved to
KFX in 2015; KDP dropped MOBI-family uploads in 2022) and does not
render in the web reader. The scanner still ingests .azw/.azw3 files
(code unchanged) — they are simply no longer documented as a supported
expectation.

2026-09-30 21:22:44 -04:00

4.5 KiB

Raw Blame History

Library Scanner Overview

The Bookhoard scanner provides comprehensive library management for ebooks, comics, and manga with both manual and automated scanning capabilities.

Scanner Types

Manual Scanning

One-time scan: On-demand scanning of library folders
Progress tracking: Real-time status updates with file-by-file progress
Error reporting: Detailed logs of failed files with error messages

Automated Scanner

Periodic scanning: Configurable interval-based background scanning
Automatic discovery: Detects new files without manual intervention
Resource-efficient: Minimizes system impact with smart scheduling

Watch Mode

Real-time monitoring: Instant detection of file system changes
Event-driven: Processes files immediately upon addition/modification
Platform support: Works with inotify (Linux), FSEvents (macOS), and ReadDirectoryChangesW (Windows)

Supported Formats

Ebooks

Format	Extensions
EPUB	`.epub`
PDF	`.pdf`
Kindle	`.mobi`
Text	`.txt`, `.rtf`
Document	`.doc`, `.docx`
Other	`.lit`, `.fb2`, `.pdb`

Comics

Format	Extensions	Archive Type
Comic Book ZIP	`.cbz`	ZIP
Comic Book RAR	`.cbr`	RAR
Comic Book 7z	`.cb7`	7-Zip
Comic Book TAR	`.cbt`	TAR
PDF Comics	`.pdf`	PDF

Manga

Format	Extensions	Notes
Comic Archives	`.cbz`, `.cbr`	Same as comics
Image Files	`.png`, `.jpg`, `.jpeg`, `.gif`, `.bmp`, `.webp`	Individual pages

Metadata Extraction

Comic Archives (.cbz, .cbr, .cb7, .cbt)

The scanner automatically extracts metadata from comic archives:

ComicInfo.xml Support:

Series title
Issue number
Publisher
Writer, artist, inker, colorist
Year, month
Genre, tags
Cover image extraction

Fallback Metadata:

Filename parsing
Archive structure analysis
Page count detection

Manga Processing

Archive-based: Processes .cbz/.cbr files like comics
Image-based: Handles directories of sequential images
Chapter detection: Identifies chapter/volume numbers from filenames
Series grouping: Groups images into logical manga volumes

Scanner Features

Smart Deduplication

SHA256 hash calculation for all files
Automatic duplicate detection and skipping
Efficient incremental updates

Library Type Awareness

Format filtering based on library type
Type-specific metadata extraction
Appropriate thumbnail generation

Error Handling

Continues on individual file errors
Detailed error reporting in scan status
Failed file tracking for retry

Progress Tracking

Total files vs. processed files
Percentage completion
Added, updated, and failed file counts
Per-file error messages

Performance Considerations

Large Libraries

Scanning speed: Processes hundreds of files per second
Memory usage: Streaming metadata extraction
Database efficiency: Batch inserts and updates

Resource Limits

Configurable intervals: Prevent excessive scanning
Rate limiting: Watch mode debounce settings
Admin controls: Start/stop operations as needed

Usage Examples

Create and Scan a Comic Library

POST /api/libraries
{
  "name": "My Comic Collection",
  "library_type_id": "comics-type-uuid",
  "description": "Marvel and DC comics"
}

POST /api/scanner/scan
{
  "library_id": "library-uuid",
  "recursive": true
}

Enable Watch Mode for Manga

POST /api/scanner/watch/start
{
  "library_id": "manga-library-uuid"
}

Check Scan Progress

GET /api/scanner/status/550e8400-e29b-41d4-a716-446655440000

Scan Library - Manual one-time scan
Start Scanner - Automated periodic scanning
Stop Scanner - Stop automated scanner
Get Scan Status - Check scan progress
Start Watch Mode - Enable real-time monitoring
Stop Watch Mode - Disable watch mode
Get Watch Mode Status - Check watch status

4.5 KiB Raw Blame History