Skip to main content

# Sonos

Multi-scrobbler can use the Sonos local API to monitor what your Sonos system is playing.

MS supports scrobbling simultaneous, different Plays based on what each Group/Zone is playing.

Use Musicbrainz for better scrobbling

For some services, including Spotify, Sonos only reports the first artist for a Track. You will most likely want to enable Musicbrainz scrobble enhancements so that your plays have correct information, including all artists, when scrobbled.

Avoid Sonos activity through other Sources

Activity reporting for other Sources does not work well when played through Sonos.

If you have other Sources configured for Multi-Scrobbler that you may play through Sonos you should try to add Sonos to the "deny" list for that Source so that it does not try to monitor Sonos activity. Check the documentation for each individual Source to see how to configure this exclusion.

For example, to prevent the Plex Source from monitoring audio played through Sonos, add Sonos to the "block" list ENV EX: `PLEX_DEVICES_BLOCK=sonos`

How to report issues

If your Sonos Source is logging errors or the scrobble data is not as expected please create a bug report after enabling the following debug logging options based on the config type you have:

- ENV
- File

Enable Debug Mode using `DEBUG_MODE=true`

Enable `logPayload` and `logFitlerFailure` in your `sonos.json`, or AIO file, config:

    [
      {
        "enable": true,
        "name": "MySonos",
        "data": {
          "host": "192.168.0.150"
        },
        "options": {
          "logFilterFailure":  "warn",
          "logPayload": true
         }
      }
    ]

Additional logging for the Sonos library may be enabled by including this environmental variable (regardless of config type):

    DEBUG=sonos:*

The above changes:

- Triggers multi-scrobbler to log the raw data recieved from Sonos when a new track/device/service is seen for the first time
- Trigger multi-scrobbler to log the reason it considers a play from Sonos as invalid (and will not monitor it)
- Logs low-level activity from the Sonos library

Please include these additional logs when creating a bug report. They are essential to troubleshooting your issue.

### Filtering Activity​

The optional `devices` and `groups` related properties found in the config below can be used to include or exclude Sonos devices/groups by name, case-insensitive.

## Configuration​

You must define the IP address of at least one Sonos/accessory in order for Multi-scrobbler to connect to your Sonos system.

- ENV
- File
- AIO

Configuration Type

This is configuration for the ENV Config Type.

Environmental Variable | Type | Default | Description
--- | --- | --- | ---
`SONOS_ID` | string |  | A globally unique ID EX `myComponentId`
`SONOS_NAME` | string | Value of `SONOS_ID` | A vanity name EX `My Cool Component`
`SONOS_ENABLE` | boolean | true | Should this component be used?
`SONOS_HOST` | string |  | IP address of any connected Sonos speaker or device
`SONOS_DEVICES_ALLOW` | string |  | Only scrobble if device name contains strings from this comma-delimited list
`SONOS_DEVICES_BLOCK` | string |  | Do not scrobble if device name contains strings from this comma-delimited list
`SONOS_GROUPS_ALLOW` | string |  | Only scrobble if the name of a group the playing device belongs to contains strings from this comma-delimited list
`SONOS_GROUPS_BLOCK` | string |  | Do not scrobble if the name of a group the playing device belongs to contains strings from this comma-delimited list

Bold/Italic = Required

Config Structure

This displays the structure of the File Configuration for a sonos type Source with all possible properties, their shape, and descriptions/types. Use this to understand how to write a valid config.

Loading ...
Config Example

This displays an example config file of a sonos Source File Configuration that adheres to the shown Config Structure.

- text mode lets you edit the JSON directly.
- tree mode gives you a guided point-and-click editing experience that always keeps the JSON syntax valid.

Both modes validate that the configuration is correct. Any errors show up as squiggly lines.

important

Only source sonos configs will validate correctly in the editor but both source and client sonos configs are allowed in the real `CONFIG/sonos.json`

After you finish editing, switch to text and then copy all text to get a completed config.

Config Example Mobile Experience

This displays an example config file of a sonos Source File Configuration that adheres to the shown Config Structure.

The example config file editor is meant for a larger screen experience so only the read-only example is shown. Please use this site on a tablet/laptop/desktop to enable file editor features.

CONFIG/sonos.json

    [
      {
        "enable": true,
        "id": "MySonos",
        "name": "Boom 2",
        "data": {
          "host": "192.168.0.150",
          "devicesAllow": [
            "move",
            "beam"
          ],
          "devicesBlock": [
            "roam"
          ],
          "groupsAllow": [
            "family"
          ],
          "groupsBlock": [
            "bedroom"
          ]
        }
      }
    ]

Config Structure

This displays the structure of the all-in-one (`config.json`) configuration with all possible properties, their shape, and descriptions/types. Use this to understand how to write a valid config.

Select the sonos type from the respective `sources` node below, then expand it.

Loading ...
Config Example

This displays an example config file of a all-in-one (`config.json`) configuration that includes a sonos Source that adheres to the shown Config Structure.

- text mode lets you edit the JSON directly.
- tree mode gives you a guided point-and-click editing experience that always keeps the JSON syntax valid.

Both modes validate that the configuraion is correct. Any errors show up as squiggly lines.

After you finish editing, switch to text and then copy all text to get a completed config.

Config Example Mobile Experience

This displays an example config file of a all-in-one (`config.json`) configuration that includes a sonos Source that adheres to the shown Config Structure.

The example config file editor is meant for a larger screen experience so only the read-only example is shown. Please use this site on a tablet/laptop/desktop to enable file editor features.

CONFIG/config.json

    {
      "sources": [
        {
          "enable": true,
          "id": "MySonos",
          "name": "Boom 2",
          "data": {
            "host": "192.168.0.150",
            "devicesAllow": [
              "move",
              "beam"
            ],
            "devicesBlock": [
              "roam"
            ],
            "groupsAllow": [
              "family"
            ],
            "groupsBlock": [
              "bedroom"
            ]
          },
          "type": "sonos"
        }
      ]
    }