Audiobind

Audiobind

Docker app from stinger303's Repository

Finds audiobooks that are split into many files, checks each one against the Audible catalog, merges the parts into a single tagged m4b with real chapter marks and cover art, and…

Requirements

Internet access (Audible / Audnex metadata lookups)
Overview
Finds audiobooks that are split into many files, checks each one against the Audible catalog, merges the parts into a single tagged m4b with real chapter marks and cover art, and files it as Author/Book/Book.m4b (or Author/Series/3 - Title/). Runs on a timer and only converts books it is confident about.

Audiobind

Fix an audiobook library instead of curating it by hand.

Audiobind walks a folder of audiobooks, works out what each book actually is, merges the ones that are spread over dozens of files into a single tagged .m4b, and files the result into a clean Author/Title library. It is built for the mess every audiobook collection eventually becomes: Part 1, Disc 3, StoneColdUnabridgedPart2, three copies of the same book, and a folder called Vince Flynn Novels 14 books Complete Collection.

What you get

  • One .m4b per book, with the Audnex chapter marks, the full tag set and an embedded cover.
  • Every book checked against the Audible catalog. A winner must beat the best different work by a margin, and knockoffs (summaries, study guides, zero-runtime stubs) never count against it.
  • A completeness check: a set whose runtime is an hour short of the catalog is reported, not merged.
  • Optional single-file MP3 output (OUTPUT_FORMAT) with ID3 chapters, cover and tags, alone or next to the .m4b.
  • Optional wishlist acquisition from a private tracker you configure, through qBittorrent. Off unless the TRACKER_* settings are complete.
  • Discover books: search the catalog, plus suggestions based on the authors, narrators and genres you already own.
  • Series completion: the Series page shows what you are missing, and Want all missing puts it on the wishlist in one click.
  • Conversion never changes or deletes your source files. Only the explicit Delete button does, and a read-only /library mount rules even that out.
  • A dry run that decides and logs everything and writes nothing.
  • One container, Python standard library only, no telemetry, no external database (state is a SQLite file under /config).

Requirements

  • Docker (or Unraid). Nothing else to install: ffmpeg is in the image.
  • Optional, for wishlist acquisition only: an account on a private tracker (and a VPN container if you want tracker traffic kept off your home connection) and qBittorrent for the downloads.

Quick start: the three mounts (/library, /output, /config), ALLOWED_HOSTS and the account must be right before the first scan - the First run checklist walks through them in order.

library-in/                         library-out/
  Michael Lewis- Moneyball/           Michael Lewis/
    Moneyball/                          Moneyball/
      1-01 1A.mp3  ... 195 files           Moneyball.m4b   (one file, 16 chapters, cover)
    Moneyball [Disc 2]/                    cover.jpg
    Moneyball [Disc 3]/                    metadata.json

The Audiobind library page: every book with its status, match confidence and runtime, and the books that need attention above the list

Status: beta — read this before you point it at your library

Audiobind is a beta: a solo project with a single front-end developer, and the code is written with heavy AI assistance (designed, reviewed and tested by a human, but not hand-written line by line). It reads real audiobook libraries and writes to a separate output library, and software like that can fail badly — you may experience data loss. Audiobind reads your source library and writes converted books to a separate output folder; the only thing that ever deletes source files is the explicit Delete button (a confirmation dialog, no undo). Keep backups, run it against a copy first, and pin a tagged release instead of latest if reproducible behavior matters to you.

How it works

  1. Group parts into books. Book/Disc 1..9 and Book/Part 1..3 collapse into one unit. A book is a unit, never a directory.
  2. Verify against the Audible catalog. Title, author, narrator, series, ASIN - via the public Audible search API and Audnex. Every candidate is scored, and the winner must beat the best different work by a margin before it is trusted. Knockoffs (summaries, reviews, study guides, zero-runtime stubs) never count against that margin, and when two candidates are neck and neck the one Audnex agrees with wins.
  3. Prove completeness. The summed runtime of the parts is compared with the catalog runtime. A set that is an hour short is reported, not merged.
  4. Merge and convert. One ffmpeg pass: concat demuxer, AAC, Audnex chapter marks scaled onto the real timeline, embedded cover, full tag set. The bitrate never drops below the configured floor (128 kbps by default) and a richer source keeps its own bitrate. A file that is already AAC in an MP4 container is remuxed with -c:a copy - no re-encode at all.
  5. File it. In the Audiobookshelf layout: Author/Title/Title.m4b or Author/Series/3 - Title/Title.m4b, plus a cover.jpg and an Audiobookshelf-compatible metadata.json. See Folder layout.

