91 lines
3.6 KiB
Markdown
91 lines
3.6 KiB
Markdown
# 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/`.
|