Refactor SDK into modular core/player architecture

README.md

@@ -65,6 +65,65 @@ player.sendCommand('switch');  // Switch group
 player.disconnect('user_request');
 ```
 
+## Advanced configuration
+
+### Bring your own WebSocket
+
+Provide an already-open (or CONNECTING) `WebSocket` via `webSocket` to let the
+player adopt it instead of creating a new one. Useful when the connection is
+managed by a surrounding app framework. Auto-reconnect is disabled for adopted
+sockets.
+
+```typescript
+const ws = new WebSocket('ws://your-server:8095/sendspin');
+const player = new SendspinPlayer({
+  playerId: 'my-player',
+  clientName: 'My Player',
+  webSocket: ws,
+});
+await player.connect();
+```
+
+### Tuning correction thresholds
+
+Override the per-mode thresholds that control when/how the scheduler corrects
+drift. Unspecified fields keep their defaults.
+
+```typescript
+const player = new SendspinPlayer({
+  baseUrl: 'http://your-server:8095',
+  correctionMode: 'sync',
+  correctionThresholds: {
+    sync: {
+      resyncAboveMs: 400,   // tolerate more drift before hard resync
+      deadbandBelowMs: 2,   // ignore errors under 2ms
+    },
+  },
+});
+```
+
+### Core + scheduler as separate layers
+
+Apps that need the decoded PCM stream (e.g. visualizers) can use
+`SendspinCore` on its own and skip the playback layer. `SendspinCore` emits
+`DecodedAudioChunk` events; `AudioScheduler` is the Web Audio consumer that
+`SendspinPlayer` wires for you.
+
+```typescript
+import { SendspinCore } from '@sendspin/sendspin-js';
+
+const core = new SendspinCore({
+  baseUrl: 'http://your-server:8095',
+});
+
+core.onAudioData = (chunk) => {
+  // chunk.samples: Float32Array per channel
+  // chunk.sampleRate, chunk.serverTimeUs, chunk.generation
+};
+
+await core.connect();
+```
+
 ## Local development
 
 ```

index.html

@@ -261,6 +261,37 @@ <h2>Local Controls</h2>
               so it may drift vs. other devices.
             </small>
           </div>
+          <details class="form-group">
+            <summary>Advanced: correction thresholds</summary>
+            <p>
+              <small
+                >Override per-mode tuning for the active correction mode.
+                Applied on connect — reconnect to apply changes.</small
+              >
+            </p>
+            <div class="form-group">
+              <label for="resync-threshold">Resync above (ms)</label>
+              <input
+                type="number"
+                id="resync-threshold"
+                placeholder="default"
+                min="0"
+                step="1"
+              />
+              <small>Hard resync when smoothed sync error exceeds this.</small>
+            </div>
+            <div class="form-group">
+              <label for="deadband-threshold">Deadband below (ms)</label>
+              <input
+                type="number"
+                id="deadband-threshold"
+                placeholder="default"
+                min="0"
+                step="0.5"
+              />
+              <small>Ignore errors smaller than this — no correction.</small>
+            </div>
+          </details>
         </section>
 
         <!-- Status Section -->

public/app.js

@@ -24,6 +24,8 @@ const STORAGE_KEYS = {
   MUTED: "sendspin-muted",
   SYNC_DELAY: "sendspin-sync-delay",
   CORRECTION_MODE: "sendspin-correction-mode",
+  RESYNC_THRESHOLD: "sendspin-resync-threshold",
+  DEADBAND_THRESHOLD: "sendspin-deadband-threshold",
 };
 
 // DOM Elements
@@ -39,6 +41,8 @@ const muteIcon = document.getElementById("mute-icon");
 const syncDelayInput = document.getElementById("sync-delay");
 const applySyncDelayBtn = document.getElementById("apply-sync-delay");
 const correctionModeSelect = document.getElementById("correction-mode");
+const resyncThresholdInput = document.getElementById("resync-threshold");
+const deadbandThresholdInput = document.getElementById("deadband-threshold");
 const groupVolumeSlider = document.getElementById("group-volume-slider");
 const groupVolumeValue = document.getElementById("group-volume-value");
 const groupMuteBtn = document.getElementById("group-mute-btn");
@@ -426,6 +430,20 @@ function loadSettings() {
   if (savedCorrectionMode !== null) {
     correctionModeSelect.value = savedCorrectionMode;
   }
+
+  const savedResyncThreshold = localStorage.getItem(
+    STORAGE_KEYS.RESYNC_THRESHOLD,
+  );
+  if (savedResyncThreshold !== null && resyncThresholdInput) {
+    resyncThresholdInput.value = savedResyncThreshold;
+  }
+
+  const savedDeadbandThreshold = localStorage.getItem(
+    STORAGE_KEYS.DEADBAND_THRESHOLD,
+  );
+  if (savedDeadbandThreshold !== null && deadbandThresholdInput) {
+    deadbandThresholdInput.value = savedDeadbandThreshold;
+  }
 }
 
 /**
@@ -456,6 +474,28 @@ function sanitizeSyncDelay(delay) {
   return Math.max(0, Math.min(5000, Math.round(delay)));
 }
 
+/**
+ * Build a correctionThresholds override from the Advanced inputs.
+ * Returns undefined when no override is set for the current mode.
+ */
+function buildCorrectionThresholds(mode) {
+  const overrides = {};
+  const resyncRaw = resyncThresholdInput?.value;
+  const deadbandRaw = deadbandThresholdInput?.value;
+  const resync = resyncRaw ? parseFloat(resyncRaw) : NaN;
+  const deadband = deadbandRaw ? parseFloat(deadbandRaw) : NaN;
+  if (Number.isFinite(resync) && resync >= 0) {
+    overrides.resyncAboveMs = resync;
+  }
+  if (Number.isFinite(deadband) && deadband >= 0) {
+    overrides.deadbandBelowMs = deadband;
+  }
+  if (Object.keys(overrides).length === 0) {
+    return undefined;
+  }
+  return { [mode]: overrides };
+}
+
 /**
  * Save correction mode to localStorage
  */
@@ -518,12 +558,15 @@ async function connect() {
     const savedCorrectionMode =
       localStorage.getItem(STORAGE_KEYS.CORRECTION_MODE) || "sync";
 
+    const correctionThresholds = buildCorrectionThresholds(savedCorrectionMode);
+
     player = new SendspinPlayer({
       playerId: getPlayerId(),
       baseUrl: serverUrl,
       clientName: "Sendspin Sample Player",
       syncDelay: sanitizedSyncDelay,
       correctionMode: savedCorrectionMode,
+      correctionThresholds,
       onStateChange,
     });
 
@@ -684,6 +727,18 @@ function init() {
   muteBtn.addEventListener("click", toggleMute);
   applySyncDelayBtn.addEventListener("click", applySyncDelay);
   correctionModeSelect.addEventListener("change", applyCorrectionMode);
+  resyncThresholdInput?.addEventListener("change", () => {
+    localStorage.setItem(
+      STORAGE_KEYS.RESYNC_THRESHOLD,
+      resyncThresholdInput.value,
+    );
+  });
+  deadbandThresholdInput?.addEventListener("change", () => {
+    localStorage.setItem(
+      STORAGE_KEYS.DEADBAND_THRESHOLD,
+      deadbandThresholdInput.value,
+    );
+  });
   groupVolumeSlider.addEventListener("input", () => {
     player.sendCommand("volume", {
       volume: parseInt(groupVolumeSlider.value, 10),