Libation headless parity (reference)

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

Bookclerk is a multi-storefront library manager. This page is a compatibility reference for the Audible / classic Libation headless surface — not a product roadmap. For day-to-day docs start at README.md.

Historical goal (PR1): Full feature parity with Libation Chardonnay for headless/CLI/daemon use. A Bookclerk-native web GUI (React, served by bookclerkd) is tracked in the UI page and is not a WinForms/Avalonia port. Native desktop/tray is deferred.

Chardonnay and Classic share the same backend; this matrix uses upstream master / LibationCli + Configuration.PersistentSettings.cs as the reference.

Verdict

Headless parity with Classic/Chardonnay is complete for the LibationCli + acquire surface. All LibationCli verbs, download/decrypt settings that affect headless operation, naming templates, podcast handling, library metadata, migrate-from-classic, and classic EF Postgres copydb are implemented.

Remaining items are either GUI-only, intentionally deferred (upgrade checks), or minor headless polish listed under Still open (non-GUI).

Status legend

Symbol Meaning
✅ Implemented
⚠️ Partial / subset
❌ Not yet implemented
🚫 Out of PR1 scope (GUI-only)

CLI verbs (LibationCli)

Verb Status bookclerk
scan ✅ library scan
liberate ✅ library acquire (Bookclerk verb) — --pdf, --force, positional ASINs; queued for bookclerkd. Libation's preloaded-license (--license) and per-run setting-override (-o key=value) flags were removed (never implemented; use config set for settings)
set-status ✅ library set-status — probe-based match; --downloaded / --not-downloaded / --force / --fix-layout + ASINs
get-license ✅ library get-license --json (summary) / --full (raw API JSON)
search ✅ library search (+ --filter saved quick filters)
export ✅ library export --csv|--json|--xlsx
convert ✅ library convert --to FORMAT:QUALITY adds a copy beside the stored book (also in the web app)
import-account ✅ auth import --mkb79
login-external ✅ auth login --external
list-accounts ✅ auth list (--bare: account, name, locale, scan, auth)
set-scan ✅ auth set-scan <account> [--scan true|false] (GUI checkbox; CLI addition)
get-setting ✅ config get/show/paths (classic key aliases + --bare)
copydb ✅ copydb — classic Libation EF Postgres schema (default); --format flat for native
version ✅ bookclerk version
version --check 🚫 Intentionally deferred (no upgrade checks in PR1)
help ✅ clap
Progress bar (acquire / convert) ✅ Queued jobs report progress while the CLI waits
Template tag list / preview ✅ config template tags / config template preview <asin>
Naming profiles ✅ output.naming_profile (audiobookshelf default, classic); config template profiles

Settings.json → config.toml

