Sonos | Media Players | S1 & S2 | IP | Version 5.15

Introduction & Manufacturer Profile

Sonos is a leading audio technology company that revolutionizes how people listen and connect to sound.

Since inventing wireless multi-room audio, Sonos has continued innovating, creating wireless speakers, home cinema systems, headphones, architectural components, and whole home audio solutions that have defined categories, pushed the boundaries of what's possible, and delighted listeners all around the world.

This driver provides network control of Sonos media players on both S1 and S2 systems.

---

Version History

• Version 3.0 — Initial release.
• Version 4.0 — Passed 'Works with Sonos' certification.
• Version 4.05 — Addresses issues with CPU load on large systems; adds remaining time variable; fixes an issue where feedback would sometimes not populate on startup.
• Version 4.09 — Fixed connection issue after a Sonos firmware update; fixed SiriusXM title feedback; fixed playback appearing to continue after a player is taken offline.
• Version 5.01 — Added OAuth authentication (required for both S1 & S2); added Search and Recently Played (S2 only); added new Playlists functionality on S2 devices; added Line-In, TV Mode, Night Mode and Speech Enhancement events; removed Loudness and Stop commands/variables, which Sonos no longer supports.
• Version 5.1 — Fixes Tidal cover art, Seek, and Volume Up/Down events; added volume control of a non-Sonos device's volume from the Sonos app (see Driver Configuration); updated to match the new Sonos template.
• Version 5.11 — Fixes cover art being assigned a player's IP (such as Subsonic); fixes metadata without cover art not falling back to the default cover; fixes TuneIn New returning no search results; fixes a player not coming back online after a software update (this should also help with disconnection issues); added Volume Monitoring (see Driver Configuration).
• Version 5.12 — Fixes the Player Name variable; added a Remove Player from a Group command; renamed some group commands to describe them more accurately; fixed the coordinator not being set for a device discovered after the first discovery; discovery now runs every 60s instead of 120s; fixed items past a certain point in the Recently Played list not playing.
• Version 5.13 — Fixed Volume Monitoring scaling issue; fixed an S1 player returning its info with an empty name field; renamed the existing remove-player command to Remove Player from a Specific Group; added a Remove Player from a Group command that removes a player from whatever group it is in without needing to know the group.
• Version 5.14 — OAuth token acquisition on the JITP transport now retries until authorized, fixing a driver left stuck after boot.
• Version 5.15 — Completed the JITP OAuth self-heal: a bootstrap watchdog covers a dropped registration, and the OAuth client is rebuilt when a token is missing or a refresh stalls.

---

System Requirements & Prerequisites

RTI System Requirements

• Integration Designer — 11.9 or later
• XP Firmware — 22.3.31 or later

Driver Information

• This driver provides network control of Sonos media players.
• If updating from V4.09, you will need to reprogram the Playlist variable for each player and add a back button, as the playlist functionality has changed.
• You might also need to reprogram the layer visibility of the keyboard.
• If Wi-Fi devices are not being discovered, try the following:
  • Increase the discovery time to 20 or higher.
  • Check that multicast is not being blocked on the Wi-Fi.
  • Play something on the players — this tends to make sure they aren't in a sleep state that stops them responding to broadcasts.

---

Authentication

The driver requires the end user to give it permission to access their account. This is done through the RTI dashboard.

1. Upload the project to the XP processor.
2. Once the driver has started up and discovered the local devices, point your browser at the XP processor by pasting http://xp.local/auth into your browser, or launch the URL provided by Integration Designer under the Driver Authentication Dashboard section.
3. You should see the Sonos driver listed.
4. Click Authenticate and have the end user sign in with their credentials and grant permission to the driver.
5. After a few moments the driver will receive a token and will start to work.

---

Driver Configuration

Note: You can't have a mix of S1 & S2 devices in the same system. The driver only works with a single household, so all players need to be from the same Sonos system.

The Volume Control option controls a non-Sonos device's volume (such as an AVR or amp) when using the Sonos app.

The Volume Monitoring option allows a non-Sonos device's level variable (such as a Lutron keypad's Raise/Lower) to control the volume of the Sonos, and in turn the AVR configured in the Volume Control option.

Device Names

Number of Players

• Set the number of players you wish to control.

Player

• Name — Give the player a display name. This does not need to match the Sonos defined name.
• Serial Number — The serial number as displayed in the desktop app.
• Enable Volume Control — Enable control of another device's volume from the Sonos app. Only works with drivers that have a set volume command.
• Enable Scaling — Select if the driver you want to control works with something other than 0-100 volumes.
• Minimum — The other driver's minimum volume. Only shows if Enable Scaling is enabled.
• Maximum — The other driver's maximum volume. Only shows if Enable Scaling is enabled.
• Enable Volume Monitoring — Enable control of the Sonos volume from another non-Sonos device's level variable.
• Enable Scaling — Select if the driver you want to control works with something other than 0-100 volumes.
• Minimum — The other driver's minimum volume. Only shows if Enable Scaling is enabled.
• Maximum — The other driver's maximum volume. Only shows if Enable Scaling is enabled.
• Volume Variable to monitor — Select the dropdown arrow on the right to choose the variable of the driver you want to use.