It is deliberately conservative

Confidence Meaning Default behaviour
HIGH title and author both corroborated, clear winner converted
MEDIUM exact title, author inferred from the catalog converted (AUTO_CONVERT=high converts only HIGH)
LOW weak or ambiguous match left for review
COLLECTION several books in one folder left for review
held runtime disagrees with the catalog by >25% - usually the wrong edition not converted

Converted books are written to the separate output library. The web UI's Delete is the one destructive path — it permanently removes the source folder and the published output, after you confirm in a dialog (one Delete permanently button; there is no typed confirmation, so read the dialog). It only removes an output folder Audiobind itself converted: a book marked already published points at a folder that was there before, and Delete forgets the book but leaves that folder alone. If you mount the library read-only instead, Delete adapts: it removes the published output and forgets the book, keeps the source folder untouched, and tells you so (the folder will reappear on the next scan unless you remove it from the share).

Delete only removes what belongs to that one book. When two books' part folders share a parent folder (Author/Foo Part 1, Author/Bar Part 1, ...), each book shows up on its own row (Author#foo, Author#bar), and Delete removes only that book's part folders, never the shared Author folder. If the folder you're deleting also holds another book's audio, Delete refuses and nothing is removed.

Documentation

  • Installation and first run - Unraid, docker, compose, hardening, a reverse proxy, the first account, signing in.
  • Using Audiobind - the web UI controls, the Series page, Discover books and the wishlist, the CLI.
  • Configuration - every environment variable with its default, and the output formats (M4B, MP3, both).
  • Acquisition - bring your own downloader, the optional private-tracker wishlist watcher, running it through a VPN.
  • Development - running the tests and building the image, and the correctness traps in the encoder.
  • SECURITY.md - how to report a vulnerability privately, and what is in and out of scope.
  • CHANGELOG.md - what changed in each release.

License

MIT - see LICENSE.

Media gallery

Categories

Related apps

Links

Details

Repository
ghcr.io/stinger303/audiobind:0.20.0
Last Updated2026-11-16
First Seen2026-11-16

Runtime arguments

Web UI
http://[IP]:[PORT:8080]
Network
bridge
Shell
sh
Privileged
false
Extra Params
--restart=unless-stopped --read-only --tmpfs /tmp --cap-drop=ALL --cap-add=CHOWN --cap-add=SETUID --cap-add=SETGID --security-opt=no-new-privileges:true

Template configuration

Library pathPathrw

Folder holding the audiobooks to fix. Writable so Delete can fully remove a book. Owner decides: set Access Mode to Read Only for a guarantee the app never touches your sources - this disables source-delete (Delete then removes only the output).

Target
/library
Default
/mnt/user/data/media/audiobooks
Value
/mnt/user/data/media/audiobooks
Output pathPathrw

Where finished m4b files are written. Never the same as the library path.

Target
/output
Default
/mnt/user/data/media/audiobooks-fixed
Value
/mnt/user/data/media/audiobooks-fixed
AppdataPathrw

Database, audit report and work files.

Target
/config
Default
/mnt/user/appdata/audiobind
Value
/mnt/user/appdata/audiobind
WebUI portPorttcp

Status page and JSON API.

Target
8080
Default
8080
Value
8080
Allowed hostsVariable

Comma-separated names/IPs you open the web UI with, e.g. 192.168.1.10,tower,tower.local. Any other address is refused (protects against DNS-rebinding attacks). Add your server's LAN IP here or the UI is only reachable from the server itself.

