Feel free to use it as you please. Consider donating if you want to support further development.

SONOS HTTP API

** Beta is no more, master is up to date with the beta now! **

This application requires node 4.0.0 or higher!

This should now work on Node 6+, please let me know if you have issues

A simple http based API for controlling your Sonos system.

There is a simple sandbox at /docs (incomplete atm)

USAGE

Start by fixing your dependencies. Invoke the following command:

npm install --production

This will download the necessary dependencies if possible.

start the server by running

npm start

Now you can control your system by invoking the following commands:

http://localhost:5005/zones
http://localhost:5005/lockvolumes
http://localhost:5005/unlockvolumes
http://localhost:5005/pauseall[/{timeout in minutes}]
http://localhost:5005/resumeall[/{timeout in minutes}]
http://localhost:5005/preset/{JSON preset}
http://localhost:5005/preset/{predefined preset name}
http://localhost:5005/reindex
http://localhost:5005/{room name}/sleep/{timeout in seconds or "off"}
http://localhost:5005/{room name}/sleep/{timeout in seconds or "off"}
http://localhost:5005/{room name}/{action}[/{parameter}]

Example:

http://localhost:5005/living room/volume/15 (will set volume for room Living Room to 15%)

http://localhost:5005/living room/volume/+1 (will increase volume by 1%)

http://localhost:5005/living room/next (will skip to the next track on living room, unless it's not a coordinator)

http://localhost:5005/living room/pause (will pause the living room)

http://localhost:5005/living room/favorite/mysuperplaylist (will replace queue with the favorite called "mysuperplaylist")

http://localhost:5005/living room/repeat/on (will turn on repeat mode for group)

The actions supported as of today:

• play
• pause
• playpause (toggles playing state)
• volume (parameter is absolute or relative volume. Prefix +/- indicates relative volume)
• groupVolume (parameter is absolute or relative volume. Prefix +/- indicates relative volume)
• mute / unmute
• groupMute / groupUnmute
• togglemute (toggles mute state)
• trackseek (parameter is queue index)
• timeseek (parameter is in seconds, 60 for 1:00, 120 for 2:00 etc)
• next
• previous
• state (will return a json-representation of the current state of player)
• favorite
• favorites (with optional "detailed" parameter)
• playlist
• lockvolumes / unlockvolumes (experimental, will enforce the volume that was selected when locking!)
• repeat (on/off)
• shuffle (on/off)
• crossfade (on/off)
• pauseall (with optional timeout in minutes)
• resumeall (will resume the ones that was pause on the pauseall call. Useful for doorbell, phone calls, etc. Optional timeout)
• say
• sayall
• queue
• clearqueue
• sleep (values in seconds)
• linein (only analog linein, not PLAYBAR yet)
• clip (announce custom mp3 clip)
• clipall
• join / leave (Grouping actions)
• sub (on/off/gain/crossover/polarity) See SUB section for more info
• nightmode (on/off, PLAYBAR only)
• speechenhancement (on/off, PLAYBAR only)

State

Example of a state json:

{
  "currentTrack":{
    "artist":"College",
    "title":"Teenage Color - Anoraak Remix",
    "album":"Nightdrive With You",
    "albumArtURI":"/getaa?s=1&u=x-sonos-spotify%3aspotify%253atrack%253a3DjBDQs8ebkxMBo2V8V3SH%3fsid%3d9%26flags%3d32",
    "duration":347,
    "uri":"x-sonos-spotify:spotify%3atrack%3a3DjBDQs8ebkxMBo2V8V3SH?sid=9&flags=32"
  },
  "nextTrack":{
    "artist":"Blacknuss",
    "title":"Thinking of You",
    "album":"3",
    "albumArtURI":"/getaa?s=1&u=x-sonos-spotify%3aspotify%253atrack%253a4U93TIa0X6jGQrTBGTkChH%3fsid%3d9%26flags%3d32",
    "duration":235,
    "uri":"x-sonos-spotify:spotify%3atrack%3a4U93TIa0X6jGQrTBGTkChH?sid=9&flags=32"
  },
  "volume":18,
  "mute":false,
  "trackNo":161,
  "elapsedTime":200,
  "elapsedTimeFormatted":"03:20",
  "zoneState":"PAUSED_PLAYBACK",
  "playerState":"PLAYING",
  "zonePlayMode":{
    "shuffle":true,
    "repeat":false,
    "crossfade":false
  }
}

Queue

