Repository navigation
Metadata and tags
Writing the metadata into the files is what this app is for. A database of titles and covers is easy and worth little: the moment you open those books in anything else — a phone, a car, another player — it is the tags inside the files that decide what you see. So this app treats those tags as the real collection and its own database as a draft of them.
Which is why two different things can be true of a book: the app shows a year, and the files carry one. My Audiobook Collection keeps them apart, tells you which is which on every card, and gives you one button to make the second match the first.
Every card lists it, in green:
In MP3: album, title, artist, album artist, narrator, genre, year, description, cover, track no
That badge is built during a scan by reading the tags out of the first file of
the book. A book with only album, artist in there is missing the rest,
whatever the card shows above the badge — My Audiobook Collection is showing you its database.
Nine tags are treated as required: album, title, artist, album artist, genre, year, description, cover, track no. (Narrator is read and shown, but a book without one is not counted as untagged.)
The narrator is read from the composer tag only. An audiobook's artist is its author, so a file with no composer tag simply has no narrator — the field stays empty until you type one in Edit metadata. Up to version 2.2.24 the author's name was used instead, which is why some books showed their author as their narrator; 2.2.32 clears those on startup, except where the files themselves name the author as the narrator, since some authors read their own books.
The Needs tags entry in the left column lists every book missing one of those, and splits the reason:
- can be written now — My Audiobook Collection already knows the value; it only has to go into the files. Write tags does it per book, or Write tags into all N for the whole list.
- needs a lookup first — My Audiobook Collection does not have it either. Find metadata from the same row, or type it in with Edit metadata.
It browses like the genres do: the authors of the books that need tags stand in the column beside it, each with how many, and picking one leaves that author's books in the pane. Write into N book(s) then counts what is on screen, so a big collection can be worked through one author at a time — and after every write the list comes back to the author you were on.
The count next to Needs tags is the number of books in that state, and it updates after every write.
Find metadata on a card opens the dialog with a search already in the box — the title and author as your folders name them — and waits there. Read it, change it if it is not what you would type, and press Search (or Enter). Then it shows what Google Books came back with.
That pause is on purpose: a folder name is often nearly right and rarely exactly right, and a search you correct first saves you looking at five results for the wrong book.
Each result offers:
- Use metadata — open Edit metadata with this result already in the fields: title, author, series, the number in that series, narrator, year and description, with the cover carried along behind them. Read it, change what is wrong, and save it there. Nothing is written until you do. Where the result says nothing, the book keeps what it has — Google names a volume number for very few books, so that field usually stays as it was.
- Use + write into MP3s — take the result as it stands and write the files as well, without the dialog.
A result may offer the series as well, ticked, with the volume number beside it:
☑ Series: Merry Gentry, book 1
With Use metadata, that series lands in the Series field of Edit metadata — which is a folder level, so saving there files the book under it. Untick it, or take a result that has none, and the field opens with the series the book is already filed under: saving then leaves it exactly where it is.
With Use + write into MP3s the series is named in the book and in its tags and the book is not moved, so it joins the series in the left column without anything on disk changing.
Google keeps series data per record, not per book, and often not at all. Where it has none, the app looks in the title's brackets and the subtitle, at the other editions in the same answer, at the ebook editions, and finally through all the records Google keeps of that book. When every one of those is silent it says so instead of leaving you guessing:
No series: Google keeps no series data for this edition — nothing in its title or subtitle either. Neither have its ebook editions, nor any of the other records Google keeps of it — type the series into Edit metadata and it stays.
Settings → What Google says about series asks about a stretch of books that have no series yet and reports, per book, what Google answered, where the series came from, and what it cost in requests. It is the way to see why one book gets nothing.
A result that credits more than one author offers the pair as a choice — both names together, or either one on its own, or the name the book is filed under:
Author: Terry Pratchett, Neil Gaiman ▾
What you pick goes into the artist and album artist tags. The author folder keeps its name, because a book can only live in one of them; use Move… if it belongs somewhere else.
Google answers with categories like Fiction / Fantasy / Epic fantasy. Each part
is offered in a Genre dropdown next to the genre the book is filed under,
which stays the default — nothing moves unless you pick something else. A
suggestion with no folder yet is marked new folder.
Picking one means what it says in this app: a genre is a folder, so the book moves into that genre's folder (created, and registered as a library folder, if it is new), keeping its author and series folders, its position and its listened marks — and the following tag write carries the new genre.
A 503 is retried after 10, 20 and 30 seconds, with the wait counting down in
the dialog, before giving up. Other errors say what they are: a rejected key, a
Books API that is not enabled for the key, a daily quota that is used up.
You need an API key for any of this. See Settings reference.
Everything by hand, when the lookup finds nothing useful:
The line at the foot of the dialog is the folder the book sits in on disk and how many files it is made of — handy when two books share a title, or when you want to find the files yourself.
Note that Series is a folder, so filling it in files the book under
genre / author / series / book, and emptying it moves the book back up a level.
The folder keeps its own name either way.
Book number in the series, under it, is the number a card shows as book 3. It is what orders the books of a series on the shelf, and it goes into the tags with the series name. Leave it empty when there is no number. This is where a number a lookup got wrong is corrected, and the only place to give one to a series that came from your folders rather than from Google.
For a book inside a part of a series, the number is its number within that part: the Series field shows the part, which is the folder the book is in, and the books of that part are ordered against each other. The series above the part groups them and is not numbered.
Beside every field is a ⧉ button that copies what is in it to the clipboard —
a title to paste into a shop or a search, a description to paste into something
else. It works whether you reach the app over https or over plain http://…, and
the field itself is left exactly as it was.
Save stores it. Save + write into MP3s stores it and writes the files.
Under the Listened tick on a card, on the admin page, is a second one: Unabridged — the whole book, not a shortened reading of it.
Nothing in the files says this. An abridged reading carries the same title, the same author and often the same cover as the full one, and the only way to know is to have been told. So it is yours to state, and it is a fact about the book rather than about one listener: the administrator ticks it and everybody sees the badge on the listening page.
Off means nobody has said so, not "abridged". A collection where nothing is ticked is one where the question has not been asked yet.
A cover is the one thing about a book you cannot type, so under Description there is a box for it.
- Find the art anywhere — a shop page, a wiki, an image search.
- Right-click it and choose Copy image (not Copy image address: that copies a link, and a link is not a picture).
- Press Ctrl+V in the dialog. It does not matter which field the cursor is in; a clipboard with a picture on it means the picture, and text you paste into a field is left alone.
You can also drop a file on that box, or click choose one and pick it.
JPEG and PNG only. Those are the two kinds an MP3 tag can carry, and the two this app keeps in its covers folder. Paste a WebP — which is what many sites now serve — and it says so plainly rather than accepting it and losing it later. Save the picture as a JPEG or a PNG first, or copy a different one.
The new art appears at once, but nothing is changed until you press Save. Press Cancel and the book keeps the cover it had. Save + write into MP3s also puts the picture into the files themselves, so it travels with them to any other player.
The old cover file is not deleted: like every cover this app replaces, it is left
behind for Tidy up unused covers in Settings to sweep into covers/duplicates.
The same goes for a picture you pasted and then cancelled.
A book whose files carry no art, and no cover.jpg beside them, is not left as an empty rectangle. My Audiobook Collection draws a cover for it instead:
On the shelves they sit beside real art without leaving a gap — here only SPQR, on the right, has no art of its own:
The colours come from the title, so two books beside each other rarely look alike, and the pair of colours turns over every night: the shelf you open in the morning is not the one you left, while a book keeps the same cover all day. The same four books, today and the two days after:
The step is 37° a day, which is enough to notice and takes a year to come back round. Real cover art never changes, and a browser is told it may keep a drawn cover only until midnight.
The same cover stands in when real art has gone missing from disk, so a moved or deleted picture never shows up as a broken image.
Nothing is written to disk for this, and it changes nothing about the book: it still appears under Needs tags until it has real art, and Find metadata will put a real cover in its place.
A book counts as done when its files carry all of album, title, artist, album artist, genre, year, description, cover art and track number. Open Needs tags and read the row: it says what a write can add now and what is not known yet.
Writing cannot invent what the app does not have. A book with no year, no description or no cover art anywhere keeps asking for those until Find metadata or Edit metadata fills them in; scanning and writing again will not change it.
Cover art beside the audio counts — a cover.jpg, folder.jpg or front.png in
the book's folder is written into the files like anything else.
Tags can only be written into MP3s, so a book in another format never leaves Needs tags however often you write. That is not the end of it: Needs converting in the left column lists every one of those books, and converting turns one into a properly tagged MP3 book — a chapter to a track — keeping what it came from.
It has a chapter of its own: Converting to MP3.
A scan reads every book's first file again, so tags written by another tagger are picked up by Scan library. Not only that they are there — which is what Needs tags counts — but what they say: the narrator, the year, the description and the cover art come into the app with them. The counts in the left column follow the scan; you do not have to reload the page.
Where a file says nothing, what the app knows is left alone, so a description you typed into Edit metadata survives a scan. Where the file does say something, the file wins — it is the collection, and writing tags puts the app's values into the files anyway.
Write into MP3s on one book does not stop you starting another. A book from one series and a book from another can be written at the same time, each with its own bar at the bottom naming the book it belongs to.
What is held back while a write runs is anything that would move those files or read them half-written: a scan, an import, the disk check, the whole-collection run, and Find metadata and Edit metadata. Those buttons grey until the write is done.
The same book is never written twice at once, whichever way you ask. The button that started it is dead while it runs; that book's metadata buttons are held back; and if you ask again from another tab, a phone, or a dialog you left open, the answer is a line saying the book is already being written — not an error, and not a second bar. Two writers on one file is worse than a wait.
Write into MP3s on a card, Save + write into MP3s in the edit dialog and Write tags into all MP3s in Settings all write the same thing into every MP3 of the book:
| Frame | Filled with |
|---|---|
TALB album |
the book title |
TIT2 title |
the book title — not "018 of 132": the track number does the ordering |
TPE1 artist, TPE2 album artist |
the author |
TCON genre |
the genre folder the book sits in |
TYER year |
the year |
COMM comment |
the description |
APIC picture |
the cover |
TCOM composer |
the narrator |
TRCK track |
renumbered in playing order, zero padded: 01/12, 001/120
|
Points worth knowing:
- Values My Audiobook Collection does not have are left out, never written empty, so a book with no description does not end up with an empty comment frame that reads back as "present".
- Writing merges: frames you are not setting are left alone.
- MP3 only. Other formats are read and played, never written.
- A bar at the bottom follows the write, file by file, and the green badge is rewritten from what actually landed in the files.
Write tags into all MP3s in Settings does the whole collection, and that is an hour of work on a big share — so it runs on the server:
- closing the page does not stop it, and reopening the page picks the bar back up
- Stop leaves it exactly where it is; the button then reads Carry on writing tags and the run continues from the next book, not from the beginning
- a container that restarts mid-run leaves the run paused with its place kept, rather than starting the whole collection again on its own
Settings says where it stands whenever you open it: not started, how far along, how many books are still to go, or what the last run wrote.
Only one tag write runs at a time, whoever asks: while the whole-collection run is going, Write into MP3s on a single book is refused with a reason rather than writing the same files twice over. Everything else — a lookup, applying metadata without writing it into the files — carries on as usual.