Driver Settings

Favorites list formatting

• No Description — Only the title is displayed.
• Description in parenthesis — The title is displayed with the description in ().
• Description on 2nd line — The title is displayed with the description on a second line.

TV Mode Poll Rate

• Frequency (in seconds) that the driver should poll a player in TV Mode for Night Mode / Enhance Dialog status changes.

Discovery Timeout

• Number of seconds for the driver to wait for a response during startup.
• On systems with a large number of Sonos devices you may need to increase this value.

Recently Played Refresh Rate

• Rate (in minutes) that the driver should refresh the recently played list. If you are not using the recently played list, set this to None.

Search Settings

• Title Text — String to display to indicate the user can search.
• Wait Text — String to display while the search is being processed.
• Image Type — None: don't display any image in the search service list. Badge: monochrome logo. Icon: color logo. Logo: white logo (most compatible).
• Clear Image Cache — The image URLs returned from the cloud service are cached to speed up future access. Checking this box clears the cache from persistent storage on startup.

Template Page Names

• Default — Sonos
• Secondary — Music Player

---

Works with Sonos

Version 5.0 of the driver was certified by Sonos, meaning Sonos tested the driver on RTI hardware to confirm it meets their requirements for both functionality and reliability.

The driver discovers all Sonos players on the network, whether you wish to control them or not. This is because the "coordinator" — the device commands must be sent to — can be a device you don't actually wish to control. This resolves the issue in previous versions where the driver would lose control after grouping/ungrouping.

As a result, the more Sonos devices on the network, the more demand is placed on the XP processor.

To be clear: this does not mean you need to add every Sonos device on the network to the driver config. Only add devices you wish to control.

---

Identifying Players

The driver doesn't need any network information — feel free to keep the system using DHCP. What it needs is the serial numbers of the players.

The serial number can be found on the device or in About My Sonos System in any of the apps. It is 19 characters long: 6 pairs of characters separated with -, ending with a : followed by a single character. For example: 38-42-0B-22-A9-E1:E

Important: Enter the serial number exactly as it appears in the desktop app.

• A subwoofer does not need to be added to the configuration, as it will never need to be sent commands on its own.
• Surrounds don't need to be configured either if they are always surrounds. The driver can adjust to surround speakers moving between surrounds, individual speakers and stereo pairs, but this increases the processing power the driver uses — so if they will always be surrounds, leave them out of the configuration.
• The names in the configuration show when programming in Integration Designer. When the system is running there are two Name variables to choose from: the name given to the player in the configuration, or the current name of the player in the system itself.
• Only players you wish to control should be put in the driver properties — this helps alleviate CPU load.

---

Stereo Pairs

When two players are to be connected in a stereo pair you have to be cautious. This cannot be done in the driver — it has to be done in the app — but the order in which you perform the steps is important.

1. Stereo pairs are created in the Settings menu in the app.
2. Select one of the players and go to Create Stereo Pair.
3. Select the device to be the other half of the pair.
4. Select which of the two will be the left speaker in the pair.

That last step has important ramifications: the device selected as the left speaker also becomes the coordinator, or master, of the pair, and all commands must go to it. The other speaker is considered 'invisible' in the system and cannot respond to any commands.

The driver can only send commands to devices in its configuration, so if you create a stereo pair you only need one of them in the configuration — but it must be the master (left speaker) of the pair, which may not be the player that remains in the app. If both players are left in the configuration, the driver will automatically send commands to the correct player.

---

Features Available on Both S1 and S2

Audio Player Control

The driver gives you all the audio controls for up to 32 players, including a 'selected' player: transport, volume, play mode (shuffle, repeat) and so on.

The default Volume, Volume Up, Volume Down and Mute tags are associated with the Group Volume commands. If a player is not grouped with other players these commands act as the standard player volumes; if it is grouped, they act as group commands and adjust all players in the group relatively.

There is also a Player Volumes Popup command/variable set that can display a popup showing the individual players' volume controls.

Favorites / Playlists

The driver keeps a copy of the Sonos Favorites and Playlists, exposed through the Favorites List and Playlist variables. Selecting an item using Select Favorite from List plays the chosen favorite on the Sonos player.

There are two functions, Select Favorite and Select Favorite Ex. The 'Ex' function adds the ability to determine how the favorite is added to the queue: add to the end, replace the queue, play now, or play next.

On S1 devices, Select Playlist plays the chosen playlist on the Sonos player.

Favorite icon metadata: the icons are no longer part of the official Sonos API. They remain in the driver but will always be blank.

Line Input Selection

Commands exist to have any player play the line input of any other device.

TV Input Selection

Commands exist to switch a player to the TV input (HDMI or optical). This requires the device to be in Home Theater Mode.

Groups

Any player can be synced to any other. When a player is following another, its is a follower variable is set; when it is a group master, its Group Master variable is set. Boolean variables also indicate which players are following a given player (or the selected player). A separate command exists for removing a player from the group.

