Implement the visualizer@v1 role (aiosendspin 6.x compatibility)

[ecohash-co]

Summary

The visualizer role is currently a placeholder: client/hello encodes
visualizer@v1_support as an empty {}, the stream/start visualizer block decodes
to an empty struct, and only binary type 16 is recognized. Against aiosendspin 6.x
(Music Assistant 2.9.x) this is worse than "not implemented": the server validates
the hello support object strictly and hard-rejects the entire client/hello when
visualizer@v1 is advertised with an empty support object, so turning the role on
breaks the whole connection during the handshake. (aiosendspin
models/visualizer.py ClientHelloVisualizerSupport requires non-empty types,
positive buffer_capacity and rate_max, and a spectrum object whenever
"spectrum" is in types.)

This PR implements the role end-to-end, following the existing artwork-role patterns:

• VisualizerConfiguration (public, throws(ConfigurationError), mirrors
  ArtworkConfiguration): feature types (loudness / beat / f_peak / spectrum /
  peak / pitch), spectrum binning, bufferCapacity, rateMax. SendspinClient
  gains a visualizerConfig: parameter; advertising .visualizerV1 without one
  throws .visualizerRoleRequiresConfiguration, so the rejected empty shape can no
  longer be sent (same pattern as .playerRoleRequiresConfiguration).
• client/hello: the internal VisualizerSupport wire struct now carries the
  validated real fields (buffer_capacity, rate_max, types, spectrum).
• stream/start: the negotiated visualizer announcement decodes into the public
  StreamVisualizerConfig (types, rate_max, tracks_downbeats, spectrum) and
  surfaces as ClientEvent.visualizerStreamStarted(_:) +
  SendspinClient.currentVisualizerStream. Decoding is tolerant: unknown feature
  strings are dropped and a malformed visualizer block cannot fail the whole
  stream/start (which would also kill the player section and silence audio).
• Binary types 17–21 (beat, f_peak, spectrum, peak, pitch — aiosendspin
  models/types.py BinaryMessageType) are recognized and routed through the
  existing gate/clock-sync checks to the visualizerData stream; previously they
  were dropped as unknown type IDs at BinaryMessage.init. Type 16
  (.visualizerData) is renamed .visualizerLoudness per the per-feature ID
  allocation (internal enum, no public API break).
• VisualizerData now carries the feature type (without it, consumers of the
  multi-type stream can't tell a loudness frame from a beat frame — the type byte is
  stripped with the header) and offers frame(spectrumBins:) decoding into the new
  typed VisualizerFrame enum. Payload layouts follow the reference wire packing
  (server/roles/visualizer/v1.py, all big-endian: loudness u16; beat flags byte,
  bit 0 = downbeat; f_peak u16 freq + u16 amp; spectrum n_disp_bins × u16; peak
  u8; pitch u16 MIDI Q8.8 + u8 confidence). Wrong-length payloads reject rather
  than mis-decode; spectrum frames require the negotiated bin count for sizing.

One field-derived default worth calling out: rateMax defaults to 30 Hz, not
60. aiosendspin queues visualizer frames per-role for the entire audio write-ahead
window in a 4096-slot queue; at 5 feature types × 60 Hz (300 frames/s), the queue
overflows once write-ahead exceeds ~13.6 s — which a 2 MB player buffer_capacity
reaches on well-compressed FLAC — and the server then disconnects the client
("Role queue full for visualizer"). 30 Hz keeps a 5-type client safe past 27 s of
write-ahead. Found and verified against a live Music Assistant 2.9.8 /
aiosendspin 6.0.5 server.

Commits

1. feat(visualizer): implement the visualizer@v1 role per aiosendspin 6.0.5 —
   models + client wiring + CHANGELOG, plus mechanical updates of the three
   existing tests that referenced .visualizerData / the empty
   StreamStartVisualizer.
2. test(visualizer): aiosendspin 6.0.5 conformance fixtures — 15 golden-message
   tests hand-derived from the reference implementation
   (Tests/SendspinKitTests/Models/VisualizerModelTests.swift), including the
   regression guard that the encoded support object can never again be {}.

Test evidence

On macOS (Apple Silicon, Swift 6.2.3 / Xcode 26.2 toolchain):

• swift test — 567 tests in 50 suites, all passing (upstream main is 552;
  +15 new visualizer conformance tests; all pre-existing tests green, including the
  updated FrameOrderingTests visualizer gate/clock-sync ordering tests).
• swiftlint lint --strict — clean.
• swiftformat --lint (0.62.1) — all files touched by this PR are clean. (Note:
  0.62.1 flags ~15 untouched files on current main — e.g.
  GroupUpdatePayload.encode's single-line if bodies — a rule-drift of the newer
  swiftformat vs. the version CI installed on the last main run. Not introduced
  here.)

Compatibility

• No breaking public API changes: visualizerConfig: is a new defaulted init
  parameter; VisualizerData gains a field (it has no public initializer);
  StreamRole gains .visualizer; new public types are additive.
• Wire behavior change: clients that previously advertised .visualizerV1 (and were
  rejected by 6.x servers at hello) now fail fast at SendspinClient.init unless
  they provide a configuration.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CbdWgqSEcL2JhwBkwabRy3

[teancom]

This is amazing! Thank you so much. One small nit and then it looks great.

[teancom]

A malformed server could send spectrumBins = Int.max, and then we trap when we try to double it. Please use checked multiplication or validate it in some other way before doing this calculation. A test for this would be great as well.

[teancom]

Oh, also I just fixed all of the existing swiftlint/swiftformat errors. If you could rebase or update the branch, it would make CI pass. 🙏