Refactor SDK into modular core/player architecture

[balloob]

Summary

Split the monolithic SDK into a composable architecture where the core protocol/decoding layer is separated from Web Audio playback. This enables:

• Visualization apps to consume the raw PCM stream without playback overhead
• Conformance tests to test protocol handling without needing Web Audio
• External WebSocket management — pass in a pre-established socket instead of a URL
• Configurable sync correction thresholds per correction mode

The SendspinPlayer public API is unchanged — existing consumers are unaffected.

Final structure

src/
  index.ts                           SendspinPlayer + public re-exports
  types.ts                           All shared types + CorrectionThresholds

  core/
    core.ts                          SendspinCore (protocol + decode coordinator)
    protocol-handler.ts              Slim message routing (342 lines, was 604)
    time-sync-manager.ts             NTP burst lifecycle (extracted)
    codec-support.ts                 Browser codec detection (extracted)
    state-manager.ts                 Observable state store
    time-filter.ts                   Kalman filter clock sync
    websocket-manager.ts             WebSocket + adopt() for external sockets

  audio/
    scheduler.ts                     Scheduling + sync correction (688 lines, was 1581)
    clock-source.ts                  Output timestamp validation state machine
    recorrection-monitor.ts          Drift detection with transient filtering
    output-latency-tracker.ts        EMA latency smoothing + persistence
    decoder.ts                       PCM/Opus/FLAC → Float32Array[]

New public exports

Export	Purpose
SendspinPlayer	Same API as before — drop-in replacement
SendspinCore	Protocol + decode only — emits DecodedAudioChunk
SendspinDecoder	Standalone audio decoder
AudioScheduler	Standalone Web Audio scheduler
DecodedAudioChunk	{ samples: Float32Array[], sampleRate, serverTimeUs, generation }
CorrectionThresholds	Per-mode sync correction tuning

Usage examples

Visualization app (tap into PCM stream):

const core = new SendspinCore({ baseUrl: "http://..." });
core.onAudioData = (chunk) => {
  renderWaveform(chunk.samples); // Float32Array[] per channel
};
await core.connect();

External WebSocket (no baseUrl needed):

const ws = new WebSocket("wss://my-proxy/sendspin");
const core = new SendspinCore({ webSocket: ws });
await core.connect();

Custom correction thresholds:

const player = new SendspinPlayer({
  baseUrl: "http://...",
  correctionThresholds: { sync: { resyncAboveMs: 400 } },
});

Changes

• Monolith split: audio-processor.ts (2261 lines) → audio/decoder.ts + audio/scheduler.ts + 3 sub-modules
• Protocol handler split: protocol-handler.ts (604 lines) → slim handler + time-sync-manager.ts + codec-support.ts
• Type safety: WebSocketManager.send() typed as ClientMessage instead of any
• Environment compat: window.setTimeout → globalThis.setTimeout everywhere
• External WebSocket: webSocket config option with WebSocketManager.adopt(); baseUrl now optional
• Configurable thresholds: correctionThresholds config option with per-mode partial overrides

Test plan

• Verify SendspinPlayer works identically to before (connect, play, volume, sync)
• Verify SendspinCore standalone emits DecodedAudioChunk events
• Verify external WebSocket pass-through works
• Verify correction threshold overrides apply correctly
• Build succeeds with tsc --noEmit

https://claude.ai/code/session_018UYYEXUZVuQ2Z4Texa7W6m

[balloob]

Validated and it works both in sendspin-js demo website + as part of sendspin party.

[maximmaxim345]

Nice! Thanks @balloob !
Tested on Chromium and Safari in through Music Assistant and the sample player, as well as on a Google Home mini.