[1.7.0] - 2026-05-05
Highlights
- Time-sync filter overhauled to canonical Sendspin/time-filter spec — faster convergence, better recovery from clock jumps, drift adapts to oscillator wander.
- Burst-pattern clock sync replaces the per-second single-message pattern, matching
sendspin-cpp'stime_burstand the upstream README's "Recommended Usage". - Player metadata correctly merges partial server updates instead of clobbering unchanged fields. Track navigation no longer silently drops Artist/Album.
- Server broadcasts metadata on playback-state transitions and on demand.
- WebSocket heartbeat detects half-open connections, triggers reconnect.
Added
pkg/sync.NewClockSyncWithConfig(cfg TimeFilterConfig)— construct aClockSyncwith a custom filter configuration.pkg/sync.TimeFilterConfig.MaxErrorScale— scalesmax_errorbefore use as the measurement standard deviation. Defaults to canonical 0.5; values <1 indicatemax_erroroverestimates noise.pkg/sync.TimeFilter.GetCovariance() int64— returns offset variance in µs². Mirrors the upstream C++get_covariance().pkg/protocol.MetadataState.HasField(jsonKey string) bool— distinguishes "field omitted" from "field set to null" in incomingserver/statemessages. Required for merge semantics.pkg/sendspin.Server.Addr() net.Addr— returns the bound network address afterStart(). Useful for tests usingPort: 0and any caller needing the actual port.pkg/sendspin.MetadataGroupRole.BroadcastMetadata()— pushes the current metadata snapshot to every attached metadata-role client. For HLS playlist advance, controller-driven track changes, etc.pkg/sendspin.GroupPlaybackStateChangedEvent— published byGroup.SetPlaybackStateon actual transitions.pkg/sendspin.PlaybackStateChangedHandler— optionalGroupRoleinterface; roles implementing it receive playback-state-change notifications.
Changed
DefaultTimeFilterConfig()adopts canonical upstream values (Sendspin/time-filter PR #6, 2026-04-27):process_std_dev=0.0,drift_process_std_dev=1e-11,forget_factor=2.0,adaptive_cutoff=3.0,
max_error_scale=0.5. The filter converges faster and recovers more strongly from clock jumps. Wire-compatible with prior versions and withaiosendspin.- Time-sync now uses a burst pattern. The receiver sends 8 messages back-to-back every 10 seconds and feeds only the lowest-RTT sample to the filter. Average network rate drops from 1 msg/s to 0.8 msg/s (bursty).
pkg/sync.ClockSyncquality is now σ-based, not RTT-based. Thresholds:<100µs→QualityGood,<5000µs→QualityDegraded, elseQualityLost. The RTT-discard branch (if rtt > 100ms: discard) is gone —
burst-best intrinsically rejects high-RTT outliers.GetStats().rttnow reports best-of-burst RTT.- Receiver merges metadata updates instead of replacing. Wire semantics:
- Field omitted from JSON → preserve prior value.
"key": null→ clear field."key": value→ replace.- Future-dated
MetadataState.Timestampdefers application until the receiver's clock-sync reaches that server time.
pkg/sendspin.NewServer(ServerConfig{Port: 0})no longer rewrites Port to 8927. The 8927 default is now supplied by the CLI flag layer (cmd/sendspin-server, examples).Port: 0means OS-assigned ephemeral
binding, matching Go convention.pkg/sendspin.Server.Start()binds the listener explicitly withnet.Listen+httpServer.Serve(listener)so the bound address is exposed viaServer.Addr().
Fixed
- Player half-open WebSocket detection.
pkg/protocol.Clientnow runs a 30 s ping / 60 s pong-wait heartbeat; if the server (or any middlebox) drops the connection silently, the client notices within ~60 s,
firesDone(), and the player's reconnect loop kicks in. Previously, the client could sit indefinitely sending into the void. - Player metadata loss on next/prev. Partial server updates that omitted unchanged fields previously collapsed Artist/Album to empty strings.
pkg/sendspinserver-test port-collision flakes. Tests now usePort: 0and read the actual port back viaServer.Addr(). Eliminates the documentedTestServerStartStopport-8929 flake and ~5 related tests
that timed out in 0.10–0.22 s under heavy parallel-race -v ./...load.- Pre-commit
go-build-allhook. Was building the deletedcmd/test-sync. Now buildscmd/sendspin-server(matches the Makefile'smaketarget). make conformancefrom non-primary worktrees. The redundantln -sfnstep that collided on a stale junction has been removed; the harness env-varCONFORMANCE_REPO_SENDSPIN_GOis sufficient (and was already
being passed).- Cosmetic stale value in a sync test's error-message string (
default (1.0)→default (0.5)after the canonical default flip).
Internal
- Plan documents added in
docs/superpowers/plans/for time-filter Phase A & B, burst pattern, server-test port flakes, metadata tristate, server metadata broadcast, WebSocket heartbeat. Each plan + paired
implementer/validator audits documents the rationale. - Heartbeat constants are package-level vars (lowercase, unexported) so tests can override with short values; production code never mutates them.
Wire compatibility
All conformance scenarios pass against aiosendspin and against sendspin-go itself: 12/12 across Client Initiated PCM, Server Initiated PCM, Metadata, Artwork, Controller, FLAC. No protocol changes, no breaking changes for existing clients or servers.
Downloads
| Platform | Player | Server |
|---|---|---|
| Linux x86_64 | sendspin-player-linux-amd64.tar.gz
| sendspin-server-linux-amd64.tar.gz
|
| Linux ARM64 | sendspin-player-linux-arm64.tar.gz
| sendspin-server-linux-arm64.tar.gz
|
| macOS Apple Silicon | sendspin-player-darwin-arm64.tar.gz
| sendspin-server-darwin-arm64.tar.gz
|
| Windows x86_64 | sendspin-player-windows-amd64.zip
| sendspin-server-windows-amd64.zip
|
Daemon mode (Linux)
tar xzf sendspin-player-linux-amd64.tar.gz
sudo install -m 755 sendspin-player-linux-amd64 /usr/local/bin/sendspin-player
# Copy the systemd unit from dist/systemd/ in the source repo, then:
sudo systemctl enable --now sendspin-player