Skip to content

Using SoundTouch Server

Jump to bottom
CONNCTED edited this page Jan 29, 2016 · 21 revisions

Basics

After running the set-up guide to start the soundtouch server, your server will expose a web address to read and give instructions.

The ip address that should be used is the ip address of the machine running this server. The port is always 5006. E.g. http://127.0.0.1:5006/

The SoundTouch Server should run on the same network as all your SoundTouch devices.

When :deviceName is mentioned in a url, the name of the soundtouch should be used. This name can be retrieved by requesting '/device/list' and choose the soundtouch you want to control or approach. If the used device name cannot be found, you will get an error: {"message":"No Device found with name Office"}

Overview

SoundTouch Discovery

/device/list

This url will return a JSON object with the found soundtouch devices on your network. When unplugging one of your soundtouches, the device will not be in the list when making a new requests. Even the soundtouches that are powered off are returned. Per soundtouch, only the basic information is displayed.

[
   {
      "name": "Bathroom",
      "addresses": ["10.0.1.7"]
   },
   {
      "name": "Kitchen",
      "addresses": ["10.0.1.20"]
   }
]

/device/listAdvanced

This url will return a JSON object with the found soundtouch devices on your network. When unplugging one of your soundtouches, the device will not be in the list when making a new requests. Even the soundtouches that are powered off are returned. This advanced view will display all information known about the soundtouch.

[
  {
    "interfaceIndex":2,
    "type":{
      "name":"sound touch",
      "protocol":"tcp",
      "subtypes":[],   
      "fullyQualified":true
     }, 
     "replyDomain":"local.",
     "flags":2, 
     "name":"Bathroom",
     "networkInterface":"ethic", 
     "fullname":"Bathroom._soundtouch._tcp.local.", 
     "host":"001122334455.local.",
     "port":8090, 
     "rawTxtRecord":{
        "type":"Buffer", 
        "data":[00,11,22,33,44,55,66,77,88,99,00,11,22,33,44,55,66]
     },
     "txtRecord":{"MAC":"001122334455"},
     "addresses":["10.0.1.7"], 
     "ip":"10.0.1.7", 
     "mac_address":"001122334455", 
     "url":"http://10.0.1.7:8090", 
     "ws_url":"ws://10.0.1.7:8080"
   }
]

Getting information from your SoundTouch

/:deviceName/volume

This url will return a JSON object with the volume of that soundtouch.

{
   "volume":{
      "deviceID":"001122334455",
      "targetvolume":"40",
      "actualvolume":"40"
   }
}

/api/keys-list

This method will get all possible keys. These keys can be used in the '/:deviceName/key/:key' to replace the :key placeholder.

{
  "keys":{
    "PLAY":"PLAY", 
    "PAUSE":"PAUSE", 
    "PLAY_PAUSE":"PLAY_PAUSE", 
    "STOP":"STOP",
    "PREV_TRACK":"PREV_TRACK",
    "NEXT_TRACK":"NEXT_TRACK",
    "THUMBS_UP":"THUMBS_UP", 
    "THUMBS_DOWN":"THUMBS_DOWN",
    "BOOKMARK":"BOOKMARK",
    "POWER":"POWER",
    "MUTE":"MUTE",
    "VOLUME_UP":"VOLUME_UP",
    "VOLUME_DOWN":"VOLUME_DOWN", 
    "PRESET_1":"PRESET_1",
    "PRESET_2":"PRESET_2",
    "PRESET_3":"PRESET_3", 
    "PRESET_4":"PRESET_4",
    "PRESET_5":"PRESET_5",
    "PRESET_6":"PRESET_6", 
    "AUX_INPUT":"AUX_INPUT",
    "SHUFFLE_OFF":"SHUFFLE_OFF",
    "SHUFFLE_ON":"SHUFFLE_ON",
    "REPEAT_OFF":"REPEAT_OFF",
    "REPEAT_ONE":"REPEAT_ONE",
    "REPEAT_ALL":"REPEAT_ALL",
    "ADD_FAVORITE":"ADD_FAVORITE",
    "REMOVE_FAVORITE":"REMOVE_FAVORITE"
  }
}

/api/sources-list

This method will get all possible sources and not only the sources your SoundTouch can handle. These sources can be used to control your SoundTouch or when getting what's playing now, the playing source will be mentioned.

