Repository navigation
Settings reference
The Settings button in the header is a pulldown over the two kinds of settings:
- Library and maintenance opens the dialog this page describes.
- Home Assistant opens a page of its own — see Home Assistant.
Everything in one dialog, on the admin page.
The folders that are scanned, as many as you like. Browse… walks the disk from inside the container, Use as library takes the folder you are standing in, and the × removes an entry (files are never touched).
Is a Genre behind an entry says the folder is one genre rather than a folder holding genre folders. Setting up your library explains when you want which.
Saving a changed list starts a scan by itself.
Not set here. There is always an administrator: on a fresh install the first page
asks you to make one, and the password you choose is kept in the app's own
database, hashed. ADMIN_USER and ADMIN_PASSWORD on the container override
that — the Unraid template has a masked field, and on Proxmox they are two lines
in /etc/my-audiobook-collection.env — which is the way back in after a
forgotten password. This section says which of the two is in force.
See Sharing with others.
Which version is answering, whether a newer one is out, and — where this install can take one — a button to install it.
GitHub is asked for the repository's tags at most once an hour, and after a failure it waits ten minutes before trying again rather than asking on every page load. Check for a newer version asks it there and then.
When there is one, a red dot appears on the icon in the top-left corner and Install the update appears in the Settings ▾ menu, so you do not have to open this page to find out. Both go away again once there is nothing to install.
What is offered depends on how the app was installed:
| a Proxmox container | Install it. The app stops for a moment and comes back on the new version; the page waits, says Updated to v…, and reloads. See Installing on Proxmox |
| a Docker image | the two commands to pull a new one. Updating an image is the host's job and not something the app could do |
| a plain checkout | the same update as the container's, by hand, in the two commands it prints |
If an update went wrong, the line here says so the next time you look: the updater restarts the page that asked for it, so it leaves a note behind instead of answering.
The genre folders it knows, with their paths, and a row to create one: the folder it goes in first, then the name. Creating a genre makes the folder, and adds it as a library folder when your libraries are single genre folders. Setting up your library has the details.
Where new audiobooks arrive. Browse… picks it, and Use as import folder in the browser sets it. Leave it empty if you never import; the Import entry in the left column then simply says there is nothing set.
Check every book against the disk opens every file of every book. That is the only way to find what a scan cannot see: a folder that has gone, a folder with no audio left in it, a truncated download, a zero-byte file, a share that answers but will not read.
It asks before it starts, because on a large collection it takes minutes rather than seconds, and the bar at the bottom follows it book by book. You can keep listening while it runs; nothing else that changes the collection can start until it is done.
What it finds goes to Broken on disk in the left column — see Moving and deleting.
Your audiobooks live on your share and survive almost anything. Everything this
app knows about them does not: where each person is in each book, the accounts
and their passwords, the levels, the hearts, what was downloaded. All of that is
in one file, library.db, and the audio on disk cannot rebuild any of it.
A copy is taken when the app starts and once a day after that, into a backups
folder beside the database — library-2026-10-06.db, one per day, the last
seven kept. They are on the same volume as the database, so whatever you
already keep of your appdata takes them with it. That is the loss this is for: a
file going wrong, rather than a disk going away. If you want them somewhere else
as well, copy that folder off on your own schedule.
Settings shows when the last copy was taken, how big it was and how many are kept. Read that line now and again — a backup nobody looks at is one that can fail quietly and be believed for months. Back up now takes one on the spot, which is worth doing before anything drastic.
To restore one: stop the container, put the copy back next to the old one as
library.db (keep the old one until you are happy), and start it again. Anything
listened to between that copy and now is not in it; the books themselves are
untouched either way.
Cover images are stored in /data/covers under the name of the image itself, so
a book that gets new artwork leaves its old file behind with nothing pointing at
it. Tidy up unused covers goes through the folder and moves every cover file
no book refers to into covers/duplicates, overwriting a file of the same name
already there. It reports how many it moved and how many are still in use.
A cover that comes from the book's own folder (cover.jpg next to the audio) is
never involved: that file was never copied into /data.
Once covers/duplicates holds more than 1000 files, it is worth a decision,
so the button asks:
- OK deletes those files.
-
Cancel keeps them, zipped into one
covers-<timestamp>.zipbeside them, and removes the loose files. An archive made earlier is left alone.
Nothing here touches a cover a book is using, and nothing touches your audiobooks.
Write tags into all MP3s writes the metadata My Audiobook Collection holds into every MP3 of every book. What it writes is in Metadata and tags — including the fact that it merges rather than overwrites, and never writes an empty frame.
It runs on the server, so you can close the page while it works, and it can be stopped and carried on: the line above the button says where it stands, and Stop appears next to it while it runs.
Settings ▾ → Home Assistant leads to a page of its own, where the address of your Home Assistant and one long-lived access token from it are all the setting up there is: the app then writes its own sensors into Home Assistant and plays books on its media players. Nothing has to be configured on the Home Assistant side. See Home Assistant.
Not here any more: both answers live together in Series to complete, in the left column under Maintenance — what is missing between the books you already have, and which volumes Wikidata knows that you do not have at all. See Browsing and listening.
Asks Google about the first books that have no series yet — 15, 30 or 40 of them — and reports what came back: the series it names, which of the places it came from (the title, the subtitle, Google's own series data, another edition, another record), the raw fields Google sent, and how many requests each book took. Use it when a book you know is in a series gets none offered. It spends one to three requests of your daily Google quota per book.
Check folder permissions reports, from inside the container, who the app writes
as and what each folder actually lets it do — the data folder, every library, the
import folder and one book folder, with the owner, the mode, and whether a file can
really be created there. It writes a test file and removes it again rather than
reading the mode and guessing. If it says the owner is 0:0, the app is running as
root and every folder it makes will be one you cannot write in yourself; see
Troubleshooting.
| Variable | What it does |
|---|---|
GOOGLE_API_KEY |
the Google Books key, used by every lookup. It lives on the container and nowhere else — there is no field for it here, so there is no second copy to drift out of step, and it survives an emptied appdata folder |
ADMIN_USER / ADMIN_PASSWORD
|
the administrator, overriding the one kept in the database. Set them together; changing them means changing them here and restarting. The way back in after a forgotten password |
PORT |
the port inside the container, 8523 by default |
DATA_DIR |
where the database and covers live, /data by default |
PUID / PGID
|
the user the app writes as — 99 and 100 on Unraid. Without them it writes as root, and the folders it creates are ones you cannot write in |
UMASK |
the mode of what it creates; 000 is what an Unraid share normally is |
GOOGLE_COUNTRY |
which country's Google catalogue answers, US by default. Series data belongs to a country's catalogue |
HA_TOKEN |
only for the polling addresses under /api/ha: set it and they ask for it. The Home Assistant page needs no container setting |
BASE_URL |
the address other machines reach the app on, behind a reverse proxy. The URLs handed to Home Assistant and to media players are built from it |
Google Cloud Console → APIs & Services → enable Books API → Credentials →
Create credentials → API key. Put it in the container's GOOGLE_API_KEY
(the Unraid template has a masked field for it) and restart the container.
The Books API is free for this kind of use, and the app asks for at most five results per lookup.
