You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Do you plan to implement in it full control of the media player ? as for now it's only basic control of the device with grouping/upgrouping but no way to browse medias avalaible in the blusound system and play them.
Not in the short term. My current focus is Home Assistant and supporting everything that integration needs. Browsing is not part of it.
Browsing seems to be the most complex part of the API. And there are a few differences depending on the service(e.g. TuneIn, Tidal,...). Do you have a specific service in mind?
I've been working on a lightweight media player that uses the BluOS Custom Integration (CI) API and have had some success with content browsing. Thanks to pyblu, I've also been able to control playback and (mostly) manage the Play Queue on my Bluesound device. Unfortunately, whilst I can control playback of songs already in the Play Queue, I haven't yet discovered how to add any new songs to the queue, a core function of a media player!
There's no pyblu.Player.add(), nor does the BluOS CI API describe an Add request. The expectation seems to be that a URL can be constructed from the player's IP Address and Port, appending the value of browsed playURL or autoplayURL attributes. I've tried calling pyblu.Player._get() supplying as path the (already encoded) playURL and autoplayURL attribute values, but the Play Queue remains unchanged. There's no HTTP error status. The request fails silently. I read that it's impossible to add DRM content to the Play Queue using the BluOS CI API. That, if correct, I might be able to understand, but it doesn't appear to allow local library/USB input tracks to be added either!
@LouisChrist, Am I missing something? Have you used pyblu to add songs to the Play Queue? If so, I'd appreciate any hints that could allow me to do the same. :)
(Incidentally, I've browsed the Music Assistant source code, hoping to gain inspiration, but found it a rather daunting experience.)
Regarding content browsing: I have been working on implementing content browsing in #83. It should work already, but I haven't tested it much. The one thing I haven't done yet are the "Context menus" provided by that API. But I think they are what you need for your usecase. Some items there have a "Play now", "Add next" and "Add last" action. They all use an undocumented route /Add.
Queue management itself is not yet implemented in this library. I did only implement what was needed for the home assistant integration, but I am open to adding those endpoints to the library if you are interested.
Thank you for directing me to your media_browsing branch. You're absolutely right about the context menus offering variations on an /Add theme. I should also mention that there are URLs with an /Add path in <item ... type='album'> (playURL attribute) and <item ... type='track'> (playURL and autoplayURL attributes) elements in /Browse responses. There's some potential for confusion, here, but I believe all of these play URLs are intended to add tracks to the Play Queue, not to provide a URL that will be passed into pyblu.Player.play_url().
Nevertheless, it's the code in the parse module's _browse_item() that led to my Eureka moment. Thank you so much for this. I see that you're decoding the percent-encoded URL in readiness for processing by pyblu.Player.play_url(). That came as a surprise to me because version 1.7 of the BluOS CI API gives an example, on page 16, of a /Play?url request featuring a percent-encoded URL! Still more significant, for me at least, is that I can now add songs to the Play Queue, having first decoded the URLs (obtained from playURL and autoplayURL attributes) and replaced any HTML entities. Marvellous!
In response to your kind offer, yes, please add the Queue Management endpoints when you have time available. Thanks! Will you need any help with testing? I'd be happy to assist.
I pushed a lot of changes to the PR. It has the queue management commands now(all that are documented) and i did some changes to the browse API.
Regarding play_url: I added some docs around that. play_url is primarily for selecting inputs and presets. But you can also use it for playing audio from external sources like a http server. That's the reason why play_url takes an unencoded url and does the url encoding internally.
The play_url and autoplay_url from the browse api have their own method now: execute_action. I also renamed them slightly to avoid confusion: play_action_url and autoplay_action_url.
It would be great if you could test the whole thing. Like try it out with your player and your use case. Fell free to comment directly in the PR if you find any problems or have any suggestions.
I've retrieved all menus/albums/tracks/context menus that I need for my media player using the pyblu media_browsing code. There are some additional response attributes that would be helpful, if they could please be included in BrowseItem:
duration (int)
isFavourite (bool)
tracks (int)
In my testing, I didn't encounter any category elements or either of the following response attributes:
parentKey (documented in BluOS CI API v1.7 on page 31)
service (undocumented)
I'll turn my attention, now, to queue management, working with the endpoints that you've recently added.
Can you give me examples for those fields? duration (int), isFavourite (bool), tracks (int) I cannot find them in the documentation and also not with my local player.
It's true that's these attributes aren't present for all services. There is no duration or isFavourite attribute for album elements retrieved from my local Library, but tracks is present, as is duration for track elements.
Why do I see tracks and (track) duration when you don't? I suspect that it may have something to do with the metadata embedded in the library's flac files. I noted, a few days ago, that certain of the local Library tracks have a text2 attribute. After looking into it, I concluded that the attribute appeared only in tracks whose metadata provided a track-level artist.
Here are BrowseItem and BrowseResult summaries of attribute usage from the three services available to me; 'Library', 'TIDAL' and 'USB':
Thanks. I appreciate all your work on this!AndrewOn Sep 13, 2026, at 7:48 AM, Louis Christ ***@***.***> wrote:
Closed #28 as completed via #83.
—Reply to this email directly, view it on GitHub, or unsubscribe.Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS and Android. Download it today!
You are receiving this because you commented.Message ID: ***@***.***>
Activity
LouisChrist commentedon Aug 28, 2024
Not in the short term. My current focus is Home Assistant and supporting everything that integration needs. Browsing is not part of it.
Browsing seems to be the most complex part of the API. And there are a few differences depending on the service(e.g. TuneIn, Tidal,...). Do you have a specific service in mind?
vincegre commentedon Aug 29, 2024
Thanks and no not any specific services but at least all the free ones avalaible in the Blusound would be awesome ;)
LouisChrist commentedon Aug 29, 2024
I will give it a try once i finished my remaining TODOs for the home assistant integration.
[-]Proper implementation of media player ?[/-][+]Implement media browsing[/+]weaveraf commentedon Jul 27, 2026
I've been working on a lightweight media player that uses the BluOS Custom Integration (CI) API and have had some success with content browsing. Thanks to pyblu, I've also been able to control playback and (mostly) manage the Play Queue on my Bluesound device. Unfortunately, whilst I can control playback of songs already in the Play Queue, I haven't yet discovered how to add any new songs to the queue, a core function of a media player!
There's no pyblu.Player.add(), nor does the BluOS CI API describe an Add request. The expectation seems to be that a URL can be constructed from the player's IP Address and Port, appending the value of browsed playURL or autoplayURL attributes. I've tried calling pyblu.Player._get() supplying as path the (already encoded) playURL and autoplayURL attribute values, but the Play Queue remains unchanged. There's no HTTP error status. The request fails silently. I read that it's impossible to add DRM content to the Play Queue using the BluOS CI API. That, if correct, I might be able to understand, but it doesn't appear to allow local library/USB input tracks to be added either!
@LouisChrist, Am I missing something? Have you used pyblu to add songs to the Play Queue? If so, I'd appreciate any hints that could allow me to do the same. :)
(Incidentally, I've browsed the Music Assistant source code, hoping to gain inspiration, but found it a rather daunting experience.)
LouisChrist commentedon Jul 28, 2026
Regarding content browsing: I have been working on implementing content browsing in #83. It should work already, but I haven't tested it much. The one thing I haven't done yet are the "Context menus" provided by that API. But I think they are what you need for your usecase. Some items there have a "Play now", "Add next" and "Add last" action. They all use an undocumented route
/Add.Queue management itself is not yet implemented in this library. I did only implement what was needed for the home assistant integration, but I am open to adding those endpoints to the library if you are interested.
weaveraf commentedon Jul 30, 2026
Thank you for directing me to your media_browsing branch. You're absolutely right about the context menus offering variations on an /Add theme. I should also mention that there are URLs with an /Add path in <item ... type='album'> (playURL attribute) and <item ... type='track'> (playURL and autoplayURL attributes) elements in /Browse responses. There's some potential for confusion, here, but I believe all of these play URLs are intended to add tracks to the Play Queue, not to provide a URL that will be passed into pyblu.Player.play_url().
Nevertheless, it's the code in the parse module's _browse_item() that led to my Eureka moment. Thank you so much for this. I see that you're decoding the percent-encoded URL in readiness for processing by pyblu.Player.play_url(). That came as a surprise to me because version 1.7 of the BluOS CI API gives an example, on page 16, of a /Play?url request featuring a percent-encoded URL! Still more significant, for me at least, is that I can now add songs to the Play Queue, having first decoded the URLs (obtained from playURL and autoplayURL attributes) and replaced any HTML entities. Marvellous!
In response to your kind offer, yes, please add the Queue Management endpoints when you have time available. Thanks! Will you need any help with testing? I'd be happy to assist.
LouisChrist commentedon Jul 30, 2026
I pushed a lot of changes to the PR. It has the queue management commands now(all that are documented) and i did some changes to the browse API.
Regarding
play_url: I added some docs around that.play_urlis primarily for selecting inputs and presets. But you can also use it for playing audio from external sources like a http server. That's the reason whyplay_urltakes an unencoded url and does the url encoding internally.The
play_urlandautoplay_urlfrom the browse api have their own method now:execute_action. I also renamed them slightly to avoid confusion:play_action_urlandautoplay_action_url.It would be great if you could test the whole thing. Like try it out with your player and your use case. Fell free to comment directly in the PR if you find any problems or have any suggestions.
weaveraf commentedon Aug 7, 2026
I've retrieved all menus/albums/tracks/context menus that I need for my media player using the pyblu media_browsing code. There are some additional response attributes that would be helpful, if they could please be included in BrowseItem:
In my testing, I didn't encounter any category elements or either of the following response attributes:
I'll turn my attention, now, to queue management, working with the endpoints that you've recently added.
LouisChrist commentedon Aug 7, 2026
Can you give me examples for those fields?
duration (int), isFavourite (bool), tracks (int)I cannot find them in the documentation and also not with my local player.weaveraf commentedon Aug 7, 2026
Sure! My examples are taken from browsing of the TIDAL service. First, here's an example of an album:
<item browseKey="Tidal:MG/Tidal-Album?albumid=15425468" contextMenuKey="Tidal:CM/Tidal-Album?album=Graceland&albumid=15425468&artist=Paul+Simon&artistid=6928&isFavourite=1" playURL="/Add?playnow=1&service=Tidal&albumid=15425468" text="Graceland" text2="Paul Simon" duration="2596" tracks="11" isFavourite="true" image="/Artwork?service=Tidal&albumcover=3d52624a-43d1-484a-b10e-9a414f0d94b3" type="album"/>
Note the duration, tracks and isFavourite response attributes.
Second, here's an example of a track:
<item contextMenuKey="Tidal:CM/Tidal-Song?albumid=15421938&artistid=6928&filename=Tidal%3A15421940&similarstationid=Tidal%3Aradio%3Aartist%2F6928&songid=Tidal%3A15421940&trackstationid=Tidal%3Aradio%3Atrack%2F15421940" playURL="/Add?playnow=1&file=Tidal%3A15421940" autoplayURL="/Add?service=Tidal&listindex=1&nextlist=1&where=last&cursor=last&playnow=1&albumid=15421938&service=Tidal" text="2. Graceland" duration="291" image="/Artwork?service=Tidal&songid=Tidal%3A15421940" type="track"/>
Note the duration response attribute.
It's true that's these attributes aren't present for all services. There is no duration or isFavourite attribute for album elements retrieved from my local Library, but tracks is present, as is duration for track elements.
Why do I see tracks and (track) duration when you don't? I suspect that it may have something to do with the metadata embedded in the library's flac files. I noted, a few days ago, that certain of the local Library tracks have a text2 attribute. After looking into it, I concluded that the attribute appeared only in tracks whose metadata provided a track-level artist.
Here are BrowseItem and BrowseResult summaries of attribute usage from the three services available to me; 'Library', 'TIDAL' and 'USB':
BrowseItem: {
"autoplayURL": 8948,
"browseKey": 841,
"contextMenuKey": 9716,
"duration": 9396,
"image": 9743,
"inputType": 6,
"isFavourite": 449,
"playURL": 9722,
"text": 9795,
"text2": 1062,
"tracks": 768,
"type": 9795
}
BrowseResult: {
"nextKey": 28,
"playURL": 787,
"searchKey": 829,
"serviceIcon": 829,
"serviceName": 829,
"type": 832
}
LouisChrist commentedon Aug 8, 2026
I added the 3 fields: duration (int), isFavourite (bool), tracks (int) 👍
weaveraf commentedon Sep 14, 2026
LouisChrist commentedon Sep 14, 2026
Had some hiccups with the release yesterday, but it version 2.2.0 is out now.