{
  "sources": {
    "SLAVE_SOURCE":"SLAVE_SOURCE",
    "INTERNET_RADIO":"INTERNET_RADIO",
    "PANDORA":"PANDORA",
    "AIRPLAY":"AIRPLAY",
    "STORED_MUSIC":"STORED_MUSIC",
    "AUX":"AUX",
    "OFF_SOURCE":"OFF_SOURCE",
    "CURRATED_RADIO":"CURRATED_RADIO",
    "STANDBY":"STANDBY",
    "UPDATE":"UPDATE",
    "DEEZER":"DEEZER",
    "SPOTIFY":"SPOTIFY",
    "IHEART":"IHEART"
  }
}

/:deviceName/nowPlaying

This method will indicate what's playing at this moment. The following example will be returned when the device is turned off.

{
  "nowPlaying":{
    "deviceID":"001122334455",
    "source":"STANDBY",
    "ContentItem":{
      "source":"STANDBY",
      "isPresetable":"true"
    }
  }
}

The next example is when the SoundTouch is playing an internet radio station.

{
  "nowPlaying":{
    "deviceID":"001122334455",
    "source":"INTERNET_RADIO",
    "ContentItem":{
      "source":"INTERNET_RADIO",
      "location":"4712",
      "sourceAccount":"",
      "isPresetable":"true",
      "itemName":"Studio Brussel"
    },
    "track":{},
    "artist":{},
    "album":{},
    "stationName":"Studio Brussel",
    "art":{
      "artImageStatus":"IMAGE_PRESENT",
      "$t":"http://logo.vtuner.net/007452/logo/logo-4712.jpg"
    },
    "playStatus":"PLAY_STATE",
    "description":"...Life is Music",
    "stationLocation":"Brussels Belgium"
  }
}

The 'source' field in the JSON response is one of the sources that can be found when calling the '/api/sources-list' method:

  • SLAVE_SOURCE
  • INTERNET_RADIO
  • PANDORA
  • AIRPLAY
  • STORED_MUSIC
  • AUX
  • OFF_SOURCE
  • CURRATED_RADIO
  • STANDBY
  • UPDATE
  • DEEZER
  • SPOTIFY
  • IHEART

/:deviceName/trackInfo

Get more information about the artist and track that is playing.

{
  "trackInfo":{
    "deviceID":"001122334455",
    "$t":"MP3  128 kbps  Brussels Belgium,  ... Life is Music"
  }
}

/:deviceName/presets

This method will return all 6 presets that are configured on the SoundTouch device.

{
  "presets":{
    "preset":[
      {
        "id":"1",
        "ContentItem":{
          "source":"INTERNET_RADIO", 
          "location":"4712",
          "sourceAccount":"",
          "isPresetable":"true",
          "itemName":"Studio Brussel"
        }
      },
      {
        "id":"2",
        "ContentItem":{
          "source":"INTERNET_RADIO",
          "location":"10749", 
          "sourceAccount":"",
          "isPresetable":"true",
          "itemName":"Q-music Belgium"
        }
      },
      {
        "id":"3", 
        "ContentItem":{
          "source":"INTERNET_RADIO",
          "location":"4746",
          "sourceAccount":"",
          "isPresetable":"true",
          "itemName":"MNM"
        }
      },
      {
        "id":"4",
        "ContentItem":{
          "source":"DEEZER",
          "type":"album",
          "location":"102293838",
          "sourceAccount":"[email protected]",
          "isPresetable":"true",
          "itemName":"IN DREAM (Deluxe Version)"
        }
      },
      {
        "id":"5",
        "createdOn":"1446545553",
        "updatedOn":"1446545553",
        "ContentItem":{
          "source":"DEEZER",
          "type":"album",
          "location":"00011100",
          "sourceAccount":"[email protected]",
          "isPresetable":"true",
          "itemName":"Drones"
        }
      },
      {
        "id":"6",
        "ContentItem":{
          "source":"INTERNET_RADIO",
          "location":"00001",
          "sourceAccount":"",
          "isPresetable":"true",
          "itemName":"Radio Station"
        }
      }
    ]
  }
}

/:deviceName/sources

