bookhoard/docs/user/calibre-integration.md

# 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. 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, 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 (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](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)