# 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

1. 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](https://pdm.fming.dev) for packaging so tooling, dependencies, and the src layout stay in sync.

1. Install PDM (`pipx install pdm` or `pip install --user pdm`).
2. Create a virtual environment via `pdm venv create --with python3.11` if your system Python does not match the required version.
3. 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/`.