This methods returns all configured sources on your SoundTouch. For every source, additional information (e.g. account name for Deezer) is also available. In this example, all default sources are enabled and a Deezer account was attached. Spotify is not configured.

{
  "sources":{
    "deviceID":"001122334455",
    "sourceItem":[
      {
        "source":"AUX",
        "sourceAccount":"AUX",
        "status":"READY",
        "isLocal":"true",
        "$t":"AUX IN"
      },
      {
        "source":"INTERNET_RADIO",
        "status":"READY"
      },
      {
        "source":"BLUETOOTH",
        "status":"UNAVAILABLE",
        "isLocal":"true"
      },
      {
        "source":"DEEZER",
        "sourceAccount":"[email protected]",
        "status":"READY",
        "$t":"[email protected]"
      },
      {
        "source":"SPOTIFY",
        "status":"UNAVAILABLE"
      }
    ]
  }
}

/:deviceName/info

This method gets all known settings for the SoundTouch device. (E.g. The type of SoundTouch)

{
  "info":{
    "deviceID":"001122334455",
    "name":"Bathroom",
    "type":"SoundTouch 20",
    "margeAccountUUID":"1234567",
    "components":{
      "component":[
        {
          "componentCategory":"SCM",
          "softwareVersion":"10.0.11.24675.1494103 epdbuild.trunk.hepdswbld04.2015-11-04T13:43:25",
          "serialNumber":"XXXXXXXXXXXXXXXXXXX1"
        },
        {
          "componentCategory":"PackagedProduct",
          "serialNumber":"YYYYYYYYYYYYYYYYYYY1"
        }
      ]
    },
    "margeURL":"https://streaming.bose.com",
    "networkInfo":[
      {
        "type":"SCM",
        "macAddress":"001122334455",
        "ipAddress":"10.0.1.7"
      }, 
      {
        "type":"SMSC",
        "macAddress":"001122334455",
        "ipAddress":"10.0.1.7"
      }
    ],
    "moduleType":"sm2",
    "variant":"spotty",
    "variantMode":"normal",
    "countryCode":"GB",
    "regionCode":"GB"
  }
}

Sending commands to your SoundTouch

When :deviceName is mentioned in a url, the name of the soundtouch should be used. This name can be retrieved by requesting '/device/list' and choose the soundtouch you want to control or approach.

/:deviceName/name/:name

This will change the name of your SoundTouch. This means that for your next call to the SoundTouch, you'll need to use the new name.

:name The new name for your SoundTouch

{
  "info":{
    "deviceID":"001122334455",
    "name":"Bathroom",
    "type":"SoundTouch 20",
    "margeAccountUUID":"1234567",
    "components":{
      "component":[
        {
          "componentCategory":"SCM",
          "softwareVersion":"10.0.11.24675.1494103 epdbuild.trunk.hepdswbld04.2015-11-04T13:43:25",
          "serialNumber":"XXXXXXXXXXXXXXXXXXX1"
        },
        {
          "componentCategory":"PackagedProduct",
          "serialNumber":"YYYYYYYYYYYYYYYYYYY1"
        }
      ]
    },
    "margeURL":"https://streaming.bose.com",
    "networkInfo":[
      {
        "type":"SCM",
        "macAddress":"001122334455",
        "ipAddress":"10.0.1.7"
      }, 
      {
        "type":"SMSC",
        "macAddress":"001122334455",
        "ipAddress":"10.0.1.7"
      }
    ],
    "moduleType":"sm2",
    "variant":"spotty",
    "variantMode":"normal",
    "countryCode":"GB",
    "regionCode":"GB"
  }
}

This JSON output of this call is the same as '/:deviceName/info'.

/:device/volume/:volume

This url will set the volume for the selected SoundTouch.

:volume should be replaced with the volume you want to set. A number between 0 and 100.

{
  "status":"/volume"
}

/:deviceName/playPause

This method will play if the SoundTouch was paused or pause when it was playing.

{
  "status":"/key"
}

/:deviceName/play

This method will start playing the SoundTouch, also when it was powered off.

{
  "status":"/key"
}

/:deviceName/powerOn

This will power on the SoundTouch.

The returned status will be true if the SoundTouch is turned on. The returned status will be false if the SoundTouch was already turned on.

{
  "status":true
}

/:deviceName/powerOff

This will power off the SoundTouch.

