Guide contents

Sendspin implementation guide

Sendspin is an open protocol for playing music in sync across the devices in a home: speakers, amplifiers, screens, lights and the apps that control them. The protocol specification defines exactly what goes over the wire. This guide covers the components you need, the user experience, and the implementation choices the protocol leaves to you.

The guide is non-normative. Where it restates a rule, the specification is the authority and the text links to it. Where it gives advice, that advice comes from the people who wrote the specification and shipped the first implementations.

Definitions

A client is an endpoint that receives audio from an existing Sendspin server. With the source role it can also hand its own audio to that server, which distributes it to other clients. Speakers, amplifiers, streamers, displays and lights are clients.

A server sends audio to clients and keeps them in sync. It can also reroute the audio of a source client to other clients. A server can be an app on a phone or desktop, or part of a music server such as Music Assistant.

One device can be both. A set-top box plays music as a client and can at the same time be a server that sends TV audio to the speakers in the room. The concepts chapter explains how the pieces fit together.

Choose your implementation path

You make devices

For speakers, amplifiers, streamers, displays and lighting, implement the client side with the C++ SDK or ESPHome.

You make software

A music player, desktop or mobile app, or streaming bridge can be a client, a server, or switch between the two depending on what the user is doing.

You run a platform

For a music server, home automation hub or multi-room system, implement the server side and the interface for pairing and groups.

Where the protocol stands

Sendspin 1.0 is at Release Candidate 1. The protocol is frozen: between now and the final release only clarifications and corrections land, and a behavioural change would start a new release candidate. What you build against RC1 today will work with 1.0. The contributing chapter explains the release process, and the specification's own governance document is the reference.

Implementing the protocol is free. There are no royalties and the specification comes with a patent license from every contributor. The Sendspin name and logo are trademarks, and using them on a product goes through the partner program. Licensing and trademarks has the details.

How to read this guide

  • The first chapters introduce the terminology and common product designs.
  • Building a client and Building a server walk through the work in order, pointing at the specification and the SDK hooks as they go. Read the side you are building; skim the other to understand your counterpart.
  • Security explains pairing and encryption in plain language, for the people who need to sign off on them.
  • Ship it covers testing, certification and how to take part in the project.

Read the whole guide on one page or save it as a PDF from there.

Getting help

Ask implementation questions in the #sendspin-protocol channel on the Music Assistant Discord. For partnership and certification questions, email [email protected]. Issues with the specification itself go to the spec repository.