Libation WebUI

A lightweight, mobile-first web interface for managing and downloading your Audible audiobook library via Libation. Black-on-white minimal design with a light/dark theme toggle, installable as a PWA on iOS and Android.

This is a self-hosted WebUI wrapper around the official libationcli. It does not bypass any Audible restrictions — it can only download titles your account is actually entitled to.

Features

• Library overview — title, author, narrator, length, series, cover, description
• Search & filter — by title, author, narrator, or series; filter by download status
• Single & batch downloads — pick one book or select several
• Organized output — files saved as /output/Author/Title/Title.m4b
• Light / dark theme — toggle in the header, remembered across sessions; very dark grey (not OLED black)
• PWA — installable to the home screen, offline app-shell, iOS-friendly
• Honest error reporting — failed downloads surface the real reason (e.g. Audible content-license denials) instead of silently creating empty folders
• Docker-first — everything configured via docker-compose.yml

Security — read this first

config/AccountsSettings.json contains your Audible authentication tokens. Treat it like a password:

• Never commit it to git. It is already listed in .gitignore.
• The repo ships only config/AccountsSettings.json.example as a placeholder.
• If you ever accidentally commit a real one, rotate it by re-authenticating in Libation desktop (consider the old tokens compromised).

Quick Start

1. One-time Audible login (on a desktop)

Audible's login needs a browser, so this step is done once in Libation desktop:

1. Install Libation desktop on any computer
2. Add your Audible account and complete the login
3. Locate your Libation config folder:
   • Linux: ~/.config/Libation/
   • Windows: %LOCALAPPDATA%\Libation\
   • macOS: ~/Libation/
4. Copy AccountsSettings.json (and optionally Settings.json) into this project's ./config/ directory

2. Clone & launch

# Clone from your Forgejo (or any git) remote
git clone https://git.example.com/you/libation-webui.git
cd libation-webui

# Create local data dirs (config & books are kept via .gitkeep)
mkdir -p config books output

# Copy your Libation auth from step 1
cp /path/to/AccountsSettings.json ./config/

# Adjust docker-compose.yml (output path, locale, quality) then launch
docker compose up -d --build

Open http://localhost:8484 (or http://<server-ip>:8484).

3. First use

1. Click Scan Library to import your Audible book list
2. Browse, search, filter
3. Click Download on a book, or Select several and Download Selected
4. Files land in your output folder as /output/Author/Title/Title.m4b

Configuration

All settings live in docker-compose.yml under environment:.

Variable	Default	Description
AUDIBLE_LOCALE	de	Audible region: us, uk, de, fr, au, ca, jp, in, es
OUTPUT_FORMAT	m4b	Audio format (m4b recommended for chapters)
OUTPUT_DIR	/output	Final destination inside the container
DOWNLOAD_QUALITY	High	Normal or High
DOWNLOAD_PDFS	true	Download accompanying PDFs
SPLIT_BY_CHAPTERS	false	Split into per-chapter files
SCAN_INTERVAL	0	Auto-scan interval in minutes (0 = disabled)
PUID / PGID	1000	User/group ID for file ownership
TZ	Europe/Berlin	Container timezone

Volumes

Container path	Host (default)	Purpose
/config	./config	Libation config (AccountsSettings.json, DB, generated Settings.json)
/data	./books	Libation working / temporary download dir
/output	./output	Final audiobook output — point this at your library

To send output straight to your media library, change the host side, e.g.:

    volumes:
      - ./config:/config
      - ./books:/data
      - /mnt/audiobooks:/output

Output Structure

/output/
├── Brandon Sanderson/
│   └── The Way of Kings/
│       └── The Way of Kings.m4b
└── Terry Pratchett/
    └── Guards! Guards!/
        └── Guards! Guards!.m4b

API Endpoints

Endpoint	Method	Description
/api/status	GET	System status and config
/api/library	GET	Full audiobook library
/api/scan	POST	Trigger a library scan
/api/download	POST	Start a download ({asin, title, authors})
/api/download/status	GET	Progress for all downloads
/api/download/status/<asin>	GET	Progress for a single book

Architecture notes

• Flask + gunicorn, served on port 8484.
• Downloads run in a background thread; gunicorn therefore runs a single worker (with multiple threads) so the in-memory download state stays consistent with status polling. Don't raise --workers above 1 unless you move the download state into a shared store.
• The frontend is a single app/templates/index.html (HTML + CSS + vanilla JS), no build step. The PWA shell is app/static/ (manifest.json, sw.js, icons).
• Download flow: clean BOOKS_DIR → libationcli liberate <ASIN> → collect the produced files → move into /output/Author/Title/. If no audio files are produced, the job is marked as an error with the real CLI message and no empty folder is created.

Troubleshooting

"Content License denied" / "does not have Ownership rights" → This is an Audible-side restriction, not a bug. Your account isn't entitled to download that specific title (common for some Plus-Catalog / Originals episodes that are streamed rather than owned). Titles you actually own download fine.

"No account configured" / login screen keeps showing → Copy a valid AccountsSettings.json from a working Libation desktop install into ./config/, then restart: docker compose restart.

Library scan finds 0 books → Check that AUDIBLE_LOCALE matches your Audible account region.

Files not appearing in output → Verify the /output volume mount and permissions. Use PUID/PGID to match your host user, or chown the output dir.

Database errors → Ensure /config is writable. Check logs: docker compose logs -f.

Old/dark UI cached after an update → The service worker is network-first and the cache is versioned, so a normal reload picks up changes. If you still see the old shell, hard-reload or reinstall the PWA once.

Development

The UI has no build step — edit app/templates/index.html directly. Running the server outside Docker still needs the Libation CLI and its environment, so Docker is the recommended path:

docker compose up -d --build
docker compose logs -f libation-webui

License

This WebUI wrapper is provided as-is for personal use. Libation itself is maintained by rmcrackan under GPLv3.