john-okeefe
4d321528b2
This commit updates all documentation files throughout the project: - Updated IMPLEMENTATION_PLAN.md with new implementation details - Updated PROJECT_GUIDELINES.md with coding standards and practices - Updated README.md with current project information - Updated SCREENSHOT_AUTOMATION.md with new automation details - Added TEST_DATA.md with test fixtures data - Updated cover_image_serving_plan.md with static URL patterns Documentation API updates: - Updated API reference documentation for all endpoints including: - Authentication (login, logout, register, refresh_token) - Book matching (auto_link, bulk_link, link_book, search) - Collections (CRUD operations, shelf mappings, auto-assign rules) - Conflicts (bulk operations, resolve/dismiss) - Devices (registration, approval, shelf management) - Highlights (create, update, delete, get) - Kobo sync (bookmark, markup, initialization, sync) - KOReader sync (library, metadata, bookmarks, progress) - Libraries (CRUD, folders, media items, stats) - Media items (bulk operations, CRUD) - Notes (CRUD operations) - OPDS (acquisition, feeds, publication) - Progress (reading progress tracking) - Queue (device queue management) - Ratings (star ratings) - Scanner (watch mode, scan operations) - Sync protocols (Kobo, KOReader) - Users (profile, password, admin operations) - WebSocket protocols - Updated user guides (admin, dashboard, settings, sync) - Updated device setup guides (Kobo, KOReader) - Updated developer guides (testing, contributing, operations) - Updated scripts/README.md
4.5 KiB
4.5 KiB
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 |
|
| Kindle | .mobi, .azw, .azw3 |
| 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 |
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
Related Endpoints
- 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