Transport Control

Visibility variables accompany each of the transport commands, so you can display only the buttons for currently relevant commands.

For instance, the Show Previous command will be false when a Pandora station is playing — use it as visibility on a Skip Back button and the button disappears while a Pandora station plays. Similar variables are available for Repeat and Shuffle.

Music Service Provider Logos

The driver provides an index to a list of music service provider logos, allowing you to display the current streaming source (Spotify, Apple Music etc).

These logos are provided as an image group in a zip file shipped with the driver. To use them in your own project file, unzip the images into your Integration Designer bitmap folder. The sample project shows how to use this feature.

---

Features Available on S2 Only

Playlists

Select Playlist shows the contents of the playlist along with Play and Shuffle options.

• Play — Loads the chosen playlist and starts playing from the beginning.
• Shuffle — Loads the chosen playlist and starts playing it in shuffle mode.
• Selecting a track — Loads the chosen playlist and starts playing from the selected track.

Recently Played

Recently Played is only available if the option has been enabled in the Sonos app. If you are not using it, set the Recently Played Refresh Rate driver setting to Never; otherwise set how often it should update. Be cautious with the frequency — it can be a large amount of data to process.

To enable Recently Played in the Sonos app, go to Account / Privacy & Security / Personalization Services and enable Use Personalization Services.

Search

The driver uses the cloud API to search using user-entered strings via a virtual keyboard.

Search results are limited to a maximum of 5 items of each type. For example, searching for an artist may return 5 albums, 5 individual tracks, 5 radio stations, 5 podcasts and so on related to the search string. For a more in-depth search, use the native Sonos apps.

Not all streaming services are searchable. This is dictated by the license Sonos has with each individual service; the driver has no influence over this.

Searchable personal services

• 80er-Radio harmony
• 80s80s - REAL 80s Radio
• 90s90s Radio
• Absolute Radio
• AccuRadio
• Aldi life Musik
• Amazon Music (unlimited tier for album content)
• ANTENNE BAYERN
• Art Radio - RadioArt.com
• Atmosphere by Kollekt.fm
• Audacy
• Audible
• Bandcamp
• BBC Sounds
• BOB! Deutschlands Rockradio
• CBC Radio & Music
• Claro Música
• Classical Archives
• Community Radio Plus
• Convoy Network
• Deezer
• DR LYD
• Familystream
• FIT Radio Workout Music
• focus@will
• Gaana
• Global Player
• Hit Network
• HIT RADIO FFH
• Hype Machine
• I Love Music
• iBroadcast
• iChill Music Service
• IDAGIO
• iHeartRadio
• JazzGroove.org
• Juuqo
• KISS
• KKBOX
• Libby by OverDrive
• LivePhish+
• Lyden av Norge
• Mixcloud
• Mofibo
• Murfie
• myTuner Radio
• Napster
• NhacCuaTui
• NRK Radio
• NTS Radio
• nugs
• Pandora
• Piraten.FM
• planet radio
• Plex
• Pocket Casts
• PowerApp
• Qobuz
• QQ
• Radio France
• Radio Javan
• Radio Paradise
• RadioApp
• RadioPlay
• Radioplayer
• radioPup
• Radioshop
• RauteMusik.FM
• Rayo
• Relisten
• rova
• Saavn
• SiriusXM
• SomaFM Radio
• Sonos Radio
• SoundCloud
• Storytel
• Sveriges Radio
• Talk
• talkSPORT
• TELMORE Musik
• TIDAL
• Times Radio
• Triple M
• TuneIn (New)
• Tunify for Business
• Yogi Tunes
• YouSee Musik
• YouTube Music (premium)

Searchable commercial services

• Backgrounds Premium
• Harmony
• Jukeboxy Music for Business
• LiveOne
• Music Source
• Pandora CloudCover
• POSmusic
• Qsic Prod Clone Staging
• Soundtrack
• storePlay
• Tribe of Noise

---

Driver Events

Driver events are triggered on a change in a player's transport status. Events are available for Pause, Play and Buffering. An additional event is available for a change in song title.

A driver event is also triggered every time a player is sent a volume up or down command. This helps when volume commands are being sent to selected players, one of which is a Sonos Connect — the events can trigger macros that change volume on your receiver. Similar events exist for the mute command.

---

Limitations

• Previous versions of the driver allowed you to get creative with how you entered player serial numbers. This is no longer the case: paste in the serial number exactly as it appears in the Help → About menu of the desktop app, for example 38-42-0B-22-A9-E1:E.
• After a Sonos software update, the driver should reconnect to the updated devices within two minutes of the update completing. If it doesn't, reboot the processor.

---

System Testing

• Integration Designer — 11.11
• XP Processor Model — XP-8v
• XP Processor Firmware — 24.3.29
• Device Model(s) — Port, Amp, Play 1, Era100

---

Support Contact

AVPro Global - Remote Technologies Inc.

Phone: +1 952-253-3100

Email: support@avproglobal.com

Copyright 2026 AVProGlobal RTI