Repository navigation
Music Assistant
Music Assistant can read this collection and play it: your books with their series, their chapters and their covers, and where you got to in each — which syncs both ways, so a book you carried on with through Music Assistant is at the right minute when you open this app, and the other way round.
Everything on this page has been run against a real Music Assistant, not only against the tests: browsing, playing on a speaker, and the position coming back.
- This app on 2.5.0 or newer. Playing does not work on older builds — a listener signed in with a password fetches the audio in a way the earlier versions had no answer for. Update the container first.
- Music Assistant 2.x with its Audiobookshelf provider, which ships with it. You do not need Audiobookshelf itself installed; nothing of it is involved.
- Both on the same network, and Music Assistant able to reach this app's
address — if it runs as a Home Assistant add-on, that is a different container
than your browser, so use the address on the network, never
localhost.
1 · Give the container a password. Put one of your choosing in the
MA_TOKEN variable. On Unraid it is Music Assistant token in the template,
and you may have to press Show more settings to see it. Anything will do as
long as it is not guessable: it is the only thing between your network and the
collection. Leave it empty and none of this exists at all — every address it
would use answers not found.
2 · Note the name you listen under. Open this app and look at the name in the header. That exact spelling is what you type in the next step.
3 · Add it in Music Assistant. Settings → Music Providers → Add → Audiobookshelf, and fill in:
| Field | What to put |
|---|---|
| Server URL | the address of this app, e.g. http://192.168.1.10:8523 — the same one you open in a browser, with no trailing path |
| Username | your listener name here, spelled exactly as in step 2 |
| Password | the MA_TOKEN you set |
Leave Verify SSL alone unless you reach this app over https.
4 · Save. Music Assistant logs in, reads the library, and your books appear under Audiobooks. Give it a moment on a large collection: it fetches them in pages of thirty.
It is which listener the places belong to. Use the name you use in the app, or Music Assistant will keep its own position under a name of its own and the two will never agree.
One provider is one listener, for everybody. Music Assistant signs in once, with one name, and every position it reports afterwards lands on that name — whoever is in the room. Set it up with your name and the book your son listens to on the kitchen speaker turns up in your Continue listening, because as far as this app can tell, you listened to it.
The app cannot do better than record it. Nothing in a Music Assistant request says who pressed play: identity is fixed at login and nothing afterwards revisits it. The remedy is on the Music Assistant side — one Audiobookshelf provider per person, each with that person's name, which Music Assistant supports. Then each one's places land on their own name.
If a book is already on your row that way, untick Listened on your own card to clear it. Asking the other person to mark it listened does nothing: it is your row that holds the place.
Browsing a provider in Music Assistant shows folders it builds itself — Audiobooks, Series, Authors, Narrators, Collections and Playlists. That layout is Music Assistant's, not this app's, which is why an Audiobooks folder appears inside the library.
- Audiobooks — everything, by title.
- Series — each series, its books in reading order.
- Authors and Narrators — their books, and an author's series under them.
- Collections and Playlists are empty: this app groups by folder and by series and has neither. Music Assistant asks, is told there are none, and moves on.
Playing works on any Music Assistant player, and a book of forty files plays as one timeline rather than forty tracks — the files are laid end to end with their offsets, so skipping forward through a book behaves.
The position syncs both ways. Play in Music Assistant and the seconds land on your listener here; carry on in this app and Music Assistant picks the book up where you left it. Finish a book in either and it counts as finished in both.
- Podcasts. This app has none.
- Instant updates. A book you add, rename or retag here reaches Music Assistant on its next sync, not the moment you do it. The live channel between the two is open — Music Assistant refuses to start without one — but this app sends nothing down it yet.
- A page that refreshes itself. If this app is open in a browser while you listen in Music Assistant, the time under the book does not move on its own: Continue listening is drawn when the page loads. Reload it and the position is there. Nothing is lost — it is only the drawing that waits.
And the thing worth knowing rather than discovering: this is an imitation of Audiobookshelf's interface, because Music Assistant has no supported way to load a provider written for another app. If an update to either side stops the connection working, that is the first place to look, not your network.
The useful evidence is almost always a short message rather than a long log. Music Assistant shows failures as a red toast in the corner, and the breadcrumb above it says where you were. Both of these solved real problems here.
| What you see | What it means |
|---|---|
| The provider will not set up at all | The address is wrong, unreachable from Music Assistant's container, or MA_TOKEN is empty or mistyped. With it empty, every address answers not found, which reads in the log as a server that is not there |
| NotFoundError on a red toast while browsing | An address this app does not answer. Note the breadcrumb — it says which folder you were opening — and report both |
| Error handling message: music/browse: with nothing after it | The same thing seen from the log side: that client raises its not-found error with no text in it |
| A folder that never opens, with nothing in the log | A listing that does not end. Every paged answer here must give an empty page past the end; if one stops doing that, Music Assistant loops for ever |
| The requested media item could not be found when you press play | The audio could not be fetched. After an update of this container, older builds lost the session Music Assistant was holding; 2.5.24 and newer read the book out of the session id, so a restart costs nothing |
| A field named in the error, e.g. Field "device_info" … is missing | The kindest failure there is: it names exactly what this app left out. Report the sentence as it stands |
Two settings that help when reporting: in Music Assistant, Settings → Providers → Audiobookshelf → Log level: DEBUG makes the provider say what it asked for and what it got. The full traceback of a browse failure needs Music Assistant's own log level at debug, not the provider's — they are different loggers, and the provider's setting does not change that line.
