feat: add PipeWire muter functionality and service files for Sendspin audio player

internal/live/http.go

@@ -259,6 +259,19 @@ type stateView struct {
 
 func (h *HTTPServer) getState(w http.ResponseWriter, _ *http.Request) {
 	active, pb, vol, members := h.mgr.State()
+	// Fill in names for offline members from the roster — the manager
+	// only knows names of currently-connected clients.
+	if len(members) > 0 {
+		roster := map[string]string{}
+		for _, e := range h.roster.List() {
+			roster[e.ClientID] = e.Name
+		}
+		for i := range members {
+			if members[i].Name == "" {
+				members[i].Name = roster[members[i].ClientID]
+			}
+		}
+	}
 	writeJSON(w, http.StatusOK, stateView{
 		ActivePreset: active,
 		Playback:     pb,

internal/live/manager.go

@@ -27,6 +27,7 @@ type StateChange struct {
 // MemberState is per-speaker detail used by /api/state.
 type MemberState struct {
 	ClientID  string `json:"client_id"`
+	Name      string `json:"name,omitempty"`
 	Connected bool   `json:"connected"`
 	Muted     bool   `json:"muted"`
 	Volume    int    `json:"volume"`
@@ -416,6 +417,7 @@ func (m *Manager) State() (string, Playback, int, []MemberState) {
 				members[i].Connected = true
 				members[i].Muted = c.Muted
 				members[i].Volume = c.Volume
+				members[i].Name = c.Name
 			}
 		}
 	}

internal/live/web/index.html

@@ -348,11 +348,16 @@ function render() {
   } else {
     mEl.innerHTML = "";
     for (const m of state.members) {
+      const label = m.name || m.client_id;
+      const showID = m.name && m.name !== m.client_id;
       const div = document.createElement("div");
       div.className = "row";
       div.innerHTML = `
         <span class="dot ${m.connected ? 'connected' : ''}"></span>
-        <span class="grow mono">${escapeHTML(m.client_id)}</span>
+        <span class="grow">
+          <div>${escapeHTML(label)}</div>
+          ${showID ? `<div class="mono muted">${escapeHTML(m.client_id)}</div>` : ''}
+        </span>
         <span class="muted">${m.connected ? `vol ${m.volume}${m.muted ? ' · muted' : ''}` : 'offline'}</span>
       `;
       mEl.appendChild(div);

internal/pipewire/muter.go

@@ -0,0 +1,228 @@
+package pipewire
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log"
+	"os/exec"
+	"strconv"
+	"sync"
+	"time"
+)
+
+// Muter keeps a single PipeWire node muted or unmuted to match a desired
+// state, re-asserting periodically so transient failures (or external
+// interference) self-heal. Resolves the numeric node ID lazily because
+// PipeWire IDs change across restarts.
+//
+// Failure modes worth knowing:
+//   - wpctl missing: the muter logs once at construction and becomes a no-op.
+//   - Target node not present yet: resolution is retried on every tick,
+//     so it's fine to start the client before the loopback exists.
+//   - Process killed with SIGKILL: nothing can unmute. SIGINT/SIGTERM and
+//     normal exits run Stop, which forces unmute synchronously.
+type Muter struct {
+	nodeName string
+	hasWpctl bool
+
+	mu           sync.Mutex
+	desired      bool // desired muted state
+	lastApplied  int  // -1 = unknown, 0 = unmuted, 1 = muted
+	lastResolved int  // cached node ID, -1 = unknown
+	lastResolveErrLogged bool
+
+	wake chan struct{}
+	stop chan struct{}
+	done chan struct{}
+}
+
+// NewMuter constructs a Muter for the given node.name. The control loop
+// starts immediately and the node is forced to unmuted on startup as a
+// defensive measure against a previous run that crashed mid-mute.
+func NewMuter(nodeName string) *Muter {
+	m := &Muter{
+		nodeName:     nodeName,
+		lastApplied:  -1,
+		lastResolved: -1,
+		wake:         make(chan struct{}, 1),
+		stop:         make(chan struct{}),
+		done:         make(chan struct{}),
+	}
+	if _, err := exec.LookPath("wpctl"); err != nil {
+		log.Printf("muter: wpctl not found (%v); loopback mute disabled", err)
+	} else {
+		m.hasWpctl = true
+	}
+	go m.run()
+	return m
+}
+
+// SetDesiredMute updates the target state. Cheap and non-blocking; the
+// control loop applies it asynchronously and re-asserts on a ticker.
+func (m *Muter) SetDesiredMute(muted bool) {
+	m.mu.Lock()
+	changed := m.desired != muted
+	m.desired = muted
+	m.mu.Unlock()
+	if changed {
+		m.kick()
+	}
+}
+
+func (m *Muter) kick() {
+	select {
+	case m.wake <- struct{}{}:
+	default:
+	}
+}
+
+func (m *Muter) run() {
+	defer close(m.done)
+	if !m.hasWpctl {
+		<-m.stop
+		return
+	}
+
+	// Eager startup unmute so a previous crashed run can't leave the
+	// loopback stuck muted before the player has reported its state.
+	m.applyOnce(false)
+
+	ticker := time.NewTicker(3 * time.Second)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-m.stop:
+			return
+		case <-m.wake:
+		case <-ticker.C:
+		}
+		m.mu.Lock()
+		want := m.desired
+		m.mu.Unlock()
+		m.applyOnce(want)
+	}
+}
+
+// applyOnce resolves the node ID if needed and issues `wpctl set-mute`
+// when the desired state differs from what we last successfully applied.
+// On apply failure, lastApplied is left untouched so the next tick retries.
+func (m *Muter) applyOnce(muted bool) {
+	id, err := m.resolveID()
+	if err != nil {
+		return
+	}
+
+	m.mu.Lock()
+	last := m.lastApplied
+	m.mu.Unlock()
+
+	want := 0
+	if muted {
+		want = 1
+	}
+	if last == want {
+		return
+	}
+
+	if err := setMute(id, muted); err != nil {
+		log.Printf("muter: wpctl set-mute %d %d failed: %v", id, want, err)
+		return
+	}
+	m.mu.Lock()
+	m.lastApplied = want
+	m.mu.Unlock()
+}
+
+// resolveID returns the cached node ID, refreshing from pw-dump on first
+// use or after a wpctl failure invalidated it. The "not found" case is
+// logged once per outage so a missing loopback doesn't spam the log every
+// 3 seconds, but a successful resolution rearms the warning.
+func (m *Muter) resolveID() (int, error) {
+	m.mu.Lock()
+	cached := m.lastResolved
+	m.mu.Unlock()
+	if cached >= 0 {
+		return cached, nil
+	}
+
+	id, err := FindNodeIDByName(m.nodeName)
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if err != nil {
+		if !m.lastResolveErrLogged {
+			log.Printf("muter: %v (will keep retrying)", err)
+			m.lastResolveErrLogged = true
+		}
+		return -1, err
+	}
+	if m.lastResolveErrLogged {
+		log.Printf("muter: node.name=%q resolved to id %d", m.nodeName, id)
+		m.lastResolveErrLogged = false
+	}
+	m.lastResolved = id
+	// Force the next apply to re-issue the wpctl command, since a new ID
+	// almost certainly means a fresh node whose mute state we don't know.
+	m.lastApplied = -1
+	return id, nil
+}
+
+func setMute(id int, muted bool) error {
+	arg := "0"
+	if muted {
+		arg = "1"
+	}
+	cmd := exec.Command("wpctl", "set-mute", strconv.Itoa(id), arg)
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		return fmt.Errorf("%w: %s", err, string(out))
+	}
+	return nil
+}
+
+// Stop tears the muter down. It forces an unmute (retried a few times)
+// before returning so a normal-exit path leaves the loopback in the
+// expected state even if wpctl was briefly flaky. Safe to call multiple
+// times.
+func (m *Muter) Stop(ctx context.Context) {
+	select {
+	case <-m.stop:
+		return
+	default:
+	}
+	close(m.stop)
+	<-m.done
+
+	if !m.hasWpctl {
+		return
+	}
+	if err := m.forceUnmute(ctx); err != nil {
+		log.Printf("muter: WARNING failed to unmute %q on shutdown: %v — loopback may be stuck muted", m.nodeName, err)
+	}
+}
+
+func (m *Muter) forceUnmute(ctx context.Context) error {
+	var lastErr error
+	backoff := 100 * time.Millisecond
+	for attempt := 0; attempt < 3; attempt++ {
+		if ctx.Err() != nil {
+			return errors.Join(lastErr, ctx.Err())
+		}
+		id, err := FindNodeIDByName(m.nodeName)
+		if err != nil {
+			lastErr = err
+		} else if err := setMute(id, false); err != nil {
+			lastErr = err
+		} else {
+			return nil
+		}
+		select {
+		case <-ctx.Done():
+			return errors.Join(lastErr, ctx.Err())
+		case <-time.After(backoff):
+		}
+		backoff *= 2
+	}
+	return lastErr
+}

internal/pipewire/nodes.go

@@ -62,6 +62,32 @@ func listAllNodes() ([]Node, error) {
 	return nodes, nil
 }
 
+// FindNodeIDByName scans every PipeWire node (not just Audio/*) and returns
+// the numeric ID of the first one whose node.name matches. Used by the
+// loopback muter, where the target may be a stream/loopback rather than a
+// sink/source. Returns -1 with an error when no match is found.
+func FindNodeIDByName(name string) (int, error) {
+	out, err := exec.Command("pw-dump").Output()
+	if err != nil {
+		return -1, fmt.Errorf("pw-dump: %w", err)
+	}
+
+	var objects []pwObject
+	if err := json.Unmarshal(out, &objects); err != nil {
+		return -1, fmt.Errorf("parse pw-dump: %w", err)
+	}
+
+	for _, o := range objects {
+		if o.Type != "PipeWire:Interface:Node" {
+			continue
+		}
+		if o.Info.Props.NodeName == name {
+			return o.ID, nil
+		}
+	}
+	return -1, fmt.Errorf("no PipeWire node with node.name=%q", name)
+}
+
 func ListSinks() ([]Node, error) {
 	all, err := listAllNodes()
 	if err != nil {

internal/pipewire/output.go

@@ -56,7 +56,8 @@ func (o *Output) Open(sampleRate, channels, bitDepth int) error {
 
 func (o *Output) startUnlocked() error {
 	nameJSON, _ := json.Marshal(o.nodeName)
-	props := fmt.Sprintf(`{"node.name":%s}`, nameJSON)
+	latency := fmt.Sprintf("960/%d", o.sampleRate)
+	props := fmt.Sprintf(`{"node.name":%s,"node.latency":"%s"}`, nameJSON, latency)
 
 	args := []string{
 		"--playback",
@@ -64,6 +65,7 @@ func (o *Output) startUnlocked() error {
 		"--format", "s32",
 		"--rate", strconv.Itoa(o.sampleRate),
 		"--channels", strconv.Itoa(o.channels),
+		"--latency", latency,
 		"--properties", props,
 	}
 	if o.target != "" {