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. 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)