Add Audiobookshelf audiobooks & podcast provider

[fmunkes]

Initial support for Audiobookshelf

This PR is an implementation of Audiobookshelf (abs) as music provider.

Features

• Populates Audiobooks from all libraries accessible by user.
• Populates Podcasts from all libraries accessible by user.
• Browse Feature shows the libraries names and podcasts/ books within.
• Progress reporting both ways (see issues below).
• API client for mass - I didn't find a suitable python lib, so I implemented what is needed.

Possible future improvements

• Browse by author, series, narrator etc.
• Search Feature
• Edit Feature

Known issues:

• Progress reporting:
  • abs to mass seems ok
  • mass to abs:
    • on_streamed function of MusicProvider:
      • only called, when next/ previous used in UI (apparently?).
      • not called on pause
      • not called regularly
    • I.e. abs progress is only updated in first case.
  • Which function is called, when "mark as (un)played" is used in the UI?
• Audiobooks:
  Am I correct, that mass only supports single file based audiobooks? abs may list multiple
  audio files per book, so if this is the case, that's something for the documentation. abs even
  offers an ffmpeg concat via its interface. Code-wise currently only the first file of an audiobook
  is respected.
• mypy:
  Is currently disabled for this provider. Unfortunately I had troubles with some type hints, due to
  a lack of knowledge on my side. Happy to figure them out.

Personal note: I used Python quite often during the years, however, I'm not a professional developer.
If you think the code is not worth pursuing, don't hesitate to let me know :). I still learned something.

Thanks for the amazing project!

[OzGav]

@fmunkes can you provide some text for the docs? We have the following headings. You don’t need text for all of them. Please see the other providers for ideas of what to add. I could extract most of this from your opening post in the PR but I am conscious of the improvements you may have made since then. Just the text is fine I will do the actual PR for the docs as a number of things need to be done.

FEATURES
CONFIGURATION
KNOWN ISSUES/ NOTES
NOT YET SUPPORTED

[marcelveldt]

on_streamed function of MusicProvider - only called, when next/ previous used in UI (apparently?).

We're looking into this one, seems to be a bug. Expect to be solved soon.

on_streamed function of MusicProvider - not called on pause

No and that is by design. It will be called when playback completed (full item played or playback stopped) which is enough imo.

on_streamed function of MusicProvider - not called regularly

No and that is by design. Why would we want to report it regularly ?

Which function is called, when "mark as (un)played" is used in the UI?

