docs: bookshelf-audio names audiobooks into series folders #384

Merged

mysticalsoap merged 1 commit from docs/bookshelf-audio-series-folders into trunk

2026-10-07 18:22:48 -04:00

mysticalsoap commented

2026-10-07 18:13:39 -04:00

Owner

Problem

New audiobooks landed in Audiobookshelf without series or sequence unless someone clicked Match (#379). The issue assumed Hardcover gives Bookshelf no series data; it does (every Dinniman book carries Dungeon Crawler Carl #N), it just never reached the files or the folders.

Fix

Docs only, recording the live setting: Bookshelf-audio's Standard Book Format now names into {Book Series}/{Book SeriesPosition} - {Book Title}/…, which Audiobookshelf parses as series and sequence on scan. The page also records why tag writing from Readarr is not an option (no series fields; in-place write through the seed hardlink) and the two manual steps that remain (Rename Files for late-arriving series; Scan and remove the old items afterwards).

Verification

Live, 2026-10-07:

Readarr's rename preview on the real author rendered all eight books as Matt Dinniman/Dungeon Crawler Carl/N - Title/…; the examples endpoint with a series-less sample book collapses to Author/Title/… with no empty segment.
Rename Files run through the API: all eight moved, every file still at link count 2 (seed untouched).
Readarr's AudioTag.cs (develop) writes title, authors, album, year, publisher, genres only; the servarr wiki states tag writing has no hardlink protection.
Audiobookshelf's scandir.js derives seriesName/seriesSequence from the third-level folder and a leading N - : after the Scan all eight new items carry Dungeon Crawler Carl 1–8, five of them from the folder alone (no ASIN tag), with description and cover from the files.
Readarr's rename creates new directories (new inodes), so Audiobookshelf's inode matching cannot follow it: the scan added eight items and marked the eight old ones missing. The watcher did not react to the moves at all; the Scan step is manual, then the old items are removed through the Issues filter.

🤖 Generated with Claude Code

## Problem New audiobooks landed in Audiobookshelf without series or sequence unless someone clicked Match (#379). The issue assumed Hardcover gives Bookshelf no series data; it does (every Dinniman book carries `Dungeon Crawler Carl #N`), it just never reached the files or the folders. ## Fix Docs only, recording the live setting: Bookshelf-audio's Standard Book Format now names into `{Book Series}/{Book SeriesPosition} - {Book Title}/…`, which Audiobookshelf parses as series and sequence on scan. The page also records why tag writing from Readarr is not an option (no series fields; in-place write through the seed hardlink) and the two manual steps that remain (Rename Files for late-arriving series; Scan and remove the old items afterwards). ## Verification Live, 2026-10-07: - Readarr's rename preview on the real author rendered all eight books as `Matt Dinniman/Dungeon Crawler Carl/N - Title/…`; the examples endpoint with a series-less sample book collapses to `Author/Title/…` with no empty segment. - Rename Files run through the API: all eight moved, every file still at link count 2 (seed untouched). - Readarr's `AudioTag.cs` (develop) writes title, authors, album, year, publisher, genres only; the servarr wiki states tag writing has no hardlink protection. - Audiobookshelf's `scandir.js` derives `seriesName`/`seriesSequence` from the third-level folder and a leading `N - `: after the Scan all eight new items carry `Dungeon Crawler Carl` 1–8, five of them from the folder alone (no ASIN tag), with description and cover from the files. - Readarr's rename creates new directories (new inodes), so Audiobookshelf's inode matching cannot follow it: the scan added eight items and marked the eight old ones missing. The watcher did not react to the moves at all; the Scan step is manual, then the old items are removed through the Issues filter. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

mysticalsoap added the

docs

label

2026-10-07 18:13:39 -04:00

mysticalsoap added 1 commit

2026-10-07 18:13:39 -04:00

docs: bookshelf-audio names audiobooks into series folders

validate / validate (pull_request) Successful in 22s

Details

559c972719

Audiobookshelf only learns series and sequence from tags, folders or a
Match. Hardcover does carry the series, Readarr has naming tokens for
it, and Audiobookshelf parses Author/Series/N - Title on scan, so the
folder layout covers what the nightly match job in #379 was for.
Readarr's own tag writer cannot do it: no series fields, and it writes
in place through the seed's hardlink.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

mysticalsoap force-pushed docs/bookshelf-audio-series-folders from 559c972719

validate / validate (pull_request) Successful in 22s

Details

to f6cc6cb7d4

validate / validate (pull_request) Successful in 24s

Details

2026-10-07 18:20:28 -04:00

Compare

mysticalsoap merged commit 1c781bbd77 into trunk

2026-10-07 18:22:48 -04:00

mysticalsoap deleted branch docs/bookshelf-audio-series-folders

2026-10-07 18:22:48 -04:00