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
149 lines
4.2 KiB
Markdown
149 lines
4.2 KiB
Markdown
# 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`, `.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` | 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
|
|
```json
|
|
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
|
|
```json
|
|
POST /api/scanner/watch/start
|
|
{
|
|
"library_id": "manga-library-uuid"
|
|
}
|
|
```
|
|
|
|
### Check Scan Progress
|
|
```http
|
|
GET /api/scanner/status/550e8400-e29b-41d4-a716-446655440000
|
|
```
|
|
|
|
## Related Endpoints
|
|
|
|
- [Scan Ebooks](scan_ebooks.md) - Manual one-time scan
|
|
- [Start Scanner](start_scanner.md) - Automated periodic scanning
|
|
- [Stop Scanner](stop_scanner.md) - Stop automated scanner
|
|
- [Get Scan Status](get_scan_status.md) - Check scan progress
|
|
- [Start Watch Mode](start_watch_mode.md) - Enable real-time monitoring
|
|
- [Stop Watch Mode](stop_watch_mode.md) - Disable watch mode
|
|
- [Get Watch Mode Status](get_watch_mode_status.md) - Check watch status
|