None, which should be fixed. I will adjust it so it calls on_streamed with 0 seconds or something (I'll chew on it a bit)

Am I correct, that mass only supports single file based audiobooks?

This is still topic of discussion as there seem to be multiple different implementations in the wild but the most common one is a single file per audiobook or podcast-episode with optional chapters.
What we have now is chapter support in a single audiobook/episode. So if you have a file per chapter that will be a challenge

mypy Is currently disabled for this provider.

OK, that will have to be fixed before we can merge but just ask for help and we will help you

[fmunkes]

@OzGav documentation:

FEATURES

• Populates Audiobooks from all libraries accessible by supplied user.
• Populates Podcasts from all libraries accessible by supplied user.
• Browse Feature shows the library names and podcasts/ books within.
• Progress reporting both ways

CONFIGURATION

• For setup you need
  • the URL of an Audiobookshelf instance
  • username of an Audiobookshelf user
  • password of this user
• You may optionally disable ssl verification.

KNOWN ISSUES/ NOTES

Audiobookshelf supports multiple files (e.g. one file per chapter) per Audiobook. Music Assistant however expects a single file. It is suggested to merge multiple files into a single file. You can do this in Audiobookshelf by selecting the Audiobook, click edit, then tools and finally "Open Manager". You will see the merge option there. Do not forget to take a backup of your initial files.

NOT YET SUPPORTED

• Browsing by author
• Browsing by collection
• Browsing by series
• Browsing by playlists

[fmunkes]

on_streamed function of MusicProvider - only called, when next/ previous used in UI (apparently?).

We're looking into this one, seems to be a bug. Expect to be solved soon.

Thanks - I think my other "on_streamed remarks" become obsolete when this is resolved.

Which function is called, when "mark as (un)played" is used in the UI?

None, which should be fixed. I will adjust it so it calls on_streamed with 0 seconds or something (I'll chew on it a bit)

Thank you!

Am I correct, that mass only supports single file based audiobooks?

This is still topic of discussion as there seem to be multiple different implementations in the wild but the most common one is a single file per audiobook or podcast-episode with optional chapters. What we have now is chapter support in a single audiobook/episode. So if you have a file per chapter that will be a challenge

I think for the time being it is sufficient to just add a comment to the documentation (maybe also to the overall one of 'Audiobooks'?). In the case of Audiobookshelf, merging into one file can be achieved within the UI.

[fmunkes]

There is a currently a single mypy error left. Everything else was resolved by switching to mashumaro as suggested.
I get:
music_assistant/providers/audiobookshelf/__init__.py:496: error: Incompatible types in assignment (expression has type "ABSAudioBook", variable has type "ABSPodcast") [assignment]
Don't see what's wrong there currently. I'll check again tomorrow.

[Jc2k]

RE your mypy error, that's a mypy quirk. Not sure whether its a limitation or a deliberate decision, but you can't use a variable twice for different types. Line 493 makes it think item is a podcast. Then on line 496 item is an audio book. I don't know if there is a better way, but if you had something link async from audiobook in ... it will probably work.

[marcelveldt]

If you rebase your branch, you get a new "on_played" callback:

[fmunkes]

RE: on_played
Thanks a lot! The callback unfortunately doesn't report the correct position for me. I tried the following cases:

• play (no item in queue)
  • callback is called with id of new stream to be played
• replace queue
  • callback is called twice, with id of old stream and new stream
• next / previous
  • same as above
    In all cases, position = 0.

When I try to (un)mark a media item I'm faced with a RuntimeError:
ERROR (MainThread) [music_assistant.webserver] Error handling message: music/mark_played: Value None of type <class 'NoneType'> is invalid for media_item

Am I missing something here?

[fmunkes]

Comment on audiobooks split accross files:
I learned today, that abs supports sessions, where the abs instance offers you an hls stream of the audiobook. I.e. multiple files would be hidden from mass. This would change the function returning StreamDetails, and add a few other schema definitions plus code complexity. I only played using curl and api calls, nothing in python yet.
I think it is reasonable to have the current PR in a merge-ready state first. I think it does cover many use cases. When that is done, I will see if I can have that feature added as well, possible via a config option of the provider, and would open another PR.

[marcelveldt]

Comment on audiobooks split accross files: I learned today, that abs supports sessions, where the abs instance offers you an hls stream of the audiobook. I.e. multiple files would be hidden from mass. This would change the function returning StreamDetails, and add a few other schema definitions plus code complexity. I only played using curl and api calls, nothing in python yet. I think it is reasonable to have the current PR in a merge-ready state first. I think it does cover many use cases. When that is done, I will see if I can have that feature added as well, possible via a config option of the provider, and would open another PR.

OK! Keep in mind that you can simply feed the HLS url as url in streamdetails and it will be automagically sorted.

[marcelveldt]

RE: on_played Thanks a lot! The callback unfortunately doesn't report the correct position for me.

What player did you use to test it ?

[fmunkes]

OK! Keep in mind that you can simply feed the HLS url as url in streamdetails and it will be automagically sorted.

Ah, excellent, I just had a look at the StreamDetails class. I do have some more time on Saturday/ Sunday, so I could report back by the end of this week on this part. So we could also wait for this, and then continue from there. I guess, I'll return something like this then:

return StreamDetails(
            provider=self.instance_id,
            item_id=audiobook_id,
            audio_format=AudioFormat(
                content_type=ContentType.UNKNOWN,
            ),
            media_type=MediaType.AUDIOBOOK,
            stream_type=StreamType.HLS,
            path=<abs_url>/output.m3u8,
)

i.e. the path is an m3u8 playlist.

[fmunkes]

What player did you use to test it ?

I used a Chromecast, and tried just now via Airplay, same result. I can also try a player integrated via HomeAssistant, though that will be later today again.

[marcelveldt]

I guess, I'll return something like this then:

Exactly that should work out of the box! ffmpeg will then care care of stitching it together.

[marcelveldt]

I used a Chromecast, and tried just now via Airplay, same result. I can also try a player integrated via HomeAssistant, though that will be later today again.

Leave this with me, I will do some more testing and make the reporting more robust.
Also marking played/unplayed us currently broken in the frontend, I need to fix that.

[marcelveldt]

Let's merge this one as-is now so people can start testing it in the beta cycle.
The multipart handling can then be added later in a small follow-up PR.

[marcelveldt]

Excellent work @fmunkes !