Target
ALLOWED_HOSTS
Default
localhost,127.0.0.1
Value
localhost,127.0.0.1
Access tokenVariable

Only for upgrading: an install that still signs in with a token keeps working while this is set. On a new install leave it empty and create your account on the setup page that opens on the first visit - until you do, anyone who can reach this port can claim it, so finish setup right after the first start. Scripts send it as 'Authorization: Bearer TOKEN'.

Target
AUTH_TOKEN
Trusted proxyVariable

true only when Audiobind sits behind your own reverse proxy: X-Forwarded-Host/-For/-Proto from the addresses in Trusted proxy IPs are then believed. Needs Trusted proxy IPs as well.

Target
TRUSTED_PROXY
Default
false
Value
false
Trusted proxy IPsVariable

Comma-separated addresses or CIDRs of your reverse proxy (for example 172.18.0.0/16). Forwarded headers are only honoured from these peers; empty means none.

Target
TRUSTED_PROXY_IPS
Auto convertVariable

Which confidence tiers convert without asking: high, medium or off.

Target
AUTO_CONVERT
Default
high
Value
high
Scan interval (minutes)Variable

How often to look for new books.

Target
SCAN_INTERVAL_MIN
Default
30
Value
30
Audio bitrate (floor)Variable

Minimum AAC bitrate. A richer source keeps its own bitrate (a 256k mp3 stays 256k); anything below this is lifted to it. Capped at 320k.

Target
AUDIO_BITRATE
Default
128k
Value
128k
ChannelsVariable

1 = mono, 2 = stereo. Stereo keeps the source layout; mono halves the file size.

Target
AUDIO_CHANNELS
Default
2
Value
2
Parallel jobsVariable

Books converted at once. Raise if your CPU is idle.

Target
JOBS
Default
1
Value
1
Nice levelVariable

CPU priority for ffmpeg. Higher = yields to everything else.

Target
NICE
Default
10
Value
10
Max runtime deltaVariable

Hold a book when its runtime differs from the catalog by more than this fraction (0.25 = 25%).

Target
MAX_RUNTIME_DELTA
Default
0.25
Value
0.25
RegionVariable

Audible region for metadata: us, ca, uk, au, fr, de, it, es, jp, in.

Target
REGION
Default
us
Value
us
Dry runVariable

true = log every decision but write nothing.

Target
DRY_RUN
Default
false
Value
false
Log fileVariable

Path of the rotating log file (5 MB, 3 backups). Written next to the console log, so it survives a container recreate. Set it to empty only if you want no file log.

Target
LOG_FILE
Default
/config/audiobind.log
Value
/config/audiobind.log
Notify URLVariable

Optional webhook (Discord/Slack/ntfy) posted a summary after each scan.

Target
NOTIFY_URL
Ingest pathPathro

