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
Overview
Readme
View on GitHubAudiobind
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
.m4bper 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
/librarymount 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

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
- Group parts into books.
Book/Disc 1..9andBook/Part 1..3collapse into one unit. A book is a unit, never a directory. - 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.
- 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.
- Merge and convert. One
ffmpegpass: 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. - File it. In the Audiobookshelf layout:
Author/Title/Title.m4borAuthor/Series/3 - Title/Title.m4b, plus acover.jpgand an Audiobookshelf-compatiblemetadata.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
Explore more like this
Explore allLinks
Details
ghcr.io/stinger303/audiobind:0.20.0Runtime 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
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
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
Database, audit report and work files.
- Target
- /config
- Default
- /mnt/user/appdata/audiobind
- Value
- /mnt/user/appdata/audiobind
Status page and JSON API.
- Target
- 8080
- Default
- 8080
- Value
- 8080
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
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
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
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
Which confidence tiers convert without asking: high, medium or off.
- Target
- AUTO_CONVERT
- Default
- high
- Value
- high
How often to look for new books.
- Target
- SCAN_INTERVAL_MIN
- Default
- 30
- Value
- 30
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
1 = mono, 2 = stereo. Stereo keeps the source layout; mono halves the file size.
- Target
- AUDIO_CHANNELS
- Default
- 2
- Value
- 2
Books converted at once. Raise if your CPU is idle.
- Target
- JOBS
- Default
- 1
- Value
- 1
CPU priority for ffmpeg. Higher = yields to everything else.
- Target
- NICE
- Default
- 10
- Value
- 10
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
Audible region for metadata: us, ca, uk, au, fr, de, it, es, jp, in.
- Target
- REGION
- Default
- us
- Value
- us
true = log every decision but write nothing.
- Target
- DRY_RUN
- Default
- false
- Value
- false
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
Optional webhook (Discord/Slack/ntfy) posted a summary after each scan.
- Target
- NOTIFY_URL
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
Set to /ingest when the Ingest path above is used; empty = ingest off.
- Target
- INGEST_DIR
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
Optional. Path of the tracker's JSON search endpoint.
- Target
- TRACKER_SEARCH_PATH
Optional. POST (default) or GET.
- Target
- TRACKER_SEARCH_METHOD
Optional. The category value to send with a search, if the site needs one. Empty = none is sent.
- Target
- TRACKER_SEARCH_CATEGORY
Optional. How a POST sends the search body: json (default) or form (application/x-www-form-urlencoded key=value pairs).
- Target
- TRACKER_SEARCH_ENCODING
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
Optional. Path of the tracker's torrent download endpoint.
- Target
- TRACKER_DOWNLOAD_PATH
Optional. Query parameter carrying the torrent id (default tid).
- Target
- TRACKER_DOWNLOAD_PARAM
Optional. Query parameter that spends a freeleech credit, e.g. fl. Empty = never sent.
- Target
- TRACKER_FREELEECH_PARAM
Optional. The name of the tracker's session cookie.
- Target
- TRACKER_COOKIE_NAME
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
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
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
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
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
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
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
Minutes between wishlist watcher cycles (10-1440).
- Target
- WATCH_INTERVAL_MIN
- Default
- 60
- Value
- 60
Wanted books the watcher searches per cycle (1-20). Also editable in Settings > Watcher.
- Target
- WATCH_MAX_PER_CYCLE
- Default
- 5
- Value
- 5
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 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
The qBittorrent category torrents are added to (its save path is your ingest folder).
- Target
- QBIT_CATEGORY
- Default
- audiobooks
- Value
- audiobooks
qBittorrent WebUI username. The watcher stays disabled without a login.
- Target
- QBIT_USER
qBittorrent WebUI password.
- Target
- QBIT_PASS
User ID for written files.
- Default
- 99
- Value
- 99
Group ID for written files.
- Default
- 100
- Value
- 100
Timezone for log timestamps.
- Default
- America/Denver
- Value
- America/Denver