bookclerk_source
Host-side content-source traits plus the storefront types guests share.
Host registration code and the plugin host adapter implementing
ContentSource. The types a storefront guest also needs (DTOs, ABI
conversions, listing / record helpers) live in the slim
bookclerk_storefront crate and are re-exported here unchanged, so host
code keeps importing them from bookclerk_source. Guests depend on
bookclerk-storefront directly and never link this crate, which pulls in
the library store and host configuration.
Product narrative: docs/plugins/README.md. Style: docs/contributing/code-documentation.md.
| Item | Kind | Summary |
|---|---|---|
ContentSource |
trait | Pluggable audiobook storefront (auth, scan, fetch, catalog). |
FetchOptions |
struct | Options passed to crate::ContentSource::fetch_title. |
DownloadOptions |
struct | Options for acquire / fetch packaging and naming. |
SourceRegistry |
struct | Maps a registry address to an installed ContentSource. |
PortalAuthMode |
enum | How the connect portal authenticates this source. |
revoke_credentials_default |
function | Shared revoke path for plugins that seal as .plugin.auth (and legacy names). |
source_scope |
function | Opens the SourceScope for source: rows are isolated by its ContentSource::plugin_key and labelled with its ContentSource::id. |
bookclerk_storefront::audio_extensionbookclerk_storefront::default_preferred_languagebookclerk_storefront::extension_from_bytesbookclerk_storefront::extension_from_content_typebookclerk_storefront::extension_from_urlbookclerk_storefront::language_rankbookclerk_storefront::listingbookclerk_storefront::normalize_languagebookclerk_storefront::recordsbookclerk_storefront::CatalogHitbookclerk_storefront::CatalogSearchFieldbookclerk_storefront::CatalogSearchOptsbookclerk_storefront::CatalogSearchSortbookclerk_storefront::CatalogSortDirbookclerk_storefront::ChapterKindbookclerk_storefront::ConfigOptionValuebookclerk_storefront::ExpandSeedbookclerk_storefront::ImportCredentialsOptionsbookclerk_storefront::LoginOptionsbookclerk_storefront::OAuthProgressbookclerk_storefront::PlainAudioPartbookclerk_storefront::PlainFetchbookclerk_storefront::PriceLookupbookclerk_storefront::PricedAnswerbookclerk_storefront::PricedListingbookclerk_storefront::PurchaseHintOptsbookclerk_storefront::Resultbookclerk_storefront::ScanOptionsbookclerk_storefront::ScanSummarybookclerk_storefront::SourceAccountbookclerk_storefront::SourceBrandbookclerk_storefront::SourceConfigOptionbookclerk_storefront::SourceErrorbookclerk_storefront::SourceFetchbookclerk_storefront::SourcePurchaseHint
abi: Host-side conversions between storefront types and the typed plugin ABI.
pub trait ContentSource: Send + Sync {
fn id(&self) -> &str;
fn plugin_key(&self) -> &str;
fn plugin_instance_id(&self) -> Option<&str>;
fn guest_pid(&self) -> Option<u32>;
fn display_name(&self) -> &str;
fn aliases(&self) -> &'static [&'static str];
fn portal_auth_mode(&self) -> PortalAuthMode;
fn portal_brand(&self) -> SourceBrand;
fn sort_key(&self) -> u32;
fn login<'life0, 'life1, 'async_trait>(
&'life0 self,
scope: &'life1 SourceScope,
opts: LoginOptions,
) -> Pin<Box<dyn Future<Output = Result<SourceAccount>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,;
fn login_with_oauth_progress<'life0, 'life1, 'life2, 'async_trait>(
&'life0 self,
scope: &'life1 SourceScope,
opts: LoginOptions,
on_progress: &'life2 dyn Fn(OAuthProgress) + Send + Sync,
) -> Pin<Box<dyn Future<Output = Result<SourceAccount>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,;
fn import_credentials<'life0, 'life1, 'life2, 'async_trait>(
&'life0 self,
scope: &'life1 SourceScope,
path: &'life2 Path,
opts: ImportCredentialsOptions,
) -> Pin<Box<dyn Future<Output = Result<Vec<SourceAccount>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,;
fn revoke_credentials<'life0, 'life1, 'life2, 'async_trait>(
&'life0 self,
scope: &'life1 SourceScope,
account_id: &'life2 str,
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,;
fn list_accounts<'life0, 'life1, 'async_trait>(
&'life0 self,
scope: &'life1 SourceScope,
) -> Pin<Box<dyn Future<Output = Result<Vec<SourceAccount>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,;
fn scan<'life0, 'life1, 'async_trait>(
&'life0 self,
scope: &'life1 SourceScope,
opts: ScanOptions,
) -> Pin<Box<dyn Future<Output = Result<ScanSummary>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,;
fn fetch_title<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>(
&'life0 self,
scope: &'life1 SourceScope,
account_id: &'life2 str,
title_id: &'life3 str,
opts: &'life4 FetchOptions,
) -> Pin<Box<dyn Future<Output = Result<SourceFetch>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait,
'life4: 'async_trait,;
fn config_options(&self) -> &'static [SourceConfigOption];
fn inspect_title<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>(
&'life0 self,
scope: &'life1 SourceScope,
account_id: &'life2 str,
title_id: &'life3 str,
opts: &'life4 FetchOptions,
) -> Pin<Box<dyn Future<Output = Result<Value>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait,
'life4: 'async_trait,;
fn search_catalog<'life0, 'life1, 'async_trait>(
&'life0 self,
opts: &'life1 CatalogSearchOpts,
) -> Pin<Box<dyn Future<Output = Result<Vec<CatalogHit>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,;
fn catalog_detail<'life0, 'life1, 'async_trait>(
&'life0 self,
product_id: &'life1 str,
) -> Pin<Box<dyn Future<Output = Result<Option<CatalogHit>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,;
fn answers_catalog_detail_by_product_id(&self) -> bool;
fn answers_catalog_detail_by_isbn(&self) -> bool;
fn catalog_detail_by_isbn<'life0, 'life1, 'async_trait>(
&'life0 self,
isbn: &'life1 str,
) -> Pin<Box<dyn Future<Output = Result<Option<CatalogHit>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,;
fn expand_candidates<'life0, 'life1, 'async_trait>(
&'life0 self,
seed: &'life1 ExpandSeed,
limit: usize,
) -> Pin<Box<dyn Future<Output = Result<Vec<CatalogHit>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,;
fn purchase_hint<'life0, 'life1, 'async_trait>(
&'life0 self,
opts: &'life1 PurchaseHintOpts,
) -> Pin<Box<dyn Future<Output = Result<Option<SourcePurchaseHint>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,;
fn purchase_hints<'life0, 'life1, 'async_trait>(
&'life0 self,
opts: &'life1 [PurchaseHintOpts],
) -> Pin<Box<dyn Future<Output = Result<Vec<Option<SourcePurchaseHint>>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,;
fn answers_price_by_isbn(&self) -> bool;
fn answers_price_by_asin(&self) -> bool;
fn acquire_pace(&self) -> AcquirePace;
fn purchase_hint_answers<'life0, 'life1, 'async_trait>(
&'life0 self,
opts: &'life1 [PurchaseHintOpts],
) -> Pin<Box<dyn Future<Output = Result<Vec<PricedAnswer>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,;
fn answers_quality_offers(&self) -> bool;
fn quality_offers<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>(
&'life0 self,
scope: &'life1 SourceScope,
account_id: &'life2 str,
title_ids: &'life3 [String],
download: &'life4 DownloadOptions,
) -> Pin<Box<dyn Future<Output = Result<Vec<Option<StreamQuality>>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait,
'life4: 'async_trait,;
fn list_deals<'life0, 'async_trait>(
&'life0 self,
limit: usize,
) -> Pin<Box<dyn Future<Output = Result<Vec<CatalogHit>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,;
}
Pluggable audiobook storefront (auth, scan, fetch, catalog).
Plugins own their id, brand, auth mode, and config parsing. Hosts register concrete crates at startup and talk only through this trait.
All credential and library mutations go through SourceScope, which
forces source / provider to this plugin's id. First-party in-repo
adapters and third-party JSON-RPC plugins share the same scope rules.
fn id(&self) -> &str
Display / CLI alias (audible, libro, …). Globally unique within one
installation; durable identity is Self::plugin_key.
fn plugin_key(&self) -> &str
Provenance-qualified PluginKey when this adapter is an external guest.
Defaults to Self::id for in-crate test doubles.
fn plugin_instance_id(&self) -> Option<&str>
Plugin instance that owns this deployed source.
None for transitional startup and in-crate adapters, which stay
addressable by Self::plugin_key and Self::id. Two deployed
instances of one key each return their own id.
fn guest_pid(&self) -> Option<u32>
Native guest pid when this process spawned the source.
None for in-process adapters and sources that have not recorded a pid.
fn display_name(&self) -> &str
Human-facing store name for UI / logs.
fn aliases(&self) -> &'static [&'static str]
Alternate ids accepted by CLI / config (libro.fm, ga, …).
fn portal_auth_mode(&self) -> PortalAuthMode
Connect-portal auth mode.
fn portal_brand(&self) -> SourceBrand
Portal button brand (colors + favicon).
fn sort_key(&self) -> u32
Stable sort key for registry listing (lower first).
fn login<'life0, 'life1, 'async_trait>(
&'life0 self,
scope: &'life1 SourceScope,
opts: LoginOptions,
) -> Pin<Box<dyn Future<Output = Result<SourceAccount>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
Authenticate and persist credentials via SourceScope.
fn login_with_oauth_progress<'life0, 'life1, 'life2, 'async_trait>(
&'life0 self,
scope: &'life1 SourceScope,
opts: LoginOptions,
on_progress: &'life2 dyn Fn(OAuthProgress) + Send + Sync,
) -> Pin<Box<dyn Future<Output = Result<SourceAccount>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
Interactive OAuth login with progress (URL / waiting).
Default: ignores progress and calls Self::login. OAuth sources
(Audible, external guests with login.start) override this.
fn import_credentials<'life0, 'life1, 'life2, 'async_trait>(
&'life0 self,
scope: &'life1 SourceScope,
path: &'life2 Path,
opts: ImportCredentialsOptions,
) -> Pin<Box<dyn Future<Output = Result<Vec<SourceAccount>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
Import credentials from a file (auth JSON, Libation export, …).
Default: unsupported. Audible implements auth-file / Libation / mkb79.
fn revoke_credentials<'life0, 'life1, 'life2, 'async_trait>(
&'life0 self,
scope: &'life1 SourceScope,
account_id: &'life2 str,
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
Delete stored credentials for account_id (books / account rows kept).
Default: removes {account}.plugin.auth, any other source_auth secrets
for the account, common legacy name patterns, and a Widevine {id}.wvd.
fn list_accounts<'life0, 'life1, 'async_trait>(
&'life0 self,
scope: &'life1 SourceScope,
) -> Pin<Box<dyn Future<Output = Result<Vec<SourceAccount>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
List accounts for this plugin (scope filters by source id).
fn scan<'life0, 'life1, 'async_trait>(
&'life0 self,
scope: &'life1 SourceScope,
opts: ScanOptions,
) -> Pin<Box<dyn Future<Output = Result<ScanSummary>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
Sync library rows using scoped credentials / upserts.
fn fetch_title<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>(
&'life0 self,
scope: &'life1 SourceScope,
account_id: &'life2 str,
title_id: &'life3 str,
opts: &'life4 FetchOptions,
) -> Pin<Box<dyn Future<Output = Result<SourceFetch>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait,
'life4: 'async_trait,
Fetch everything needed to acquire one title (no storage writes).
title_id is the source-native product id (Audible ASIN or Libro ISBN).
Auth is loaded through scope; opts.files_dir carries the
BOOKCLERK_FILES_DIR path for CDM / Widevine resolution.
fn config_options(&self) -> &'static [SourceConfigOption]
Source-native [sources.<id>] knobs for config / UI discovery.
fn inspect_title<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>(
&'life0 self,
scope: &'life1 SourceScope,
account_id: &'life2 str,
title_id: &'life3 str,
opts: &'life4 FetchOptions,
) -> Pin<Box<dyn Future<Output = Result<Value>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait,
'life4: 'async_trait,
Optional diagnostic / license inspect for one title (opaque JSON).
Default: unsupported. Hosts must not special-case store APIs — sources that expose license dumps (e.g. Audible) override this.
fn search_catalog<'life0, 'life1, 'async_trait>(
&'life0 self,
opts: &'life1 CatalogSearchOpts,
) -> Pin<Box<dyn Future<Output = Result<Vec<CatalogHit>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
Public catalog typeahead / search (no account required).
Default: empty. Discover aggregates hits across registered sources.
fn catalog_detail<'life0, 'life1, 'async_trait>(
&'life0 self,
product_id: &'life1 str,
) -> Pin<Box<dyn Future<Output = Result<Option<CatalogHit>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
Fetch rich bibliographic metadata for one catalog product (no account).
Default: none. Used when search/expand hits are lean (e.g. HTML scrape) and a title detail dialog needs narrator, runtime, description, etc.
fn answers_catalog_detail_by_product_id(&self) -> bool
Whether Self::catalog_detail resolves this source's own product ids
(the ids its search, expand and deals hits carry) to a full record:
the guest's declared CatalogCapabilities.detailByProductId.
Catalog search and title dialogs ask a source for an edition it listed
only when this is true, so a source without a detail lookup is never
woken for one. Default: false.
fn answers_catalog_detail_by_isbn(&self) -> bool
Whether Self::catalog_detail_by_isbn resolves any audiobook ISBN to
a full record (the guest's declared CatalogCapabilities.detailByIsbn).
Catalog search asks every source that returns true to fill lean
result rows from other stores, instead of naming one storefront.
Default: false.
fn catalog_detail_by_isbn<'life0, 'life1, 'async_trait>(
&'life0 self,
isbn: &'life1 str,
) -> Pin<Box<dyn Future<Output = Result<Option<CatalogHit>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
Full catalog record for an ISBN, from a source that declares
Self::answers_catalog_detail_by_isbn.
Default: Self::catalog_detail with the ISBN as the product id.
Returns the source's error; external guests soft-fail to Ok(None).
fn expand_candidates<'life0, 'life1, 'async_trait>(
&'life0 self,
seed: &'life1 ExpandSeed,
limit: usize,
) -> Pin<Box<dyn Future<Output = Result<Vec<CatalogHit>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
Expand related / series / author candidates from a taste seed.
Default: empty. limit caps returned hits (sources may also budget HTTP).
fn purchase_hint<'life0, 'life1, 'async_trait>(
&'life0 self,
opts: &'life1 PurchaseHintOpts,
) -> Pin<Box<dyn Future<Output = Result<Option<SourcePurchaseHint>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
Resolve a purchase / catalog URL (optionally with live price).
Default: none.
fn purchase_hints<'life0, 'life1, 'async_trait>(
&'life0 self,
opts: &'life1 [PurchaseHintOpts],
) -> Pin<Box<dyn Future<Output = Result<Vec<Option<SourcePurchaseHint>>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
Resolve purchase hints for several titles in one call, one answer per query in order.
Default: Self::purchase_hint for each query, stopping at the
first error. A store whose catalog prices many products per request
overrides this to make one request. A SourceError::RateLimited
error applies to the whole batch.
Returns the first query's error.
fn answers_price_by_isbn(&self) -> bool
Whether Self::purchase_hint_answers prices a query with
lookup = PriceLookup::Isbn by that exact ISBN (the guest's
declared CatalogCapabilities.priceByIsbn).
Default: false, so the host never sends ISBN lookups.
fn answers_price_by_asin(&self) -> bool
Whether Self::purchase_hint_answers prices a query with
lookup = PriceLookup::Asin by that exact ASIN (the guest's
declared CatalogCapabilities.priceByAsin).
Default: false, so the host never sends ASIN lookups.
fn acquire_pace(&self) -> AcquirePace
How fast the host may download from one store account of this
storefront when it starts the downloads itself (the manifest's
[acquire] table; see bookclerk_library::pacing).
Default: no budget, no gap, the host's default cool-down.
fn purchase_hint_answers<'life0, 'life1, 'async_trait>(
&'life0 self,
opts: &'life1 [PurchaseHintOpts],
) -> Pin<Box<dyn Future<Output = Result<Vec<PricedAnswer>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
Self::purchase_hints with each query's title-search records
(PricedAnswer::records), one answer per query in order.
Default: Self::purchase_hints with no records, so a caller falls
back to the store's own pick. External guests override this to pass
the records a PriceLookup::Title query returned.
fn answers_quality_offers(&self) -> bool
Whether Self::quality_offers answers which stream an account
would download today (the guest's declared
CatalogCapabilities.qualityOffers).
Default: false, so the quality-upgrade check skips the store.
fn quality_offers<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>(
&'life0 self,
scope: &'life1 SourceScope,
account_id: &'life2 str,
title_ids: &'life3 [String],
download: &'life4 DownloadOptions,
) -> Pin<Box<dyn Future<Output = Result<Vec<Option<StreamQuality>>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
'life1: 'async_trait,
'life2: 'async_trait,
'life3: 'async_trait,
'life4: 'async_trait,
The stream account_id would download for each of title_ids (the
store's product ids) today with download's fetch options, one
answer per id in order; None where the store could not say.
Nothing is licensed or downloaded.
Default: no answers.
Returns SourceError::RateLimited when the store asked to slow
down, and another error when the credentials cannot be read or the
call or its reply fails; either applies to the whole batch.
fn list_deals<'life0, 'async_trait>(
&'life0 self,
limit: usize,
) -> Pin<Box<dyn Future<Output = Result<Vec<CatalogHit>>> + Send + 'async_trait>>
where
Self: 'async_trait,
'life0: 'async_trait,
Current deals / promos for discovery shelves.
Default: empty.
pub struct FetchOptions {
pub download: DownloadOptions,
pub cache_dir: PathBuf,
pub files_dir: PathBuf,
pub max_cache_bytes: Option<u64>,
pub cancel: Option<Arc<AtomicBool>>,
}
Options passed to crate::ContentSource::fetch_title.
Fields
download: Packaging / naming knobs for this acquire (from[output]+ destination).cache_dir: Absolute directory for scratch downloads for this fetch.files_dir: Root files directory (BOOKCLERK_FILES_DIR). Used for CDM / Widevine path resolution by Audible. Non-auth operations only; auth is loaded from thebookclerk_library::LibraryStorepassed directly to the trait method.max_cache_bytes: Optional on-disk budget forcache_dir(bytes). Sources should callSelf::enforce_cache_budgetbetween chunks.cancel: Cooperative cancel for mid-fetch quota or a lost job fence.
pub fn enforce_cache_budget(&self) -> Result<()>
Fails when cancel is set or cache_dir exceeds Self::max_cache_bytes.
Returns SourceError::Other when the fetch was cancelled or the
cache directory is over the remaining scratch quota.
Implements: Clone, Debug
pub struct DownloadOptions {
pub quality: AudioQuality,
pub format: OutputFormat,
pub widevine: bool,
pub xhe_aac: bool,
pub widevine_cdm: Option<PathBuf>,
pub widevine_cdm_provider: Option<String>,
pub naming_profile: NamingProfile,
pub folder_template: Option<String>,
pub file_template: Option<String>,
pub download_cover: bool,
pub download_pdf: bool,
pub create_cue: bool,
pub fixup_metadata: bool,
pub keep_codec_in_m4b: bool,
pub chapter_json: ChapterJsonMode,
pub save_metadata_json: bool,
pub cover_size: String,
pub chapter_layout: String,
pub overwrite_existing: bool,
pub split_files_by_chapter: bool,
pub split_mp3_max_mb: u32,
pub chapter_file_template: Option<String>,
pub chapter_title_template: Option<String>,
pub minimum_file_duration_minutes: u32,
pub combine_nested_chapter_titles: bool,
pub merge_opening_and_end_credits: bool,
pub strip_unabridged: bool,
pub strip_audible_brand_audio: bool,
pub download_clips_bookmarks: bool,
pub retain_aax_file: bool,
pub download_speed_limit_kbps: u32,
pub lame: LameConfig,
pub copies: Vec<OutputCopy>,
pub opus: OpusSettings,
pub max_sample_rate: Option<u32>,
pub creation_time: FileTimestampMode,
pub last_write_time: FileTimestampMode,
pub replacement_characters: Vec<ReplacementRule>,
pub path_limits: PathLimits,
pub save_podcasts_to_parent_folder: bool,
}
Options for acquire / fetch packaging and naming.
Store-specific ingest knobs live on each crate::ContentSource instance
(parsed from [sources.<id>] at registration). quality remains here so
Audible’s download helpers can overlay the plugin bitrate for a single fetch.
Fields
quality: Optional per-fetch audio quality overlay (set by plugins that need it).format: Post-download packaging format (M4B / MP3 / passthrough).widevine: Prefer Widevine/CENC download when the store offers it.xhe_aac: Prefer xHE-AAC on the Widevine path when offered.widevine_cdm: Optional local Widevine.wvdpath (absolute or under files dir).widevine_cdm_provider: Remote L3 CDM provider URL (None= classic Libation AudibleCdm; empty/off= disable).naming_profile: Path-template profile; per-field template overrides win when set.folder_template: Optional folder-path template override;Noneuses the naming profile.file_template: Optional file-stem template override;Noneuses the naming profile.download_cover: When true, download a cover JPEG alongside audio.download_pdf: When true, download a companion PDF when the store exposes one.create_cue: When true, write a.cuesidecar from API chapters.fixup_metadata: When true, embed tags, cover, and chapters after packaging.keep_codec_in_m4b: When true, an M4B keeps Opus, FLAC, ALAC, E-AC-3 or AC-4 audio as it is instead of encoding it to AAC (output.keep_codec_in_m4b).chapter_json: Which chapter JSON sidecars to write (off/flat/tree/both).save_metadata_json: When true, persist raw catalog API JSON asmetadata.json.cover_size: Cover image size request (500,1215, ornative).chapter_layout: Preferred Audible chapter API layout when fetching (treeorflat).overwrite_existing: When true, re-acquire even if media already exists at the destination.split_files_by_chapter: When true, also split packaged output into per-chapter files.split_mp3_max_mb: Max MP3 part size in MiB when format issplit_mp3_by_size.chapter_file_template: Optional per-chapter file-stem template.chapter_title_template: Optional embedded chapter-title template.minimum_file_duration_minutes: Drop chapter splits shorter than this many minutes (0= keep all).combine_nested_chapter_titles: When true, flatten nested chapter titles into a single path segment.merge_opening_and_end_credits: When true, merge opening/end credit chapters into adjacent chapters.strip_unabridged: When true, strip an "Unabridged" suffix from titles used in naming.strip_audible_brand_audio: When true, trim Audible brand intro/outro from the remux window.download_clips_bookmarks: When true, download Audible clips/bookmarks sidecars when offered.retain_aax_file: When true, keep the encrypted download in storage (RetainAaxFile).download_speed_limit_kbps: Fetch speed cap in KB/s (0= unlimited).lame: LAME encoder knobs used when packaging to MP3.copies: Further copies of each book beside the oneSelf::formatandSelf::lamemake (output.copies).opus: Opus encoder settings used whenSelf::formatisopus: the main output's defaults, or an Opus copy's quality afterSelf::for_copy.max_sample_rate: Optional ceiling for output sample rate in Hz (None= leave source rate).creation_time: How to set the file creation / birth timestamp after acquire.last_write_time: How to set the file last-write / mtime after acquire.replacement_characters: Resolved find/replace rules the host applies to tag values when it fills a naming template.path_limits: Length limits for the host keys naming templates build.save_podcasts_to_parent_folder: Save podcast episodes under the parent show folder.
pub fn from_fetch_options(fetch: &FetchOptions) -> Self
Guest-side reconstruction: host defaults overlaid with the fetch knobs
the host sent in abi::FetchTitleParams::fetch.
pub fn apply_fetch_options(&mut self, fetch: &FetchOptions)
Overlays wire fetch knobs onto these options (packaging knobs untouched).
pub fn for_destination(cfg: &Config, naming: &DestinationNaming, prefix: &str) -> Self
Build acquire options stamped for one output destination.
Packaging knobs come from global [output]; naming templates prefer
the destination's own overrides, which a storage plugin may
declare as [[settings]] and the host reads from the deployed
instance document. prefix is that document's key prefix, which
the host-key length budget leaves room for. The storage plugin
translates each host key into the key it stores.
pub fn effective_output(&self) -> OutputFormat
Resolved post-processing format.
pub fn copies_to_make(&self) -> Vec<OutputCopy>
Every copy an acquire makes, the one Self::format and
Self::lame make first (bookclerk_config::copies_to_make).
pub fn for_copy(&self, copy: &OutputCopy) -> Self
The options packaging copy: its format and the encoder settings
its quality gives, with chapter splitting on exactly for
mp3_chapters.
pub fn wants_mp3(&self) -> bool
True when the effective format re-encodes to MP3.
pub fn wants_split_by_chapter(&self) -> bool
True when output should be split into per-chapter files.
pub fn is_noop_output(&self) -> bool
True when store-delivered media is left as-is (no remux/transcode).
pub fn wants_opus(&self) -> bool
True when the effective format encodes to Ogg Opus.
pub fn wants_split_by_size(&self) -> bool
True when output is split into MP3 parts by target size.
pub fn chapter_json_flat(&self) -> bool
True when a flat chapters.flat.json sidecar should be written.
pub fn chapter_json_tree(&self) -> bool
True when a nested chapters.tree.json sidecar should be written.
pub fn wants_chapter_json(&self) -> bool
True when any chapter JSON sidecar should be written.
pub fn naming_templates(&self) -> ResolvedNamingTemplates
Resolve folder / file / chapter-file templates from the naming profile with per-field overrides.
Implements: Clone, Debug, Default, Deserialize<'de>, From<&Config>, From<&DownloadOptions>, From<&OutputConfig>, PartialEq, Serialize
pub struct SourceRegistry {
/* private fields */
}
Maps a registry address to an installed ContentSource.
A deployed source is addressed by ContentSource::plugin_instance_id.
A source with no instance id is addressed by ContentSource::plugin_key.
A plugin key or display alias that several instances share routes to the
plugin's default instance (see Self::set_default_instance); a job may
pin another instance through Self::route. Nothing fails closed on a
shared key: accounts belong to the plugin, so any instance may serve them.
pub fn new() -> Self
Empty registry with no sources registered.
pub fn register(&mut self, source: Arc<dyn ContentSource>)
Register (or replace) a source at its instance id, or its PluginKey.
A second instance of the same plugin key stays in the map. Re-registering the same instance id replaces that guest only.
pub fn remove_instance(&mut self, plugin_instance_id: &str) -> bool
Drops the source registered under plugin_instance_id.
Other instances of the same plugin key stay. Returns whether a row was removed.
pub fn set_default_instance(&mut self, plugin_key: &str, plugin_instance_id: &str)
Names the instance a bare plugin key or alias routes to when several
instances of plugin_key are registered.
pub fn default_instance(&self, plugin_key: &str) -> Option<&str>
Default instance id recorded for plugin_key, if any.
pub fn get(&self, id_or_alias: &str) -> Option<Arc<dyn ContentSource>>
Look up a source by plugin instance id, PluginKey, or display alias.
An instance id matches that deployed source. A plugin key or alias shared by several instances of one plugin routes to the default instance, else the lowest instance id, so a bare key always resolves while any instance is registered. An alias that two different plugins claim is ambiguous and resolves to nothing: the caller names the PluginKey or an instance id instead.
pub fn route(
&self,
id_or_alias: &str,
preferred_instance: Option<&str>,
) -> Option<Arc<dyn ContentSource>>
Self::get with an optional pinned instance.
preferred_instance must be a registered instance of the plugin that
id_or_alias names; a pin for another plugin, or an unknown id, yields
None rather than silently falling back.
pub fn require(&self, id_or_alias: &str) -> Result<Arc<dyn ContentSource>>
Look up a source or return crate::SourceError::Api when missing.
Returns an API error when id_or_alias is not registered.
pub fn require_routed(
&self,
id_or_alias: &str,
preferred_instance: Option<&str>,
) -> Result<Arc<dyn ContentSource>>
Self::require with an optional pinned instance.
Returns an API error when nothing is registered under id_or_alias,
or when preferred_instance is not one of its instances.
pub fn resolve_id(&self, id_or_alias: &str) -> Option<String>
Resolve a needle to the canonical plugin id when registered.
pub fn all(&self) -> Vec<Arc<dyn ContentSource>>
All registered sources in stable plugin order.
pub fn routed(&self) -> Vec<Arc<dyn ContentSource>>
One routed source per registered plugin key, in stable plugin order.
Accounts belong to the plugin, so a scan that visited every instance
of one key would read and write the same rows twice. Bare-key routing
picks the instance; a pinned job goes through Self::route.
pub async fn scan_all(
&self,
library: &LibraryStore,
opts: ScanOptions,
) -> Result<ScanSummary>
Scan every registered plugin once (honoring per-source account filters).
When opts.accounts is non-empty, each source only receives the subset of
account needles that resolve to an account on that source. Sources with no
matching accounts are skipped instead of failing the whole multi-source scan.
ScanOptions::cancel is checked between sources.
Returns an error when the operation fails.
pub async fn scan_one(
&self,
library: &LibraryStore,
source: Arc<dyn ContentSource>,
opts: ScanOptions,
) -> Result<ScanSummary>
Scan one registered source (a job pinned to a plugin instance).
Account filters apply as in Self::scan_all.
Returns an error when the scan fails or no account matches.
Implements: Clone, Default
pub enum PortalAuthMode {
Oauth,
Password,
}
How the connect portal authenticates this source.
Variants
Oauth: Browser / QR OAuth (Audible).Password: Username + password form.
pub fn as_str(self) -> &'static str
Wire / portal id (oauth or password).
Implements: Clone, Copy, Debug, Eq, PartialEq
pub async fn revoke_credentials_default(
scope: &SourceScope,
account_id: &str,
) -> Result<()>
Shared revoke path for plugins that seal as .plugin.auth (and legacy names).
Returns an error when the operation fails.
pub fn source_scope(library: &LibraryStore, source: &dyn ContentSource) -> SourceScope
Opens the SourceScope for source: rows are isolated by its
ContentSource::plugin_key and labelled with its ContentSource::id.
Every instance of one plugin shares this scope; accounts are not tied to a plugin instance.
Generated from crates/bookclerk-source at main · View as Markdown