obsidian-yanxin/agent_skills/calibre_import_workflow.md

Calibre Book Import Workflow

Library Setup

The Calibre library lives on an Unraid server with two Docker containers:

• linuxserver/calibre — full desktop GUI, accessible via browser (for manual imports/editing)
• linuxserver/calibre-web — web reader frontend for reading books

Library path on Unraid: /mnt/user/la-share/home/books/calibre_library/

Docker permissions

• Containers should use PUID=99 and PGID=100 (maps to nobody:users)
• If SMB write issues occur: chown -R nobody:users /mnt/user/la-share/home/books/calibre_library/

Importing New Books

Option 1: Calibre GUI container (recommended for routine imports)

1. Upload new book files to Unraid (via copyparty or SMB)
2. Open the Calibre GUI container in browser
3. Drag and drop to import, edit metadata, fetch covers

Option 2: With Claude's help (for bulk imports or metadata cleanup)

1. Upload new book files to Unraid
2. Import into the Calibre GUI container
3. Ask Claude to generate calibredb commands for metadata fixes
4. Run commands via Unraid terminal or docker exec:

   docker exec calibre calibredb list --library-path /config/library
   docker exec calibre calibredb set_metadata <id> -f title:"Title" --library-path /config/library
   

   (Adjust container name and library path as needed)

Option 3: Local import then sync (for large batches)

1. Import and fix metadata locally on Mac using CLI tools at /Applications/calibre.app/Contents/MacOS/
2. Copy the specific book folders + updated metadata.db to Unraid via copyparty
3. Stop containers before overwriting metadata.db, restart after

Import Steps (Detail)

1. List files to import

Show file names, sizes, and formats from the source folder.

2. Check for duplicates

# Local
sqlite3 "$HOME/Calibre Library/metadata.db" "SELECT id, title FROM books ORDER BY title;"

# Or on Unraid
docker exec calibre calibredb list --library-path /config/library

3. Fetch metadata (do NOT import yet)

fetch-ebook-metadata -t "Title" -a "Author"

Uses 3 plugins: New Douban Books, Google Books, Amazon.com.

If not found online, read embedded metadata:

• ebook-meta file.epub (often has good embedded data)
• ebook-convert file.pdf /tmp/out.txt (extract text to identify unknown files)

4. Show complete metadata for approval

Present ALL metadata for ALL books before importing:

• Title, Author(s), Publisher, Tags, ISBN

Wait for explicit approval before proceeding.

5. Import

calibredb add "file.epub" --library-path "$LIB"

For multi-format books (same book in epub + mobi + pdf):

• Import the first format with calibredb add
• Add additional formats with calibredb add_format <id> <file>
• Do NOT pass all formats to calibredb add at once — it creates separate entries

6. Apply metadata

calibredb set_metadata <id> \
  -f title:"Book Title" \
  -f authors:"Author Name" \
  -f publisher:"Publisher" \
  -f tags:"tag1,tag2,tag3" \
  -f identifiers:"isbn:1234567890" \
  -f series:"Series Name" \
  -f series_index:"1" \
  --library-path "$LIB"

7. Verify and clean up

• Check for split entries — merge with add_format + remove
• Verify titles, authors, tags are correct
• Delete source files after successful import

Tag Rules

• Chinese tags for Chinese books — never English equivalents
• No publisher/author/year/title as tags — use their dedicated fields
• No overly generic tags — avoid 经典, 中国, 人文, 入门, 教程, 参考
• Consolidate similar tags — check existing tags before creating new ones

Reading on Boox (KOReader + OPDS)

Calibre-web serves an OPDS catalog automatically. KOReader on Boox has built-in OPDS support.

Setup

1. Open KOReader → Search (magnifying glass) → OPDS catalog
2. Add a new catalog: http://UNRAID_IP:8083/opds (adjust port to match Calibre-web)
3. Browse library, tap a book to download directly to the e-reader

Reading strategy

• KOReader for books — optimized for e-ink, great typography control, PDF reflow, offline dictionary
• Readwise Reader for articles, RSS, newsletters — highlight sync, cross-device reading

Serving Externally

Options for accessing the library outside the home network:

• Tailscale (recommended) — install on Unraid (community plugin) + Boox (Android app). Access Calibre-web OPDS via Tailscale IP: http://100.x.x.x:8083/opds. Free tier supports 100 devices.
• Cloudflare Tunnel — free, no open ports, gives public URL like books.yourdomain.com
• Reverse proxy — Nginx Proxy Manager + domain, requires port 443 open