Sendspin Protocol Specification – Sendspin

Sendspin is a multi-room music experience protocol. The goal of the protocol is to orchestrate all devices that make up the music listening experience. This includes outputting audio on multiple speakers simultaneously, screens and lights visualizing the audio or album art, and wall tablets providing media controls.
Sendspin is an open, royalty-free protocol that anyone may implement. This specification is licensed under the Community Specification License 1.0, which includes a royalty-free patent license from every contributor for implementations of the specification within its Scope. Contributions are accepted under the Contributor License Agreement.
Sendspin is a trademark of the Open Home Foundation. Implementing the protocol grants no right to use the Sendspin name or logo on commercial products; see TRADEMARKS.md.
THESE MATERIALS ARE PROVIDED “AS IS.” The Contributors and Licensees expressly disclaim any warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to the materials. The entire risk as to implementing or otherwise using the materials is assumed by the implementer and user. IN NO EVENT WILL THE CONTRIBUTORS OR LICENSEES BE LIABLE TO ANY OTHER PARTY FOR LOST PROFITS OR ANY FORM OF INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER FROM ANY CAUSES OF ACTION OF ANY KIND WITH RESPECT TO THIS DELIVERABLE OR ITS GOVERNING AGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE, AND WHETHER OR NOT THE OTHER MEMBER HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 RFC 2119 RFC 8174 when, and only when, they appear in all capitals, as shown here.
A typical session, from handshake through playback to disconnect:
Roles define what capabilities and responsibilities a client has. All roles use explicit versioning with the @ character: <role>@<version> (e.g., player@v1, controller@v1).
This specification defines the following roles: player, source, controller, metadata, artwork, visualizer, color. All servers MUST implement all versions of these roles described in this specification.
All role names and versions not starting with _ are reserved for future revisions of this specification.
Clients list roles in supported_roles in priority order (most preferred first). If a client supports multiple versions of a role, all SHOULD be listed: ["player@v2", "player@v1"].
The server activates at most one version per role family (e.g., one player@vN, one controller@vN) - the first match it implements from the client's list, or none if server policy declines to activate that family. A server MUST NOT activate a role or version the client did not list in supported_roles. The server reports activated roles in active_roles; clients MUST consult the activation state established by the server/activate messages they have received and refrain from sending commands or state for roles that aren't active.
Message object keys (e.g., player?, controller?) use unversioned role names. The server determines the appropriate version from the client's active_roles.
Servers SHOULD track when clients request roles or role versions they don't implement (excluding those starting with _). This indicates the client supports newer role versions than the server and the server needs to be updated.
This mechanism only detects role-version skew, and only because roles are exchanged after the handshake. A newer core version, cipher suite, or handshake (a cipher or handshake change is itself a core version bump) makes the handshake abort before roles are exchanged, so that skew surfaces as a failed connection rather than through this role-request signal.
Custom roles outside the specification start with _ and MUST include an explicit version when advertised (e.g., _myapp_controller@v1, _custom_display@v1). To avoid collisions between independent vendors, custom role names SHOULD include a vendor-specific prefix (e.g., _vendorname_role).
Their binary message IDs come from the unmanaged 192-255 range: an application-specific role's own definition assigns its IDs, and a client MUST NOT advertise two roles with conflicting IDs.
This section describes how future revisions of this specification can add standard protocol features, roles, and role versions. It does not grant additional permissions to application-specific roles.
Core and role versions define behavior as well as message formats. If a new feature is not selected, existing behavior MUST remain unchanged. A change that breaks an existing role's contract requires a new role version. A core change that breaks existing behavior requires a new core version unless it can apply only when both peers explicitly opt in.
Future revisions of this specification MAY add optional information if older receivers can ignore it without changing the message's meaning. If a new feature needs the receiver to behave differently, the sender MUST confirm support through role activation or an explicitly defined capability negotiation before relying on that behavior. Matching core versions, the peer's software version, and the absence of an error do not confirm support. New features SHOULD use role support objects for role-specific capabilities.
A feature that changes connection-wide behavior, such as admission or ownership, MUST define how both peers opt in and what happens if they do not. It MUST NOT break the protocol rules that apply to peers on other connections that have not opted in. Support for a role MUST NOT be taken as support for a separate connection-wide feature unless that role version explicitly includes it.
Sendspin has two standard ways to establish connections: Server and Client initiated. Server Initiated conne