SendSpin

[imonlinux]

Let's kick the tires!

# Install + Testing: Sendspin Client (branch: `sendspin_client`)

This branch adds a **Sendspin client** to Linux Voice Assistant (LVA) so it can register as a **Music Assistant (MA) Sendspin player**, receive **PCM audio streams**, and support **volume/mute** control from MA.

Key features included:

- mDNS discovery of Music Assistant’s Sendspin server (`_sendspin-server._tcp.local.`)
- WebSocket handshake (`client/hello` → wait for `server/hello`)
- Player registration in MA (shows up as a player)
- PCM streaming playback through **mpv** (rawaudio over stdin)
- Volume + mute commands from MA applied **independently** of LVA’s own volume
- Persist last Sendspin volume to `preferences.json` and restore it on startup
- Audio ducking based on LVA events

---

1) Clone the branch

git clone --branch sendspin_client --single-branch https://github.com/imonlinux/linux-voice-assistant
cd linux-voice-assistant

---

2) Install dependencies

Run setup with the flag for sendspin:

script/setup --sendspin

---

3) Update config.json to enable Sendspin

Add a sendspin section at the top-level of your config.json.

Minimal example:

{
  "sendspin": {
    "enabled": true,
    "connection": {
      "mdns": true
    }
  }
}

See the config.json.example for all the Sendspin configuration options

This is my working config file at the time that this is posted.

{
  "app": {
    "name": "LVA Sendspin"
  },
  "audio": {
    "volume_sync": false,
    "max_volume_percent": 100
  },
  "mqtt": {
    "host": "192.168.1.2",
    "port": 1883,
    "username": "mqtt_user",
    "password": "mqtt_password"
  },
  "led": {
    "enabled": true,
    "led_type": "dotstar",
    "interface": "gpio",
    "clock_pin": 13,
    "data_pin": 12,
    "num_leds": 40
  },
  "button": {
    "enabled": true,
    "mode": "gpio",
    "pin": 17,
    "long_press_seconds": 1.0,
    "poll_interval_seconds": 0.01
  },
  "sendspin": {
    "enabled": true,
    "connection": {
      "mode": "client_initiated",
      "mdns": true,
      "server_host": null,
      "server_port": 8927,
      "server_path": "/sendspin"
    },
    "roles": {
      "player": true,
      "metadata": true,
      "controller": true,
      "artwork": false,
      "visualizer": false
    },
    "player": {
      "preferred_codec": "pcm",
      "supported_codecs": ["pcm"],
      "sample_rate": 48000,
      "channels": 2,
      "bit_depth": 16,
      "buffer_capacity_bytes": 1048576
    }
  }
}

Notes:

• If connection.server_host is set, mDNS discovery is skipped.
• If both are omitted, the client will attempt mDNS discovery if mdns: true.

---

4) Preferences: persisting Sendspin volume

This branch persists the last Sendspin client volume to preferences.json so it can be restored at startup and reported to MA immediately.

Example preferences.json:

{
  "active_wake_words": ["okay_computer"],
  "volume_level": 1.0,
  "num_leds": 40,
  "alarm_duration_seconds": 10,

  // New:
  "sendspin_volume": 42
}

Notes:

• sendspin_volume is 0–100 (Sendspin/MA style).
• This is intentionally independent from volume_level (LVA master OS volume). I haven't tested with "volume_sync": true.

---

5) Start LVA and verify Sendspin connects

Run LVA with debug enabled so you can see the handshake:

script/run --debug

What you should see (examples):

• Discovery:

  • Sendspin: discovered ... _sendspin-server._tcp.local. -> <ip>:8927/sendspin

• Websocket connect:

  • Sendspin: connecting to ws://<ip>:8927/sendspin

• Handshake:

  • client/hello sent
  • server/hello received

• State heartbeats:

  • client/state heartbeat sent ...

---

6) Test in Music Assistant UI

1. Open Music Assistant.
2. Go to Players.
3. Confirm a new player appears (e.g. LVA Sendspin or the MAC-derived ID).
4. Select that player and start playback of a track.

Expected results:

• Audio plays from the LVA host speakers.
• MA volume slider changes the Sendspin client volume.
• Mute toggles apply.

---

7) Test volume + mute behavior

Volume test (MA → LVA Sendspin)

• In MA, set the player volume to 50%.

• In LVA logs, you should see:

  • server/command ... {"command":"volume","volume":50}
  • followed by client/state ... {"volume":50,...}

Mute test

• Toggle mute in MA.
• LVA logs should show a server/command with mute and state updates.

---

8) Ducking while wakeword/voice is active

The Sendspin client can duck MA playback when LVA transitions into voice states.

Typical events published by LVA include:

• voice_listen
• voice_thinking
• voice_responding
• voice_idle

Expected behavior:

• When a wake word triggers and LVA enters listening/thinking/responding, Sendspin audio is reduced (duck).
• When LVA returns to idle, Sendspin audio restores (unduck).

---

9) Restart requirements

You must restart LVA for config/preference changes to apply.

If running as a systemd user service:

systemctl --user restart linux-voice-assistant.service

