audibooksorter

An audiobook sorter for Audiobookshelf libraries. Give the root path of your Audiobookshelf library and the tool will materialize a sorted structure arranged by:

-Author --Series ----Title

Title Folder Naming

In addition to the book title, the title folder can include the publish year, series sequence, the subtitle, and the narrator.

Here are a bunch of ways the same book could be named:

Wizards First Rule

Wizards First Rule {Sam Tsoutsouvas}

1994 - Wizards First Rule

Wizards First Rule - A Really Good Subtitle

1994 - Book 1 - Wizards First Rule

1994 - Volume 1. Wizards First Rule {Sam Tsoutsouvas}

Vol 1 - 1994 - Wizards First Rule

1994 - Wizards First Rule - Volume 1

Vol. 1 - 1994 - Wizards First Rule - A Really Good Subtitle {Sam Tsoutsouvas}

(1994) - Wizards First Rule - A Really Good Subtitle

1 - Wizards First Rule

Wizards First Rule

Subtitle: Parsing out subtitles into a separate field is optional and must be enabled in settings. Subtitle must be separated by " - ". Series Sequence: Case insensitive & decimals supported. The sequence can be placed anywhere in the folder name. It must be followed by " - " or ". " If it is not at the beginning of the folder name, it must be preceded by " - " and "Vol" "Vol." "Volume" or "Book" Publish Year: The publish year must be the first part of the name OR directly after a series sequence, and separated by " - " on both sides. Narrator: Must be wrapped in curly braces. e.g. {Sam Tsoutsouvas}. Disc Numbers: The title folder can contain subfolders for discs as long as they are named "Disc", "CD", or "Disk" with a number following (case insensitive). Example: "Disc 1", "CD 2", "Disk 3", "Disc 004", or no space between like "Disc1".

Author Folder Naming

Supports "Last, First" author naming as well as multiple authors separated by ",", ";", "&" or "and".

Valid author folder names:

Ichiro Kishimi

Kishimi, Ichiro

Ichiro Kishimi, Fumitake Koga

Kishimi, Ichiro, Koga, Fumitake

Ichiro Kishimi & Fumitake Koga

Kishimi, Ichiro & Koga, Fumitake

Terry Goodkind, Ichiro Kishimi and Fumitake Koga

Development setup

This repository now uses PDM for packaging so tooling, dependencies, and the src layout stay in sync.

Install PDM (pipx install pdm or pip install --user pdm).
Create a virtual environment via pdm venv create --with python3.11 if your system Python does not match the required version.
Install the application and dev requirements with pdm install --dev.

PDM writes metadata to pdm.lock; regenerate it with pdm lock --refresh whenever dependencies change.

Common commands

Run the CLI: pdm run python -m audiobooksorter.cli --library /path/to/library --output ./sorted_library (pass a JSON export from samples/ only when running tests)
Format and lint: pdm run ruff check --fix && pdm run ruff format
Test with coverage: pdm run pytest -q

Library ingestion

The sorter walks the supplied library directory looking for metadata.json files (one per audiobook folder). Those metadata files must at least contain title and author, and may optionally declare series and seriesIndex. For integration tests and CI you can still point --library at a JSON export; the CLI will treat JSON inputs as fixtures and skip filesystem moves.

Project layout

Source code lives under src/audiobooksorter/ with ingestion, sorter, and export modules split into subpackages so the command-line interface stays thin. Static assets are kept in assets/, while anonymized example exports live in samples/. Pytest suites mirror the package structure inside tests/.

3.6 KiB Raw Blame History