lox-airplay-sender 0.3.0 → 0.3.2

package/README.md

@@ -63,6 +63,7 @@ Creates and starts a sender for one AirPlay device. Returns the instance so you
 - `device`: `{ event: "device", message: status, detail: { key, desc } }`
 - `buffer`: `{ event: "buffer", message: status }` where status is `buffering|playing|drain|end`
 - `error`: `{ event: "error", message }`
+- `metrics`: `{ event: "metrics", detail }` sync drift snapshots emitted on each sync tick when enabled.
 
 ### `LoxAirplaySender` methods
 - `sendPcm(chunk: Buffer)`: Push raw PCM audio. If `inputCodec` is `"alac"` you can push ALAC frames.

package/dist/core/audioOut.d.ts

@@ -12,6 +12,7 @@ export default class AudioOut extends EventEmitter {
     private lastSeq;
     private hasAirTunes;
     private rtpTimeRef;
+    private monotonicRef;
     private startTimeMs?;
     private latencyFrames;
     private latencyApplied;

package/dist/core/audioOut.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const node_events_1 = require("node:events");
+const node_perf_hooks_1 = require("node:perf_hooks");
 const config_1 = __importDefault(require("../utils/config"));
 const numUtil_1 = require("../utils/numUtil");
 const SEQ_NUM_WRAP = Math.pow(2, 16);
@@ -14,7 +15,8 @@ const SEQ_NUM_WRAP = Math.pow(2, 16);
 class AudioOut extends node_events_1.EventEmitter {
     lastSeq = -1;
     hasAirTunes = false;
-    rtpTimeRef = Date.now();
+    rtpTimeRef = 0;
+    monotonicRef = 0;
     startTimeMs;
     latencyFrames = 0;
     latencyApplied = false;
@@ -29,7 +31,10 @@ class AudioOut extends node_events_1.EventEmitter {
             typeof startTimeMs === 'number' && Number.isFinite(startTimeMs)
                 ? startTimeMs
                 : undefined;
-        this.rtpTimeRef = this.startTimeMs ?? Date.now();
+        const wallToMonoOffset = Date.now() - node_perf_hooks_1.performance.now();
+        // Anchor the RTP clock to a monotonic base to avoid NTP slews.
+        this.rtpTimeRef = (this.startTimeMs ?? Date.now()) - wallToMonoOffset;
+        this.monotonicRef = node_perf_hooks_1.performance.now();
         devices.on('airtunes_devices', (hasAirTunes) => {
             this.hasAirTunes = hasAirTunes;
         });
@@ -42,17 +47,34 @@ class AudioOut extends node_events_1.EventEmitter {
             packet.timestamp = (0, numUtil_1.low32)(seq * config_1.default.frames_per_packet + 2 * config_1.default.sampling_rate);
             if (this.hasAirTunes && seq % config_1.default.sync_period === 0) {
                 this.emit('need_sync', seq);
+                const expectedTimeMs = this.rtpTimeRef +
+                    ((seq * config_1.default.frames_per_packet) / config_1.default.sampling_rate) * 1000;
+                const deltaMs = Date.now() - expectedTimeMs;
+                this.emit('metrics', { type: 'sync', seq, deltaMs, latencyFrames: this.latencyFrames });
             }
             this.emit('packet', packet);
             packet.release();
         };
+        const frameDurationMs = (config_1.default.frames_per_packet / config_1.default.sampling_rate) * 1000;
         const syncAudio = () => {
-            const elapsed = Date.now() - this.rtpTimeRef;
+            const nowMs = node_perf_hooks_1.performance.now();
+            const elapsed = nowMs - this.rtpTimeRef;
             if (elapsed < 0) {
                 setTimeout(syncAudio, Math.min(config_1.default.stream_latency, Math.abs(elapsed)));
                 return;
             }
-            const currentSeq = Math.floor((elapsed * config_1.default.sampling_rate) / (config_1.default.frames_per_packet * 1000));
+            let currentSeq = Math.floor((elapsed * config_1.default.sampling_rate) / (config_1.default.frames_per_packet * 1000));
+            // If we're lagging behind significantly, jump forward to avoid long hitches.
+            const expectedTimeMs = this.rtpTimeRef + currentSeq * frameDurationMs;
+            const deltaMs = nowMs - expectedTimeMs;
+            if (deltaMs > config_1.default.jump_forward_threshold_ms) {
+                const jumpSeq = Math.ceil((config_1.default.jump_forward_lead_ms * config_1.default.sampling_rate) /
+                    (config_1.default.frames_per_packet * 1000));
+                const newSeq = currentSeq + jumpSeq;
+                this.rtpTimeRef = nowMs - newSeq * frameDurationMs;
+                this.lastSeq = newSeq - 1;
+                currentSeq = newSeq;
+            }
             for (let i = this.lastSeq + 1; i <= currentSeq; i += 1) {
                 sendPacket(i);
             }

package/dist/core/index.js

@@ -69,6 +69,9 @@ class AirTunes extends node_stream_1.Duplex {
             this.emit('buffer', status);
         });
         audioOut.init(this.devices, this.circularBuffer, options.startTimeMs);
+        audioOut.on('metrics', (metrics) => {
+            this.emit('metrics', metrics);
+        });
         this.circularBuffer.on('drain', () => {
             this.emit('drain');
         });

package/dist/esm/core/audioOut.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const node_events_1 = require("node:events");
+const node_perf_hooks_1 = require("node:perf_hooks");
 const config_1 = __importDefault(require("../utils/config"));
 const numUtil_1 = require("../utils/numUtil");
 const SEQ_NUM_WRAP = Math.pow(2, 16);
@@ -14,7 +15,8 @@ const SEQ_NUM_WRAP = Math.pow(2, 16);
 class AudioOut extends node_events_1.EventEmitter {
     lastSeq = -1;
     hasAirTunes = false;
-    rtpTimeRef = Date.now();
+    rtpTimeRef = 0;
+    monotonicRef = 0;
     startTimeMs;
     latencyFrames = 0;
     latencyApplied = false;
@@ -29,7 +31,10 @@ class AudioOut extends node_events_1.EventEmitter {
             typeof startTimeMs === 'number' && Number.isFinite(startTimeMs)
                 ? startTimeMs
                 : undefined;
-        this.rtpTimeRef = this.startTimeMs ?? Date.now();
+        const wallToMonoOffset = Date.now() - node_perf_hooks_1.performance.now();
+        // Anchor the RTP clock to a monotonic base to avoid NTP slews.
+        this.rtpTimeRef = (this.startTimeMs ?? Date.now()) - wallToMonoOffset;
+        this.monotonicRef = node_perf_hooks_1.performance.now();
         devices.on('airtunes_devices', (hasAirTunes) => {
             this.hasAirTunes = hasAirTunes;
         });
@@ -42,17 +47,34 @@ class AudioOut extends node_events_1.EventEmitter {
             packet.timestamp = (0, numUtil_1.low32)(seq * config_1.default.frames_per_packet + 2 * config_1.default.sampling_rate);
             if (this.hasAirTunes && seq % config_1.default.sync_period === 0) {
                 this.emit('need_sync', seq);
+                const expectedTimeMs = this.rtpTimeRef +
+                    ((seq * config_1.default.frames_per_packet) / config_1.default.sampling_rate) * 1000;
+                const deltaMs = Date.now() - expectedTimeMs;
+                this.emit('metrics', { type: 'sync', seq, deltaMs, latencyFrames: this.latencyFrames });
             }
             this.emit('packet', packet);
             packet.release();
         };
+        const frameDurationMs = (config_1.default.frames_per_packet / config_1.default.sampling_rate) * 1000;
         const syncAudio = () => {
-            const elapsed = Date.now() - this.rtpTimeRef;
+            const nowMs = node_perf_hooks_1.performance.now();
+            const elapsed = nowMs - this.rtpTimeRef;
             if (elapsed < 0) {
                 setTimeout(syncAudio, Math.min(config_1.default.stream_latency, Math.abs(elapsed)));
                 return;
             }
-            const currentSeq = Math.floor((elapsed * config_1.default.sampling_rate) / (config_1.default.frames_per_packet * 1000));
+            let currentSeq = Math.floor((elapsed * config_1.default.sampling_rate) / (config_1.default.frames_per_packet * 1000));
+            // If we're lagging behind significantly, jump forward to avoid long hitches.
+            const expectedTimeMs = this.rtpTimeRef + currentSeq * frameDurationMs;
+            const deltaMs = nowMs - expectedTimeMs;
+            if (deltaMs > config_1.default.jump_forward_threshold_ms) {
+                const jumpSeq = Math.ceil((config_1.default.jump_forward_lead_ms * config_1.default.sampling_rate) /
+                    (config_1.default.frames_per_packet * 1000));
+                const newSeq = currentSeq + jumpSeq;
+                this.rtpTimeRef = nowMs - newSeq * frameDurationMs;
+                this.lastSeq = newSeq - 1;
+                currentSeq = newSeq;
+            }
             for (let i = this.lastSeq + 1; i <= currentSeq; i += 1) {
                 sendPacket(i);
             }

package/dist/esm/core/index.js

@@ -69,6 +69,9 @@ class AirTunes extends node_stream_1.Duplex {
             this.emit('buffer', status);
         });
         audioOut.init(this.devices, this.circularBuffer, options.startTimeMs);
+        audioOut.on('metrics', (metrics) => {
+            this.emit('metrics', metrics);
+        });
         this.circularBuffer.on('drain', () => {
             this.emit('drain');
         });

package/dist/esm/index.js

@@ -84,6 +84,9 @@ class LoxAirplaySender extends node_events_1.EventEmitter {
         this.airtunes.on('error', (err) => {
             onEvent?.({ event: 'error', message: err instanceof Error ? err.message : String(err) });
         });
+        this.airtunes.on('metrics', (detail) => {
+            onEvent?.({ event: 'metrics', detail });
+        });
         const dev = this.airtunes.add(options.host, {
             port: options.port,
             name: options.name,

package/dist/esm/utils/config.js

@@ -27,6 +27,8 @@ exports.config = {
     rtsp_retry_jitter_ms: 150,
     control_sync_base_delay_ms: 2,
     control_sync_jitter_ms: 3,
+    jump_forward_threshold_ms: 180,
+    jump_forward_lead_ms: 220,
     device_magic: (0, numUtil_1.randomInt)(9),
     ntp_epoch: 0x83aa7e80,
     iv_base64: 'ePRBLI0XN5ArFaaz7ncNZw',

package/dist/index.js

@@ -84,6 +84,9 @@ class LoxAirplaySender extends node_events_1.EventEmitter {
         this.airtunes.on('error', (err) => {
             onEvent?.({ event: 'error', message: err instanceof Error ? err.message : String(err) });
         });
+        this.airtunes.on('metrics', (detail) => {
+            onEvent?.({ event: 'metrics', detail });
+        });
         const dev = this.airtunes.add(options.host, {
             port: options.port,
             name: options.name,

package/dist/utils/config.d.ts

@@ -22,6 +22,8 @@ export interface AirplayConfig {
     rtsp_retry_jitter_ms: number;
     control_sync_base_delay_ms: number;
     control_sync_jitter_ms: number;
+    jump_forward_threshold_ms: number;
+    jump_forward_lead_ms: number;
     device_magic: number;
     ntp_epoch: number;
     iv_base64: string;

package/dist/utils/config.js

@@ -27,6 +27,8 @@ exports.config = {
     rtsp_retry_jitter_ms: 150,
     control_sync_base_delay_ms: 2,
     control_sync_jitter_ms: 3,
+    jump_forward_threshold_ms: 180,
+    jump_forward_lead_ms: 220,
     device_magic: (0, numUtil_1.randomInt)(9),
     ntp_epoch: 0x83aa7e80,
     iv_base64: 'ePRBLI0XN5ArFaaz7ncNZw',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lox-airplay-sender",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "AirPlay sender (RAOP/AirPlay 1 + AirPlay 2 auth flows) ",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",