Snapcast binary protocol

Each message sent with the Snapcast binary protocol is split up into two parts:

• A base message that provides general information like time sent/received, type of the message, message size, etc
• A typed message that carries the rest of the information

The protocol is using little endian.

Client joining process

When a client joins a server, the following exchanges happen

1. Client opens a TCP socket to the server (default port is 1704)
2. Client sends a Hello message
3. Server sends a Server Settings message
4. Server sends a Codec Header message
   1. Until the server sends this, the client shouldn't play any Wire Chunk messages
5. The server will now send Wire Chunk messages, which can be fed to the audio decoder.
6. When it comes time for the client to disconnect, the socket can just be closed.
7. Client periodically sends a Time message, carrying a sent timestamp t_client-sent
   1. Receives a Time response containing the client to server time delta latency_c2s = t_server-recv - t_client-sent + t_network-latency and the server sent timestamp t_server-sent
   2. Calculates latency_s2c = t_client-recv - t_server-sent + t_network_latency
   3. Calcutates the time diff between server and client as (latency_c2s - latency_s2c) / 2, eliminating the network latency (assumed to be symmetric)

sequenceDiagram
    participant Client as Snapclient
    participant Server as Snapserver
    Note over Client,Server: Client connects to the server
over TCP or WS
    Client ->> Server: Hello
    Server ->> Client: Server Settings
    Server ->> Client: Codec Header
    loop Time sync
        Client ->> Server: Time
        Server ->> Client: Time
    end
    Note over Client,Server: Audio starts playing on the server
Time sync continues
    loop Stream
        Server ->> Client: Wire Chunk
    end
    Note over Client,Server: Client closes the connection

Messages

Base

Codec Header

The payload depends on the used codec:

• Flac: the FLAC audio file header, as described here. The decoder must be initialized with this header.
• Ogg: the vorbis stream header, as described here. The decoder must be initialized with this header.
• PCM: a RIFF WAVE header, as described here. PCM is not encoded, but the decoder must know the samplerate, bit depth and number of channels, which is encoded into the header
• Opus: a dummy header is sent, containing a 4 byte ID (0x4F505553, ascii for "OPUS"), 4 byte samplerate, 2 byte bit depth, 2 byte channel count (all little endian)

Wire Chunk

Server Settings

Sample JSON payload (whitespace added for readability):

{
    "bufferMs": 1000,
    "latency": 0,
    "muted": false,
    "volume": 100
}

• volume can have a value between 0-100 inclusive

Time

Hello

Sample JSON payload (whitespace added for readability):

{
    "Arch": "x86_64",
    "Auth": {
        "param": "YmFkYWl4OnBhc3N3ZA==",
        "scheme": "Basic"
    },
    "ClientName": "Snapclient",
    "HostName": "my_hostname",
    "ID": "00:11:22:33:44:55",
    "Instance": 1,
    "MAC": "00:11:22:33:44:55",
    "OS": "Arch Linux",
    "SnapStreamProtocolVersion": 2,
    "Version": "0.32.0"
}

The field Auth is optional and only used if authentication and authorization is enabled on the server.

Client Info

Sample JSON payload (whitespace added for readability):

{
    "volume": 100,
    "muted": false,
}

• volume can have a value between 0-100 inclusive

Error