Multi-destination library support: Jellyfin + Audiobookshelf + concurrent fan-out

[jesposito]

When you merged PR #1 you said:

I love this. I'm happy to bring support to Emby users and later we can now add Jellyfin support thanks to your groundwork.

I took the bait. This PR adds Jellyfin support — and while I was extending the Backend abstraction, I found that picking one media server at a time wasn't quite the right primitive for me... I'm weird and have... a few, so the abstraction became multi-destination: Audplexus can now fan out to N media servers concurrently. Plex + Emby + Jellyfin + Audiobookshelf are all first-class, and a single install can push every download to all of them at once.

Plex behavior is unchanged for existing users. The path from a v0.2.x Plex install to this branch is invisible: legacy env vars and settings synthesize a Plex destination row at first boot. I worked hard on that — see "Backwards compatibility" below.

Motivation

Two things drove this beyond just "add Jellyfin":

1. Real households fan out. Mine uses Emby and Audiobookshelf (the offline app is the best). Both point at the same /audiobooks mount. With v0.2.x I was picking a winner per environment and manually pushing scans to the others. The Backend interface was 80% of the way to fixing that, making it 100% just meant teaching the pipeline to iterate enabled destinations instead of dispatching to one.

2. Closes [Feature Request] JellyFin integration #5. A Jellyfin user filed it the day you merged PR Add Emby support via a media-server backend abstraction (Plex unchanged) #1. I confirmed Jellyfin isn't a literal copy of Emby. It diverges auth header, item kind, image MIME.

Audiobookshelf came in as a bonus once the multi-destination shape was right. ABS doesn't fit "media server" perfectly (no streaming clients, audiobook-first), but it does fit "library destination" perfectly, which is the noun I set the new schema and UI use (All yours to change up!)

Approach

The Backend interface from PR #1 stayed the central abstraction. Three additions on top:

type Backend interface {
    Name() string
    Configured(ctx context.Context) bool
    Capabilities() CapabilitySet                                  // NEW
    OnBookOrganized(ctx, OrganizedBook) []Outcome                 // NEW (replaces fire-and-forget pair)
    ReconcileLibrary(ctx, progressFn) error
    LibraryItemCount(ctx) (int, error)
    TriggerLibraryScan(ctx) error
}

// PlexBackend / EmbyBackend / JellyfinBackend / ABSBackend each implement
// WithDestination(*LibraryDestination) so multiple instances of the same
// type get independent URL/api_key/library_id.
backend := mediaserver.NewPlex(db, libraryDir).WithDestination(row)

The biggest change is OnBookOrganized replacing TriggerScanForBook + EnsureBookInSeriesCollection + TagItem. Those three were fire-and-forget in PR #1 — they spawned goroutines and logged errors. That worked when there was one backend and "did the scan trigger succeed?" wasn't observable, but multi-destination forced the issue: the pipeline needs typed outcomes per destination per operation so it can record state in book_library_destinations. The new contract returns []Outcome, each tagged with Operation (scan_trigger / item_match / series_grouping / franchise_tag / image_upload / ...) and Status (succeeded / skipped_existing / unsupported / failed / deferred / skipped_not_configured). Backends never silently no-op — Plex's old TagItem quietly returning was the central case I wanted to kill.

Capabilities are advisory: each backend declares what it supports (Plex doesn't have CapFranchiseTag; ABS doesn't have CapBoxSetCovers). The UI uses these to hide controls that don't apply per-destination. Runtime contract is still the typed Outcome — a missing capability never reaches a no-op.

The fan-out itself is bounded:

sem := semaphore.NewWeighted(int64(maxConcurrency))   // default 3
for _, dest := range enabledDestinations {
    sem.Acquire(ctx, 1)
    go func() {
        defer sem.Release(1)
        perDestCtx, cancel := context.WithTimeout(ctx, 2*time.Minute)
        defer cancel()
        outcomes := dest.Backend.OnBookOrganized(perDestCtx, book)
        recordOutcomes(ctx, book.BookID, dest, outcomes)   // outer ctx so DB writes survive per-dest timeouts
    }()
}

