bookhoard/docs/user/calibre-integration.md

Calibre Integration Guide

Bookhoard provides seamless integration with Calibre 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. Open the Administration panel in the sidebar and go to Libraries
2. Click Create Library
3. Configure:
   • Library Name: "My Calibre Library"
   • Description: Optional
   • Library Type: Ebook (or Audiobook/Comic)
4. Click the library in the list to expand its panel
5. Add your Calibre library folder in the Folders section:
   • Enter the path (or click Browse to find it on the server) and click Add
6. Trigger a scan (see below), or rely on watch mode if enabled

Bookhoard scans the library and imports all books with their Calibre metadata. Scan progress shows in the sidebar next to the logo.

Step 3: Verify Import

1. Open the Dashboard or All Books page (sidebar navigation)
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, 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 (Administration → Libraries → expand the library → Folders)
2. Trigger a scan via the Scanner API, or let watch mode pick up the changed files (the File Watcher status is shown on the admin dashboard)
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:
   • Via the Scanner API (POST /api/scanner/scan), or
   • Let watch mode detect the changed files automatically (see File Watcher on the admin dashboard)
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: Trigger a scan via the Scanner API to re-import all metadata (watch mode also picks up changed files automatically)
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
• ✅ Let Bookhoard's next scan (or watch mode) pick up the 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 OPDS-capable clients:

• KOReader (Kindle, Kobo, PocketBook hardware)
• Phone/tablet apps (KYBook, Chunky, etc.)

See the KOReader Setup Guide 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.

Writing metadata back to files (admin)

The book page's metadata editor has a Write to file action alongside Save. Save updates Bookhoard's database only; Write to file persists the currently saved values into the artifact on disk, then re-extracts so everything stays in sync:

• EPUB/KEPUB — the OPF embedded in the book is rewritten in place (cover, chapters and reading position are untouched). The file's checksum changes, so device syncs (Kobo, KOReader) re-key the book on their next sync.
• Everything else (PDF, comics, folder books, audio until tag writing ships) — a Calibre-style sidecar is written next to the file: metadata.opf when the book is alone in its folder (Calibre's own convention, so Calibre reads it too), or <filename>.opf when several books share a folder, so one book's sidecar can never leak onto its neighbours.

The write mirrors exactly what the scanner reads back, and the original file is never touched if anything fails (temp file + atomic rename).

Resources

• Calibre Website
• Calibre User Manual
• Calibre Forum
• Bookhoard GitHub

Need Help?

• Documentation: See User Guide for general Bookhoard usage
• Troubleshooting: See Operations Guide for common issues
• Developer Docs: See Developer Portal for technical details
• Issues: Report bugs or request features on GitHub Issues