Obtain the current queue list from a specified player. The request will accept: - limit (optional) - offset (optional, requires limit) - detailed flag (optional, include uri in response)

    http://localhost:5005/living room/queue
    http://localhost:5005/living room/queue/10 (only return top 10)
    http://localhost:5005/living room/queue/10/10 (return result 11-20)
    http://localhost:5005/living room/queue/detailed
    http://localhost:5005/living room/queue/10/detailed

Example queue response:

[
    {
      "albumArtURI": "/getaa?s=1&u=x-sonos-spotify%3aspotify%253atrack%253a0AvV49z4EPz5ocYN7eKGAK%3fsid%3d9%26flags%3d8224%26sn%3d3",
      "title": "No Diggity",
      "artist": "Blackstreet",
      "album": "Another Level"
    },
    {
      "albumArtURI": "/getaa?s=1&u=x-sonos-spotify%3aspotify%253atrack%253a5OQGeJ1ceykovrykZsGhqL%3fsid%3d9%26flags%3d8224%26sn%3d3",
      "title": "Breathless",
      "artist": "The Corrs",
      "album": "In Blue"
    }
]

Preset

A preset is a predefined grouping of players with predefined volumes, that will start playing whatever is in the coordinators queue.

Example preset (state and uri are optional):

{
  "players": [
    { "roomName": "room1", "volume": 15},
    {"roomName": "room2", "volume": 25}
  ],
  "state": "stopped",
  "favorite": "my favorite name",
  "uri": "x-rincon-stream:RINCON_0000000000001400",
  "playMode": {
    "shuffle": true
  },
  "pauseOthers": true
  "sleep": 600
}

The first player listed in the example, "room1", will become the coordinator. It will loose it's queue when ungrouped but eventually that will be fixed in the future. Playmode defines the three options "shuffle", "repeat", "crossfade" similar to the state Favorite will have precedence over a uri. pauseOthers will pause all zones before applying the preset, effectively muting your system. sleep is an optional value that enables the sleep timer and is defined in total seconds (600 = 10 minutes).

presets.json (deprecated, use preset files instead)

You can create a file with pre made presets, called presets.json. It will be loaded upon start, any changes requires a restart of the server.

Example content:

{
  "all": {
    "playMode": {
      "shuffle": true
    },
    "players": [
      {
        "roomName": "Bathroom",
        "volume": 10
      },
      {
        "roomName": "Kitchen",
        "volume": 10
      },
      {
        "roomName": "Office",
        "volume": 10
      },
      {
        "roomName": "Bedroom",
        "volume": 10
      },
      {
        "roomName": "TV Room",
        "volume": 15
      }
    ],
    "pauseOthers": true
  },
  "tv": {
    "players": [
      {
        "roomName": "TV Room",
        "volume": 20
      }
    ],
    "pauseOthers": true,
    "uri": "x-rincon-stream:RINCON_000XXXXXXXXXX01400"
  }
}

In the example, there is one preset called all, which you can apply by invoking:

http://localhost:5005/preset/all

presets folder

You can create a preset files in the presets folder with pre made presets. It will be loaded upon start, any changes made to files in this folder (addition, removal, modification) will trigger a reload of your presets. The name of the file (xxxxxx.json) will become the name of the preset. It will be parsed as JSON5, to be more forgiving of typos. See http://json5.org/ for more info.

Example content:

{
  "players": [
    {
      "roomName": "Bathroom",
      "volume": 10
    },
    {
      "roomName": "Kitchen",
      "volume": 10
    },
    {
      "roomName": "Office",
      "volume": 10
    },
    {
      "roomName": "Bedroom",
      "volume": 10
    },
    {
      "roomName": "TV Room",
      "volume": 15
    }
  ],
  "playMode": {
    "shuffle": true,
    "repeat": "all",
    "crossfade": false
  },
  "pauseOthers": false,
  "favorite": "My example favorite"
}

There is an example.json bundled with this repo. The name of the file will become the name of the preset.

settings.json

If you want to change default settings, you can create a settings.json file and put in the root folder. This will be parsed as JSON5, to be more forgiving. See http://json5.org/ for more info.

Available options are:

• port: change the listening port
• https: use https which requires a key and certificate or pfx file
• auth: require basic auth credentials which requires a username and password
• announceVolume: the percentual volume use when invoking say/sayall without any volume parameter
• presetDir: absolute path to look for presets (folder must exist!)

