Add support for the source role for audio input clients newly added to Sendspin spec?

[Hedda]

Tracking the adding of initial basic support for the source role v1 to this specific library (i.e. first version of source role for audio input clients) that were recently added as a new role to the Sendspin specification? Please close this tracker issue when implemented is this library.

• Add source role for audio input clients spec#105

Note that Sendspin/spec#113 removed supported_formats from source@v1_support after the above linked PR was opened.

For reference see ongoing developer discussions of source role implementations in these draft PR to the aiosendspin and sendspin-cli repos:

• feat(source): implement the source@v1 role aiosendspin#286

• feat(source): add a source@v1 capture client (sendspin source) sendspin-cli#270

For suggested real world use-cases for this new source with the combination of Music Assistant and ESPHome please see these related discussions:

• Add a "Source Role" for audio input devices so hardware can have Line-Level Audio input and can act as a Sendspin audio source? spec#14

  • https://github.com/orgs/music-assistant/discussions/2343

  • https://github.com/orgs/music-assistant/discussions/3763

Source - captures audio from a local input and streams it to the server. A client captures audio from a local input (line-in, turntable, Bluetooth, microphone) and streams it to the server, which decodes, mixes, and distributes it to players like any other audio.

• https://github.com/Sendspin/spec/blob/main/README.md#source-messages

Note that this first version of the new source is heavily based on Sendspin/spec#52 by rudyberends but simplified to the core and thus removed functions and features that might be added to a future version of the Sendspin specification where the source role could maybe get extended.

For reference, this "also rebases it onto the encryption work (Sendspin/spec#84), and now requires source clients to be paired since an unpaired source could otherwise inject malformed audio into the server."

Source messages

This section describes messages specific to clients with the source role, which capture audio from a local input (e.g., AUX/line-in, turntable preamp, Bluetooth receiver, or microphone) and stream it to the server. Unlike other roles, a source sends audio to the server; the server remains the single place that resamples, transcodes, mixes, buffers, and distributes audio to output players. Sources stay simple: they capture and encode audio, optionally report basic signal presence (line sensing), and stream timestamped audio frames.

A device MAY implement both the source and player roles (e.g., a speaker with a local AUX input forwarded into Sendspin).

Note: The source role (capturing input into Sendspin) is distinct from a client reporting available: false, which marks a client whose output has been taken over by a non-Sendspin system.

A source client uses the same clock synchronization mechanism as all clients. Binary source audio messages are timestamped in the server time domain by converting the local capture time with the offset the time filter tracks.

Pairing required: A source streams captured audio (potentially from a microphone or line-in) to the server, so it MUST only run on a paired connection (trust level user). Servers MUST NOT activate source@v1 over unpaired access, and a source client MUST refuse to stream when the connection's trust level is none.

Client → Server: client/hello source@v1 support object

The source@v1_support object in client/hello has this structure:

• source@v1_support: object
  • features?: object - optional feature hints
    • line_sense?: boolean - true if source reports signal

Note: Servers MUST support all audio codecs: 'opus', 'flac', and 'pcm'.

Client → Server: client/state source object

The source object in client/state has this structure:

• source: object
  • signal?: 'present' | 'absent' - optional line sensing/signal presence, only if 'line_sense' is supported

Server → Client: server/command source object

The source object in server/command has this structure:

• source: object
  • command: 'start' | 'stop'

Source command semantics

• command controls whether this source streams to the server:
  • start: server requests the source to begin streaming. The client SHOULD send client_stream/start and then send source audio chunks.
  • stop: server requests the source to stop streaming. The client SHOULD send client_stream/end and stop sending source audio chunks.

Default streaming behavior

The default after the handshake is stop: a source MUST NOT stream until the server sends command: "start". The server is the only party that initiates streaming.

A source that supports line sensing reports signal in client/state. The server MAY use it as a hint for when to send command: "start" or command: "stop", but the decision is server policy.

When the server removes source from active_roles, the client sends client_stream/end and stops sending chunks.

Client → Server: client_stream/start

The client_stream/start message announces the active input stream format and provides any required codec header data.

• source: object
  • codec: 'opus' | 'flac' | 'pcm'
  • channels: integer
  • sample_rate: integer
  • bit_depth: integer
  • codec_header?: string - codec header encoded as standard Base64, if necessary (e.g., FLAC)

Client → Server: client_stream/end

The client ends the current input stream. After this message, no more source audio chunks SHOULD be sent until a new client_stream/start.

Client → Server: Source Audio Chunks (Binary)

Binary messages SHOULD be rejected by the server if there is no open input stream (i.e., received before a client_stream/start or after a client_stream/end) or the client is not available.
Clients MUST send client_stream/start before the first audio chunk.

• Byte 0: message type 12 (uint8)
• Bytes 1-8: timestamp (big-endian int64) - server clock time in microseconds when the first sample was captured
• Rest of bytes: encoded audio frame

The timestamp indicates when the first audio sample in this chunk was captured (in server time domain). The server MAY resample/transcode and then distribute the audio to players with its normal buffering and synchronization strategy.

A device that implements both source and player MUST NOT play its captured input locally. Like every player, it outputs only the stream the server distributes, so its output stays in sync with the rest of the group.

Note: Source timestamps are derived from the client's clock offset, which the time filter keeps re-estimating, so they may show discontinuities or drift (e.g., ADC clock variance). Server implementations SHOULD NOT assume perfectly continuous timestamps; the audio sample stream itself SHOULD remain continuous.