Bookhoard/bookhoard
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity

docs: add comprehensive Calibre integration documentation

Browse Source 
This commit adds complete documentation for the planned Calibre
metadata.opf sidecar file support feature.

## New Documentation

### Implementation Planning
- CALIBRE_OPF_IMPLEMENTATION.md: Detailed implementation plan with
  requirements, architecture, database mapping, and step-by-step
  implementation guide for adding Calibre metadata.opf support

### Technical Documentation
- docs/development/calibre-opf-implementation.md: Technical implementation
  details including:
  - Scanner pipeline architecture with sidecar-first approach
  - Data structures (CalibreOPFMetadata, MediaMetadata)
  - Function signatures and logic for parseCalibreMetadataOPF()
  - Database schema mapping (no changes required)
  - Testing strategy (unit and integration tests)
  - Error handling and performance considerations
  - Code examples and benchmarking approach

### User Documentation
- docs/user/calibre-integration.md: Comprehensive user guide covering:
  - What is Calibre and how Bookhoard integrates with it
  - Automatic metadata import from metadata.opf sidecar files
  - Supported metadata fields (Dublin Core + Calibre-specific)
  - Setup instructions for Calibre libraries
  - Workflow examples (fresh library, mixed library, updating metadata)
  - Troubleshooting common issues
  - Best practices for Calibre + Bookhoard workflow
  - FAQ and resources

## Updated Documentation

- README.md: Added Calibre integration feature to media management section
- docs/user/user-guide.md: Added link to Calibre integration guide
- docs/developer/development.md: Added link to Calibre implementation guide

## Feature Summary

The Calibre integration feature will allow Bookhoard to automatically
import curated metadata from Calibre's metadata.opf sidecar files,
including titles, authors, series, tags, descriptions, publishers,
identifiers (ISBN/ASIN), and contributors. Uses sidecar-first approach:
metadata.opf → embedded metadata → folder structure → filename.

