Sonos api

[Gravy]

Hi,

I am interested in integrating the SONOS system with Windows Phone 7. Does SONOS provide an API or any such technical documentation on how I could communicate with it?

[ratty]

Sonos provides no API documentation, but the players are essentially UPnP MediaRenderers plus proprietary extensions. Poke around with Intel Device Spy and you can get a feel for what's going on. Dig in the Unsupported Area forum to see what others have been doing by way of third party controllers.

[kimaldis]

MODERATOR NOTE:
This and the following posts were split from this thread as they were off topic

Originally Posted by Master_J

We already have some kind of API called UPnP.
You can do a lot of things with that; including your examples.
Take a look at this project:
http://forums.sonos.com/showthread.php?t=16485

UPnP isn't an API, it's a set of protocols. Not the same thing at all. And there's no Sonos documentation either, unless you count a UPnP sniffer. Which I don't, so my request stands. An API, properly documented please.

And that project is mostly about Arduino, which is hardware.

[Majik]

Originally Posted by kimaldis

UPnP isn't an API, it's a set of protocols. Not the same thing at all. And there's no Sonos documentation either, unless you count a UPnP sniffer. Which I don't, so my request stands. An API, properly documented please.

Opinion is nice, but on the other hand some facts:

1. UPnP is just as much an API as any other network controllable protocol. The only other possible definition would be a software toolkit which realises those protocols. This would be platform specific and would also be called an "SDK". There is a choice of standard UPnP API/SDKs available for a range of platforms and which can be used to develop Sonos control applications. Presumably these come with documentation.

2. 99% of the core functionality of Sonos that is controlled by UPnP is documented within the UPnP AV specifications. Anyone who claims "it's not documented" simply hasn't been bothered to do any research and check these specifications (or has a very specific and non-standard view of what API documentation constitutes).

3. The whole of the Sonos UPnP control capability is documented in the form of Device control specifications that can be extracted from the Zoneplayers themselves. Anyone with an understanding of UPnP would know this. This documentation is readily available in a more friendly form using a tool like Device Spy. (For the avoidance of doubt, Device Spy is not a sniffer, it is a UPnP developers tool). These document the individual Actions, States, and what variables are used for each Action.

4. It is correct that there are no Sonos specific "how-to" or tutorials. On the other hand, most of the Actions are pretty obvious and the majority are generic UPnP AV which are described in the UPnP AV specifications for example:

2.4.9. Play
Start playing the resource of the specified instance, at the specified speed, starting at the current position, according to the current play mode. Keep playing until the resource ends or the transport state is changed via actions Stop or Pause. The device should do a ‘best effort’ to match the specified play speed. Actually supported speeds can be retrieved from the AllowedValueList of the TransportPlaySpeed state variable in the AVTransport service description.
If no AVTransportURI is set, the resource being played is device-dependent.

2.4.9.1. Arguments

