Shelfarr Documentation

Quick start (Docker Compose)

Mount your audiobooks into the container and open the web UI.

services:
  shelfarr:
    image: vacantlycrushing/shelfarr:latest
    ports:
      - "5055:5055"
    environment:
      PORT: "5055"
      ABR_SETTINGS_DB: "/data/settings.db"
      ABR_HISTORY_LOG: "/data/shelfarr_history.jsonl"
      ABR_LOG_FILE: "/data/shelfarr.log"
    volumes:
      - ./data:/data
      - /path/to/your/audiobooks:/library
    restart: unless-stopped

docker compose up -d

Open http://localhost:5055 and scan /library.

Path rule

The browser is just the UI — pick paths that exist on the machine running Shelfarr.

Run locally (Python)

Run the Shelfarr server directly on Windows, macOS, or Linux.

macOS / Linux

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
PORT=5055 python3 app.py

Example library: /Users/you/Audiobooks

Windows (PowerShell)

py -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
$env:PORT = "5055"
py .\app.py

Example library: D:\Audiobooks (or a mapped network drive)

If you’re using Docker Desktop on macOS/Windows, Shelfarr runs inside a Linux container. Use container paths you’ve mounted (like /library), not your host paths.

First scan workflow

Shelfarr is preview-first: it plans renames, then you choose what to apply.

1) Choose a scan root

Pick a folder (or drive location) that contains your audiobooks.

2) Review the plan

Missing metadata, conflicts, or low-confidence matches show up as manual/review.

3) Apply (or undo)

Apply only when you’re happy. Undo restores prior paths where possible.

How names are decided

1) Read embedded tags → 2) optionally enrich from Audiobookshelf → 3) apply regex transforms → 4) render your template.

Settings reference

The UI is the source of truth. These are the current settings keys and what they do.

Defaults & environment variables

Defaults can be set via env vars (especially helpful for Docker). Common ones: PORT, ABR_DRY_RUN, ABR_BACKUP, ABR_FILENAME_TEMPLATE, ABR_ALLOW_DIRECTORY_MOVE, ABS_BASE_URL, ABS_TOKEN.

General

Setting	What it does
`dry_run`	When enabled, renames are simulated (no file changes).
`make_backup`	When enabled, creates a `.bak` copy before renaming.
`use_abs_metadata`	When enabled, Shelfarr can use Audiobookshelf metadata for matching/naming.
`allow_directory_move`	If enabled, templates may include folders (e.g. `{author}/{series}/{title}`). If disabled, rename-only in the same folder.
`rename_parent_folder`	If enabled, also renames the folder containing each renamed file to match the file’s new base name (skips conflicting folders).
`audio_exts`	List of file extensions Shelfarr considers for scanning (e.g. `.m4b`, `.m4a`, `.mp3`).
`drive_locations`	Saved scan roots (paths you scan often).

Regex transforms

Setting	What it does
`regex_rules`	Ordered transform rules applied to `author`/`title`/`series`/`album` before templating. See Regex transforms.

Batching

Setting	What it does
`batch_size`	How many files to process per UI batch (higher is faster; lower feels smoother).

Matching

Setting	What it does
`filename_template`	Template string for output names. Supports `{author}`, `{title}`, `{series}`, `{album}`.
`manual_review_min`	Review threshold: below this confidence, items are marked manual.
`auto_approve_min`	Auto-safe threshold: at/above this (and margin), items become auto-safe.
`top2_margin_min`	Top-2 margin: if best match isn’t clearly better than runner-up, force review.
`matching_mode`	How ABS matches are evaluated. Options include `fuzzy`, `exact`, `pattern`, `statistical`.

Audiobookshelf metadata options

Setting	What it does
`strip_abs_subtitle`	When enabled (default), ignore subtitles from ABS titles while naming.
`abs_first_author_only`	When enabled, naming uses only the first author returned by ABS.

Keyword cleanup