---

Quick “Known-good” smoke test checklist

• sendspin.enabled=true in config.json
• mpv installed (this should already be the case)
• LVA starts with --debug
• MA shows player “LVA Sendspin”
• Track plays and audible output occurs
• MA volume slider changes audible volume
• sendspin_volume is saved to preferences.json
• Restart LVA → player comes up with prior volume restored

[cknic]

This would be very cool and i'm definitely willing to help test it out.

[imonlinux]

Hey @cknic. First working attempt posted to the repo.

[imonlinux]

Just pushed some minor bug fixes (mute in MA didn't mute the sendspin client). Also added the option to not duck sendspin audio on voice events. Default behavior is to duck to 20%.

[imonlinux]

Today's push has fixed some bugs with the sendspin player disconnecting on track change and pause events from the MA.

Up next will be to enable additional codecs as the client is currently hard coded to PCM.

[rnieuwen]

Hey there! I guess I can just switch to the sendspin branch on an existing linux-voice-assistant right?

[imonlinux]

Hey @rnieuwen, you can if you like. What I usually do is stop the LVA service, mv the current linux-voice-assistant folder to something like linux-voice-assistant_save. I then clone the branch as a I want to test. This prevents issues that can come up with switching branches instead. You will protect your config.json and preferences.json files which can be copied over to the new branch after you run the script/setup --sendspin to set it up.

btw, the sendspin_client branch includes the changes made for configurable_oww_thresholds including the available options documented in the config.json.example file.

[imonlinux]

I just pushed a change that enable the configuration of supported and preferred codec via config.json setting. I have also added opuslib as a python library dependency in pyproject.toml. You will need to run script/setup --sendspin again to install it.

Currently opus, flac, and pcm are working. This is the relevant setting for config.json. I just submitted the commit that enables reliable playback with flac via ffmpeg. FFMPEG is a dependency for flac support and must be installed in the OS. Default path is /usr/bin/ffmpeg but it is a configuration option noted in the config.json.example file.

,
  "sendspin": {
    "enabled": true,
    "coordination": { 
      "duck_during_voice": true },
    "connection": {
      "mode": "client_initiated",
      "mdns": true,
      "server_host": null,
      "server_port": 8927,
      "server_path": "/sendspin" },
    "roles": {
      "player": true,
      "metadata": true,
      "controller": true,
      "artwork": false,
      "visualizer": false },
    "player": {
      "preferred_codec": "opus",
      "supported_codecs": ["opus","flac","pcm"],
      "sample_rate": 48000,
      "channels": 2,
      "bit_depth": 16,
      "buffer_capacity_bytes": 1048576
    }
  }

[imonlinux]

I just merged the sendspin and configurable_oww_thresholds branches into main.

Feel free to open issue if you run into anything.

[JenniferHatches]

Is the audio supposed to actually be synchronized between devices? I've got a rpi4 and a rpi5 and they are far from synchronized when playing in a sendspin group.

[imonlinux]

Hey @JenniferHatches, that is great question. I did that same test and had the exact same result. The lack of synchronicity between clients were even more pronounced when they were using different codec (flac).

I just thought about doing the same test with browsers as they are automatically registered as clients when you open MA. I will share what I find.

[imonlinux]

I just added a clock_sync.py function to the sendspin client. There is a significant number of knobs available for the config.json file to help tune the client. All of the options and a description of their function has been added to the config.json.example file.

[imonlinux]

The changes continue. I had the LVA Sendspin code compared to the Sendspin-CLI client and implemented a lot of the sync functionality that is used in that project. I am now able to establish a stable sync with an ESP32-S3 sendspin client without it drifting. These are the sendspin config.json settings that I am using. All knobs have been updated in the config.json.example file.

"sendspin": {
  "enabled": true,
  "connection": {
    "time_sync_adaptive": true,
    "time_sync_interval_seconds": 1.0
  },
  "player": {
    "output_latency_ms": -600,
    "sync_target_latency_ms": 350,
    "sync_late_drop_ms": 250
  }
}

Due to differences in chipsets and the mpv player pipeline, there may be a consistent lead/lag when compared to other sendspin clients. Especially when they are on other platforms (i.e. ESP32). The best knob for bringing the LVA sendspin client into initial sync (calibrate) is the output_latency_ms. My client was a ~1 second behind the other player. The -600 value has closed that to a point that it is hard to hear a difference, but you may need to adjust accordingly based on what your testing show.

Here is a good rule for tuning:

LVA player 1 second behind other player = "output_latency_ms": -600
LVA player 1 second ahead other player = "output_latency_ms": 600

Then make adjustments until the two players are synchronized.

[JenniferHatches]

I can say that with the latest version, music does sync between my clients.
I don't have any esp32 based media players right now, because media players don't work on the m5stack atom echo (I have 3 of these doing voice assistant stuff).

[dthreee]

Just did a fresh install and, although I'm not using sendspin, I could not get the LVA service to work without installing it.

[imonlinux]

Hey @dthreee, thanks for letting me know. I have just committed an update that removes the websocket dependency when not using sendspin.