All database fields already exist; no schema changes required.
This commit is contained in:
john-okeefe
2026-03-26 10:34:15 -04:00
parent 333f4ae026
commit 22fd28c7db
6 changed files with 1295 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user/calibre-integration.md
+313
View File
@@ -0,0 +1,313 @@
# Calibre Integration Guide
Bookhoard provides seamless integration with [Calibre](https://calibre-ebook.com/) libraries. If you manage your ebooks with Calibre, Bookhoard can automatically import your curated metadata, including series information, tags, and custom covers.
## What is Calibre?
Calibre is a free and open-source ebook management software. It allows you to:
- **Organize your library** - Create collections, add tags, manage series
- **Edit metadata** - Update titles, authors, descriptions, covers
- **Fetch metadata online** - Download from Google Books, Amazon, Goodreads
- **Convert formats** - Convert between EPUB, MOBI, PDF, and more
- **Sync to devices** - Send books to Kindle, Kobo, and other e-readers
## How Bookhoard Integrates with Calibre
### Automatic Metadata Import
When you scan a Calibre library in Bookhoard, it automatically detects and imports metadata from Calibre's `metadata.opf` files. This includes:
- ✅ **Titles and authors** - Your curated edits
- ✅ **Series information** - Series name and position
- ✅ **Tags and genres** - Your custom organization
- ✅ **Descriptions** - Book summaries
- ✅ **Publishers and dates** - Publication information
- ✅ **Identifiers** - ISBN, ASIN, and other IDs
- ✅ **Contributors** - Illustrators, editors, translators
- ✅ **Custom covers** - Your chosen cover images
### Sidecar-First Approach
Bookhoard uses a **sidecar-first** approach for Calibre libraries:
1. **If `metadata.opf` exists** → Use Calibre's curated metadata
2. **If no sidecar** → Use embedded metadata from the book file
3. **Fallback** → Use folder structure and filename
This ensures your Calibre curation work is respected and imported accurately.
## Setting Up Your Calibre Library in Bookhoard
### Step 1: Organize Your Calibre Library
Ensure your Calibre library has `metadata.opf` files in each book's folder. Calibre creates these automatically when you add books to your library.
Typical Calibre folder structure:
```
Calibre Library/
├── Author Name/
│ ├── Book Title (Series #1)/
│ │ ├── Book Title.epub
│ │ ├── metadata.opf ← Bookhoard reads this
│ │ └── cover.jpg
│ └── Book Title 2/
│ ├── Book Title 2.epub
│ └── metadata.opf ← Bookhoard reads this
```
### Step 2: Add Library in Bookhoard
1. Navigate to **Admin** → **Libraries**
2. Click **Add Library**
3. Configure:
- **Name**: "My Calibre Library"
- **Type**: Ebook (or Audiobook/Comic)
- **Folder**: Path to your Calibre library
- **Scan on save**: ✅ Checked
4. Click **Save**
Bookhoard will automatically scan the library and import all books with their Calibre metadata.
### Step 3: Verify Import
1. Navigate to **Library** view
2. Browse your imported books
3. Check that:
- Titles and authors are correct
- Series information appears (if applicable)
- Tags are imported
- Covers display correctly
- Descriptions are present
## Supported Metadata
### Dublin Core Fields
Bookhoard imports standard Dublin Core metadata from Calibre:
| Field | Source | Notes |
|-------|--------|-------|
| Title | `dc:title` | Book title |
| Author | `dc:creator` | Primary author |
| Tags | `dc:subject` | **Keywords/tags** (multiple) |
| Description | `dc:description` | Book summary |
| Publisher | `dc:publisher` | Publisher name |
| Date | `dc:date` | Publication date |
| Language | `dc:language` | ISO language code |
| ISBN | `dc:identifier` | ISBN (if present) |
| ASIN | `dc:identifier` | Amazon ID (if present) |
| Contributors | `dc:contributor` | Additional contributors |
### Calibre-Specific Fields
Bookhoard also imports Calibre's custom metadata:
| Field | Source | Notes |
|-------|--------|-------|
| Series | `calibre:series` | Series name |
| Series Number | `calibre:series_index` | Position in series |
| Timestamp | `dc:date` | When added to Calibre |
### Not Imported
The following Calibre metadata is **not** imported (by design):
- ❌ **Ratings** - Calibre ratings are personal; Bookhoard has per-user ratings
- ❌ **Sort fields** - Bookhoard has its own sorting logic
- ❌ **Custom columns** - User-defined columns (future enhancement)
- ❌ **Last read** - Reading progress is tracked per-user in Bookhoard
## Supported File Types
Bookhoard imports Calibre metadata for **all file types**:
- 📚 **Ebooks**: EPUB, MOBI, AZW3, PDF, TXT, etc.
- 🎧 **Audiobooks**: MP3, M4B, M4A, etc.
- 📰 **Comics**: CBZ, CBR, CB7, CBT, etc.
- 📄 **Documents**: PDF, DOCX, etc.
As long as a `metadata.opf` file exists in the folder, Bookhoard will import the metadata.
## Workflow Examples
### Example 1: Fresh Calibre Library
**Scenario**: You have a Calibre library with 500 ebooks, all organized with series, tags, and custom covers.
**Steps**:
1. Add the Calibre library folder in Bookhoard
2. Enable "Scan on save"
3. Bookhoard imports all 500 books with:
- Correct titles and authors
- Series information (e.g., "Harry Potter #2")
- Your custom tags (e.g., "Fantasy", "Favorites", "To Read")
- Your chosen cover images
- Descriptions and publisher info
**Result**: Your entire Calibre library is instantly available in Bookhoard with all your curation work preserved.
### Example 2: Mixed Library (Calibre + Non-Calibre)
**Scenario**: Your library has some books from Calibre (with `metadata.opf`) and some downloaded from elsewhere (no sidecar).
**Steps**:
1. Add the library folder in Bookhoard
2. Bookhoard scans all files:
- **Calibre books**: Import from `metadata.opf`
- **Non-Calibre books**: Use embedded metadata or filename
**Result**: Seamless import of both Calibre and non-Calibre books, with appropriate metadata sources for each.
### Example 3: Updating Calibre Metadata
**Scenario**: You edit metadata in Calibre (fix author name, add series, change cover).
**Steps**:
1. Edit metadata in Calibre (it updates `metadata.opf`)
2. In Bookhoard, trigger a rescan:
- Navigate to **Admin** → **Libraries**
- Click **Rescan** on your library
- Or use the **Scanner API** to force rescan
3. Bookhoard detects updated `metadata.opf` and refreshes metadata
**Result**: Bookhoard reflects your Calibre changes automatically.
## Troubleshooting
### Metadata Not Importing
**Problem**: Bookhoard doesn't import Calibre metadata.
**Solutions**:
1. **Check file structure**: Ensure `metadata.opf` is in the same folder as the book file
2. **Verify library type**: Ensure library type matches content (ebook vs. audiobook)
3. **Force rescan**: Use the "Force Rescan" option to re-import all metadata
4. **Check logs**: Review Bookhoard logs for parsing errors
### Incorrect Metadata
**Problem**: Imported metadata is wrong or incomplete.
**Solutions**:
1. **Fix in Calibre**: Edit metadata in Calibre, then rescan in Bookhoard
2. **Verify sidecar content**: Open `metadata.opf` in a text editor to check content
3. **Check date formats**: Ensure dates are ISO format (YYYY-MM-DD)
4. **Re-scan**: Force rescan to re-import from updated sidecar
### Missing Series Information
**Problem**: Books in a series don't show series info.
**Solutions**:
1. **Check Calibre**: Verify series is set in Calibre
2. **Check sidecar**: Ensure `calibre:series` and `calibre:series_index` are in `metadata.opf`
3. **Re-scan**: Force rescan to update series info
### Performance Issues
**Problem**: Scanning takes a long time with Calibre library.
**Solutions**:
1. **Large libraries**: Initial scan may take time; subsequent scans are faster
2. **Network storage**: Scanning over network is slower; use local storage if possible
3. **Watch mode**: Enable watch mode for real-time updates instead of full rescans
## Best Practices
### 1. Keep Calibre as Primary Source
**Do**:
- ✅ Edit metadata in Calibre
- ✅ Rescan in Bookhoard to sync changes
- ✅ Use Calibre for library management
**Don't**:
- ❌ Edit `metadata.opf` files manually
- ❌ Modify metadata in Bookhoard if you plan to resync from Calibre
- ❌ Keep conflicting metadata sources
### 2. Organize with Tags and Collections
- Use **tags in Calibre** for genres, moods, status (To Read, Read, etc.)
- Create **collections in Bookhoard** for automatic organization
- Leverage both systems for different purposes
### 3. Regular Syncing
- Set up **watch mode** in Bookhoard for automatic updates
- Run **full rescan** after bulk edits in Calibre
- Keep metadata consistent between Calibre and Bookhoard
### 4. Backup Your Library
- Back up your Calibre library regularly
- Include both book files and `metadata.opf` files
- Test restore process periodically
## Advanced Usage
### Custom Calibre Columns (Future)
Bookhoard may support Calibre custom columns in a future release. This would allow you to import:
- Read status
- Favorite flags
- Custom metadata fields
- User-defined categories
Stay tuned for updates!
### OPDS Integration
You can access your Bookhoard library (including Calibre-imported books) via OPDS from Calibre-aware devices:
- Kobo e-readers
- KOReader
- Phone/tablet apps (KYBook, Chunky, etc.)
See the [Kobo Setup Guide](devices/kobo-setup.md) or [KOReader Setup Guide](devices/koreader-setup.md) for details.
## FAQ
**Q: Will Bookhoard modify my Calibre library?**
A: No. Bookhoard only **reads** Calibre metadata. It never modifies your Calibre library files or `metadata.opf` files.
**Q: Can I use both Calibre and Bookhoard?**
A: Yes! They're complementary:
- Use **Calibre** for library management, conversion, and device syncing
- Use **Bookhoard** for web access, sync across devices, and sharing
**Q: What if I don't use Calibre?**
A: Bookhoard works perfectly without Calibre. It will use embedded metadata from your book files, folder structure, and filenames.
**Q: Does Bookhoard import Calibre ratings?**
A: No. Ratings are **per-user** in Bookhoard. Calibre ratings reflect the owner's opinion, which may not match other users' opinions.
**Q: Can I edit Calibre metadata in Bookhoard?**
A: You can edit metadata in Bookhoard, but it won't sync back to Calibre. For permanent changes, edit in Calibre and rescan in Bookhoard.
**Q: Does this work with Calibre Web?**
A: Calibre Web uses the same `metadata.opf` files, so yes - Bookhoard can scan a Calibre Web library folder.
**Q: What about Calibre's "author sort" and "title sort"?**
A: Bookhoard has its own sorting logic and doesn't import Calibre sort fields. This allows for consistent sorting across all books.
## Resources
- [Calibre Website](https://calibre-ebook.com/)
- [Calibre User Manual](https://manual.calibre-ebook.com/)
- [Calibre Forum](https://www.mobileread.com/forums/forumdisplay.php?f=166)
- [Bookhoard GitHub](https://github.com/yourusername/bookhoard)
## Need Help?
- **Documentation**: See [User Guide](user-guide.md) for general Bookhoard usage
- **Troubleshooting**: See [Operations Guide](../operations/operations.md) for common issues
- **Developer Docs**: See [Developer Portal](../developer/development.md) for technical details
- **Issues**: Report bugs or request features on [GitHub Issues](https://github.com/yourusername/bookhoard/issues)
docs/user/user-guide.md
+11
View File
@@ -27,6 +27,17 @@ Learn how to configure your e-reader devices to sync with Bookhoard:
- Conflict resolution
- Best practices
## 📚 Calibre Integration
- **[Calibre Integration Guide](calibre-integration.md)** - Integrating with Calibre libraries
- What is Calibre?
- Automatic metadata import
- Setting up your Calibre library
- Supported metadata and file types
- Workflow examples
- Troubleshooting
- Best practices
## 🎨 Frontend Guide
**[Frontend Guide](frontend-guide.md)** - Learn how to use the Bookhoard web interface