Audiobook Manager

A Docker-based automation toolkit connecting Libation with Audiobookshelf.

Features

• Watches a Libation download inbox
• Imports completed audiobooks into Audiobookshelf
• Prevents duplicate imports
• Quarantines questionable duplicates instead of deleting them
• Scans the Audiobookshelf library
• Learns author and series classifications
• Maintains configurable collections
• Produces reports
• Supports optional ntfy notifications
• Migrates Audible finished status once
• Migrates Audible listening positions once
• Never moves Audiobookshelf progress backward
• Never repeatedly overwrites Audiobookshelf progress

Requirements

• Linux
• Docker Engine
• Docker Compose plugin
• Audiobookshelf
• Libation
• Audiobookshelf API token
• Libation configuration containing:
  • LibationContext.db
  • AccountsSettings.json

The default configuration uses Docker host networking so the manager can reach Audiobookshelf at http://127.0.0.1:13378.

Installation

Clone the repository:

git clone https://github.com/matthew03phillips-cell/audiobook-manager-public.git
cd audiobook-manager

Create the local configuration and runtime directories:

cp .env.example .env
mkdir -p secrets cache model-cache reports logs

Edit .env:

nano .env

Replace the example paths with real paths from your server:

TZ=America/Chicago
ABS_URL=http://127.0.0.1:13378
ABS_TOKEN_PATH=./secrets/abs-token
NTFY_URL_PATH=./secrets/ntfy-url
LIBATION_CONFIG_PATH=/real/path/to/libation/config
MEDIA_ROOT=/real/path/to/media
WORKFLOW_ROOT=/real/path/to/audiobook-workflow
INBOX_POLL_SECONDS=30
INBOX_MINIMUM_AGE=120

Create the workflow directories using the real path selected above:

mkdir -p /real/path/to/audiobook-workflow/{inbox,processing,failed,quarantine}

Do not literally use /real/path/to/; replace it with a valid directory on your server.

Audiobookshelf token

Place your Audiobookshelf API token in:

secrets/abs-token

Example:

printf '%s\n' 'YOUR_AUDIOBOOKSHELF_API_TOKEN' > secrets/abs-token
chmod 600 secrets/abs-token

For no ntfy notifications, create an empty placeholder:

: > secrets/ntfy-url
chmod 600 secrets/ntfy-url

Build and test

Build the image:

docker compose build

Test the Audiobookshelf connection:

docker compose run --rm audiobook-manager \
  python src/probe_api.py

Start the inbox watcher

docker compose up -d audiobook-inbox-watcher

Check its status:

docker compose ps
docker compose logs --tail 100 audiobook-inbox-watcher

Libation should place completed downloads in:

WORKFLOW_ROOT/inbox

The watcher then processes and imports them into Audiobookshelf.

Run collection management manually

./run_manager.sh

This scans Audiobookshelf, checks for newly imported books, learns author and series information, updates collections, and scans the library again.

Scheduled collection management

Example cron entry running every six hours:

0 */6 * * * /absolute/path/to/audiobook-manager/run_manager.sh >> /absolute/path/to/audiobook-manager/logs/automation.log 2>&1

The continuous watcher handles new downloads. The scheduled manager updates classification and collections.

One-time finished-status migration

Preview:

docker compose run --rm audiobook-manager \
  python src/sync_finished.py

Apply after reviewing the preview:

docker compose run --rm audiobook-manager \
  python src/sync_finished.py --apply

This command is intentionally not included in run_manager.sh.

One-time Audible listening-position migration

Export Audible listening positions using Libation's saved authentication:

docker compose run --rm audiobook-manager \
  python src/export_audible_progress.py

This creates:

reports/audible-progress-preview.json

Preview the migration while ignoring accidental plays shorter than one minute:

docker compose run --rm audiobook-manager \
  python src/sync_progress.py --minimum-seconds 60

Apply after reviewing the preview:

docker compose run --rm audiobook-manager \
  python src/sync_progress.py \
  --minimum-seconds 60 \
  --apply

The migration:

• Matches books by Audible ASIN
• Skips books missing from Audiobookshelf
• Skips duplicate ASIN matches
• Leaves finished books finished
• Never moves Audiobookshelf progress backward
• Creates a pre-migration recovery report
• Does not run automatically afterward

After migration, Audiobookshelf becomes the source of truth for listening progress.

Security

Never commit:

• .env
• Audiobookshelf tokens
• Private ntfy URLs
• AccountsSettings.json
• LibationContext.db
• Audible authentication tokens
• Audible private keys
• Listening-progress reports
• Personal learned-author or learned-series files

These files are excluded by .gitignore.

Troubleshooting

Validate Compose:

docker compose config

Rebuild after source or dependency changes:

docker compose build --no-cache

Check watcher logs:

docker compose logs --tail 200 audiobook-inbox-watcher

Test Audiobookshelf access:

docker compose run --rm audiobook-manager \
  python src/probe_api.py