Metadata

Metadata should be treated as an evidence system, not a single lookup result.

Current Scanner Evidence

The read-only scanner emits candidate evidence records. Each evidence record includes:

• source: the relative file path that produced the evidence.
• sourceType: path, opf, json, nfo, description-text, or reader-text.
• confidence: high, medium, low, or hint.
• fields: normalized metadata fields found in that source.
• notes: parse notes, classification reasons, or warnings.

Current extraction covers:

• OPF title, authors, language, published date, identifiers, and Calibre series metadata.
• JSON title, authors, narrators, series, duration, and source fields.
• NFO title, authors, published date, and genres.
• Path-derived file name, stem, and directory hints for every file.

Duplicate signals currently compare normalized title, author, and media kind fingerprints. Duplicate candidates are routed to review in the dry-run import plan.

Metadata Lookup Workflows

External metadata sources are needed for two core workflows:

• Wanted-author discovery: when an operator adds an author to look for, Library Manager should use metadata sources to discover works, series, editions, identifiers, contributor aliases, and enough context to decide what should become wanted.
• Missing-item enrichment: when scanned or imported items have weak metadata, Library Manager should look up title, author, narrator, series, publisher, publication date, identifiers, descriptions, cover images, genres, language, and related fields.

The metadata plan covers both ebooks and audiobooks. Narrators, editions, formats, series placement, covers, sidecars, publisher data, dates, ISBN/ASIN-style identifiers, and audiobook duration/chapter signals should all remain evidence-backed.

Lookup results should be stored as source-attributed evidence before they become canonical library data. Conflicting values should remain visible for operator review, and trusted local metadata should not be silently overwritten by a remote provider until confidence rules and source priority are designed.

As of the post-v0.2.6 main branch, Add New can run live author and item lookup through GET /api/metadata/authors?q= and GET /api/metadata/items?q=, display ranked provider matches and evidence, and use selected matches to seed wanted author, work, or edition records. When the provider returns a source identifier or item identifier, the wanted record preserves a provider-backed target key; manually typed names still fall back to normalized wanted keys.

Provider Guardrails

Metadata providers should be backend-mediated. Credentials, rate limits, caching, provider-specific normalization, and terms-sensitive behavior stay server-side.

Provider adapters should record:

• Provider name and source URL or identifier.
• Query used and normalized lookup key.
• Returned identifiers and field-level values.
• Confidence, match reason, and conflict notes.
• Cache/provenance data so large imports do not repeatedly query the same provider.

Resolver Foundation

The first backend resolver contract lives in internal/metadata.

It supports:

• Wanted-author lookup across provider adapters.
• Missing-item enrichment across provider adapters.
• Source-attributed evidence records.
• Provider error propagation.
• Confidence-based result ordering.

Open Library, Google Books, Hardcover, and Audible/Chirp-compatible provider adapters are implemented behind the resolver. Add New now consumes author lookup and work/edition evidence results; release-candidate ranking, cache policy, source-priority promotion, and field-level confidence remain next steps.

Large-Library Requirements

A realistic initial scan may include 10,000+ files. The current stress checks run at 30,000 files. Metadata evidence and duplicate signals are persisted incrementally, indexed for review workflows, and covered by re-scan tests for missing and moved file states. SQLite is accepted for the first app scaffold, with the option to revisit after real-library testing.

Planned Evidence Sources

• Folder and filename parsing.
• Embedded e-book metadata.
• Embedded audiobook tags.
• OPF sidecars.
• NFO, JSON, desc.txt, reader.txt, cover files, and Calibre-style exports.
• External metadata providers.
• Operator corrections and remembered overrides.

Resolver Goals

• Show confidence and why a match was selected.
• Preserve editions and formats without flattening them into one ambiguous book record.
• Treat audiobook narrator, duration, track order, disc order, chapters, and ASIN/ISBN as meaningful signals.
• Prefer explicit warnings over silent guesses for weak metadata.
• Support wanted-author discovery without assuming every discovered work should automatically be acquired.