bookclerk_enrich
Source-agnostic Audible metadata enrichment.
Matches library rows that lack an Audible ASIN using public Audible catalog search and the deployed metadata-provider plugins (AudioBookshelf-style confidence scoring). Intended for Libro.fm, Chirp, GraphicAudio, and any future non-Audible sources.
A confident match stores the Audible ASIN and catalog fields on the row; acquire then overlays the provider's chapter layout (and related tags) onto plain audio that lacks Audible brand intro/outro.
| Item | Kind | Summary |
|---|---|---|
MetadataProviders |
trait | Deployed metadata providers the host asks for bibliographic records. |
Enrichment |
struct | Metadata pulled from the Audible catalog and a metadata provider for a confident match. |
ScoredMatch |
struct | A scored Audible match candidate. |
MatchQuery |
struct | Owned-title (e.g. Libro) metadata used as the match query. |
ScoreInput |
struct | Candidate metadata used for confidence scoring. |
ChaptersAnswer |
struct | The first chapter layout any deployed provider had for one edition. |
MetadataAnswer |
struct | What every deployed provider answered for one lookup or search. |
NoMetadataProviders |
struct | No providers: every answer is empty. For callers with no plugin host. |
ProvidedChapters |
struct | A chapter layout and the provider plugin that returned it. |
ProvidedRecord |
struct | One record and the provider plugin that returned it. |
ProviderFailure |
struct | A provider call that failed, so its records are missing from the answer. |
EnrichError |
enum | Errors from public-catalog enrichment and match scoring. |
apply_enrichment_to_edition |
function | Apply a confident Audible catalog match to a held edition. |
confidence_percent_to_fraction |
function | Convert a 0–100 percent threshold to a 0.0–1.0 fraction. |
enrich_editions_from_audible |
function | Match held editions that have no ASIN to the Audible catalog through the deployed metadata providers, and record each confident match. |
enrichment_for_asin |
function | Provider metadata for a known ASIN (no confidence scoring). |
enrichment_from_record |
function | Maps a provider record into enrichment fields. |
lookup_by_metadata |
function | Look up the best Audible match for the given query metadata. |
lookup_by_metadata_with_client |
function | Catalog search + provider lookup against an already-built HTTP client. |
calculate_match_confidence |
function | Calculate match confidence in [0.0, 1.0]. |
canonicalize_isbn |
function | Normalize then convert ISBN-10 → ISBN-13 (978…) when possible. |
clean_author_for_compares |
function | Clean an author string for fuzzy compares (AudioBookshelf cleanAuthorForCompares). |
clean_title_for_compares |
function | Clean a title for fuzzy compares (AudioBookshelf cleanTitleForCompares). |
is_asin_title |
function | True when a title field holds an Audible ASIN rather than a real title. |
isbn_exact_match |
function | Returns true when both sides normalize to the same ISBN-13 (or matching ISBN-10). |
levenshtein_distance |
function | Levenshtein distance (case-insensitive by default, matching ABS). |
levenshtein_similarity |
function | Similarity in [0.0, 1.0] from Levenshtein distance. |
normalize_isbn |
function | Digits-only ISBN for exact matching (strips hyphens / spaces / ISBN prefix). |
asin_identifier |
function | An ASIN identifier scoped to marketplace. |
chapter_info_from_layout |
function | Rebuilds a provider's flat pre-order chapter list as the nested Audible chapter_info object the acquire pipeline reads. |
isbn_identifier |
function | An ISBN identifier. |
record_identifier |
function | The first value of scheme among a record's identifiers. |
Result |
type alias | Result alias for this crate's error type. |
DEFAULT_ENRICH_MIN_CONFIDENCE |
constant | Default minimum confidence percent (AudioBookshelf-style 0–100 scale). |
MAX_CHAPTER_DEPTH |
constant | Deepest chapter nesting chapter_info_from_layout builds. A provider's layout is plugin output and the tree is later walked recursively, so a deeper depth is clamped to this level. Audible itself nests at most a few levels. |
bookclerk_audible_catalog::fetch_audible_catalog_ratingbookclerk_audible_catalog::fetch_audible_catalog_reviewsbookclerk_audible_catalog::fetch_audible_catalog_reviews_pagebookclerk_audible_catalog::is_audible_podcast_productbookclerk_audible_catalog::normalize_regionbookclerk_audible_catalog::normalize_review_bodybookclerk_audible_catalog::public_http_clientbookclerk_audible_catalog::region_tldbookclerk_audible_catalog::resolve_genre_category_idbookclerk_audible_catalog::search_catalog_asinsbookclerk_audible_catalog::search_catalog_by_genre_namebookclerk_audible_catalog::search_catalog_by_narratorbookclerk_audible_catalog::search_catalog_by_series_asinbookclerk_audible_catalog::search_catalog_by_series_namebookclerk_audible_catalog::search_catalog_keywordsbookclerk_audible_catalog::search_catalog_productsbookclerk_audible_catalog::search_catalog_products_exbookclerk_audible_catalog::search_catalog_products_ex2bookclerk_audible_catalog::search_catalog_products_pagedbookclerk_audible_catalog::search_catalog_products_richbookclerk_audible_catalog::search_catalog_storefrontbookclerk_audible_catalog::CatalogErrorbookclerk_audible_catalog::CatalogProductbookclerk_audible_catalog::CatalogRatingbookclerk_audible_catalog::CatalogReviewbookclerk_audible_catalog::CatalogReviewsPagebookclerk_audible_catalog::CatalogReviewsSortbookclerk_library::decode_html_entitiesmatch_score::is_valid_asin
pub trait MetadataProviders: Send + Sync {
fn lookup<'life0, 'life1, 'async_trait>(
&'life0 self,
params: &'life1 MetadataLookupParams,
) -> Pin<Box<dyn Future<Output = MetadataAnswer> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,;
fn search<'life0, 'life1, 'async_trait>(
&'life0 self,
params: &'life1 MetadataSearchParams,
) -> Pin<Box<dyn Future<Output = MetadataAnswer> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,;
fn chapters<'life0, 'life1, 'async_trait>(
&'life0 self,
params: &'life1 MetadataChaptersParams,
) -> Pin<Box<dyn Future<Output = ChaptersAnswer> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,;
}
Deployed metadata providers the host asks for bibliographic records.
Implementations ask every provider in a stable order. A provider that
fails is reported in the answer's failures and does not stop the others.
fn lookup<'life0, 'life1, 'async_trait>(
&'life0 self,
params: &'life1 MetadataLookupParams,
) -> Pin<Box<dyn Future<Output = MetadataAnswer> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
Records for a set of identifiers.
params- Identifiers (never empty), marketplace and limit.
Every provider's records plus the providers that failed.
fn search<'life0, 'life1, 'async_trait>(
&'life0 self,
params: &'life1 MetadataSearchParams,
) -> Pin<Box<dyn Future<Output = MetadataAnswer> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
Records matching a title and author.
params- Title (never empty), author, language, marketplace and limit.
Every provider's records plus the providers that failed.
fn chapters<'life0, 'life1, 'async_trait>(
&'life0 self,
params: &'life1 MetadataChaptersParams,
) -> Pin<Box<dyn Future<Output = ChaptersAnswer> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
The chapter layout of one edition.
params- Identifiers of the edition (never empty) and marketplace.
The first layout a provider found, plus the providers that failed before it.
Implemented by: NoMetadataProviders
pub struct Enrichment {
pub asin: String,
pub title: String,
pub authors: Option<String>,
pub narrators: Option<String>,
pub series: Option<String>,
pub series_index: Option<String>,
pub series_asin: Option<String>,
pub length_minutes: Option<i64>,
pub publisher: Option<String>,
pub subtitle: Option<String>,
pub cover_url: Option<String>,
pub isbn: Option<String>,
pub published_at: Option<String>,
pub categories: Option<String>,
pub description: Option<String>,
pub language: Option<String>,
pub confidence: Option<f64>,
}
Metadata pulled from the Audible catalog and a metadata provider for a confident match.
Fields
asin: Audible / Amazon ASIN when this edition is sold on Audible.title: Display title as shown on the storefront or library card.authors: Comma-separated author names when the storefront provides them.narrators: Comma-separated narrator names when known.series: Series name when the title belongs to a named series.series_index: Position within the series (e.g.1,1.5) when known.series_asin: Audible series ASIN when the catalog associates one.length_minutes: Audiobook runtime in whole minutes when known.publisher: Publisher imprint as reported by the catalog.subtitle: Optional subtitle when the catalog distinguishes it from the title.cover_url: HTTPS URL for cover art when the catalog exposes one.isbn: Canonical ISBN-13 (or ISBN-10 normalized) when published.published_at: ISO-8601 / RFC3339 timestamp when known (releaseDate).categories: ABS-style genre string (;-separated).description: Publisher or storefront synopsis; may be truncated for embeddings.language: BCP-47 / storefront language code (en,de, …) when known.confidence: Match confidence in[0.0, 1.0](omit/Nonefor legacy callers).
Implements: Clone, Debug, Deserialize<'de>, PartialEq, Serialize
pub struct ScoredMatch {
pub enrichment: Enrichment,
pub confidence: f64,
}
A scored Audible match candidate.
Fields
enrichment: Filled metadata fields from the public catalog match.confidence: Match confidence in[0.0, 1.0]; higher means a stronger ASIN match.
Implements: Clone, Debug
pub struct MatchQuery<'a> {
pub title: &'a str,
pub subtitle: Option<&'a str>,
pub author: Option<&'a str>,
pub narrator: Option<&'a str>,
pub isbn: Option<&'a str>,
pub duration_minutes: Option<f64>,
}
Owned-title (e.g. Libro) metadata used as the match query.
Fields
title: Display title as shown on the storefront or library card.subtitle: Optional subtitle when the catalog distinguishes it from the title.author: Primary author name used for fuzzy matching.narrator: Primary narrator name used for fuzzy matching.isbn: Canonical ISBN-13 (or ISBN-10 normalized) when published.duration_minutes: Candidate runtime in minutes for scoring against the seed.
Implements: Clone, Debug, Default
pub struct ScoreInput<'a> {
pub title: &'a str,
pub subtitle: Option<&'a str>,
pub author: Option<&'a str>,
pub narrator: Option<&'a str>,
pub isbn: Option<&'a str>,
pub duration_minutes: Option<f64>,
}
Candidate metadata used for confidence scoring.
Fields
title: Display title as shown on the storefront or library card.subtitle: Optional subtitle when the catalog distinguishes it from the title.author: Primary author name used for fuzzy matching.narrator: Primary narrator name used for fuzzy matching.isbn: Canonical ISBN-13 (or ISBN-10 normalized) when published.duration_minutes: Runtime in minutes (Audible / AudnexusruntimeLengthMin).
Implements: Clone, Debug
pub struct ChaptersAnswer {
pub found: Option<ProvidedChapters>,
pub failures: Vec<ProviderFailure>,
}
The first chapter layout any deployed provider had for one edition.
Fields
found: The firstfoundlayout in provider order, if any.failures: Providers whose call failed before a layout was found.
Implements: Clone, Debug, Default, Eq, PartialEq
pub struct MetadataAnswer {
pub records: Vec<ProvidedRecord>,
pub failures: Vec<ProviderFailure>,
}
What every deployed provider answered for one lookup or search.
Fields
records: Records in provider order, each provider's own relevance order kept.failures: Providers whose call failed. A caller that caches "nothing found" should not do so while this is non-empty, since the missing provider may have had a record.
pub fn incomplete(&self) -> bool
True when at least one provider failed.
Implements: Clone, Debug, Default, PartialEq
pub struct NoMetadataProviders;
No providers: every answer is empty. For callers with no plugin host.
Implements: Clone, Copy, Debug, Default, MetadataProviders
pub struct ProvidedChapters {
pub provider: String,
pub chapters: MetadataChapters,
}
A chapter layout and the provider plugin that returned it.
Fields
provider: PluginKey of the provider that answered.chapters: The layout; alwaysfound.
Implements: Clone, Debug, Eq, PartialEq
pub struct ProvidedRecord {
pub provider: String,
pub record: MetadataRecord,
}
One record and the provider plugin that returned it.
Fields
provider: PluginKey of the provider that answered.record: The record as the provider described it.
Implements: Clone, Debug, PartialEq
pub struct ProviderFailure {
pub provider: String,
pub message: String,
}
A provider call that failed, so its records are missing from the answer.
Fields
provider: PluginKey of the provider that failed.message: Error text from the plugin call.
Implements: Clone, Debug, Eq, PartialEq
pub enum EnrichError {
Sync(String),
Io(Error),
Catalog(CatalogError),
Library(LibraryError),
}
Errors from public-catalog enrichment and match scoring.
Variants
Sync: Failure during a blocking / sync enrich step.Io: Underlying filesystem or stream I/O failure.Catalog: The public Audible catalog request failed.Library: Error propagated frombookclerk_library.
Implements: Debug, Display, Error, From<CatalogError>, From<Error>, From<LibraryError>
pub async fn apply_enrichment_to_edition(
library: &LibraryStore,
edition_id: &str,
marketplace: &str,
matched: &ScoredMatch,
) -> Result<()>
Apply a confident Audible catalog match to a held edition.
The edition records the matched ASIN as its identifier (in the
edition's marketplace; an ASIN another edition already holds stays
there), its work takes the description, genres and cover it lacks, its
expression the language it lacks, and its own cover when it has none.
The edition then records audible as its enrichment source.
Each held title of the edition's listings also takes the match: catalog
fields win for display metadata
(title, contributors, series, ISBN, genres, publish date), an existing
asin is kept, and a store-native length_minutes is kept because
Audible runtimes include brand intro/outro that plain Acquire files
omit.
library- Open library store used for reads/writes.edition_id- The held edition matched (editions.id).marketplace- The marketplace the ASIN was matched in (such asus).matched- The catalog match and its confidence.
Returns an error when the edition is gone or a store read or write fails.
pub fn confidence_percent_to_fraction(percent: u8) -> f64
Convert a 0–100 percent threshold to a 0.0–1.0 fraction.
percent- Confidence threshold expressed as 0–100.
f64 result.
pub async fn enrich_editions_from_audible(
library: &LibraryStore,
providers: &dyn MetadataProviders,
min_confidence_percent: u8,
) -> Result<usize>
Match held editions that have no ASIN to the Audible catalog through the deployed metadata providers, and record each confident match.
Source-agnostic: any held edition with a title and/or an ISBN and no
ASIN is considered, which leaves out every edition an Audible listing
sells (its scan records the ASIN). Uses title, subtitle, author,
narrator, ISBN, and running time when present, and searches the
marketplace of the edition's first listing. min_confidence_percent is
0–100 (default DEFAULT_ENRICH_MIN_CONFIDENCE). With no provider that
answers ASIN lookups, nothing matches.
library- Open library store used for reads/writes.providers- Deployed metadata providers asked for each candidate ASIN.min_confidence_percent- Minimum match confidence, 0–100.
How many editions were matched.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub async fn enrichment_for_asin(
providers: &dyn MetadataProviders,
asin: &str,
region: &str,
) -> Option<Enrichment>
Provider metadata for a known ASIN (no confidence scoring).
Used by Discover / Wishlist / Library detail views to surface description, runtime, publisher, and related fields without requiring a library row. The first provider record that carries a title wins.
providers- Deployed metadata providers.asin- Audible / Amazon ASIN.region- Marketplace / region code (us,uk, …).
The record's fields, or None when the ASIN is malformed or no provider
has a record. A provider failure is logged and treated as no record.
pub fn enrichment_from_record(record: &MetadataRecord, asin: &str) -> Option<Enrichment>
Maps a provider record into enrichment fields.
record- The provider's record.asin- ASIN asked for; used when the record does not name one.
None when the record has no title.
pub async fn lookup_by_metadata(
providers: &dyn MetadataProviders,
query: &MatchQuery<'_>,
region: &str,
min_confidence: f64,
) -> Result<Option<ScoredMatch>>
Look up the best Audible match for the given query metadata.
Candidate ASINs come from the public Audible catalog search; each one's
record comes from the deployed metadata providers. Returns None when
no candidate meets min_confidence (0.0–1.0), or when no provider has a
record for any candidate.
providers- Deployed metadata providers asked for each candidate.query- Title, author, ISBN and runtime of the row to match.region- Marketplace / region code (us,uk, …).min_confidence- Minimum match confidence in[0.0, 1.0]to apply enrichment.
The highest-scoring candidate at or above min_confidence.
Returns an error when the HTTP client cannot be built or a catalog search fails.
pub async fn lookup_by_metadata_with_client(
http: &Client,
providers: &dyn MetadataProviders,
query: &MatchQuery<'_>,
region: &str,
min_confidence: f64,
) -> Result<Option<ScoredMatch>>
Catalog search + provider lookup against an already-built HTTP client.
http- Client for the public Audible catalog search.providers- Deployed metadata providers asked for each candidate.query- Title, author, ISBN and runtime of the row to match.region- Marketplace / region code (us,uk, …).min_confidence- Minimum match confidence in[0.0, 1.0]to apply enrichment.
The highest-scoring candidate at or above min_confidence.
Returns an error when a catalog search fails.
pub fn calculate_match_confidence(book: &ScoreInput<'_>, query: &MatchQuery<'_>) -> f64
Calculate match confidence in [0.0, 1.0].
Base score follows AudioBookshelf (duration / title / author). When Libro (or other) query metadata is richer:
- Narrator (both sides present): small extra weight in the blend
- Exact ISBN (normalized digits): boost by closing
ISBN_MATCH_GAP_CLOSEof the remaining gap to 1.0 (not a forced accept)
When the query title (without its subtitle) is an ASIN (see
is_asin_title), returns 1.0: the lookup fetched the candidate by
that ASIN. A plain ten-letter title such as Foundation is not an ASIN
and is scored like any other title.
book- Library book row to update.query- Query vector or free-text search string.
f64 result.
pub fn canonicalize_isbn(raw: &str) -> String
Normalize then convert ISBN-10 → ISBN-13 (978…) when possible.
ISBN is not available from every storefront (Chirp / GraphicAudio / Audible public catalog often omit it). When present, prefer this canonical form so 10- and 13-digit variants of the same book share one key.
raw- Stringrawfor this call.
String result for this operation.
pub fn clean_author_for_compares(author: &str) -> String
Clean an author string for fuzzy compares (AudioBookshelf cleanAuthorForCompares).
Decodes HTML entities, then cleans with
bookclerk_resolve::normalize::clean_author.
author- Author name or comma-separated names.
The cleaned, lower-cased name.
pub fn clean_title_for_compares(title: &str, keep_subtitle: bool) -> String
Clean a title for fuzzy compares (AudioBookshelf cleanTitleForCompares).
Decodes HTML entities (Libro.fm and others ship entity-encoded titles),
then cleans with bookclerk_resolve::normalize::clean_title.
title- Display title.keep_subtitle- When true, retain subtitle text for soft compares.
The cleaned, lower-cased title.
pub fn is_asin_title(title: &str) -> bool
True when a title field holds an Audible ASIN rather than a real title.
is_valid_asin accepts any ten ASCII alphanumerics, which every
ten-letter title (Foundation, Persuasion) also satisfies. A title is
only treated as an ASIN when it also has an ASIN's shape: B0 followed by
eight letters or digits (Audible's own ids), or an ISBN-10 (nine digits
and a digit or X check character), which older numeric ASINs use.
Case and surrounding whitespace are ignored.
title- Title text from a match query, possibly an ASIN typed or stored in place of a title.
true when the title should be looked up and scored as an ASIN.
pub fn isbn_exact_match(query_isbn: Option<&str>, book_isbn: Option<&str>) -> bool
Returns true when both sides normalize to the same ISBN-13 (or matching ISBN-10).
query_isbn- Stringquery_isbnfor this call.book_isbn- Stringbook_isbnfor this call.
true when the predicate holds.
pub fn levenshtein_distance(a: &str, b: &str) -> usize
Levenshtein distance (case-insensitive by default, matching ABS).
a- Left-hand vector.b- Right-hand vector.
usize result.
pub fn levenshtein_similarity(a: &str, b: &str) -> f64
Similarity in [0.0, 1.0] from Levenshtein distance.
a- Left-hand vector.b- Right-hand vector.
f64 result.
pub fn normalize_isbn(raw: &str) -> String
Digits-only ISBN for exact matching (strips hyphens / spaces / ISBN prefix).
raw- Stringrawfor this call.
String result for this operation.
pub fn asin_identifier(asin: &str, marketplace: &str) -> Identifier
An ASIN identifier scoped to marketplace.
asin- The ASIN as the library stores it.marketplace- Marketplace code (us,uk, …); blank means none.
pub fn chapter_info_from_layout(layout: &MetadataChapters) -> Value
Rebuilds a provider's flat pre-order chapter list as the nested Audible
chapter_info object the acquire pipeline reads.
Each node carries both the camelCase keys Audnexus uses and the
snake_case keys of Audible's own API, as the pipeline accepts either.
A chapter whose depth skips a level is attached to the deepest open
shallower chapter, so a malformed list still nests without losing a
chapter, chapters of equal depth stay siblings, and
nesting stops at MAX_CHAPTER_DEPTH levels.
layout- The provider's chapter layout.
An object with chapters, the brand intro/outro and runtime lengths when
known, and isAccurate.
pub fn isbn_identifier(isbn: &str) -> Identifier
An ISBN identifier.
isbn- ISBN-10 or ISBN-13, already normalized by the caller.
pub fn record_identifier(
record: &MetadataRecord,
scheme: IdentifierScheme,
) -> Option<&str>
The first value of scheme among a record's identifiers.
record- The provider record.scheme- The scheme wanted.
pub type Result<T> = Result<T, EnrichError>;
Result alias for this crate's error type.
pub const DEFAULT_ENRICH_MIN_CONFIDENCE: u8 = 90;
Default minimum confidence percent (AudioBookshelf-style 0–100 scale).
pub const MAX_CHAPTER_DEPTH: usize = 8;
Deepest chapter nesting chapter_info_from_layout builds. A provider's
layout is plugin output and the tree is later walked recursively, so a
deeper depth is clamped to this level. Audible itself nests at most a few
levels.
Generated from crates/bookclerk-enrich at main · View as Markdown