The returned status will be true if the SoundTouch is turned off. The returned status will be false if the SoundTouch was already turned off.

{
  "status":true
}

/:deviceName/key/:key

This method will press the provided key. Mention the key by replacing :key.

{
  "status":"/key"
}

All possible keys are:

  • PLAY
  • PAUSE
  • PLAY_PAUSE
  • STOP
  • PREV_TRACK
  • NEXT_TRACK
  • THUMBS_UP
  • THUMBS_DOWN
  • BOOKMARK
  • POWER
  • MUTE
  • VOLUME_UP
  • VOLUME_DOWN
  • PRESET_1
  • PRESET_2
  • PRESET_3
  • PRESET_4
  • PRESET_5
  • PRESET_6
  • AUX_INPUT
  • SHUFFLE_OFF
  • SHUFFLE_ON
  • REPEAT_OFF
  • REPEAT_ONE
  • REPEAT_ALL
  • ADD_FAVORITE
  • REMOVE_FAVORITE

Playing another music source

The following methods can be used to control the SoundTouch:

  • /:deviceName/select/:source/:sourceAccount/:location
  • /:deviceName/select/:source/:location

When the method is called, SoundTouch server will respond with:

{
  "status":"/key"
}

But when invalid source data is passed, it can also be:

{
  "message":"Source \"INTERNET_RADIO_TEST\" is not supported"
}

Or when another error occurs, it can also be:

{
  "errors":{
    "deviceID":"001122334455",
    "error":{
      "value":"1005",
      "name":"UNKNOWN_SOURCE_ERROR",
      "severity":"Unknown",
      "$t":"1005"
    }
  }
}

':source' is one of the sources (use /api/sources-list to get a list of all possible sources, where /:deviceName/sources actually returns all available sources on your SoundTouch.) :sourceAccount is needed for some sources (e.g. Deezer) :location is the id of the playable content

How do I known what settings I need to pass?

  1. Set your SoundTouch to your desired music source with the SoundTouch app.
  2. Request the /:deviceName/nowPlaying method to get the details. (you can also use the /:deviceName/presets methods if that music source was configured like a preset)
  3. Look for the ContentItem object in this response:
...
    "ContentItem":{
      "source":"INTERNET_RADIO",
      "location":"4712",
      "sourceAccount":"",
      "isPresetable":"true",
      "itemName":"Studio Brussel"
    }
...

The source, location and sourceAccount in this output should be used to set the SoundTouch to that specific music source.

Radio station

/:deviceName/select/:source/:location

...
    "ContentItem":{
      "source":"INTERNET_RADIO",
      "location":"4712",
      "sourceAccount":"",
      "isPresetable":"true",
      "itemName":"Studio Brussel"
    }
...

E.g. http://10.0.1.102:5006/Bathroom/select/INTERNET_RADIO/4712

Deezer

/:deviceName/select/:source/:sourceAccount/:location

...
    "ContentItem":{
      "source":"DEEZER",
      "type":"album",
      "location":"10506011",
      "sourceAccount":"[email protected]",
      "isPresetable":"true",
      "itemName":"Drones"
    }
...

E.g. http://10.0.1.102:5006/Bathroom/select/DEEZER/[email protected]/10506011

Zone handling

/:deviceName/getZone

This method will check if the SoundTouch mentioned in :deviceName is member of a group and will return the group members..

{TODO}

/:deviceName/setZone/:slaveDeviceName

This method will create a zone where :deviceName is the master and :slaveDeviceName is the slave. You need to provide the name of the SoundTouch in both cases. Current limitation is that you can only add 1 SoundTouch as slave to the master.

{TODO}

/:deviceName/addZoneSlave/:slaveDeviceName

This method will add an additional slave to a zone where :deviceName is the master. The :slaveDeviceName is the slave you want to add. You need to provide the name of the SoundTouch in both cases.

{TODO}

/:deviceName/removeZoneSlave/:slaveDeviceName

This method will remove 1 slave of a zone where :deviceName is the master. The :slaveDeviceName is the slave you want to remove. You need to provide the name of the SoundTouch in both cases.

{TODO}

/auto/virtualZone

This method will scan over all SoundTouches and create a group automatically when discovering 2 or more devices playing the same music source.

{TODO}
Clone this wiki locally