One special feature of our SoundTouch 10 speakers is their ability to form left/right stereo pair groups. To help answer a question on the forum, we've been working on building out our documentation for handling these stereo pairs via the SoundTouch Control API. In this post, we'll walk through the key things you need to know to best incorporate stereo pair handling into your application.

Groups vs. Zones

In the SoundTouch Control API you may notice that there are two different ways you can combine products - groups and zones. Groups are the special stereo pairs that SoundTouch 10 speakers on firmware version 14.x or higher can make, where one speaker plays the right channel audio and the other plays the left channel audio. Zones are the multiroom pairing feature that all SoundTouch products support, where all products in the zone play the same audio in sync. A stereo pair group of SoundTouch 10 speakers can be included within a larger zone of SoundTouch products.

Initial Group State

When you begin interacting with a SoundTouch 10, it is important to send it a /getGroup request using the Control API REST component to determine if it's in a stereo pair group. If it is NOT in a group, the response will be:

<group />

If a speaker IS in a group, the response will look something like this:

<group id="251427">
    <name>Jake + Elwood</name>
    <masterDeviceId>XXXXXXXXXXXX</masterDeviceId>
    <roles>
        <groupRole>
            <deviceId>XXXXXXXXXXXX</deviceId>
            <role>LEFT</role>
            <ipAddress>10.0.1.138</ipAddress>
        </groupRole>
        <groupRole>
            <deviceId>YYYYYYYYYYYY</deviceId>
            <role>RIGHT</role>
            <ipAddress>10.0.1.139</ipAddress>
        </groupRole>
    </roles>
    <senderIPAddress>10.0.1.135</senderIPAddress>
    <status>GROUP_OK</status>
</group>

Within a group, a speaker will either be the master or member. The /getGroup response will look the same from both the master and member speaker. You should use the MAC and IP Addresses reported to determine which speaker is which. In this example, the left speaker is the master with the MAC Address: XXXXXXXXXXXX and IP Address: 10.0.1.138 and the right speaker is the member speaker with the MAC Address: YYYYYYYYYYYY and IP Address: 10.0.1.139.

Handling Groups

Knowing which speaker is the master and which speaker is the member is important for controlling the speakers: you should always send commands to the master speaker. Volume and playback are linked while the speakers are in a stereo pair group. Commands sent to the master, like /volume and /key, will update both speakers. If you send commands only to the member speaker, they may not take effect.

Additionally, once you've detected two SoundTouch 10s are paired into a group, you should display that pair as you would a single product in your application.

Right now, we do not support creating or disbanding stereo pair groups through the API. Users can manage these elements of their stereo pair groups through the SoundTouch App, and you can use the API to stay up-to-date on the group states and control speakers in or out of groups.

Monitoring Groups

The master and member speakers may swap roles during playback. You should use the WebSocket Notification component of the Control API to track group state and dermine whether you need to update your handling of SoundTouch 10 products. Alternatively, you can also periodically send /getGroup requests through the REST API to accomplish this if WebSockets is not an option. A /groupsUpdated notification will be sent out whenever a group is created, modified, or disbanded. The group WebSocket notifications look very similar to the REST API - when a group is created or modified, the notification will look like:

<updates deviceID='YYYYYYYYYYYY'>
    <groupUpdated>
        <group id="251427">
            <name>Jake + Elwood</name>
            <masterDeviceId>XXXXXXXXXXXX</masterDeviceId>
            <roles>
                <groupRole>
                    <deviceId>XXXXXXXXXXXX</deviceId>
                    <role>LEFT</role>
                    <ipAddress>10.0.1.138</ipAddress>
                </groupRole>
                <groupRole>
                    <deviceId>YYYYYYYYYYYY</deviceId>
                    <role>RIGHT</role>
                    <ipAddress>10.0.1.139</ipAddress>
                </groupRole>
            </roles>
            <senderIPAddress>10.0.1.135</senderIPAddress>
            <status>GROUP_OK</status>
        </group>
    </groupUpdated>
</updates>

When a group is disbanded, the notification will look like: 

<updates deviceID='YYYYYYYYYYYY'><groupUpdated><group /></groupUpdated></updates>

Takeaways

  • 'Group' is the API term for the Stereo Pair Group feature of SoundTouch 10, which is available on firmware version 14.x and higher
  • You should use the WebSocket Notification API component to monitor the status of SoundTouch 10s and group statuses
  • Commands to control a group should always be sent to the master speaker
  • You should display groups as single products within your application

Still have questions or comments about stereo pair groups? Let us know over in the forum!