Argument Direction relatedStateVariable
InstanceID IN A_ARG_TYPE_InstanceID
Speed IN TransportPlaySpeed
(continues for another page so I won't paste it all)

5. No other documentation is required for a developer to write Sonos control apps. When the Sonos UPnP capability was first revealed, a hobby developer created a reasonably complete Sonos .Net library within a few days. He required no additional documentation and didn't even have to ask any questions about how things worked. Another hobby developer created a Web controller within a few weeks of this, again with no documentation or cries for help.

6. There IS a considerable learning curve associated with learning UPnP (and in learning whichever UPnP library/toolkit you decide to use). Once you've been through this learning curve and can develop simple UPnP programs, adapting this to Sonos is trivial and obvious.

Finally there are numerous threads on this forum discussing this. This isn't the right place for specific discussions so I suggest if you wish to discuss this further you move to one of the existing threads.

Cheers,

Keith

[ianmacd]

Originally Posted by Majik

Opinion is nice, but on the other hand some facts:

Actually, I see no factual inaccuracies in the post to which you replied. UPnP isn't an API, it is a set of protocols, and there isn't any Sonos documentation of it.

To claim otherwise requires redefinition of the term API to encompass any technology that allows a degree of device control, and broadening of the scope of the word documentation beyond the common interpretation.

At that point, you're dealing in opinion, not facts.

1. UPnP is just as much an API as any other network controllable protocol.

I'll grant you that it comes closer to being an API than other protocols, but it still falls a long way short.

For the sake of argument, though, let's call UPnP an API, so that we don't get hung up on semantics.

Now, we can say that UPnP is an extremely limited API, because it allows control points to be constructed, but provides access to none of the other things one might hope for in a Sonos API.

2. 99% of the core functionality of Sonos that is controlled by UPnP is documented within the UPnP AV specifications.

That's nice, but not very helpful if you're trying to do something beyond the very narrow scope of UPnP.

For example, I can't use UPnP to display the composer, genre, bit rate, codec or file path on the controller while the song is playing.

I also can't use UPnP to hook in a plug-in that implements a codec not natively supported by the Sonos.

These are just two of the things that a full API might expose and make possible, things that are not suited to or even possible with UPnP.

I recognise that it's expedient to equate UPnP with a proper API, because it allows the dismissal of those who call for an API as inexpert at best, fools at worst. After all, what they want already exists.

The truth of the matter is that many users (myself included) would like to see a real API made available, so that the user community can implement the features that Sonos either can't or won't.

The rest of your posting further expounds on UPnP, continuing to ignore the fact that the person to whom you're replying indicated that he was aware of its existence, but still desired a proper API.

[Majik]

Originally Posted by ianmacd

Actually, I see no factual inaccuracies in the post to which you replied. UPnP isn't an API, it is a set of protocols, and there isn't any Sonos documentation of it.

This part, we agree, is a matter of semantics. "Network APIs" are a common thing in IT. For instance, Google provide a rich set of APIs into their cloud services. All of these are exposed through a set of network protocols, just like UPnP.

An API in the very specific way you seem to be describing it implies a local set of procedure calls. This can either be provided by the native Operating System or extensions of it, or by some kind of add-on library.

As I said, such a library will be highly platform specific.

The OP said:

Originally Posted by kimaldis

I'd like to see, for example, widgets in my menu bar that do simple stuff that takes an age to get to through the interface: volume control, change to radio 4, mute the kitchen, bring back the kitchen.

This is certainly stuff that you could do using the Sonos "API" as I describe it

Build this stuff for me if you like but if I had an API I could drive through perl, python, applescript, php and html .... I could do it myself. You'd start to see it appear on the street too.

The implication is multi-language, multi-platform support. That's not something that can be provided by a single software toolkit or library. The only sort of "API" that can support that is one that is independent of the OS, platform, and language. In other words, something like UPnP.

And UPnP can support what the OP is asking for (certainly for Perl & Python as well as C/C++, Java and .Net). If, for instance, you want an "API" to control Sonos on Windows CE, Microsoft make one for you.

So by the requirement given by the OP. UPnP, in conjunction with an appropriate platform/language specific library (of which there are many to choose from), is fully capable of the sorts of capabilities he is after.

I'll grant you that it comes closer to being an API than other protocols, but it still falls a long way short.

Now, we can say that UPnP is an extremely limited API, because it allows control points to be constructed, but provides access to none of the other things one might hope for in a Sonos API.

That's a matter of opinion. As far as I want everything I need to do is available from the Sonos UPnP capability. From the description of what the OP wants to do it would meet his needs too.

What you are after is completely different.

For example, I can't use UPnP to display the composer, genre, bit rate, codec or file path on the controller while the song is playing.

I also can't use UPnP to hook in a plug-in that implements a codec not natively supported by the Sonos.

These are just two of the things that a full API might expose and make possible, things that are not suited to or even possible with UPnP.

Firstly there is nothing in the definition of "API" that means that any of these capabilities must be exposed.

This is your personal and unique view of what "a full API" means. It doesn't apply outside of your head.

Just as you previously tried to redefine "documentation" as something you would personally read in bed, and anything outside of that, by your definition, wasn't documentation.

Well, I have news for you: the rest of the world and (especially) the Engineering/IT business do not share your definitions.

What Sonos provide via UPnP is a fully-functional capability (whether you call it an API or not) and it fit for purpose. The words you use "full", "proper" and "real" are weasel words. They have no meaning. They are only there to try to force a point. That point hasn't been made because it's not based on reality.

The UPnP capability provided by Sonos is "full", it is "proper" and it is "real".

I recognise that it's expedient to equate UPnP with a proper API, because it allows the dismissal of those who call for an API as inexpert at best, fools at worst. After all, what they want already exists.

Firstly I never called anyone anything like inexpert or a fool. Once again you are assigning statements to me which are not true. Secondly criticism of the OP's stated opinion is certainly expedient in the case where the capabilities the person that dismissed UPnP wanted are actually fully possible with UPnP. It's expedient in the case where the OPs view was wrong.

The rest of your posting further expounds on UPnP, continuing to ignore the fact that the person to whom you're replying indicated that he was aware of its existence, but still desired a proper API.

Being aware of it, and actually understanding it are two completely different things. Certainly all of the examples they gave of applications they would like to see are possible using the UPnP capability, but they seem to have incorrectly decided that isn't the case.

The trouble is it seems the OP dismissed UPnP out of hand without exploring it. If they are serious about doing some of the developments then I would be happy to point them in the right direction, but they have to open their mind to the possibility their original assessment may have been wrong.

The truth of the matter is that many users (myself included) would like to see a real API made available, so that the user community can implement the features that Sonos either can't or won't.

Secondly, what you describe is not an API. It's so far away from being "an API" that I find it hard to fathom you can confuse the two. If anything, it's a development platform.

What you are asking for is for Sonos to open the hardware and software platform up to third-party developers. To allow others to log into the Zoneplayers and to execute their own code on it. To create some kind of "plugin" capability to support modular swapping in/out of core pieces of code. Some of this involves APIs, naturally, but what your asking for is a whole lot more than an API.

The OP wants an API to be able to use Sonos. You seem to want some kind of hackers toolkit to allow you to extend the platform.

To assign this as the definition of "a full/real/proper API" is incorrect and misleading.

Cheers,

Keith

[buzz]

I think that a number of individuals were seeking a formal document that offers sample code and discussions. This is what they are calling the "API".

To these individuals, once you learn about UPnP, turn on a packet sniffer and harvest as many examples as you need. While this might not seem like as much fun as throwing a few sample code strings at your favorite scripting language, the real chore is crafting your user interface, not executing commands and extracting data.

[ianmacd]

Originally Posted by Majik

Firstly there is nothing in the definition of "API" that means that any of these capabilities must be exposed.

That's why I wrote "things that a full API might expose".

APIs often allow the customisation, manipulation and extension of core functionality

This is your personal and unique view of what "a full API" means. It doesn't apply outside of your head.

Since you misread me and thought I had written that an API must include the capabilities I listed, I'll assume you'll now concede that I don't have a "personal and unique view" of what a comprehensive API should include. Those were merely examples.

Well, I have news for you: the world and the Engineering/IT business doesn't share your definitions.

Funny, then, that IT and software engineering should be the industries I've made my living in for the past 20-something years, in which time I have authored several APIs, written for third-party APIs, etc.

You'd think my complete failure to understand the terminology of the industry that put food on my table for so long would have come to light before I started to post in the Sonos forums.

Luckily for me, the people I worked with were similarly deluded and shared my misconceptions. How unfortunate for them that they continue to operate in ignorance, whilst I have now been shown the light.

What Sonos provide via UPnP is a fully-functional capability (whether you call it an API or not) and it fit for purpose.

Fit for a purpose, yes, but not all purposes.

To assign this as the definition of "a full/real/proper API" is incorrect and misleading.

And the people incarcerated in lunatic asylums think that everyone on the outside is crazy.

I will finish by urging people who aren't knowledgeable on the subject to do their own research into what commonly constitutes an API. The Wikipedia page makes a good starting point.

Then they can decide for themselves who speaks from a purely technical standpoint and who is kidding himself and attempting to kid others.

[Majik]

Originally Posted by ianmacd

That's why I wrote "things that a full API might expose".

APIs often allow the customisation, manipulation and extension of core functionality

That's one potential use of an API. Your implicit suggestion was that unless an API did this, it's not worthy of being considered complete.

Fit for a purpose, yes, but not all purposes.

Of course not. No single API on this entire planet is can be said to be fit for every possible purpose.

Your criticism of what Sonos supports seems to hinge on it not meeting this impossible ideal.

Since you misread me and thought I had written that an API must include the capabilities I listed, I'll assume you'll now concede that I don't have a "personal and unique view" of what a comprehensive API should include. Those were merely examples.

Examples, it seems, of why the Sonos control API should be discounted from being called "an API", along with words like "full", "proper" and "real", you seemed to imply that Sonos was none of these because it didn't meet your particular standards.

Now you are saying this is not what these examples were to illustrate.

I apologize if I misunderstood, but I do wonder what all of those words you wrote were actually for. The meaning appeared fairly obvious to me, but now you are saying that the obvious meaning of your words, that of claiming the Sonos Control API to be "incomplete", "unreal" or "not proper" in other words, not an API at all, due to lack of specific functionality... you're claiming that this is not the meaning enshrined in your post.

Are you telling me you wrote all of those lines for no reason at all? Maybe it was just to make the post nice and long

I will finish by urging people who aren't knowledgeable on the subject to do their own research into what commonly constitutes an API. The Wikipedia page makes a good starting point.

Then they can decide for themselves who speaks from a purely technical standpoint and who is kidding himself and attempting to kid others.

"An application programming interface (API) is a particular set of rules and specifications that a software program can follow to access and make use of the services and resources provided by another particular software program that implements that API"

Sounds like what UPnP AV does to Sonos to me. There's some software running on the zoneplayers which controls them. UPnP provides a set of rules and specifications that, if your software follows them, allows you to make use of the software and resources of the zoneplayer.

I also note the Wikipedia article references "Web Service" and "Corba", which are both a frameworks of protocols for remotely accessing capabilities across a network, very similar to UPnP (in fact UPnP uses Web Services and some other concepts which originated in Corba).

All of these are well defined Interfaces which support Programming to develop Applications.

From the linked Web Service Wikipedia page:

"A web service is a method of communication between two electronic devices."

"...Web API is typically a defined set of Hypertext Transfer Protocol (HTTP) request messages along with a definition of the structure of response messages, usually expressed in an Extensible Markup Language (XML) or JavaScript Object Notation (JSON) format."

That's remarkably similar to UPnP!

Of course, all of this is semantic BS and is a diversion.


Let's get back to the original thread:

• The OP wanted some programs on his desktop PC to do things like control volume, Zoneplayer transport or change music sources
• The OP requested an API capable of doing this
• The UPnP capability of Sonos supports these capabilities
• The capability the OP asked for exists already

And, once again, you jump in to criticise me for pointing this out. This is becoming a habit!

Cheers,

Keith

[BarryM]

Originally Posted by buzz

I think that a number of individuals were seeking a formal document http://forums.sonos.com/images/editor/separator.gifthat offers sample code and discussions. This is what they are calling the "API".

To these individuals, once you learn about UPnP, turn on a packet sniffer and harvest as many examples as you need. While this might seem like as much fun as throwing a few sample code strings at your favorite scripting language, the real chore is crafting your user interface, not executing commands and extracting data.

I can't really catch the drift of what Buzz is saying here.

I may be just echoing his thought, I am not real sure.

The community generated ecosystem of apps, plugins, scripts, etc within the Sonos environment is sparse. Why is this? It seems strange if you consider that there is probably a fairly large crossover between geeky people with programming interest, and with music lovers. I can recognise a number of programming types who post here just by their language.

I am not qualified to enter any pi##ing contest as to whether UPnp is an api or not, or whether it is fit for use, as I haven't looked into what UPnp is, and what it offers yet. This is my next planned project, as I am about done with ripping now.

What I do see is that Sonos provide no materials to encourage or support budding developers.

Compare this to the situation with some of the other vendors in my music listening arena:
Last.fm: http://www.last.fm/api
NAS: http://www.readynas.com/?p=346
MediaMonkey: http://www.mediamonkey.com/wiki/index.php/Scripting

In my view Sonos, and the community of its customers, would benefit from a healthy community development. Here is my example; I am sure that other people have examples of their own.

Sonos seem to be unable, or unwilling, to extend their music browsing options due to whatever reason. The assumed reason is that the early zone players have insufficient memory, and that Sonos want a seamless common experience across their whole range. Fine, I can understand that, but it is kind of stuck in 1995 isn't it? Other products have moved on: all products in fact, iTunes, MediaMonkey, Winamp, ... you name it ... it has moved forwards.

I am not about to ditch Sonos, as the first requirement is that the music just goes, without interruption, whenever I turn it on, and Sonos currently own this space. I still want better browsing facilities. I often locate an unplayed album via MediaMonkey, because it knows my Sonos play counts, and it also knows which is my recently purchased music, and it can list an artist's albums in date released sequence. Having chosen an album, I then have to relocate it with a Sonos controller to add it onto a queue.

Why isn't it in Sonos' interest to encourage people to build plugins so that albums could be dropped into a Sonos queue from some of these full featured browsers? The "top 5 things I want Sonos to do" thread is still going strong. A large proportion (I think that it was over 20% last time I looked) ask for improvement to the browsing facilities.

I know that Majik thinks that Sonos have no self interest in generating and supporting community developments. We have had this conversation before (http://forums.sonos.com/showthread.p...160#post115160). I still don't agree.

Take Last.fm as an example. Majik said that I was disingenuous by comparing Sonos to last.fm. I asked why, but no answer. Here is the Last.fm team: http://www.last.fm/about/team ... So Sonos don't have 62 people?

He said that Sonos had tried to encourage community development in the past, and it had been unsuccessful. Well that was then. With the advent of the S5 there must be an order of magnitude or more of people in the community now.

The difference between the companies mentioned above, who do something to encourage development, and Sonos is like the difference between light and day. Here are the 200+ "Extras built by the community to extend your Last.fm experience" http://build.last.fm/ The community, and Last.fm, are expanded and enriched by this activity. The same thing at ReadyNas (http://www.readynas.com/?cat=75) and MediaMonkey (http://www.mediamonkey.com/addons/general/) ... Couldn't Sonos do with some of this too? I think that is a chicken and egg kind of situation.