Optional. Folder where downloaded audiobooks land (for example qBittorrent's completed folder for the wishlist watcher). Mounted read-only. Leave empty to turn ingest off.

Target
/ingest
Ingest dirVariable

Set to /ingest when the Ingest path above is used; empty = ingest off.

Target
INGEST_DIR
Tracker URLVariable

Optional. Base URL of your private tracker, e.g. https://tracker.example (no path). The wishlist watcher is off until this, both paths, the cookie name and the session are set (plus the qBittorrent login below).

Target
TRACKER_URL
Tracker search pathVariable

Optional. Path of the tracker's JSON search endpoint.

Target
TRACKER_SEARCH_PATH
Tracker search methodVariable

Optional. POST (default) or GET.

Target
TRACKER_SEARCH_METHOD
Tracker search categoryVariable

Optional. The category value to send with a search, if the site needs one. Empty = none is sent.

Target
TRACKER_SEARCH_CATEGORY
Tracker search encodingVariable

Optional. How a POST sends the search body: json (default) or form (application/x-www-form-urlencoded key=value pairs).

Target
TRACKER_SEARCH_ENCODING
Tracker search bodyVariable

Required for the watcher. The search request as a JSON object with {{title}}, {{author}} and {{category}} placeholders, e.g. {"q": "{{title}} {{author}}"}. A member that is only placeholders and comes out empty is left out.

Target
TRACKER_SEARCH_BODY
Tracker download pathVariable

Optional. Path of the tracker's torrent download endpoint.

Target
TRACKER_DOWNLOAD_PATH
Tracker download id fieldVariable

Optional. Query parameter carrying the torrent id (default tid).

Target
TRACKER_DOWNLOAD_PARAM
Tracker freeleech fieldVariable

Optional. Query parameter that spends a freeleech credit, e.g. fl. Empty = never sent.

Target
TRACKER_FREELEECH_PARAM
Tracker cookie nameVariable

Optional. The name of the tracker's session cookie.

Target
TRACKER_COOKIE_NAME
Tracker session (secret)Variable

Optional. The value of the tracker's session cookie. Create the session for the IP the container reaches the tracker from. A secret.

Target
TRACKER_SESSION
Tracker proxyVariable

Optional. http://host:port (or https://) proxy for every tracker request, e.g. a VPN container's HTTP proxy. Empty = direct. Fail-closed: a dead proxy means no tracker request, never a direct one. Prefer running Audiobind in the VPN container's network (see the README, Running the watcher through a VPN).

Target
TRACKER_PROXY
Tracker user agentVariable

Optional. Text to send as the User-Agent to the tracker. Empty = audiobind/version. Set to none to send no User-Agent (some trackers refuse that with HTTP 400).

Target
TRACKER_USER_AGENT
Tracker premium memberVariable

Set to true if your account holds the tracker's top membership tier. When false, torrents restricted to that tier are skipped instead of attempted. Can also be changed in Settings > Watcher without a restart.

Target
TRACKER_VIP
Default
false
Value
false
Expected egress IP (guard)Variable

Optional. Your VPN's exit address. When set, the watcher checks which IP the tracker would see before every cycle and refuses to contact it unless it is exactly this one. Leave empty to skip this check. Can also be changed in Settings > Watcher without a restart.

Target
TRACKER_EXPECTED_EGRESS_IP
Home IP (guard)Variable

Optional. Your home connection's public IP. When set, the watcher checks which IP the tracker would see before every cycle and refuses to contact it if it is this one, or if it cannot tell. One small HTTPS request per cycle to ipinfo.io.

Target
TRACKER_HOME_IP
Watcher dry runVariable

true = the watcher searches and logs what it would download, but never downloads. Separate from Dry run.

Target
WATCH_DRY_RUN
Default
false
Value
false
Watch interval (minutes)Variable

Minutes between wishlist watcher cycles (10-1440).

Target
WATCH_INTERVAL_MIN
Default
60
Value
60
Watch max per cycleVariable

Wanted books the watcher searches per cycle (1-20). Also editable in Settings > Watcher.

Target
WATCH_MAX_PER_CYCLE
Default
5
Value
5
Watch max incompleteVariable

No torrent is added in a cycle while this many in the qBittorrent category are still downloading. 0 = no limit.

Target
WATCH_MAX_INCOMPLETE
Default
10
Value
10
qBittorrent URLVariable

qBittorrent WebUI the watcher hands torrents to. If qBittorrent shares a VPN container's network with Audiobind, use http://127.0.0.1:8083 (the LAN address times out).

Target
QBIT_URL
Default
http://localhost:8083
Value
http://localhost:8083
qBittorrent categoryVariable

The qBittorrent category torrents are added to (its save path is your ingest folder).

Target
QBIT_CATEGORY
Default
audiobooks
Value
audiobooks
qBittorrent userVariable

qBittorrent WebUI username. The watcher stays disabled without a login.

Target
QBIT_USER
qBittorrent passwordVariable

qBittorrent WebUI password.

Target
QBIT_PASS
PUIDVariable

User ID for written files.

Default
99
Value
99
PGIDVariable

Group ID for written files.

Default
100
Value
100
TZVariable

Timezone for log timestamps.

Default
America/Denver
Value
America/Denver