Skip to content

Audiobookshelf import: match hints, the certificate error and the import inside setup - #310

Merged
KodeStar merged 8 commits into
mainfrom
docs/abs-import-setup
Nov 14, 2026
Merged

KodeStar merged 8 commits into
mainfrom
docs/abs-import-setup

Conversation

@KodeStar

Copy link
Copy Markdown
Owner

Docs for KodeStar/audiosilo-server#366, the Audiobookshelf import. It covers part 2 (KodeStar/audiosilo-server#393, merged) and part 1 (KodeStar/audiosilo-server#395). Merge with or after #395: the certificate error, the import inside setup, the match offer and setup/abs.png exist only there.

User Guide

  • admin/import.md: a new "Match your books after an import" section. An import's ASINs and ISBNs are match hints. They never become the book's ASIN and never show in the apps, and the book stays unmatched until a match is applied (hence the offer). Hints come only from libraries the token can see. It also covers:
    • undo, and which import owns the hints;
    • an identifier-only import refused when it would replace an applied one;
    • the certificate error, with the advice to use Audiobookshelf's plain http:// address (never trust the certificate);
    • waiting for the scan.
  • getting-started/first-run.md: step 6 now runs the import inside the step, says to wait for the scan, and shows the Match automatically offer.
  • getting-started/coming-from-audiobookshelf.md: matches the above. ABS's "Store metadata with item" is off by default (server/objects/settings/ServerSettings.js, storeMetadataWithItem = false, v2.37.2), so that line is unchanged.
  • admin/health.md: a new "Audiobookshelf's ASINs and ISBNs" section. A metadata.json's ids are the book's own; an import's are hints. A wrong hint is settled by matching the book by hand.
  • admin/books.md ("What matching sends") and features.md.

Developer Docs

  • api/reference.md:
    • abs_certificate, both as a 502 and as an error_code;
    • the summary's identifiers {books, asin, isbn, by_title, already_matched} and a new "Identifiers (match hints)" section;
    • the apply's 409 import_not_ready refusal;
    • undo, the match dialog's hint order and identifier_disagrees from a hint.
  • data-model.md: book_hints (0074) and "Match hints from an import". It gives the QueryFor order: own ids win, an Audiobookshelf hint goes ahead of tag hints, a tag ASIN goes only when the import gave no identifier, and a tag ISBN may go beside an ABS ASIN. It also covers ownership and the LibriVox drop: a book placed from LibriVox drops the hints at its path, and an adopted folder keeps them.
  • web-ui.md (the abs step and UnmatchedPrompt sites), scanner.md (hints don't count as matched), bridge/librivox.md, cross-repo-contract.md, and a listening-imports row in the documentation mapping table.

Screenshots

setup/abs.png is recaptured against #395's server. It shows the inline Connect form and the Match automatically offer.

Checks

npm run build is green. The docs review (/simplify and /code-review high) applied 15 fixes, each checked against the code (internal/matchrun/plan.go QueryFor, hints_test.go, the PR1 console).

…error and the import inside setup

An import now brings Audiobookshelf's ASIN and ISBN as match hints that show
nothing until a match run applies, so Past imports and the setup step offer
Match automatically. An import with no listening can't replace one already
applied. A self-signed https address fails with its own message: use ABS's
plain http:// address. The setup step runs the import inline and waits for
the first scan.

Part of KodeStar/audiosilo-server#366.
…cate and the setup abs step

The reference gains the imports summary's identifiers, the 502 abs_certificate
code and the 409 import_not_ready refusal of an apply with no listening that
would undo an applied import. The data model documents book_hints, who owns a
hint and QueryFor's exact order (own ids, then an import's, a tag ASIN only
without an import identifier, a tag ISBN beside an import ASIN). A LibriVox
placement drops the path's hints too. web-ui covers the inline import and the
match offer; the mapping table gains a listening-imports row.

Part of KodeStar/audiosilo-server#366.
…offer

Captured against the server's feat/abs-import-setup build: the step now holds
the Connect to Audiobookshelf form and, once the first scan is done, the books
not matched offer. The capture waits for both and takes the step's full height.

Part of KodeStar/audiosilo-server#366.
… matching sends

The console's privacy line now names an ASIN or ISBN from an Audiobookshelf
import beside the tags', so the User Guide says the same. Also tidies two
mid-sentence colons and a symbol name in the new Developer Docs text.

Part of KodeStar/audiosilo-server#366.
The match dialog's params and the cross-repo contract summarised
QueryFor's order as "an import's, else its tags'", which misses a tag
ISBN going beside an import ASIN; they now link to the data model's
rule. Hint ownership on undo and what counts as listening for the apply
refusal were spelled out twice with differing detail; each now lives in
one place with a link from the other. Long lines re-wrapped.

Part of KodeStar/audiosilo-server#366.
Moving from Audiobookshelf restated the self-signed certificate advice
the import page already gives; it now links to When a fetch fails. The
setup step's Match automatically line links to Matching every book at
once.

Part of KodeStar/audiosilo-server#366.
The review outcome still named only a tag ASIN or ISBN as the source of
identifier_disagrees, and the unmatched issue rule said only tag hints
don't count, though matchedExpr ignores book_hints too. The setup abs
step's offer also needs a books library, and an older Bridge's LibriVox
fold keeps a path's hints as an adopted one does.

Part of KodeStar/audiosilo-server#366.
An Audiobookshelf hint goes ahead of the tags, so correcting a tag does
not stop a wrong one coming back; matching the book by hand does. The
import only sees the libraries its token can see, and Past imports
offers Match automatically only with community metadata on.

Part of KodeStar/audiosilo-server#366.
@KodeStar
KodeStar merged commit bc1d130 into main Nov 14, 2026
1 check passed
@KodeStar
KodeStar deleted the docs/abs-import-setup branch November 14, 2026 23:19
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