One destination's failure doesn't affect the others. Per-destination 2-minute timeout. Pipeline blocks until every destination returns, then marks the download complete — which fixes a subtle bug the old code had: PR #1's handleProcessStage set DownloadStatusComplete before the fire-and-forget media-server work even started. With OnBookOrganized synchronous, "complete" finally means delivered.

What changed

Multi-destination schema (005_library_destinations)

Two new tables. Both sqlite + postgres migrations.

library_destinations — one row per configured destination. Multiple of the same type allowed.

id, display_name, type, enabled, created_at, updated_at,
url, api_key, plex_token, plex_section_id, library_id,
audiobook_path, destination_path,
last_health_check_at, last_health_check_ok, last_health_check_err

Per-type config columns rather than a JSON blob. CHECK constraint enforces required fields per type. api_key and plex_token are sensitive — json:"-" and a custom Stringer that prints <redacted> so fmt.Printf("%v", row) can't accidentally leak them via reflection.

book_library_destinations — per-(book, destination) state.

book_id, destination_id, server_item_id, server_item_title,
sync_state, last_attempted_at, last_succeeded_at, last_error,
attempt_count, disabled_reason, per_op_outcomes (JSON)

The state machine has pending | syncing | synced | failed | orphaned | removed_from_destination. Failed is the only non-terminal state — the rest never auto-retry.

per_op_outcomes is JSON because operations are an open set per backend (a future Plex-only operation doesn't force a schema migration on Emby/Jellyfin/ABS).

Backends

Plex — verbatim from PR #1, now bound to a LibraryDestination row via WithDestination. Per-destination scan paths honored: if the row sets audiobook_path + destination_path, those win over the global library dir + cached plex_section_path. Means two Plex destinations on the same Audplexus can route to different mounts.

Emby — same shape as PR #1 with the same WithDestination extension. BoxSet collection logic, franchise tag write, author images all preserved.

Jellyfin — new. Mostly mirrors EmbyBackend but with three real differences (the gotchas that took a while to find):

• Auth header. Jellyfin 10.x still accepts X-Emby-Token behind a EnableLegacyAuthorization config flag (default true), but PR #13306 added the kill switch and 12.0 will remove it. New code uses Authorization: MediaBrowser Token="...", Client="Audplexus", Device="...", DeviceId="...", Version="1.0" from day one.
• Item kind. Jellyfin has first-class BaseItemKind.AudioBook. Emby returns books as both Audio and MusicAlbum — your existing reconcile filters to MusicAlbum to dedupe. Jellyfin's filter is IncludeItemTypes=AudioBook. The Emby filter returns zero rows on Jellyfin.
• Image upload. Jellyfin's ImageController validates Content-Type strictly: image/jpeg, not image/jpg, not image/*. Emby tolerates loose types. JellyfinBackend builds concrete MIME from the source URL extension.

Audiobookshelf — new. Different in shape from the other three because ABS is metadata-driven rather than collection-driven:

• Bearer auth (Authorization: Bearer <api_key>). Admin-scope key required for scans (post-v2.26.0 JWT rewrite, 2025-07).
• POST /api/libraries/{id}/scan for library refresh.
• ASIN-based item match via GET /api/libraries/{id}/search?q=<ASIN> — no native ASIN filter, so we verify media.metadata.asin client-side.
• Series support is implicit: the new Audiobook-rich tag profile (below) writes series and series-part freeform iTunes atoms, which ABS reads via ffprobe. Falls back to PATCH /api/items/{id}/media with metadata.series=[{name,sequence}] if tags are absent.
• ABS has a chokidar folder watcher on by default — the scan trigger is belt-and-suspenders, idempotent so calling both is safe.

Audiobook-rich tag profile

Optional Settings choice. Default stays Basic (your historical tag set, byte-for-byte unchanged for existing libraries). Audiobook-rich adds three freeform iTunes atoms via existing ffmpeg -metadata:

• series (book.Series)
• series-part (book.SeriesPosition)
• asin (book.ASIN)

The album field stays at book.Title — your Plex album-collapse workaround is preserved. Audiobookshelf reads these atoms natively for series auto-grouping; Plex/Emby/Jellyfin ignore them harmlessly.

There's one subtle empirical detail I learned the hard way: ffmpeg's mp4 muxer drops unknown -metadata keys unless -movflags use_metadata_tags is also set. Without that flag, the freeform atoms vanish silently — the ffmpeg output looks fine, the file looks fine, but ffprobe shows nothing. The flag flips output to QuickTime mdta metadata format which preserves the keys. EmbedMetadata + buildDecryptArgs both set the flag when the profile is Audiobook-rich. There's a unit test guarding it on both paths so we don't regress.

Settings UI

The "Active Media Server" radio + the per-type Plex/Emby panels are gone. Library Destinations CRUD replaces them: list of destination cards, each with an Edit / Toggle / Delete action set, status badge (Healthy / Failed / Never checked / Not configured), and a "Test Connection" button. Add-destination is a two-page server-rendered wizard (type picker → type-specific config form). No JS framework — vanilla forms + HTMX for the test-connection result swap.

Per-field instructions live in <details> collapsibles next to each input. Plex token: walks through "Get Info → View XML → copy ?X-Plex-Token=" + links to Plex's official guide. Emby/Jellyfin/ABS API keys + library IDs: each has its own walk-through + the curl | jq one-liner for the API alternative.

a11y review notes (an a11y-lead consult I ran during the work):

• Cards rendered as <ul role="list"> because Safari/VoiceOver strips list semantics under list-style:none. Each card has its own <h4 id="dest-{id}-name"> so action buttons get unique accessible names via aria-labelledby.
• Test result container has role="status" aria-live="polite" aria-atomic="true". Toggle button label flips ("Enable" ↔ "Disable") rather than using aria-pressed (the dual conveyance creates confusing announcements).
• Delete is POST-only — destructive actions must not be safe GETs (RFC 9110 + WCAG semantics for destructive controls). Same endpoint two-state: first POST renders the confirm page, second POST with confirm=1 actually deletes.

Dashboard

Single "Emby Connected / Library Items / Coverage" stat-cards replaced with a per-destination summary section: one mini-card per configured destination with display name, type badge, status badge, item count, coverage %, and "Last checked: 4 min ago" via <time datetime="...">. aria-live="polite" on the list with aria-live="off" on the numeric cells, so SR users get health flips ("Plex destination failed") but not 12s count chatter.

Backwards compatibility

This is the part I worked hardest on (again). The codex pre-PR review caught a P1 here that I want to call out explicitly — see "Pre-PR review pass" below.

• Existing v0.2.x Plex installs upgrade silently. The most common config doesn't set MEDIA_SERVER or media_server_type because Plex was the silent default in your v0.2.x. First-boot synthesis now infers Plex when those are unset but plex_url + plex_token + plex_section_id are all present. Same for Emby. Result: no manual steps required on upgrade.
• MEDIA_SERVER env var still works as a first-boot synthesis hint. Once any destination exists, it's logged-and-ignored. Removed entirely in v0.5.
• Legacy fallback in pipeline_stages.go. If the destinations table is empty AND a legacy single backend is configured (env vars or settings), OnBookOrganized falls through to the legacy path. So even if synthesis fails for any reason, downloads still work.
• Legacy books.media_server_id / media_server_title columns stay populated by UpdateBookMediaServerInfo during this minor version. A future 006 drops them after one release of dual-write soak.
• Plex's scan-and-wait completion polling is preserved for the synthesized Plex destination. Same flow you wrote.
• Default Tag Profile is Basic for everyone, including fresh installs. Audiobook-rich is opt-in only. Existing libraries see zero diff in their next download's m4b.
• All existing routes you didn't ask to change are unchanged: /auth/marketplace, /auth/start, /auth/callback, /auth/plex/*, /api/sync/*, /api/downloads/*. The only routes I removed are /auth/emby/configure, /auth/emby/scan, and /auth/media-server/select — those posted to the now-removed UI panels and have no other callers. Their handlers + the internal/web/emby_settings.go file are gone.

Testing

• go test ./... passes. New tests cover: typed Outcome contract, WithDestination row binding (both with-row and without-row paths), first-boot synthesis (every type + the inferred-Plex P1 case), tag profile parsing + ffmpeg muxer flag (both embedArgs and buildDecryptArgs), schema CHECK constraints, FK CASCADE, secret redaction in fmt formatters, summarizeOutcomesState table-driven, franchiseFromSeries table-driven, normalizeTitle table-driven.
• I ran the full image against my home setup with three live destinations: Emby 4.x (the same one from PR Add Emby support via a media-server backend abstraction (Plex unchanged) #1), a fresh Jellyfin 10.11.8 install pointed at the same /audiobooks mount, and an Audiobookshelf 2.34.0 instance. Single book delete + Full Sync + Queue All New round-trip: download → decrypt → organize → fan-out completes in ~16 seconds, all three destinations report sync_state=synced in book_library_destinations, the freeform asin atom shows up in the m4b's ffprobe output, and cmd/abstest and cmd/jellytest (small live-verification programs in cmd/) confirm the auth + scan + ASIN-search round-trips against real servers.
• Plex flow was retested live this round (I have a Plex install handy now, unlike PR Add Emby support via a media-server backend abstraction (Plex unchanged) #1 — sorry for the gap last time). Section scan + collection management both fire correctly via the synthesized Plex destination.

Pre-PR review pass

I ran a codex review against this branch before opening the PR. It caught three real things, all fixed before this PR went up:

1. [P1] firstboot_destinations.go — the original synthesis returned empty for unknown MEDIA_SERVER, which would have stranded existing v0.2.x Plex installs (the case described in "Backwards compatibility"). Fixed via inference from per-type settings/env presence.
2. [P2] buildDecryptArgs was missing the use_metadata_tags muxer flag. The actual download path goes through DecryptAAX(C)WithMetadata → buildDecryptArgs, not EmbedMetadata → embedArgs. My PR-A test only exercised the latter, so the freeform atoms were silently dropped during real downloads while the unit test passed. Flag added; regression test on both paths.
3. [P2] Per-destination audiobook_path / destination_path were saved by the form but ignored at scan time — backends still resolved from the global libraryDir + cached plex_section_path. Now honored via destination field on each backend struct.

Open questions for you

A handful of judgment calls I'd love your read on, in priority order:

1. Naming. The user-facing noun is "library destination" (in the Settings UI, the schema, the dashboard). The Go interface name stays Backend — I didn't rename code. If you'd rather stay with "media server" everywhere, I can revert; the schema columns are easy to alias.
2. Multiple instances of the same type. Schema permits two Plex destinations side-by-side (household + parents'). I think that's a real use case but mild scope creep over what you originally wanted. Easy to add a unique constraint on type if you'd rather hold it to one-per-type for now.
3. MEDIA_SERVER env var deprecation timeline. I have it as: respected for first-boot synthesis, logged-and-ignored thereafter, removed in v0.5. If you'd rather keep it as a permanent headless-config bootstrap, easy.
4. Default Tag Profile for fresh installs. I went with Basic for everyone (zero behavior change for upgrades; opt-in to Audiobook-rich). The alternative is Audiobook-rich for fresh installs only, which gets new ABS users the better experience by default. I went conservative.
5. Mega-PR vs. sequential split. This branch is 17 functional commits. If you'd rather review it as 7 sequential PRs (operational contract → tag profile → schema → fan-out + UI → Jellyfin → ABS → cleanup), each commit is self-contained and the branches are still on my fork. Just say the word and I'll open them in order. My default assumption is one mega-PR is easier, since each piece depends on the previous one for end-to-end verification, but you tell me.
6. The cmd/abstest and cmd/jellytest standalone Go programs are ~80 lines each. They're live-server integration test recipes — anyone with a real Audiobookshelf or Jellyfin can run ABS_URL=... ABS_API_KEY=... ABS_LIBRARY_ID=... ./abstest to verify their config end-to-end. They share an internal/database/StubDB so the dedupe is reasonable. Happy to drop them if you'd rather; they're not load-bearing.
7. docs/destinations.md is a 1-page architecture overview I wrote for myself while building. Probably useful for future contributors. Happy to drop or relocate.

Happy to revise anything — just let me know what you'd like changed. Thanks again for the original groundwork. The Backend interface in PR #1 was the right shape; the multi-destination version mostly just exercised it harder.

[Copilot]

Pull request overview

This PR expands Audplexus’s media-server integration from a single selected backend to a multi-destination “library destinations” model, adding first-class Jellyfin and Audiobookshelf support and enabling bounded concurrent fan-out of post-organize operations with per-destination outcome/state tracking.

Changes:

• Introduces library_destinations + book_library_destinations schema and CRUD, plus first-boot synthesis from legacy settings/env.
• Reworks mediaserver.Backend around synchronous OnBookOrganized(...) []Outcome + capability advertisement, and updates Plex/Emby implementations to be destination-row bound (WithDestination); adds Jellyfin/ABS backends.
• Updates pipeline + sync + UI to operate on multiple destinations and to record/reflect per-destination health and outcomes.

Reviewed changes

Copilot reviewed 53 out of 53 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
README.md	Updates documentation from single media server selection to multi-destination setup and tag profiles.
internal/web/templates/settings.html	Replaces “Media Server” settings panel with tag profile selector and destinations list UI.
internal/web/templates/downloads.html	Fixes “Pipeline” heading typo and shows titles alongside ASINs.
internal/web/templates/destinations_new.html	Adds destination type picker page.
internal/web/templates/destinations_form.html	Adds create/edit destination form with per-type fields, path translation, and HTMX “Test Connection”.
internal/web/templates/destinations_delete.html	Adds POST-only delete confirmation page for destinations.
internal/web/templates/dashboard_summary.html	Replaces single-backend dashboard stats with per-destination summary cards and health badges.
internal/web/templates/base.html	Removes backend-specific subtitle (“Audible to Plex/Emby…”) in favor of generic copy.
internal/web/static/style.css	Adds badge styles and a reusable .visually-hidden utility for a11y.
internal/web/emby_settings.go	Removes legacy Emby settings handlers (superseded by destinations CRUD).
internal/web/destinations_handlers.go	Implements destination CRUD + toggle + delete and HTMX test endpoint.
internal/mediaserver/with_destination_test.go	Tests WithDestination overrides legacy settings-table config per backend.
internal/mediaserver/plex.go	Adds destination binding, capabilities, synchronous outcomes, and per-destination path translation support.
internal/mediaserver/outcome.go	Introduces typed Outcome contract, operations, and capability flags.
internal/mediaserver/outcome_test.go	Unit tests for Outcome helpers and terminality semantics.
internal/mediaserver/mediaserver.go	Extends backend types (Jellyfin/ABS) and updates interface to Capabilities + OnBookOrganized.
internal/mediaserver/jellyfin_abs_test.go	Compile-time + contract tests for Jellyfin/ABS and capability assertions.
internal/mediaserver/emby.go	Adds destination binding, capabilities, and synchronous per-book outcome workflow (scan/match/group/tag).
internal/mediaserver/backend_contract_test.go	Enforces “not configured returns typed skip” contract and provides a settings-only stub DB.
internal/library/sync.go	Renames user-facing “Plex Sync” messaging to backend-agnostic “Library Scan” while preserving phase ID.
internal/library/pipeline_stages.go	Runs destination fan-out before marking downloads complete; adds structured outcome logging.
internal/library/library_reconcile_test.go	Extends reconcile test DB mock to satisfy new DB interface methods.
internal/library/firstboot_destinations.go	Adds first-boot synthesis of a destination row from legacy single-backend settings/env.
internal/library/firstboot_destinations_test.go	Tests first-boot synthesis behavior, including inferred Plex/Emby cases for upgrades.
internal/library/download.go	Threads DestinationManager into DownloadManager and uses tag profile resolution during decrypt.
internal/library/destinations.go	Adds DestinationManager for bounded concurrent fan-out + scan/reconcile fan-out + per-destination state recording.
internal/library/destinations_test.go	Integration-style tests for fan-out recording and outcome→state summarization.
internal/database/testutil_stub.go	Adds database.StubDB helper for tests and live probe binaries.
internal/database/sqlite.go	Fixes SQLite DSN pragmas to ensure FK enforcement works under modernc.org/sqlite.
internal/database/models.go	Adds LibraryDestination / BookDestination models and secret-redacting formatters.
internal/database/migrations/005_library_destinations.up.sql	Adds SQLite schema for destinations + per-(book,destination) state with FKs and constraints.
internal/database/migrations/005_library_destinations.down.sql	Adds SQLite down migration for new tables/indexes.
internal/database/migrations_postgres/005_library_destinations.up.sql	Adds Postgres schema equivalents (JSONB, TIMESTAMPTZ, BOOLEAN).
internal/database/migrations_postgres/005_library_destinations.down.sql	Adds Postgres down migration for new tables/indexes.
internal/database/library_destinations_test.go	Adds DB-level tests for CRUD, constraints, and FK cascades.
internal/database/library_destinations_sqlite.go	Implements SQLite CRUD for destinations and book-destination state.
internal/database/library_destinations_redaction_test.go	Tests secret redaction for fmt formatting of destination rows.
internal/database/library_destinations_postgres.go	Implements Postgres CRUD for destinations and book-destination state.
internal/database/interface.go	Extends database.Database interface with destination CRUD/state methods.
internal/audnexus/metadata.go	Populates series/series-part/ASIN fields in audio.Metadata (emitted based on selected profile).
internal/audio/tag.go	Adds tag profile support and -movflags use_metadata_tags for audiobook-rich freeform atoms.
internal/audio/tag_test.go	Tests metadata args and decrypt/embed arg behavior for both tag profiles.
internal/audio/tag_profile.go	Adds tag profile parsing/resolution and UI label/description helpers.
internal/audio/tag_profile_test.go	Tests tag profile parsing and DB resolution behavior.
internal/audio/decrypt.go	Ensures audiobook-rich metadata atoms survive decrypt+embed path via movflags.
go.mod	Adds golang.org/x/sync dependency for semaphore-based fan-out.
docs/destinations.md	Adds architecture doc for destinations model, runtime contract, and fan-out behavior.
cmd/server/main.go	Adds first-boot destination synthesis and wires DestinationManager into download pipeline.
cmd/jellytest/main.go	Adds live Jellyfin probe utility using production backend logic.
cmd/abstest/main.go	Adds live Audiobookshelf probe utility using production backend logic.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jesposito]

Pushed two commits addressing both threads:

ac95d6d — merge of upstream/master (PR #4). Three real conflict points:

• internal/audio/decrypt.go: combined movflags. +faststart (always-on, PR Implement MP3 (chapter-split) output format and add per-book convert action #4) plus +use_metadata_tags when AudiobookRich profile is active. Single -movflags +faststart+use_metadata_tags arg.
• internal/library/download.go: kept your metadataWithOptionalCover helper. Moved my tag-profile resolution INTO the helper so all 4 callers (DecryptAndOrganize, convert m4b<->mp3, pipeline chapter-split) pick up the profile uniformly.
• internal/library/{convert,pipeline_stages}.go: your new chapter-split + convert paths called the removed TriggerScanForBook / EnsureBookInSeriesCollection. Extracted a dm.fanOutPostOrganize() helper from the standard path; all four code paths now route through it identically. Multi-destination fan-out + legacy fallback apply to chapter-split and m4b<->mp3 convert too.

9bce4c7 — Copilot's 7 findings, all fixed:

1. [P1] firstboot Plex path inversion — plex_section_path is the server-side translation target, not the audplexus-side source. Was being persisted into AudiobookPath (source); now goes to DestinationPath (target). Test updated to assert correct field placement.
2. [P1] firstboot Emby path inversion — same fix for emby_library_path.
3. [P2] handlers — server-side required-field validation — empty plex_token / api_key on create now returns 400 with a user-facing message instead of falling through to a CHECK-constraint 500.
4. [P2] plex.go — short-circuit empty LocalPath — re-ordered resolveScanPath after the empty-path check so we don't do a cache fetch on a request that's going to fail.
5. [P3] go.mod — golang.org/x/sync moved to direct requires via go mod tidy.
6. [P3] sqlite CHECK — IS NOT NULL → length(trim(coalesce(col,''))) > 0. The coalesce is load-bearing (CHECK passes on NULL, length(trim(NULL)) is NULL). New TestCreateRejectsWhitespaceOnlyValues guards future drift.
7. [P3] postgres CHECK — same.

go test ./... green. Re-ran the live fan-out test on my home setup post-merge — Plex / Emby / Jellyfin / ABS all still good.

If anything else stands out from your read, happy to iterate.

[mstrhakr]

Thanks for your work on this.