@lox-audioserver/node-slimproto 0.1.0 → 0.1.2

package/dist/client.d.ts

@@ -25,6 +25,9 @@ export declare class SlimClient {
     private _autoPlay;
     private _heartbeatTimer;
     private _heartbeatId;
+    private readonly heartbeatSentAt;
+    private pendingClockSync;
+    private clockBase;
     constructor(socket: net.Socket, callback: SlimClientCallback);
     disconnect(): void;
     get connected(): boolean;
@@ -42,6 +45,26 @@ export declare class SlimClient {
     get elapsedMilliseconds(): number;
     get jiffies(): number;
     get lastHeartbeatAt(): number | null;
+    /**
+     * Best-effort mapping between server wall clock time (ms) and player jiffies.
+     * Derived from `strm t` / `stat STMt` heartbeat exchange.
+     */
+    get clockSync(): {
+        serverTimeMs: number;
+        jiffies: number;
+        rttMs: number;
+        updatedAtMs: number;
+    } | null;
+    /**
+     * Estimate the player jiffies value at the given server time.
+     * Returns a 32-bit unsigned timestamp suitable for `unpauseAt`.
+     */
+    estimateJiffiesAt(serverTimeMs: number): number;
+    /**
+     * Request an immediate clock sync sample (one `strm t` roundtrip).
+     * Resolves true when the matching STMt arrives, false on timeout or disconnect.
+     */
+    requestClockSync(timeoutMs?: number): Promise<boolean>;
     stop(): Promise<void>;
     play(): Promise<void>;
     pause(): Promise<void>;

package/dist/client.js

@@ -27,6 +27,9 @@ export class SlimClient {
     _autoPlay = false;
     _heartbeatTimer = null;
     _heartbeatId = 0;
+    heartbeatSentAt = new Map();
+    pendingClockSync = new Map();
+    clockBase = null;
     constructor(socket, callback) {
         this.socket = socket;
         this.callback = callback;
@@ -96,6 +99,67 @@ export class SlimClient {
     get lastHeartbeatAt() {
         return this._lastTimestamp || null;
     }
+    /**
+     * Best-effort mapping between server wall clock time (ms) and player jiffies.
+     * Derived from `strm t` / `stat STMt` heartbeat exchange.
+     */
+    get clockSync() {
+        return this.clockBase;
+    }
+    /**
+     * Estimate the player jiffies value at the given server time.
+     * Returns a 32-bit unsigned timestamp suitable for `unpauseAt`.
+     */
+    estimateJiffiesAt(serverTimeMs) {
+        if (!this.clockBase) {
+            return Math.max(0, Math.round(this._jiffies + (serverTimeMs - Date.now()))) >>> 0;
+        }
+        const delta = Math.round(serverTimeMs - this.clockBase.serverTimeMs);
+        const target = this.clockBase.jiffies + delta;
+        // Keep within uint32 domain (SlimProto uses 32-bit timestamps).
+        return (target >>> 0);
+    }
+    /**
+     * Request an immediate clock sync sample (one `strm t` roundtrip).
+     * Resolves true when the matching STMt arrives, false on timeout or disconnect.
+     */
+    async requestClockSync(timeoutMs = 800) {
+        if (!this._connected)
+            return false;
+        this._heartbeatId += 1;
+        const id = this._heartbeatId;
+        const sentAt = Date.now();
+        this.heartbeatSentAt.set(id, sentAt);
+        // Clean up old send timestamps to avoid unbounded growth.
+        for (const [key, value] of this.heartbeatSentAt) {
+            if (sentAt - value > 60_000) {
+                this.heartbeatSentAt.delete(key);
+            }
+        }
+        const result = await new Promise((resolve) => {
+            const timeout = setTimeout(() => {
+                this.pendingClockSync.delete(id);
+                resolve(false);
+            }, Math.max(50, timeoutMs));
+            timeout.unref?.();
+            this.pendingClockSync.set(id, (ok) => {
+                clearTimeout(timeout);
+                this.pendingClockSync.delete(id);
+                resolve(ok);
+            });
+            void this.sendStrm({
+                command: 't',
+                autostart: '0',
+                flags: 0,
+                replayGain: id,
+            }).catch(() => {
+                clearTimeout(timeout);
+                this.pendingClockSync.delete(id);
+                resolve(false);
+            });
+        });
+        return result;
+    }
     async stop() {
         if (this._state === PlayerState.STOPPED)
             return;
@@ -231,14 +295,28 @@ export class SlimClient {
             'Range: bytes=0-\r\n' +
             '\r\n', 'ascii');
         this._autoPlay = autostart;
+        const isSyncGroup = parsed.searchParams.has('sync') && parsed.searchParams.has('expect');
+        const expectCount = isSyncGroup ? Number(parsed.searchParams.get('expect') ?? '0') : 0;
+        // For sync-groups we want BUFFER_READY quickly so we can do coordinated unpause.
+        // With MP3 @ 256kbps, 200KB threshold can take ~6s to fill; lowering keeps groups snappy.
+        const thresholdKb = isSyncGroup ? (expectCount === 1 ? 32 : 64) : 200;
+        // For sync-groups we prefer a bit more output buffer to avoid early underruns,
+        // especially with lossless streams or weaker WiFi links.
+        // However, `expect=1` is also used for single-player "alert" playback, where startup
+        // latency matters more than underrun protection. Keep output buffering near zero there.
+        const outputThreshold = isSyncGroup ? (expectCount === 1 ? 0 : 50) : 20;
         await this.sendStrm({
             command: 's',
             codecDetails,
             autostart: autostart ? '3' : '0',
             serverPort: port,
             serverIp: ipToInt(ipAddress),
-            threshold: 20,
-            outputThreshold: 5,
+            // Amount of input buffer (KB) before autostart or BUFFER_READY notification.
+            // Match aioslimproto defaults (200KB) for normal playback, but reduce for sync-groups.
+            threshold: thresholdKb,
+            // Amount of output buffer data before playback starts, in tenths of a second.
+            // Increase to reduce early underruns (tradeoff: more startup latency).
+            outputThreshold,
             transDuration: transitionDuration,
             transType: transition,
             flags: scheme === 'https' ? 0x20 : 0x00,
@@ -529,11 +607,41 @@ export class SlimClient {
     processStatHeartbeat(data) {
         if (data.length < 47)
             return;
+        const now = Date.now();
         const jiffies = data.readUInt32BE(21);
         const elapsedMs = data.readUInt32BE(39);
+        const serverHeartbeat = data.readUInt32BE(43);
         this._jiffies = jiffies;
         this._elapsedMs = elapsedMs;
-        this._lastTimestamp = Date.now();
+        this._lastTimestamp = now;
+        const sentAt = this.heartbeatSentAt.get(serverHeartbeat);
+        if (typeof sentAt === 'number') {
+            const rttMs = Math.max(0, now - sentAt);
+            const midTime = sentAt + rttMs / 2;
+            const shouldReplace = !this.clockBase ||
+                now - this.clockBase.updatedAtMs > 10_000 ||
+                rttMs <= this.clockBase.rttMs;
+            if (shouldReplace) {
+                // Prefer the lowest-RTT sample; it yields the best wallclock<->jiffies mapping.
+                this.clockBase = {
+                    serverTimeMs: midTime,
+                    jiffies,
+                    rttMs,
+                    updatedAtMs: now,
+                };
+            }
+            this.heartbeatSentAt.delete(serverHeartbeat);
+            const pending = this.pendingClockSync.get(serverHeartbeat);
+            if (pending) {
+                pending(true);
+            }
+        }
+        else {
+            const pending = this.pendingClockSync.get(serverHeartbeat);
+            if (pending) {
+                pending(true);
+            }
+        }
         this.signalEvent(EventType.PLAYER_HEARTBEAT);
     }
     async processResp(data) {
@@ -626,16 +734,12 @@ export class SlimClient {
         if (this._heartbeatTimer) {
             clearInterval(this._heartbeatTimer);
         }
+        // Send one immediately to establish a clock base quickly.
+        void this.requestClockSync().catch(() => undefined);
         this._heartbeatTimer = setInterval(() => {
             if (!this._connected)
                 return;
-            this._heartbeatId += 1;
-            void this.sendStrm({
-                command: 't',
-                autostart: '0',
-                flags: 0,
-                replayGain: this._heartbeatId,
-            });
+            void this.requestClockSync().catch(() => undefined);
         }, HEARTBEAT_INTERVAL * 1000);
     }
     async togglePower() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lox-audioserver/node-slimproto",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "SlimProto server/client utilities for controlling Squeezebox-compatible players in Node.js.",
   "type": "module",
   "main": "dist/index.js",

package/src/client.ts

@@ -66,6 +66,9 @@ export class SlimClient {
   private _autoPlay = false;
   private _heartbeatTimer: NodeJS.Timeout | null = null;
   private _heartbeatId = 0;
+  private readonly heartbeatSentAt = new Map<number, number>();
+  private pendingClockSync = new Map<number, (ok: boolean) => void>();
+  private clockBase: { serverTimeMs: number; jiffies: number; rttMs: number; updatedAtMs: number } | null = null;
 
   constructor(socket: net.Socket, callback: SlimClientCallback) {
     this.socket = socket;
@@ -153,6 +156,69 @@ export class SlimClient {
     return this._lastTimestamp || null;
   }
 
+  /**
+   * Best-effort mapping between server wall clock time (ms) and player jiffies.
+   * Derived from `strm t` / `stat STMt` heartbeat exchange.
+   */
+  public get clockSync(): { serverTimeMs: number; jiffies: number; rttMs: number; updatedAtMs: number } | null {
+    return this.clockBase;
+  }
+
+  /**
+   * Estimate the player jiffies value at the given server time.
+   * Returns a 32-bit unsigned timestamp suitable for `unpauseAt`.
+   */
+  public estimateJiffiesAt(serverTimeMs: number): number {
+    if (!this.clockBase) {
+      return Math.max(0, Math.round(this._jiffies + (serverTimeMs - Date.now()))) >>> 0;
+    }
+    const delta = Math.round(serverTimeMs - this.clockBase.serverTimeMs);
+    const target = this.clockBase.jiffies + delta;
+    // Keep within uint32 domain (SlimProto uses 32-bit timestamps).
+    return (target >>> 0);
+  }
+
+  /**
+   * Request an immediate clock sync sample (one `strm t` roundtrip).
+   * Resolves true when the matching STMt arrives, false on timeout or disconnect.
+   */
+  public async requestClockSync(timeoutMs = 800): Promise<boolean> {
+    if (!this._connected) return false;
+    this._heartbeatId += 1;
+    const id = this._heartbeatId;
+    const sentAt = Date.now();
+    this.heartbeatSentAt.set(id, sentAt);
+    // Clean up old send timestamps to avoid unbounded growth.
+    for (const [key, value] of this.heartbeatSentAt) {
+      if (sentAt - value > 60_000) {
+        this.heartbeatSentAt.delete(key);
+      }
+    }
+    const result = await new Promise<boolean>((resolve) => {
+      const timeout = setTimeout(() => {
+        this.pendingClockSync.delete(id);
+        resolve(false);
+      }, Math.max(50, timeoutMs));
+      timeout.unref?.();
+      this.pendingClockSync.set(id, (ok) => {
+        clearTimeout(timeout);
+        this.pendingClockSync.delete(id);
+        resolve(ok);
+      });
+      void this.sendStrm({
+        command: 't',
+        autostart: '0',
+        flags: 0,
+        replayGain: id,
+      }).catch(() => {
+        clearTimeout(timeout);
+        this.pendingClockSync.delete(id);
+        resolve(false);
+      });
+    });
+    return result;
+  }
+
   public async stop(): Promise<void> {
     if (this._state === PlayerState.STOPPED) return;
     await this.sendStrm({ command: 'q', flags: 0 });
@@ -316,14 +382,29 @@ export class SlimClient {
 
     this._autoPlay = autostart;
 
+    const isSyncGroup = parsed.searchParams.has('sync') && parsed.searchParams.has('expect');
+    const expectCount = isSyncGroup ? Number(parsed.searchParams.get('expect') ?? '0') : 0;
+    // For sync-groups we want BUFFER_READY quickly so we can do coordinated unpause.
+    // With MP3 @ 256kbps, 200KB threshold can take ~6s to fill; lowering keeps groups snappy.
+    const thresholdKb = isSyncGroup ? (expectCount === 1 ? 32 : 64) : 200;
+    // For sync-groups we prefer a bit more output buffer to avoid early underruns,
+    // especially with lossless streams or weaker WiFi links.
+    // However, `expect=1` is also used for single-player "alert" playback, where startup
+    // latency matters more than underrun protection. Keep output buffering near zero there.
+    const outputThreshold = isSyncGroup ? (expectCount === 1 ? 0 : 50) : 20;
+
     await this.sendStrm({
       command: 's',
       codecDetails,
       autostart: autostart ? '3' : '0',
       serverPort: port,
       serverIp: ipToInt(ipAddress),
-      threshold: 20,
-      outputThreshold: 5,
+      // Amount of input buffer (KB) before autostart or BUFFER_READY notification.
+      // Match aioslimproto defaults (200KB) for normal playback, but reduce for sync-groups.
+      threshold: thresholdKb,
+      // Amount of output buffer data before playback starts, in tenths of a second.
+      // Increase to reduce early underruns (tradeoff: more startup latency).
+      outputThreshold,
       transDuration: transitionDuration,
       transType: transition,
       flags: scheme === 'https' ? 0x20 : 0x00,
@@ -636,11 +717,42 @@ export class SlimClient {
 
   private processStatHeartbeat(data: Buffer): void {
     if (data.length < 47) return;
+    const now = Date.now();
     const jiffies = data.readUInt32BE(21);
     const elapsedMs = data.readUInt32BE(39);
+    const serverHeartbeat = data.readUInt32BE(43);
     this._jiffies = jiffies;
     this._elapsedMs = elapsedMs;
-    this._lastTimestamp = Date.now();
+    this._lastTimestamp = now;
+
+    const sentAt = this.heartbeatSentAt.get(serverHeartbeat);
+    if (typeof sentAt === 'number') {
+      const rttMs = Math.max(0, now - sentAt);
+      const midTime = sentAt + rttMs / 2;
+      const shouldReplace =
+        !this.clockBase ||
+        now - this.clockBase.updatedAtMs > 10_000 ||
+        rttMs <= this.clockBase.rttMs;
+      if (shouldReplace) {
+        // Prefer the lowest-RTT sample; it yields the best wallclock<->jiffies mapping.
+        this.clockBase = {
+          serverTimeMs: midTime,
+          jiffies,
+          rttMs,
+          updatedAtMs: now,
+        };
+      }
+      this.heartbeatSentAt.delete(serverHeartbeat);
+      const pending = this.pendingClockSync.get(serverHeartbeat);
+      if (pending) {
+        pending(true);
+      }
+    } else {
+      const pending = this.pendingClockSync.get(serverHeartbeat);
+      if (pending) {
+        pending(true);
+      }
+    }
     this.signalEvent(EventType.PLAYER_HEARTBEAT);
   }
 
@@ -754,15 +866,11 @@ export class SlimClient {
     if (this._heartbeatTimer) {
       clearInterval(this._heartbeatTimer);
     }
+    // Send one immediately to establish a clock base quickly.
+    void this.requestClockSync().catch(() => undefined);
     this._heartbeatTimer = setInterval(() => {
       if (!this._connected) return;
-      this._heartbeatId += 1;
-      void this.sendStrm({
-        command: 't',
-        autostart: '0',
-        flags: 0,
-        replayGain: this._heartbeatId,
-      });
+      void this.requestClockSync().catch(() => undefined);
     }, HEARTBEAT_INTERVAL * 1000);
   }