github coconautilus17/LibraForge v0.3.1

one hour ago

Upgrade notes

  • The first Folder Forge run rebuilds its structure cache (its format changed),
    about 4 minutes on a large library on a network share; later rebuilds read only
    folders that changed.
  • Original metadata is now backed up by default before Metadata Forge writes.
    Turn Backup off if you don't want the backups.
  • Apply writes the last dry run's matches for books that haven't changed since,
    instead of searching again. Choose "Search and match again" to search everything.
  • New defaults: searches run 8 books at a time and Apply writes 4 at a time.
  • Dry runs and Start Here scans no longer write into the library. Old sidecar
    files are converted the next time Apply writes that book.

New Features

  • Audiobook Guild catalog ships with LibraForge: the store's catalog (813 books)
    comes in the image, each book with its length, so matching a Guild author's book
    reads no store pages. The weekly refresh keeps every book's length; only a book
    the store adds needs its page read once. (#498)

  • Apply reuses the dry run: a dry run saves each book's match with its files'
    signatures, and Apply writes those matches for unchanged books instead of
    searching again; changed books are searched. "Search and match again" opts
    out. (#532)

  • Dry runs and Start Here scans write nothing into the library. Before:

    • a Start Here scan created or updated a libraforge.json in every book
      folder it read (its tag check), so one scan touched every book;
    • a Metadata Forge dry run wrote a skip marker into libraforge.json for
      every book it couldn't match and, with Backup on, the original-tags backup
      for every book;
    • every run, Apply too, rewrote a <folder>.chapter-count-cache.json in each
      multi-part folder.

    Now the scan's tag check lives in the reports folder, skip markers and backups
    are written only by Apply, and chapter counts come from the media facts store.
    Old files are still read. A dry run also leaves old-format sidecars as they
    are; Apply converts them. (#530, #547)

  • Original metadata is backed up by default in Metadata Forge, Manual
    Review and the API, unless turned off; the fixer has --no-backup. (#531)

  • Audible unavailable: a book Audible couldn't answer for (still throttling,
    server errors after retries, or unreachable) is no longer treated as "Audible
    has no listing". It's marked Audible unavailable: no later source is tried,
    nothing is written, no skip marker is left, and Apply after a dry run searches
    it again. The match report shows a badge, a filter and a count. (#544)

  • FFmpeg 9.0.2 in both images: built from FFmpeg's signed release with
    libfdk_aac, LAME, Opus and Vorbis, replacing ffmpeg 5.0.1 and ffprobe 6.1.1,
    so xHE-AAC books can be read. (#538)

  • Folder Forge: folders for books with several authors: a naming template
    can now name every author of a co-written book in one folder, written the way
    Audiobookshelf reads a folder back as authors. {+} turns on all authors,
    {,} {;} or {&} goes between them and <, &>, <and> and the like
    before the last one, so {+}{author}<, &> gives "Ana Pell, Ivo Sand, & Lee
    Doan". {fname}, {lname} and {initials} write names in parts
    ({lname}, {fname} gives "Holt, Mara"), split the way Audiobookshelf splits names.

    • Up to 4 authors are named, then "et al". Translators and other role credits
      are left out. ";" credits and last-first credits ("Holt, Mara") are split
      the way Audiobookshelf splits them, and a trailing "et al" or "others" in
      the tags isn't counted as an author.
    • Initials are written closed up ("J. R. R." becomes "J.R.R."). With "Initials
      follow the author-name scheme" on, they follow Settings' author-name scheme
      instead, so folders match your tags.
    • A co-written book gets the same author order and spelling as the first book
      of those authors in the run.
    • Review flags: a folder Audiobookshelf would read back as different authors
      (shown with what it would read), more than 4 authors, author order differing
      from another book, and a co-written book filed apart from the rest of its
      series. The page warns when a layout writes only part of each name, and the
      run counts organized books moving to another author folder.
    • Templates without {+} render exactly as before.
      (#554)

Fixes

  • Another book of the same series: a listing in the series the file names
    whose main title isn't the file's is another book, so book 4 "The End Has Come
    and Gone" is no longer written over book 3 "The End" when their runtimes are
    close. A listing that is the file's title plus a number ("What If? 2" for "What
    If?") is a later book and is rejected when the file names no number. (#495, #496)

  • Faster matching on the Audible public catalog: LibraForge keeps one
    connection to Audible open instead of opening a new one for every request, and
    books that already carry an ASIN are looked up up to 50 at a time. A run first
    reads the tags of the books LibraForge hasn't processed yet, so their ASINs are
    batched too. On 300 benchmark books the typical book now takes about half the
    time (535 to 257 ms), with every result unchanged. (#497)

  • A book listed in several series: when Audible lists a book in more than one
    series, the series the file's title names is the one its number is checked
    against, so Into the Storm ("Book One of The Malcontents"), now listed as War
    Machine 5 first, is matched again as The Malcontents 1. (#501)

  • "Author; Series; Book NN; Title" folders: the series such a folder names is
    read and used to pick between the series a book is listed in and to search for
    the series, without replacing the title or book number from the tags. (#502)

  • The same series every run: a book Audible lists in several series gets the
    same one on every run, chosen from the file itself: its series tag, the series
    folder it sits in, and its book number. Before, the order Audible happened to
    send decided for about 1 in 100 books, so Discworld 19 could come back as City
    Watch 3 on the next run. (#504)

  • ISBN-10-shaped ASINs: LibraForge now links a book to its Audiobookshelf
    item by ASIN when that ASIN looks like an ISBN-10 (152913417X, common on
    older Audible titles). Before, it skipped such ASINs and could link the item
    only by its folder path. Thanks to X6M-Work. (#307)

  • An exact title breaks a tie with a collection: when a Goodreads search
    returns the book and a collection that lists it, the one whose title is the
    file's own wins instead of the book being skipped as ambiguous. All 14
    Goodreads ambiguity skips in the matching benchmark now match. (#507)

  • A failed Audible search is no longer remembered as "no results" for the
    rest of the run, and workers share one back-off when Audible throttles. (#513)

  • Match report runtimes show whole minutes, not "197.86700000000002 min".
    (#514)

  • Applied books aren't re-applied every run: a book whose metadata Audiobookshelf
    already holds (synced through its API, so no metadata.json of its own) counted as
    unfinished and was applied again from its marker on every run. It's now skipped as
    done. (#546)

  • Folder Forge finds existing series of single-file books: its structure index
    only covered books made of several files, so a new book of a series kept as
    single files was planned as a new structure ("Book 11 - Title" next to "Vol. 1" to
    "Vol. 10"). Single-file books in their own folder are indexed now, and a new book
    takes the Book/Vol. wording the series already uses. (#549)

  • Folder Forge's structure index is fast and reads any naming template: each book
    folder's index records are kept with its listing signature, so a rebuild reads only
    new or changed folders (about 4,000 books on a network share: a rebuild with nothing
    changed 15 min to 25 s, a full build 15 min to 228 s). Folders stand in for author and
    series only under an {author}/{series} layout; under any other template each book is
    read from its own metadata, so {author} - {series} folders and series-and-order book
    folders no longer produce junk series. Books stored as files in a series folder and
    books split into Disc N folders are indexed correctly. (#550)

  • Cue sheet chapters in the default image: building an M4B from one file with
    saved Chapter Forge chapters lost them in the default image (1 chapter, no error);
    only the -chaptering image had the m4b-tool fix. Both images have it now, and CI
    checks it. (#541)

  • Start Here's cache no longer keeps a stale category: a file changing in a book
    folder right after the scan read it could be cached as if the scan had seen it,
    until something else touched that folder. (#238)

  • Books Audible returns but LibraForge missed:

    • an author tag that is the brand the title starts with ("Tom Clancy's Point of
      Contact", written by Mike Maden) gives way to the book's Author folder;
    • a "read by X" author credit becomes the narrator;
    • titles with leading series initials ("HGTTG [03] ...") or several "+"-joined
      titles are also searched without that noise, and such a set matches its box set
      when the runtime does.

    In the matching benchmark 9 missed books now match and none change for the worse.
    (#489)

  • Faster everywhere:

    • Each media file is read once and the result shared across LibraForge, kept
      while the file is unchanged; MP4s are read in-process (identical results on
      4,243 library MP4s, a local scan's read step 60 s to 14.5 s), and other
      audio through PyAV instead of an ffprobe per file (99 to 6.3 ms a file on a
      NAS). (#508, #509, #534)
    • The library walk lists 8 folders at a time: 22 s to 7.3 s on the NAS. (#509)
    • Matching remembers title and author cleanup, and searches 8 books at a time
      by default (300 books: 97 s at 1 worker, 15 s at 8). (#512)
    • New books are read in parallel processes before the search (3,986 books:
      27.8 s to 9.1 s). Covers are fetched and library ASINs scanned while books
      are still matched. (#533)
    • Apply writes with 4 workers by default (50 books: 45 s to 5.7 s), leaves
      1 MiB spare in the tag block so a later cover lands in place (a second Apply
      adding covers wrote 47 MB instead of 1,162 MB), and writes the marker and
      backup in one sidecar write. (#527, #528, #529)
    • Cover thumbnails (up to 320 px) are kept and made while the fixer searches,
      instead of sending the full embedded cover on every request. (#540)
    • Each book's report item and dry-run plan file signatures are made on the search
      workers instead of one book at a time on the run's main thread, and the marker
      is read once per search, so a whole-library run on a NAS is no longer capped by
      serial sidecar reads. (#548)

Docs

  • README rewritten: short and plain, with a banner, a tools table and
    screenshots from a 356-book demo library; install details moved to the docs.
    (#525, #539)
  • Product Model updated for media-file reuse, incremental discovery, scans
    that write nothing, Apply reusing the preview, and Audible unavailable. (#543)
  • Product Model describes Folder Forge's author block and its run checks.
    (#559)

Don't miss a new LibraForge release

NewReleases is sending notifications on new releases.