john-okeefe
c4607cd9b5
Complete API documentation audit covering all backend endpoints. Auth Endpoints: - Fixed endpoint paths from /api/users/me/* to /api/auth/* - Added update_email.md and update_username.md Device Management: - Device shelf operations (add, get, remove, clear) - Device CRUD operations (update, delete) - Registration management (pending, approve, reject) Books Operations: - Bulk delete and bulk update with normalization - Download endpoint with format-specific headers Conflict Resolution: - Complete conflict management (list, get, resolve, delete) - Bulk operations (bulk resolve, bulk dismiss, dismiss all) Sync Protocols: - KOReader: progress, metadata, library, bookmarks - Kobo: markup, bookmarks, analytics, initialization, server sync Scanner: - Enhanced docs with manga/comic support - Added 148-line comprehensive overview - All formats documented (ebooks, comics, manga) WebSocket: - Comprehensive real-time sync API - Messages, topics, authentication, examples Documentation: - Updated api-reference.md with all 122+ endpoints - Updated index.md with new categories Total: 36 new files, 6 modified files, 100% coverage
4.2 KiB
4.2 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 Ebooks - 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