Example:

    {
      "voicerss": "Your api key for TTS with voicerss",
      "microsoft": {
        "key": "Your api for Bing speech API",
        "name": "ZiraRUS"
      },
      "port": 5005,
      "securePort": 5006,
      "https": {
        "key": "/path/to/key.pem",
        "cert" : "/path/to/cert.pem"

        //... for pfx (alternative configuration)
        "pfx": "/path/to/pfx.pfx",
        "passphrase": "your-passphrase-if-applicable"
      },
      "auth": {
        "username": "admin",
        "password": "password"
      },
      "announceVolume": 40,
      "pandora": {
        "username": "your-pandora-account-email-address",
        "password": "your-pandora-password"
      },
      "spotify": {
        "clientId": "your-spotify-application-clientId",
        "clientSecret": "your-spotify-application-clientSecret"
      },
      "library": {
        "randomQueueLimit": 50
      }
    }

Override as it suits you.

Note for Spotify users!

To use Spotify, go to https://developer.spotify.com/my-applications/#!/applications/create and create a Spotify application to get your client keys. You can name it Sonos or anything else and you don't have to change any values. Use the Client ID and the Client Secret values in the settings.json file as indicated above.

Favorites

It now has support for starting favorites. Simply invoke:

http://localhost:5005/living room/favorite/[favorite name]

and it will replace the queue with that favorite. Bear in mind that favorites may share name, which might give unpredictable behavior at the moment.

Playlist

Playing a Sonos playlist is now supported. Invoke the following:

http://localhost:5005/living room/playlist/[playlist name]

and it will replace the queue with the playlist and starts playing.

Say (TTS support)

Experimental support for TTS. Today the following providers are available:

• voicerss
• Microsoft Cognitive Services (Bing Text to Speech API)
• AWS Polly
• Google (default)

It will use the one you configure in settings.json. If you define settings for multiple TTS services, it will not be guaranteed which one it will choose!

VoiceRSS

This REQUIRES a registered API key from voiceRSS! See http://www.voicerss.org/ for info.

You need to add this to a file called settings.json (create if it doesn't exist), like this:

{
  "voicerss": "f5e77e1d42063175b9219866129189a3"
}

Replace the code above (it is just made up) with the api-key you've got after registering.

Action is:

/[Room name]/say/[phrase][/[language_code]][/[announce volume]]
/sayall/[phrase][/[language_code]][/[announce volume]]

Example:

/Office/say/Hello, dinner is ready
/Office/say/Hej, maten är klar/sv-se
/sayall/Hello, dinner is ready
/Office/say/Hello, dinner is ready/90
/Office/say/Hej, maten är klar/sv-se/90

language code needs to be before volume if specified.

Sayall will group all players, set 40% volume (by default) and then try and restore everything as the way it where. Please try it out, it will probably contain glitches but please report detailed descriptions on what the problem is (starting state, error that occurs, and the final state of your system).

The supported language codes are:

Language code	Language
ca-es	Catalan
zh-cn	Chinese (China)
zh-hk	Chinese (Hong Kong)
zh-tw	Chinese (Taiwan)
da-dk	Danish
nl-nl	Dutch
en-au	English (Australia)
en-ca	English (Canada)
en-gb	English (Great Britain)
en-in	English (India)
en-us	English (United States)
fi-fi	Finnish
fr-ca	French (Canada)
fr-fr	French (France)
de-de	German
it-it	Italian
ja-jp	Japanese
ko-kr	Korean
nb-no	Norwegian
pl-pl	Polish
pt-br	Portuguese (Brazil)
pt-pt	Portuguese (Portugal)
ru-ru	Russian
es-mx	Spanish (Mexico)
es-es	Spanish (Spain)
sv-se	Swedish (Sweden)

Microsoft

This one also requires a registered api key. You can sign up for free here: https://www.microsoft.com/cognitive-services/en-US/subscriptions?mode=NewTrials and select "Bing Speech - Preview".

The following configuration is available (the entered values except key are default, and may be omitted):

    {
      "microsoft": {
        "key": "Your api for Bing speech API",
        "name": "ZiraRUS"
      }
    }

You change language by specifying a voice name correlating to the desired language. Name should be specified according to this list: https://www.microsoft.com/cognitive-services/en-us/speech-api/documentation/API-Reference-REST/BingVoiceOutput#SupLocales where name is the right most part of the voice font name (without optional Apollo suffix). Example:

Microsoft Server Speech Text to Speech Voice (ar-EG, Hoda) name should be specified as Hoda

Microsoft Server Speech Text to Speech Voice (de-DE, Stefan, Apollo) name should be specified as Stefan

Microsoft Server Speech Text to Speech Voice (en-US, BenjaminRUS) name should be specified as BenjaminRUS

Action is:

/[Room name]/say/[phrase][/[name]][/[announce