Skip to content

Read Audiobookshelf's metadata.json as a metadata layer - #135

Merged
KodeStar merged 1 commit into
mainfrom
feat/abs-metadata-json
Oct 14, 2026
Merged

KodeStar merged 1 commit into
mainfrom
feat/abs-metadata-json

Conversation

@KodeStar

@KodeStar KodeStar commented Oct 14, 2026 •

Copy link
Copy Markdown
Owner

When AudioSilo is pointed at a library Audiobookshelf manages, each book folder may hold the metadata.json ABS keeps ("Store metadata with item"). It often carries the ASIN/ISBN the tags lack, plus the corrections and matches made in ABS. This reads it.

Precedence: path → tags → ABS file → community match → admin edit, as ABS itself ranks the file above the tags. Path-first libraries included.

Fields read:

  • title (not subtitle)
  • authors and narrators, joined with ", "
  • series "Name #seq": the first is the main series; the rest go to more_series
  • publishedDate, else publishedYear
  • description (HTML to plain text)
  • asin, isbn

Genres, tags, publisher, language and chapters are not read. An empty value never clears a tag's. Each value goes through the field's edit rules, so an ASIN from the file makes the book matched: Health, /meta, the community chapter check and refresh runs all work.

Scope: folder books only. A loose file at the root never takes a metadata.json beside it. An ignore rule metadata.json turns the feature off for a library.

Storage and scans:

  • Migration 0046 adds books.abs_sig, abs_indexed_at and abs_file: derived from the file, so rebuildable.
  • Discovery records each folder's file signature during the walk.
  • An unchanged book whose file is new, changed or gone is re-read with no re-index (SetABSFiles, batched beside the path backfill).
  • After upgrade, only books that have a file are touched.
  • A read failure keeps the last reading.
  • A book an older server re-indexed is re-resolved.
  • Links are not followed.

Console: a new abs provenance source, shown as an amber "Audiobookshelf" marker, in the legend, in 6 locales, and in STYLEGUIDE tokens.

Tests: parser, layer and precedence, the series position rule, file books, the backfill (including the stale-stamp case), and a scanner lifecycle test (read, edit picked up without re-index, upgrade backfill, ignore rule, removal, IndexPath, unreadable-file retry).

Checked on a real server with the user-posted sample file: the book page shows every value marked Audiobookshelf, in both themes.

Docs: KodeStar/audiosilo-docs#134. Not a wire change.

Known gaps (not fixed here):

  • A position read from an ABS title shows as tag.
  • The Revert tooltip says "File tag:" for ABS values, as it already does for path values.
  • Authors are joined with ", " like community matches.

A folder book whose folder holds the metadata.json Audiobookshelf keeps
("Store metadata with item") now takes its title, authors, narrators,
series, published year, description, ASIN and ISBN from it, over the
tags and path (ABS's own default priority); edits and community matches
still go over it. Values are normalized as an edit would be, so an ASIN
from the file makes the book matched.

- metadata.ParseABSFile: lenient, size-capped, regular files only.
- books.abs_sig / abs_indexed_at / abs_file (0046): the file's
  signature, the index it was read for, what it says.
- Discovery records each folder's file signature from the walk; an
  unchanged book whose file is new, changed or gone is re-read without
  a re-index (SetABSFiles). A read failure keeps the last reading.
- New provenance source "abs" (console marker, legend, six locales).
- An ignore rule "metadata.json" turns it off for a library.
@KodeStar
KodeStar merged commit d264205 into main Oct 14, 2026
3 checks passed
@KodeStar
KodeStar deleted the feat/abs-metadata-json branch October 14, 2026 17:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant