[Kavita] Idea / Feature Submission: Automatic BookImport for Kavita

[pkhanpara]

Idea Description

Summary

BookImport enables zero-effort book file imports into a library folder. Kavita automatically detects, processes, and organizes files according to the Scanner's directory structure requirements, eliminating manual intervention except for choosing library when adding new books.

---

Problem & Solution

Challenges:

• Manual file organization into appropriate directory structures
• Consistent file naming across diverse formats (EPUB, PDF, CBZ, CBR)
• Time-consuming metadata extraction

Solution:
An automated workflow that monitors an import folder, extracts metadata, creates Scanner-compatible directory structures, and integrates files into the library catalog.

---

Workflow Architecture

User Action → Monitor Files → Extract Metadata → Organize & Rename → Finalize Import
     ↓              ↓                ↓                 ↓                  ↓
  Upload      File System       Pattern-based    Directory           Library
  Files       Events            Naming           Creation            Catalog

Watched Folder Structure:

/bookimport/
├── uploaded/              # New files awaiting processing
│   ├── epub/
│   ├── pdf/
│   └── comics/
├── temp-downloads/        # Temporary processing files
├── cover-images/          # Extracted covers
└── processed/             # Finalized files ready for library

---

Core Components

1. BookimportMonitoringService

• File System Monitoring: OS-level event detection for file creation, modification, deletion
• Stability Checks: Validates complete file transfers before processing
• Format Filtering: Supports EPUB, PDF, CBZ, CBR, and image formats

2. BookimportMetadataService

• Data Model:

  BookimportFileEntity
  ├── id, filePath, fileName, fileSize
  ├── status: PENDING_REVIEW | FINALIZED
  ├── originalMetadata: {title, authors, format, publicationDate, coverImage}
  └── assignedLibrary, targetPath, timestamps
  

3. FilenamePatternExtractor

• Supported Placeholders:

Placeholder	Pattern	Example
{Title}	(.+?)	Harry Potter
{SeriesNumber}	(\d+(\.\d+)?)	Vol.01
{Published}	(.+?)	2024
{ISBN13}	([0-9]{13})	9780747532699

• Naming Templates:
  • Book: {Title} - {SeriesName} - Vol.{SeriesNumber}.{Extension}
  • Manga: [{Publisher}] {Title} - Vol.{SeriesNumber} Ch.{SeriesNumber}.{Extension}
  • Light Novel: {Title} - {Authors} - {SeriesName} - {SeriesNumber}.epub

4. BookimportBulkService

• Library assignment and path optimization
• Bulk operations for mass file processing
• File movement and catalog integration

---

Directory Structure (Scanner-Compatible)

Target Library Layout:

/library/
│── {Series}/
│       ├── {Title}-v{Vol}-c{Chap}.cbz
│       └── [Specials]/
├──{Title}/
│      ├── {Title}-v{Vol}.epub
└── {Series}/
│      ├── {Chapter}
│            ├──{image}.png

Content Type Classification:

Library Type	Formats	Pattern
Manga	CBZ, CBR	{Title}-v{Vol}-c{Chap}.cbz
Book	EPUB, PDF	{Title}-Vol.{Number}.{ext}
LightNovel	EPUB, PDF	{Title}-v{Number}.{ext}
Image	PNG, JPG, WEBP	{Title}-S{Season}-c{Chap}.ext

---

Author Experience

I have used CWA, Booklore, Kavita. I liked the epub reader of Kavita and import functionality of Booklore. I would like to have something similar for Kavita. I have not found an easier way to import books to Kavita. This is help with new adoptions. It will certainly help me. I can take a stab at implementing this.

Idea Category

Feature Enhancement

Duration of Using Kavita

30 days

Before submitting

• I've already searched for existing ideas before posting.

[majora2007]

This is similar to #2668.

I have no plans to build an importer system into Kavita. Kavita has an explicit no-modification policy for file mounts.