Libation headless parity (reference)
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.
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).
| Symbol | Meaning |
|---|---|
| ✅ | Implemented |
| ⚠️ | Partial / subset |
| ❌ | Not yet implemented |
| 🚫 | Out of PR1 scope (GUI-only) |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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