Setting	What it does
`strip_keywords_on`	When enabled, removes configured keywords from output names.
`strip_keywords`	List of keywords to strip (case-insensitive), e.g. `abridged`, `unabridged`.

Appearance

Setting	What it does
`theme`	UI theme. Options include `oled`, `midnight`, `obsidian`, `ocean`, `forest`, `velvet`, `ember`, `espresso`, `midnight-blue`, `dracula-white`.
`nav_position`	Navigation placement: `top` or `side`.
`font_family`	Typeface: `noto-sans`, `source-sans`, `helvetica`, `inter`, `ibm-sans`.
`text_size`	Base text size: `small`, `medium`, `large`.

Onboarding

Setting	What it does
`onboarding_done`	Controls whether the welcome/setup wizard is shown.

Audiobookshelf / SMB

Setting	What it does
`abs_base_url`	Audiobookshelf base URL (e.g. `http://192.168.1.10:13378`).
`abs_token`	Audiobookshelf API token.
`abs_check_interval_sec`	How often Shelfarr pings ABS for health/status (seconds; UI offers 1m–1h presets).
`smb_check_interval_sec`	How often Shelfarr refreshes SMB status automatically (seconds; UI offers 1m–1h presets).

Templates

Templates are simple substitutions with safe sanitization.

Placeholders:

{author}
{title}
{series}
{album}

Examples:

{author} - {title}
{author}/{title}
{author}/{series}/{title}
{series} - {title}

Folders

Using folders in templates requires allow_directory_move to be enabled.

Regex transforms

Clean up fields before templating (title/author/series/album).

Transforms run in order. Bad rules never break a scan — errors and no-matches are ignored (and logged on the server).

Rule fields

Apply to field: title / author / series / album
Pattern: regular expression
Replacement: replacement string (can be empty)
Flags: supported: i m s x a

Examples

Remove “(Unabridged)” from titles Transform

Field: title
Pattern: \\s*\\((Unabridged|Abridged)\\)
Replacement: (empty)
Flags: i

Normalize series naming Transform

Field: series
Pattern: \\s*Trilogy$
Replacement: (empty)
Flags: i

Limits

Max rules: 25
Max input length per rule: 2048 chars
Timeout support when optional regex module is installed

Audiobookshelf / SMB

Optional integration for better matching and naming.

Audiobookshelf

Set abs_base_url and abs_token in Settings (or via ABS_BASE_URL/ABS_TOKEN env vars).
Tune matching_mode and thresholds for your library.

Reachability

If ABS isn’t reachable from the Shelfarr server, it falls back to file tags.

Health check intervals

Setting	What it does
`abs_check_interval_sec`	How often Shelfarr pings ABS for health/status (seconds; UI offers 1m–1h presets).
`smb_check_interval_sec`	How often Shelfarr refreshes SMB status automatically (seconds; UI offers 1m–1h presets).

Safety & undo

Designed to prevent surprises.

Dry-run: propose without changing files
Backups: optional .bak files
No overwrites: refuses to overwrite existing targets
Undo: restores previous state where possible

Troubleshooting

“Missing fields for template”

Switch templates, enable ABS matching, or add regex transforms to clean up tags.

Targets already exist

Rename conflicts are marked manual. Adjust templates or clean duplicates first.

ABS unreachable

Check URL/token, container networking, and that the ABS host is reachable from the server.

Report issues

Open a GitHub issue with a sample path and expected output: github.com/VacantlyCrushing/Shelfarr/issues

Documentation

Quick start (Docker Compose)

py Run locally (Python)

macOS / Linux

Windows (PowerShell)

First scan workflow

Settings reference

General

Regex transforms

Batching

Matching

Audiobookshelf metadata options

Keyword cleanup

Appearance

Onboarding

Audiobookshelf / SMB

Templates

Regex transforms

Rule fields

Examples

Limits

Audiobookshelf / SMB

Audiobookshelf

Health check intervals

Safety & undo

Troubleshooting

Run locally (Python)