Classic key Status bookclerk key
Books ✅ local plugin setting root (bookclerk plugins config set local root …)
FileDownloadQuality ✅ audible plugin setting bitrate
DecryptToLossy ✅ output.format = "single_mp3" or "enriched_m4b"
UseWidevine ✅ output.widevine
Request_xHE_AAC ✅ output.xhe_aac
FolderTemplate / FileTemplate ✅ Libation NamingTemplate port (bookclerk-naming) + config template preview; defaults from naming_profile
MaxFilenameLength (255) ✅ output.max_filename_length + S3 full-key budget in acquire naming
DownloadCoverArt ✅ output.download_cover
CreateCueSheet ✅ output.create_cue
AllowLibationFixup ✅ output.fixup_metadata
SaveMetadataToFile ✅ output.save_metadata_json
AutoDownloadEpisodes ✅ library.auto_acquire
AutoScan ✅ library.scan_interval_minutes
OverwriteExisting ✅ output.overwrite_existing
InProgress ✅ output.in_progress
ImportEpisodes ✅ library.import_episodes
ImportPlusTitles ✅ library.import_plus_titles
DownloadEpisodes ✅ library.download_episodes
BadBook ✅ output.bad_book_action
SplitFilesByChapter ✅ output.format = "split_mp3_by_chapter"
ChapterFileTemplate / ChapterTitleTemplate ✅ output.chapter_file_template / chapter_title_template
MinimumFileDuration ✅ output.minimum_file_duration_minutes
CombineNestedChapterTitles ✅ output.combine_nested_chapter_titles
MergeOpeningAndEndCredits ✅ output.merge_opening_and_end_credits
StripUnabridged / StripAudibleBrandAudio ✅ output.strip_unabridged / strip_audible_brand_audio (brand audio is trimmed from the media using chapter brand_intro/brand_outro durations; titles are scrubbed too)
DownloadClipsBookmarks ✅ output.download_clips_bookmarks (JSON sidecar)
ClipsBookmarksFileFormat ⚠️ Always JSON; classic also offers CSV/XLSX
RetainAaxFile ✅ output.retain_aax_file
DownloadSpeedLimit ✅ output.download_speed_limit_kbps
Lame* ✅ output.lame.* (target/quality/bitrate/mode/downsample/CBR)
LameMatchSourceBR ⚠️ Not a separate toggle; bitrate path uses configured kbps
MoveMoovToBeginning ⚠️ Always on for native remux (moov faststart)
ReplacementCharacters ✅ output.replacement_characters (explicit) or output.path_sanitization (auto/windows/posix/s3/none)
MaxSampleRate ✅ output.max_sample_rate
CreationTime / LastWriteTime ✅ output.creation_time / last_write_time (local + S3 object metadata)
SavePodcastsToParentFolder ✅ library.save_podcasts_to_parent_folder
RequestSpatial / SpatialAudioCodec 🚫 Stubbed/false in upstream classic today
Theme / Grid* / Column layout 🚫 GUI-only
UseCoverAsFolderIcon 🚫 GUI/OS folder-icon behavior
UseWebView / BetaOptIn / ShowImportedStats / FirstLaunch 🚫 GUI-only

Library / user metadata

Field Status
Tags ✅ DB + search index + migrate import
User ratings (overall/performance/story) ✅ DB + migrate import
Finished flag ✅ DB + migrate import
Separate PDF status ✅
Publisher, length, categories, subtitle, published_at, content_kind, series_asin ✅ scan + DB
Podcast parents skipped on acquire ✅ classic WithoutParents
Podcast episode parent-folder naming ✅ SavePodcastsToParentFolder
Lucene/Tantivy search index ✅
Saved quick filters ✅ library filters list/save/delete

Still open (non-GUI)

Item Notes
Upgrade checks (version --check) Intentionally deferred for PR1
Clips/bookmarks export format JSON only (classic CSV/XLSX options unused in headless path)
MoveMoovToBeginning / LameMatchSourceBR toggles Behavior covered by defaults / always-on moov_faststart
Exotic naming edge cases Rare TimeSpan masks / locale-specific number formats
Per-byte download progress Queued acquire and convert jobs report progress; classic also draws a byte bar mid-download

Explicitly out of PR1 (GUI)

Item Reason
Chardonnay / Classic GUI (WinForms / Avalonia) Not planned — Bookclerk ships a web GUI + optional tray (the UI page)
Password + CAPTCHA WebView login GUI-only; OAuth headless paths cover CLI
Hangover trash-bin / deleted-title recovery UI Separate classic tool / GUI
Series view, find-better-quality, theme, grid layout GUI-only

Beyond classic (Bookclerk extras)

Capability Notes
Multi-storefront sources Libro.fm, Chirp, GraphicAudio (+ plugin sources)
Pluggable integrations Audiobookshelf, SPA claim/Accounts, external Workers RPC plugins
Multi-destination output Local + S3/MinIO simultaneously
S3 / MinIO storage Not in classic Libation
bookclerkd daemon + HTTP control plane Scheduled scan / auto-acquire
TOML config + env overrides Classic uses Settings.json
QR / local callback-server login Extra headless login modes beyond login-external
config template tags / profiles / preview Headless template tooling

Post-PR1 (planned)

Item Notes
Spatial / Atmos (Widevine L1) Hardware TEE only; desktop L3 cannot satisfy L1 license grants
GUI MVP React web UI + optional tray→browser (the UI page); early Tauri desktop window, built from source; not Avalonia

Source: docs/contributing/research/libation-parity.md at main · View as Markdown