Audiobookshelf Integration

[masonfox]

Context

Part of the Book Sources architecture evolution. After Phase R1 (Book Sources Refactor), Tome's database schema now supports books existing in multiple sources simultaneously via the book_sources many-to-many table.

Dependencies

Blocked by: #185 (Support non-Calibre books)

• Must wait until Phase R1 (Book Sources Refactor) is released and stable in production
• Requires Phase R2 (Remove calibre_id) to be completed for full architectural consistency
• UI already supports displaying multiple source badges (implemented in Phase R1.6)

Goal

Enable Tome to track books that exist in both Calibre and Audiobookshelf simultaneously, allowing users to:

• See which books have audiobook versions
• Track progress separately for ebook (Calibre) vs audiobook (Audiobookshelf)
• Display both source badges in the UI
• Sync metadata from both sources with configurable priority

Current State

After Phase R1:

• ✅ book_sources table supports many-to-many relationships
• ✅ UI components already display multiple provider badges
• ✅ provider_configs table manages provider priority for metadata conflicts
• ✅ bookSourceRepository provides all necessary CRUD operations
• ❌ No Audiobookshelf provider implementation exists
• ❌ No sync service for Audiobookshelf

Scope

1. Provider Configuration

• Add Audiobookshelf provider config to seed data

  {
    providerId: 'audiobookshelf',
    displayName: 'Audiobookshelf',
    priority: 5, // Lower priority than Calibre (1) but higher than metadata providers (10+)
    supportsSync: true,
    requiresCredentials: true
  }

2. Audiobookshelf Provider Implementation

• Create lib/providers/audiobookshelf.provider.ts
• Implement IMetadataProvider interface
• Add Audiobookshelf API client
• Handle authentication/credentials
• Map Audiobookshelf data to Tome schema

3. Sync Service

• Create lib/services/audiobookshelf-sync.service.ts
• Implement book discovery and matching
• Handle audiobook-specific metadata (narrator, duration, etc.)
• Sync progress tracking (if supported by Audiobookshelf)
• Implement orphan detection for Audiobookshelf sources

4. Book Matching Logic

• Match books between Calibre and Audiobookshelf by:
  • ISBN (primary)
  • Title + Author (fuzzy match)
  • User manual linking
• Create/update book_sources entries when match found
• Handle no-match scenario (create separate book entry)

5. Metadata Conflict Resolution

• Implement priority-based metadata selection
• Calibre (priority: 1) wins over Audiobookshelf (priority: 5)
• Allow user override via book_sources.is_primary
• Log conflicts for user review

6. UI Updates

• Settings page: Configure Audiobookshelf connection
  • Server URL
  • API token
  • Enable/disable sync
• Settings page: Trigger manual sync
• Book detail page: Already supports multiple badges (Phase R1.6)
• Book cards: Already support multiple badges (Phase R1.6)

7. Progress Tracking

• Determine how to track separate progress for ebook vs audiobook
  • Option A: Separate sessions per source
  • Option B: Unified progress with source indicator
  • Option C: Let user choose which to track
• Sync progress to/from Audiobookshelf (if API supports)

8. Testing

• Unit tests for Audiobookshelf provider
• Integration tests for sync service
• E2E tests for book matching
• Test multi-source scenarios
• Test metadata conflict resolution

9. Documentation

• User guide: Setting up Audiobookshelf integration
• Architecture docs: Multi-source book handling
• API docs: Audiobookshelf endpoints
• Troubleshooting guide

Design Decisions Needed

1. Book Matching Strategy:

   • Should we automatically create book_sources links when ISBN matches?
   • Should we require user confirmation for fuzzy matches?
   • How do we handle series matching?

2. Progress Tracking:

   • One session for both sources, or separate sessions?
   • How to display dual progress in UI?
   • Should audiobook duration be converted to page equivalents?

3. Sync Direction:

   • One-way (Audiobookshelf → Tome only)?
   • Two-way sync?
   • What data flows in each direction?

4. Conflict Resolution:

   • What happens when both sources update the same metadata?
   • Should we log conflicts for user review?
   • Can users manually select preferred source per field?

Research Needed

• Audiobookshelf API documentation
• Authentication methods
• Available metadata fields
• Progress tracking capabilities
• Rate limiting / API constraints
• Webhooks / real-time sync support

Timeline

Estimated: 30-40 hours (1-2 weeks)

• Research & planning: 4 hours
• Provider implementation: 8 hours
• Sync service: 12 hours
• Book matching: 6 hours
• UI updates: 4 hours
• Testing: 4 hours
• Documentation: 2 hours

Risk Assessment

High Risk:

• Book matching logic is complex and error-prone
• Metadata conflicts could cause data loss if not handled carefully

Medium Risk:

• Audiobookshelf API might not support all features we need
• Progress tracking for audiobooks vs ebooks is conceptually different

Mitigation:

• Start with read-only sync (Audiobookshelf → Tome)
• Implement comprehensive logging for debugging
• Add user confirmation for all automatic matches
• Backup database before first sync

Success Criteria

• Users can configure Audiobookshelf connection in settings
• Manual sync discovers Audiobookshelf books and creates book_sources entries
• Books with both Calibre and Audiobookshelf sources display both badges
• Metadata conflicts resolved according to provider priority
• Full test suite passes (3880+ tests)
• Documentation covers setup and troubleshooting

Future Enhancements (Out of Scope)

• Automatic sync on schedule
• Webhook-based real-time sync
• Manual book linking UI (drag-and-drop to link books)
• Multiple Audiobookshelf servers
• Plex audiobooks integration

[masonfox]

Blocked by: #185

This issue cannot be started until #185 (Support non-Calibre books - Phase R1) is released to production and has been validated in real-world use. The multi-source architecture must be proven stable before adding Audiobookshelf as a second source.

Recommended: Also wait for #363 (Phase R2: Remove calibre_id) to complete for full architectural consistency, though not strictly required.