Node-roon-api-transport update to version 2.0


(Ben) #1

We just pushed changes to the node-roon-api and node-roon-api-transport libraries to update them to work with version 2 of the transport API service.

Version 2 adds these capabilities:

  • Support for subscribing to the play queue for a specific zone
  • Support for playing from specific points in the play queue for that zone
  • An optimization to not send a full zone update every time the seek position changes

Existing extensions that use versions less than 1.1 of the node-roon-api-transport library should continue to work without any changes. Using version 1.1 will mean that the event callback provided to subscribe_zones will also need to handle Changed messages with a msg.zones_seek_changed which is an array of objects like this:

{
    zone_id: zone_id_as_string
    seek_position: optional number representing new seek position in seconds
    queue_time_remaining: optional number representing new remaining queue time in seconds
}

See line 365 and onwards of the node-roon-api-transport library for an example of how this might be handled: https://github.com/RoonLabs/node-roon-api-transport

Let me know if you have any questions or encounter any problems with this, I’ll see what I can do to help.


Command line usage and/or REST API?
How to implement queue management?
Roon Extension: Roon Web Controller v1.2.0
(JohnV) #2

What should an API end user do now, if anything?


(Ben) #4

Right now, my advice for end users is to mostly ignore this update. If you have extensions that you are using, and they work now, just don’t touch them until you hear something from the extension authors. New extension installs should generally work as well, but it might be possible for things to be broken somehow there.


(Jan Koudijs) #5

Hi @ben,

Good to see that the Roon API hasn’t been forgotten!

Considering the jump to version 2 and the breaking change it introduces (the seek position optimization), I want to suggest to add version tags to the 1.0 and 1.1 version of the transport library. This will make it easier for an extension developer to force the use of a specific library version by appending the version in the dependencies section of the package.json file:

"node-roon-api-transport": "github:roonlabs/node-roon-api-transport#v1.0"

The only way I know to do this for the current situation is by referring to a specific commit:

"node-roon-api-transport": "github:roonlabs/node-roon-api-transport#c6c229c"

You might also consider the semantic versioning scheme as suggested by npm. This could add the flexibility to use the latest compatible version of an API.


(Ben) #6

I thought we had the a version tag in the package.json file here: https://github.com/RoonLabs/node-roon-api-transport/blob/master/package.json

Is there something else I need to do to specify that version correctly?

I could be convinced that the new transport library should be version 2.0 instead of 1.1, mirroring the Roon core side API version number sounds reasonable to me.


(Jan Koudijs) #7

As I understood it, the version specified in the package.json file can only be used in a dependency specification if the package is published (i.e. can be found in the npm registry).

"node-roon-api-transport": "1.0"

Git dependencies are a bit different and refer to a git tag.

That would be my preference but the choice is yours.


(Ben) #8

I believe I understand now, I made these changes to the github repo. We will make a best-effort attempt to match semantic versioning, although I can’t quite promise we will always get it right.

Let me know if this looks correct to you know, I am quite far from an npm/github expert.


(Jan Koudijs) #9

Thanks @ben, looks perfect to me!


(Mike Plugge) #10

Thanks @ben! Once I get home from dealing with a family situation, I will start playing with this. These changes should let me optimize a LOT of code on the Web Controller extension!


(Jan Koudijs) #11

I had a look at my extensions (see my profile description) and did not find anything that got broken by the update of the Roon API.

If you find an extension that has issues it is best to report this in the thread of the applicable extension.

One addition; After the update of an extension you might have to re-enable it because of the higher revision of the transport API.


(Jan Koudijs) #12

Hi @ben,

I ran into an issue with the queue_time_remaining field that got added in version 2 of the transport API. If an internet radio stream is playing then there is no clear indication that the remaining time is unknown/infinite:

"zones_seek_changed":[{"zone_id":"","queue_time_remaining":0,"seek_position":0}]
"zones_seek_changed":[{"zone_id":"","queue_time_remaining":-1,"seek_position":1}]
"zones_seek_changed":[{"zone_id":"","queue_time_remaining":-2,"seek_position":2}]
"zones_seek_changed":[{"zone_id":"","queue_time_remaining":-3,"seek_position":3}]

The remaining time is the seek position with a minus sign in front. It is also possible that both values are 0 if the radio stream has just been started.

This issue isn’t limited to the Roon API, also Roon itself reports negative remaining times of the queue when internet radio is playing:

image

Would it be possible to define a constant for an unknown/infinite remaing time (e.g. -1)?


(Ian William) #13

Looking forward to further functionality from the API. Am I missing the roadmap somewhere, or are we just posting change/feature requests here in the forum?


(Ian William) #14

Things I think would make the API more fun/functional:

√ Add current UI theme (light/dark) to zone.settings.
√ Expose the user’s LastFM auth token.
√ Send audio channel frequencies in transport api. (I.E. low, mid, high range frequencies).


(Adam Goodfellow) #15

If you mean a low rate data stream that could be used to render a real time FFT with a few bands even from in a web app - yes - that would be cool. :+1:

I was thinking about this the other day :slight_smile:


(Adam Goodfellow) #17

Hmmm - you could add an extension then to control lighting like Philips hue or even a DMX based club systems (I still have old lighting systems form my DJing days) :wink:


(Ian William) #20

I need some clarity on searching. The current api seems to be missing documentation for performing an advanced search.

Referencing:
https://roonlabs.github.io/node-roon-api/index.html

Ex.
Get results by genre and date range.
Get similar artists as X.
Get recently played.
Get artist bio.
Get album review.